Skip to content

CLI for SidePulse

Python
14.3 KB
Raw Blame
#!/usr/bin/env python3
from __future__ import annotations

import argparse
import math
import queue
import sys
import time
from pathlib import Path
from typing import Any


REPO_SRC = Path(__file__).resolve().parents[1] / "src"
if REPO_SRC.exists():
    sys.path.insert(0, str(REPO_SRC))

from sidepulse.device_writer import (  # noqa: E402
    DEFAULT_FILE_NAME,
    DeviceWriteError,
    validate_led_text,
    write_led_program,
)
from sidepulse.led_status import apply_brightness, led_count_for_target  # noqa: E402


DEFAULT_FPS = 25.0
DEFAULT_IDLE_BRIGHTNESS = 0.08
DEFAULT_MAX_BRIGHTNESS = 1.0
DEFAULT_NOISE_FLOOR_DB = -54.0
DEFAULT_PEAK_DB = -8.0
DEFAULT_CURVE = 0.72
DEFAULT_ATTACK_SECONDS = 0.045
DEFAULT_RELEASE_SECONDS = 0.32
DEFAULT_TRANSITION_MS = 90
MIN_RMS = 1e-9


def clamp(value: float, low: float = 0.0, high: float = 1.0) -> float:
    return max(low, min(high, value))


def normalize_led_count(led_count: int) -> int:
    return max(1, min(8, int(led_count)))


def green_to_red_rgb(index: int, led_count: int) -> tuple[int, int, int]:
    count = normalize_led_count(led_count)
    if count == 1:
        return 0, 255, 0

    position = clamp(index / (count - 1))
    if position <= 0.5:
        red = int(round(255 * (position / 0.5)))
        green = 255
    else:
        red = 255
        green = int(round(255 * (1.0 - ((position - 0.5) / 0.5))))
    return red, green, 0


def scale_rgb(rgb: tuple[int, int, int], brightness: float) -> tuple[int, int, int]:
    brightness = clamp(brightness)
    return tuple(int(round(channel * brightness)) for channel in rgb)


def rgb_hex(rgb: tuple[int, int, int]) -> str:
    red, green, blue = rgb
    return f"#{red:02X}{green:02X}{blue:02X}"


def build_led_program(
    level: float,
    *,
    led_count: int = 8,
    idle_brightness: float = DEFAULT_IDLE_BRIGHTNESS,
    max_brightness: float = DEFAULT_MAX_BRIGHTNESS,
    transition_ms: int = DEFAULT_TRANSITION_MS,
) -> str:
    count = normalize_led_count(led_count)
    level = clamp(level)
    idle = clamp(idle_brightness)
    peak = max(idle, clamp(max_brightness))
    fill = level * count
    duration = max(0, int(transition_ms))
    global_brightness = int(round(peak * 255))

    segments: list[str] = []
    for index in range(count):
        segment_level = clamp(fill - index)
        absolute_brightness = idle + ((peak - idle) * segment_level)
        brightness = absolute_brightness / peak if peak > 0 else 0.0
        color = rgb_hex(scale_rgb(green_to_red_rgb(index, count), brightness))
        token = f"{index}:{color}"
        if duration:
            token += f" {duration}ms cosine"
        segments.append(token)

    program = apply_brightness("; ".join(segments), global_brightness)
    validate_led_text(program)
    return program


def rms_to_dbfs(rms: float, *, gain_db: float = 0.0) -> float:
    return 20.0 * math.log10(max(float(rms), MIN_RMS)) + gain_db


def rms_to_level(
    rms: float,
    *,
    noise_floor_db: float = DEFAULT_NOISE_FLOOR_DB,
    peak_db: float = DEFAULT_PEAK_DB,
    gain_db: float = 0.0,
    curve: float = DEFAULT_CURVE,
) -> float:
    if peak_db <= noise_floor_db:
        raise ValueError("--peak-db must be greater than --noise-floor-db")

    db = rms_to_dbfs(rms, gain_db=gain_db)
    level = clamp((db - noise_floor_db) / (peak_db - noise_floor_db))
    return level ** max(0.05, float(curve))


def smooth_level(
    previous: float,
    target: float,
    *,
    elapsed: float,
    attack_seconds: float = DEFAULT_ATTACK_SECONDS,
    release_seconds: float = DEFAULT_RELEASE_SECONDS,
) -> float:
    previous = clamp(previous)
    target = clamp(target)
    tau = attack_seconds if target > previous else release_seconds
    if tau <= 0:
        return target
    alpha = 1.0 - math.exp(-max(0.0, elapsed) / tau)
    return previous + ((target - previous) * alpha)


def push_latest(samples: queue.Queue[float], value: float) -> None:
    try:
        samples.put_nowait(value)
        return
    except queue.Full:
        pass

    try:
        samples.get_nowait()
    except queue.Empty:
        pass
    samples.put_nowait(value)


def drain_peak(samples: queue.Queue[float]) -> float:
    peak = 0.0
    while True:
        try:
            peak = max(peak, samples.get_nowait())
        except queue.Empty:
            return peak


def terminal_meter(level: float, *, led_count: int) -> str:
    count = normalize_led_count(led_count)
    fill = clamp(level) * count
    cells: list[str] = []
    for index in range(count):
        segment_level = clamp(fill - index)
        if segment_level >= 0.66:
            char = "#"
        elif segment_level >= 0.33:
            char = "="
        elif segment_level > 0:
            char = "-"
        else:
            char = "."

        red, green, blue = green_to_red_rgb(index, count)
        cells.append(f"\033[38;2;{red};{green};{blue}m{char}\033[0m")
    return "".join(cells)


def parse_input_device(value: str | None) -> int | str | None:
    if value is None:
        return None
    try:
        return int(value)
    except ValueError:
        return value


def load_audio_modules() -> tuple[Any, Any]:
    try:
        import numpy as np
        import sounddevice as sd
    except ImportError as exc:
        raise SystemExit(
            "audio_monitor.py needs sounddevice and numpy for live audio.\n"
            "Install them with: python3 -m pip install sounddevice numpy"
        ) from exc
    return sd, np


def list_input_devices() -> int:
    sd, _ = load_audio_modules()
    devices = sd.query_devices()
    default_input = None
    try:
        default_input = sd.default.device[0]
    except (AttributeError, IndexError, TypeError):
        pass

    for index, device in enumerate(devices):
        channels = int(device.get("max_input_channels", 0))
        if channels <= 0:
            continue
        marker = "*" if index == default_input else " "
        name = device.get("name", "Unnamed input")
        sample_rate = int(float(device.get("default_samplerate", 0)))
        print(f"{marker} {index:2d}: {name} ({channels} ch, {sample_rate} Hz)")
    return 0


def resolve_target(args: argparse.Namespace) -> Path | None:
    if args.dry_run and args.device is None:
        return None
    return write_led_program(
        "off",
        device_path=args.device,
        file_name=args.file_name,
        dry_run=True,
    )


def infer_led_count(args: argparse.Namespace, target: Path | None) -> int:
    if args.led_count is not None:
        return normalize_led_count(args.led_count)
    if target is not None:
        return led_count_for_target(target)
    return 8


def print_preview(
    *,
    level: float,
    rms: float,
    led_count: int,
    target: Path | None,
    dry_run: bool,
) -> None:
    db = rms_to_dbfs(rms)
    destination = "dry-run" if dry_run else str(target)
    print(
        f"\r{terminal_meter(level, led_count=led_count)} "
        f"{level:5.1%} {db:6.1f} dBFS -> {destination}",
        end="",
        flush=True,
    )


def run_monitor(args: argparse.Namespace) -> int:
    if args.list_inputs:
        return list_input_devices()

    sd, np = load_audio_modules()
    target = resolve_target(args)
    led_count = infer_led_count(args, target)
    audio_samples: queue.Queue[float] = queue.Queue(maxsize=8)
    stream_errors: queue.Queue[str] = queue.Queue(maxsize=4)
    preview = args.terminal or args.dry_run
    frame_seconds = 1.0 / max(1.0, float(args.fps))
    input_device = parse_input_device(args.input_device)
    sample_rate = int(args.sample_rate)
    block_size = max(0, int(args.block_size))

    def callback(indata: Any, frames: int, time_info: Any, status: Any) -> None:
        if status:
            try:
                stream_errors.put_nowait(str(status))
            except queue.Full:
                pass
        rms = math.sqrt(float(np.mean(np.square(indata))))
        push_latest(audio_samples, rms)

    if args.dry_run:
        print(f"audio monitor: dry-run preview with {led_count} LEDs")
    else:
        print(f"audio monitor: writing {led_count} LEDs to {target}")
    print("press Ctrl-C to stop")

    smoothed = 0.0
    latest_rms = 0.0
    last_program: str | None = None
    last_time = time.monotonic()
    printed_preview = False

    try:
        with sd.InputStream(
            channels=1,
            samplerate=sample_rate,
            blocksize=block_size,
            callback=callback,
            device=input_device,
            dtype="float32",
        ):
            while True:
                frame_start = time.monotonic()
                rms = drain_peak(audio_samples)
                if rms > 0.0:
                    latest_rms = rms

                target_level = rms_to_level(
                    rms,
                    noise_floor_db=args.noise_floor_db,
                    peak_db=args.peak_db,
                    gain_db=args.gain_db,
                    curve=args.curve,
                )
                now = time.monotonic()
                smoothed = smooth_level(
                    smoothed,
                    target_level,
                    elapsed=now - last_time,
                    attack_seconds=args.attack,
                    release_seconds=args.release,
                )
                last_time = now

                program = build_led_program(
                    smoothed,
                    led_count=led_count,
                    idle_brightness=args.idle_brightness,
                    max_brightness=args.max_brightness,
                    transition_ms=args.transition_ms,
                )
                if program != last_program:
                    if not args.dry_run:
                        write_led_program(program, device_path=target, file_name=args.file_name)
                    last_program = program

                if preview:
                    printed_preview = True
                    print_preview(
                        level=smoothed,
                        rms=latest_rms,
                        led_count=led_count,
                        target=target,
                        dry_run=args.dry_run,
                    )

                try:
                    error = stream_errors.get_nowait()
                except queue.Empty:
                    error = None
                if error and not preview:
                    print(f"audio stream: {error}", file=sys.stderr)

                sleep_for = frame_seconds - (time.monotonic() - frame_start)
                if sleep_for > 0:
                    time.sleep(sleep_for)
    except KeyboardInterrupt:
        return 0
    finally:
        if printed_preview:
            print()
        if args.off_on_exit and target is not None and not args.dry_run:
            try:
                write_led_program("off", device_path=target, file_name=args.file_name)
            except (DeviceWriteError, OSError) as exc:
                print(f"audio monitor: could not turn LEDs off: {exc}", file=sys.stderr)


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description="Show microphone volume as a smooth dim green-to-red SidePulse LED bar.",
    )
    parser.add_argument(
        "--device",
        type=Path,
        help="Mounted device folder or LED program file. Defaults to auto-detecting /Volumes.",
    )
    parser.add_argument(
        "--file-name",
        default=DEFAULT_FILE_NAME,
        help=f"Target file name when --device is a folder. Default: {DEFAULT_FILE_NAME}.",
    )
    parser.add_argument("--led-count", type=int, help="LED count. Defaults to device name, then 8.")
    parser.add_argument("--fps", type=float, default=DEFAULT_FPS, help="LED update rate.")
    parser.add_argument(
        "--transition-ms",
        type=int,
        default=DEFAULT_TRANSITION_MS,
        help="Controller-side cosine fade per frame; set 0 for immediate updates.",
    )
    parser.add_argument(
        "--idle-brightness",
        type=float,
        default=DEFAULT_IDLE_BRIGHTNESS,
        help="Dim baseline brightness from 0.0 to 1.0.",
    )
    parser.add_argument(
        "--max-brightness",
        type=float,
        default=DEFAULT_MAX_BRIGHTNESS,
        help="Peak brightness from 0.0 to 1.0.",
    )
    parser.add_argument(
        "--noise-floor-db",
        type=float,
        default=DEFAULT_NOISE_FLOOR_DB,
        help="Input level that maps to an empty bar.",
    )
    parser.add_argument(
        "--peak-db",
        type=float,
        default=DEFAULT_PEAK_DB,
        help="Input level that maps to a full bar.",
    )
    parser.add_argument("--gain-db", type=float, default=0.0, help="Gain applied before level mapping.")
    parser.add_argument(
        "--curve",
        type=float,
        default=DEFAULT_CURVE,
        help="Response curve; lower values make quiet sounds more visible.",
    )
    parser.add_argument(
        "--attack",
        type=float,
        default=DEFAULT_ATTACK_SECONDS,
        help="Seconds for the meter to rise toward louder audio.",
    )
    parser.add_argument(
        "--release",
        type=float,
        default=DEFAULT_RELEASE_SECONDS,
        help="Seconds for the meter to fall after audio gets quieter.",
    )
    parser.add_argument("--sample-rate", type=float, default=44100.0, help="Audio sample rate.")
    parser.add_argument("--block-size", type=int, default=0, help="Audio callback block size; 0 lets PortAudio choose.")
    parser.add_argument("--input-device", help="sounddevice input index or name.")
    parser.add_argument("--list-inputs", action="store_true", help="List audio input devices and exit.")
    parser.add_argument("--terminal", action="store_true", help="Show a terminal meter while running.")
    parser.add_argument(
        "--dry-run",
        action="store_true",
        help="Preview without writing to a SidePulse Pro or SidePulse Dot device.",
    )
    parser.add_argument("--off-on-exit", action="store_true", help="Write 'off' when the monitor exits.")
    return parser


def main(argv: list[str] | None = None) -> int:
    parser = build_parser()
    args = parser.parse_args(argv)
    try:
        return run_monitor(args)
    except ValueError as exc:
        print(f"audio monitor: {exc}", file=sys.stderr)
        return 2
    except DeviceWriteError as exc:
        print(f"audio monitor: {exc}", file=sys.stderr)
        return 2
    except OSError as exc:
        print(f"audio monitor: {exc}", file=sys.stderr)
        return 1


if __name__ == "__main__":
    raise SystemExit(main())