claudible 0.1.0__py3-none-any.whl

claudible/__init__.py

@@ -0,0 +1,3 @@
+"""Claudible - ambient audio soundscape feedback for terminal output."""
+
+__version__ = "0.1.0"

claudible/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as python -m claudible."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

claudible/audio.py

@@ -0,0 +1,309 @@
+"""Sound engine for procedural audio generation."""
+
+import numpy as np
+import sounddevice as sd
+from typing import Optional
+import threading
+
+try:
+    from scipy.signal import butter, lfilter
+    _HAS_SCIPY = True
+except ImportError:
+    _HAS_SCIPY = False
+
+from .materials import Material, get_random_material
+
+
+class SoundEngine:
+    """Generates and plays procedural sounds based on physical material models."""
+
+    SAMPLE_RATE = 44100
+    BUFFER_SIZE = 44100 * 2  # 2 seconds of audio buffer
+
+    def __init__(self, material: Optional[Material] = None, volume: float = 0.5):
+        self.material = material or get_random_material()
+        self.volume = volume
+        self._stream: Optional[sd.OutputStream] = None
+        self._running = False
+        self._hum_phase = 0.0
+        self._lock = threading.Lock()
+
+        # Ring buffer for mixing audio
+        self._buffer = np.zeros(self.BUFFER_SIZE, dtype=np.float32)
+        self._write_pos = 0
+        self._read_pos = 0
+
+        # Pre-generate grain variations for efficiency
+        self._grain_cache = [self._generate_grain() for _ in range(8)]
+        self._cache_index = 0
+
+    def start(self):
+        """Start the audio output stream."""
+        self._running = True
+        self._stream = sd.OutputStream(
+            samplerate=self.SAMPLE_RATE,
+            channels=1,
+            callback=self._audio_callback,
+            blocksize=1024,
+        )
+        self._stream.start()
+
+    def stop(self):
+        """Stop the audio output stream."""
+        self._running = False
+        if self._stream:
+            self._stream.stop()
+            self._stream.close()
+            self._stream = None
+
+    # --- DSP utilities ---
+
+    def _highpass(self, data: np.ndarray, cutoff: float) -> np.ndarray:
+        """High-pass filter. Uses scipy if available, else differentiation."""
+        if _HAS_SCIPY:
+            nyq = self.SAMPLE_RATE / 2
+            norm = min(cutoff / nyq, 0.99)
+            if norm <= 0:
+                return data
+            b, a = butter(2, norm, btype='high')
+            return lfilter(b, a, data).astype(np.float32)
+        # Fallback: repeated differentiation
+        out = np.diff(data, prepend=data[0])
+        return np.diff(out, prepend=out[0]).astype(np.float32)
+
+    def _lowpass(self, data: np.ndarray, cutoff: float) -> np.ndarray:
+        """Low-pass filter. Uses scipy if available, else moving average."""
+        if _HAS_SCIPY:
+            nyq = self.SAMPLE_RATE / 2
+            norm = min(cutoff / nyq, 0.99)
+            if norm <= 0:
+                return np.zeros_like(data)
+            b, a = butter(2, norm, btype='low')
+            return lfilter(b, a, data).astype(np.float32)
+        # Fallback: simple moving average
+        n = max(int(self.SAMPLE_RATE / cutoff / 2), 1)
+        kernel = np.ones(n, dtype=np.float32) / n
+        return np.convolve(data, kernel, mode='same').astype(np.float32)
+
+    def _apply_reverb(self, signal: np.ndarray, amount: float,
+                      room_size: float = 1.0, damping: float = 0.3) -> np.ndarray:
+        """Multi-tap reverb with high-frequency damping on later reflections."""
+        if amount <= 0:
+            return signal
+        base_delays_ms = [23, 37, 53, 79, 113, 149]
+        out = signal.copy()
+        for i, d in enumerate(base_delays_ms):
+            delay_samples = int(d * room_size * self.SAMPLE_RATE / 1000)
+            if delay_samples >= len(signal) or delay_samples <= 0:
+                continue
+            tap = np.zeros_like(signal)
+            tap[delay_samples:] = signal[:-delay_samples]
+            # Damp high frequencies in later reflections
+            if i > 1 and damping > 0:
+                cutoff = max(4000 - i * 500 * damping, 500)
+                tap = self._lowpass(tap, cutoff)
+            out += tap * amount * (0.55 ** i)
+        return out / max(1.0 + amount * 1.5, 1.0)
+
+    # --- Audio callback ---
+
+    def _audio_callback(self, outdata, frames, time, status):
+        """Audio stream callback - mixes queued sounds with background hum."""
+        output = np.zeros(frames, dtype=np.float32)
+
+        # Background hum: multiple detuned oscillators with slow wobble
+        t = np.arange(frames) / self.SAMPLE_RATE
+        phase_inc = 2 * np.pi * 55.0 / self.SAMPLE_RATE * frames
+        wobble = 0.002 * np.sin(2 * np.pi * 0.08 * t + self._hum_phase * 0.01)
+
+        for freq, amp in [(55.0, 0.007), (55.15, 0.006), (54.85, 0.006), (110.05, 0.001)]:
+            output += amp * np.sin(
+                2 * np.pi * freq * (1 + wobble) * t + self._hum_phase * (freq / 55.0)
+            ).astype(np.float32)
+
+        self._hum_phase = (self._hum_phase + phase_inc) % (2 * np.pi)
+
+        # Read from ring buffer
+        with self._lock:
+            for i in range(frames):
+                output[i] += self._buffer[self._read_pos]
+                self._buffer[self._read_pos] = 0.0
+                self._read_pos = (self._read_pos + 1) % self.BUFFER_SIZE
+
+        outdata[:] = (output * self.volume).reshape(-1, 1)
+
+    def _add_to_buffer(self, samples: np.ndarray):
+        """Add samples to the ring buffer (mixes with existing)."""
+        with self._lock:
+            for i, sample in enumerate(samples):
+                pos = (self._read_pos + i) % self.BUFFER_SIZE
+                self._buffer[pos] += sample
+
+    # --- Sound generation ---
+
+    def _generate_grain(self) -> np.ndarray:
+        """Generate a single grain sound from the material's physical model."""
+        m = self.material
+        # Vary duration per grain
+        duration = m.grain_duration * np.random.uniform(0.85, 1.15)
+        n = int(duration * self.SAMPLE_RATE)
+        t = np.linspace(0, duration, n, dtype=np.float32)
+
+        grain = np.zeros(n, dtype=np.float32)
+
+        # Randomise base frequency within the material's spread
+        base_freq = m.base_freq * (2 ** (np.random.uniform(-m.freq_spread, m.freq_spread) / 12))
+
+        # Generate each partial with its own decay, detuning, and random phase
+        for i, (ratio, amp) in enumerate(m.partials):
+            detune_cents = np.random.uniform(-m.detune_amount, m.detune_amount)
+            freq = base_freq * ratio * (2 ** (detune_cents / 1200))
+            # Extra micro-variation per partial
+            freq *= np.random.uniform(0.997, 1.003)
+            phase = np.random.uniform(0, 2 * np.pi)
+
+            decay_rate = m.decay_rates[i] if i < len(m.decay_rates) else m.decay_rates[-1]
+            envelope = np.exp(-decay_rate * t)
+
+            grain += amp * envelope * np.sin(2 * np.pi * freq * t + phase)
+
+        # Noise transient (the "tick" of physical impact)
+        if m.attack_noise > 0:
+            noise = np.random.randn(n).astype(np.float32)
+            noise = self._highpass(noise, m.noise_freq)
+            # Shape: fast attack, very fast decay with micro-variation
+            noise_env = np.exp(-150 * t)
+            noise_env *= np.clip(
+                1.0 + 0.3 * np.random.randn(n).astype(np.float32) * np.exp(-200 * t),
+                0, 1,
+            )
+            grain += m.attack_noise * 0.3 * noise * noise_env
+
+        # Attack shaping
+        attack_samples = max(int(m.attack_ms / 1000 * self.SAMPLE_RATE), 2)
+        if attack_samples < n:
+            grain[:attack_samples] *= np.linspace(0, 1, attack_samples, dtype=np.float32)
+
+        # Pitch drop envelope (physical: pitch drops as energy dissipates)
+        if m.pitch_drop != 1.0:
+            pitch_env = np.linspace(1.0, m.pitch_drop, n)
+            phase_mod = np.cumsum(pitch_env) / np.sum(pitch_env) * n
+            indices = np.clip(phase_mod.astype(int), 0, n - 1)
+            grain = grain[indices]
+
+        # Multi-tap reverb with HF damping
+        grain = self._apply_reverb(grain, m.reverb_amount, m.room_size, m.reverb_damping)
+
+        # Truncate reverb tail back to grain length
+        grain = grain[:n]
+
+        # Normalise with per-material volume
+        peak = np.max(np.abs(grain))
+        if peak > 0:
+            grain = grain / peak * 0.4 * m.volume
+
+        return grain.astype(np.float32)
+
+    def play_grain(self):
+        """Play a grain/sparkle sound."""
+        # Pick a random cached grain
+        idx = np.random.randint(len(self._grain_cache))
+        grain = self._grain_cache[idx].copy()
+
+        # Per-play pitch variation via resampling (±4 semitones)
+        pitch_shift = 2 ** (np.random.uniform(-4, 4) / 12)
+        if abs(pitch_shift - 1.0) > 0.001:
+            new_len = int(len(grain) / pitch_shift)
+            if new_len > 0:
+                grain = np.interp(
+                    np.linspace(0, len(grain) - 1, new_len),
+                    np.arange(len(grain)),
+                    grain,
+                ).astype(np.float32)
+
+        # Random amplitude variation
+        grain *= np.random.uniform(0.6, 1.0)
+
+        # Regenerate cached grains aggressively for variety
+        if np.random.random() < 0.5:
+            self._grain_cache[np.random.randint(len(self._grain_cache))] = self._generate_grain()
+
+        self._add_to_buffer(grain)
+
+    def play_chime(self):
+        """Play a soft completion chime using the material's tonal character."""
+        m = self.material
+        duration = 0.35
+        n = int(duration * self.SAMPLE_RATE)
+        t = np.linspace(0, duration, n, dtype=np.float32)
+
+        chime = np.zeros(n, dtype=np.float32)
+
+        # Use the material's own partials at a lower register for the chime
+        base = m.base_freq * 0.5
+        for i, (ratio, amp) in enumerate(m.partials[:4]):
+            freq = base * ratio * np.random.uniform(0.998, 1.002)
+            phase = np.random.uniform(0, 2 * np.pi)
+            decay_rate = m.decay_rates[i] if i < len(m.decay_rates) else m.decay_rates[-1]
+            # Slower decay for sustained chime
+            envelope = np.exp(-decay_rate * 0.25 * t) * np.sin(np.pi * t / duration)
+            chime += amp * 0.3 * np.sin(2 * np.pi * freq * t + phase) * envelope
+
+        # Softer noise transient
+        if m.attack_noise > 0:
+            noise = np.random.randn(n).astype(np.float32)
+            noise = self._highpass(noise, m.noise_freq)
+            chime += m.attack_noise * 0.15 * noise * np.exp(-50 * t)
+
+        # More reverb for chimes
+        chime = self._apply_reverb(
+            chime, m.reverb_amount * 1.3,
+            room_size=m.room_size * 1.2,
+            damping=m.reverb_damping,
+        )
+        chime = chime[:n]
+
+        peak = np.max(np.abs(chime))
+        if peak > 0:
+            chime = chime / peak * 0.35 * m.volume
+
+        self._add_to_buffer(chime.astype(np.float32))
+
+    def play_attention(self):
+        """Play a gentle attention signal using the material's tonal character."""
+        m = self.material
+        duration = 0.8
+        n = int(duration * self.SAMPLE_RATE)
+        t = np.linspace(0, duration, n, dtype=np.float32)
+
+        signal = np.zeros(n, dtype=np.float32)
+
+        # Two-note rising pattern using material's frequency
+        note_samples = n // 2
+        for i, pitch_mult in enumerate([1.0, 1.25]):  # Root and major third
+            start = i * note_samples
+            end = start + note_samples
+            nt = t[start:end] - t[start]
+            freq = m.base_freq * 0.4 * pitch_mult
+
+            envelope = np.sin(np.pi * nt / (duration / 2)) ** 2
+            # Use a couple of the material's partials
+            for j, (ratio, amp) in enumerate(m.partials[:2]):
+                pfreq = freq * ratio * np.random.uniform(0.998, 1.002)
+                signal[start:end] += 0.2 * amp * np.sin(
+                    2 * np.pi * pfreq * nt + np.random.uniform(0, 2 * np.pi)
+                ) * envelope
+
+        # Gentle reverb
+        signal = self._apply_reverb(
+            signal, m.reverb_amount * 1.5,
+            room_size=m.room_size * 1.3,
+            damping=m.reverb_damping,
+        )
+        signal = signal[:n]
+
+        peak = np.max(np.abs(signal))
+        if peak > 0:
+            signal = signal / peak * 0.3 * m.volume
+
+        self._add_to_buffer(signal.astype(np.float32))

claudible/cli.py

@@ -0,0 +1,176 @@
+"""Command-line interface for claudible."""
+
+import argparse
+import os
+import pty
+import select
+import subprocess
+import sys
+import time
+from typing import Optional
+
+from .audio import SoundEngine
+from .materials import get_material, get_random_material, list_materials, MATERIALS
+from .monitor import ActivityMonitor
+
+
+def run_pipe_mode(engine: SoundEngine, monitor: ActivityMonitor):
+    """Run in pipe mode, reading from stdin."""
+    engine.start()
+    monitor.start()
+
+    try:
+        while True:
+            data = sys.stdin.buffer.read(1024)
+            if not data:
+                break
+            monitor.process_chunk(data)
+            sys.stdout.buffer.write(data)
+            sys.stdout.buffer.flush()
+        # Let audio buffer drain
+        time.sleep(0.5)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        monitor.stop()
+        engine.stop()
+
+
+def run_wrap_mode(command: str, engine: SoundEngine, monitor: ActivityMonitor):
+    """Run in wrap mode, spawning a PTY for the command."""
+    import shlex
+    import tty
+    import termios
+
+    engine.start()
+    monitor.start()
+
+    if ' ' in command:
+        args = shlex.split(command)
+    else:
+        args = [command]
+
+    master_fd, slave_fd = pty.openpty()
+
+    try:
+        process = subprocess.Popen(
+            args,
+            stdin=slave_fd,
+            stdout=slave_fd,
+            stderr=slave_fd,
+            preexec_fn=os.setsid,
+        )
+        os.close(slave_fd)
+
+        old_settings = termios.tcgetattr(sys.stdin)
+        try:
+            tty.setraw(sys.stdin.fileno())
+
+            while process.poll() is None:
+                rlist, _, _ = select.select([sys.stdin, master_fd], [], [], 0.1)
+
+                for fd in rlist:
+                    if fd == sys.stdin:
+                        data = os.read(sys.stdin.fileno(), 1024)
+                        if data:
+                            os.write(master_fd, data)
+                    elif fd == master_fd:
+                        try:
+                            data = os.read(master_fd, 1024)
+                            if data:
+                                monitor.process_chunk(data)
+                                sys.stdout.buffer.write(data)
+                                sys.stdout.buffer.flush()
+                        except OSError:
+                            break
+        finally:
+            termios.tcsetattr(sys.stdin, termios.TCSADRAIN, old_settings)
+
+    except KeyboardInterrupt:
+        pass
+    finally:
+        os.close(master_fd)
+        monitor.stop()
+        engine.stop()
+
+
+def main():
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        prog='claudible',
+        description='Ambient audio soundscape feedback for terminal output',
+    )
+    parser.add_argument(
+        'command',
+        nargs='?',
+        default='claude',
+        help='Command to wrap (default: claude)',
+    )
+    parser.add_argument(
+        '--pipe',
+        action='store_true',
+        help='Pipe mode: read from stdin instead of wrapping a command',
+    )
+    parser.add_argument(
+        '--character', '-c',
+        choices=list_materials(),
+        help='Sound character (default: random)',
+    )
+    parser.add_argument(
+        '--volume', '-v',
+        type=float,
+        default=0.5,
+        help='Volume 0.0-1.0 (default: 0.5)',
+    )
+    parser.add_argument(
+        '--attention', '-a',
+        type=float,
+        default=30.0,
+        help='Seconds of silence before attention signal (default: 30)',
+    )
+    parser.add_argument(
+        '--reverse', '-r',
+        action='store_true',
+        help='Reverse mode: sound plays during silence, not during output',
+    )
+    parser.add_argument(
+        '--list-characters',
+        action='store_true',
+        help='List available sound characters',
+    )
+
+    args = parser.parse_args()
+
+    if args.list_characters:
+        print("Available sound characters:\n")
+        for name, mat in MATERIALS.items():
+            print(f"  {name:10} - {mat.description}")
+        return
+
+    if args.character:
+        material = get_material(args.character)
+    else:
+        material = get_random_material()
+
+    volume = max(0.0, min(1.0, args.volume))
+
+    engine = SoundEngine(material=material, volume=volume)
+    monitor = ActivityMonitor(
+        on_grain=engine.play_grain,
+        on_chime=engine.play_chime,
+        on_attention=engine.play_attention,
+        attention_seconds=args.attention,
+        reverse=args.reverse,
+    )
+
+    mode_label = " (reverse)" if args.reverse else ""
+    print(f"[claudible] {material.name}{mode_label} - {material.description}", file=sys.stderr)
+
+    if args.pipe:
+        run_pipe_mode(engine, monitor)
+    else:
+        run_wrap_mode(args.command, engine, monitor)
+
+
+if __name__ == '__main__':
+    main()

claudible/materials.py

@@ -0,0 +1,336 @@
+"""Material character presets for sound generation."""
+
+from dataclasses import dataclass, field
+from typing import List, Tuple
+import random
+
+
+@dataclass
+class Material:
+    """Defines the sonic character of a material.
+
+    Based on physical vibration properties of real materials.
+    """
+
+    name: str
+    base_freq: float  # centre frequency in Hz
+    partials: List[Tuple[float, float]]  # (ratio, amplitude) pairs
+    decay_rates: List[float]  # per-partial exponential decay (higher = faster)
+    grain_duration: float  # base grain duration in seconds
+    attack_noise: float  # 0-1, amount of noise transient on attack
+    noise_freq: float  # high-pass cutoff for noise transient in Hz
+    detune_amount: float  # cents of random micro-detuning per partial
+    reverb_amount: float  # 0-1 reverb wet amount
+    reverb_damping: float  # 0-1 high-frequency damping in reverb tails
+    room_size: float  # reverb room size multiplier
+    pitch_drop: float  # pitch envelope multiplier (<1 = drops, >1 = rises, 1 = flat)
+    attack_ms: float  # attack ramp time in milliseconds
+    freq_spread: float  # semitones of random base freq variation per grain
+    volume: float  # per-material volume scaling (0-1)
+    description: str
+
+
+MATERIALS = {
+    # --- Original materials (upgraded with physics parameters) ---
+
+    "ice": Material(
+        name="ice",
+        base_freq=2800,
+        partials=[(1.0, 1.0), (2.71, 0.7), (5.13, 0.5), (8.41, 0.3), (12.7, 0.15)],
+        decay_rates=[25, 40, 60, 80, 100],
+        grain_duration=0.035,
+        attack_noise=0.4,
+        noise_freq=5000,
+        detune_amount=8,
+        reverb_amount=0.2,
+        reverb_damping=0.3,
+        room_size=1.0,
+        pitch_drop=0.995,
+        attack_ms=0.5,
+        freq_spread=4.0,
+        volume=0.85,
+        description="Brittle, very high, fast decay with pitch drop",
+    ),
+
+    "glass": Material(
+        name="glass",
+        base_freq=1200,
+        partials=[(1.0, 1.0), (2.32, 0.6), (4.17, 0.35), (6.85, 0.15)],
+        decay_rates=[18, 28, 45, 65],
+        grain_duration=0.05,
+        attack_noise=0.35,
+        noise_freq=4000,
+        detune_amount=5,
+        reverb_amount=0.28,
+        reverb_damping=0.3,
+        room_size=1.0,
+        pitch_drop=1.0,
+        attack_ms=0.8,
+        freq_spread=3.0,
+        volume=0.9,
+        description="Classic wine glass ping",
+    ),
+
+    "crystal": Material(
+        name="crystal",
+        base_freq=1800,
+        partials=[(1.0, 1.0), (1.003, 0.9), (2.41, 0.5), (2.43, 0.45), (4.2, 0.2)],
+        decay_rates=[12, 13, 22, 24, 40],
+        grain_duration=0.07,
+        attack_noise=0.25,
+        noise_freq=3500,
+        detune_amount=3,
+        reverb_amount=0.35,
+        reverb_damping=0.25,
+        room_size=1.2,
+        pitch_drop=1.0,
+        attack_ms=1.0,
+        freq_spread=2.5,
+        volume=0.85,
+        description="Pure lead crystal with beating from close partial pairs",
+    ),
+
+    "ceramic": Material(
+        name="ceramic",
+        base_freq=600,
+        partials=[(1.0, 1.0), (2.15, 0.5), (3.87, 0.35), (5.21, 0.2), (7.43, 0.1)],
+        decay_rates=[30, 45, 60, 75, 90],
+        grain_duration=0.04,
+        attack_noise=0.5,
+        noise_freq=2500,
+        detune_amount=12,
+        reverb_amount=0.22,
+        reverb_damping=0.4,
+        room_size=0.9,
+        pitch_drop=0.998,
+        attack_ms=1.2,
+        freq_spread=3.5,
+        volume=1.0,
+        description="Duller muted earthenware tap",
+    ),
+
+    "bell": Material(
+        name="bell",
+        base_freq=900,
+        partials=[
+            (1.0, 1.0), (1.183, 0.8), (1.506, 0.6),
+            (2.0, 0.7), (2.514, 0.4), (3.011, 0.25),
+        ],
+        decay_rates=[10, 12, 15, 14, 20, 28],
+        grain_duration=0.08,
+        attack_noise=0.2,
+        noise_freq=3000,
+        detune_amount=6,
+        reverb_amount=0.4,
+        reverb_damping=0.2,
+        room_size=1.3,
+        pitch_drop=1.0,
+        attack_ms=0.3,
+        freq_spread=2.5,
+        volume=0.8,
+        description="Small metallic bell, classic ratios, long ring",
+    ),
+
+    "droplet": Material(
+        name="droplet",
+        base_freq=1400,
+        partials=[(1.0, 1.0), (2.8, 0.3), (5.2, 0.1)],
+        decay_rates=[35, 50, 70],
+        grain_duration=0.03,
+        attack_noise=0.15,
+        noise_freq=6000,
+        detune_amount=4,
+        reverb_amount=0.45,
+        reverb_damping=0.2,
+        room_size=1.0,
+        pitch_drop=0.92,
+        attack_ms=0.3,
+        freq_spread=4.0,
+        volume=0.8,
+        description="Water droplet, pitch bend down, liquid",
+    ),
+
+    "click": Material(
+        name="click",
+        base_freq=3500,
+        partials=[(1.0, 1.0), (2.5, 0.3)],
+        decay_rates=[40, 60],
+        grain_duration=0.02,
+        attack_noise=0.7,
+        noise_freq=7000,
+        detune_amount=15,
+        reverb_amount=0.1,
+        reverb_damping=0.5,
+        room_size=0.5,
+        pitch_drop=1.0,
+        attack_ms=0.2,
+        freq_spread=6.0,
+        volume=0.95,
+        description="Sharp mechanical click, keyboard-like",
+    ),
+
+    # --- New materials with distinct textures ---
+
+    "wood": Material(
+        name="wood",
+        base_freq=420,
+        partials=[
+            (1.0, 1.0), (2.0, 0.55), (3.0, 0.28),
+            (4.01, 0.12), (5.02, 0.05),
+        ],
+        decay_rates=[22, 32, 45, 55, 70],
+        grain_duration=0.04,
+        attack_noise=0.45,
+        noise_freq=2000,
+        detune_amount=8,
+        reverb_amount=0.18,
+        reverb_damping=0.55,
+        room_size=0.8,
+        pitch_drop=0.997,
+        attack_ms=0.6,
+        freq_spread=4.0,
+        volume=1.0,
+        description="Hollow wooden tap, warm marimba-like resonance",
+    ),
+
+    "stone": Material(
+        name="stone",
+        base_freq=280,
+        partials=[
+            (1.0, 1.0), (2.37, 0.5), (4.73, 0.25),
+            (7.11, 0.12), (9.89, 0.06),
+        ],
+        decay_rates=[35, 48, 60, 72, 85],
+        grain_duration=0.03,
+        attack_noise=0.6,
+        noise_freq=1800,
+        detune_amount=15,
+        reverb_amount=0.15,
+        reverb_damping=0.6,
+        room_size=0.7,
+        pitch_drop=0.994,
+        attack_ms=0.4,
+        freq_spread=5.0,
+        volume=1.0,
+        description="Dense slate tap, heavy and earthy",
+    ),
+
+    "bamboo": Material(
+        name="bamboo",
+        base_freq=680,
+        partials=[
+            (1.0, 1.0), (3.01, 0.5), (5.03, 0.25), (7.02, 0.1),
+        ],
+        decay_rates=[15, 24, 34, 45],
+        grain_duration=0.05,
+        attack_noise=0.3,
+        noise_freq=5000,
+        detune_amount=6,
+        reverb_amount=0.35,
+        reverb_damping=0.25,
+        room_size=1.1,
+        pitch_drop=1.0,
+        attack_ms=1.0,
+        freq_spread=3.5,
+        volume=0.85,
+        description="Hollow tube resonance, odd harmonics, breathy and airy",
+    ),
+
+    "ember": Material(
+        name="ember",
+        base_freq=350,
+        partials=[
+            (1.0, 1.0), (1.73, 0.6), (2.91, 0.35), (4.37, 0.15),
+        ],
+        decay_rates=[42, 55, 68, 80],
+        grain_duration=0.025,
+        attack_noise=0.7,
+        noise_freq=1500,
+        detune_amount=22,
+        reverb_amount=0.2,
+        reverb_damping=0.7,
+        room_size=0.6,
+        pitch_drop=0.98,
+        attack_ms=0.3,
+        freq_spread=8.0,
+        volume=0.9,
+        description="Warm crackling ember, fire-like with wide pitch scatter",
+    ),
+
+    "silk": Material(
+        name="silk",
+        base_freq=1800,
+        partials=[(1.0, 1.0), (2.01, 0.4), (3.5, 0.1)],
+        decay_rates=[22, 35, 50],
+        grain_duration=0.045,
+        attack_noise=0.55,
+        noise_freq=6500,
+        detune_amount=10,
+        reverb_amount=0.5,
+        reverb_damping=0.15,
+        room_size=1.4,
+        pitch_drop=1.0,
+        attack_ms=2.5,
+        freq_spread=5.0,
+        volume=0.6,
+        description="Soft breathy whisper, delicate airy texture",
+    ),
+
+    "shell": Material(
+        name="shell",
+        base_freq=750,
+        partials=[
+            (1.0, 1.0), (1.003, 0.9), (2.01, 0.6),
+            (2.016, 0.55), (3.02, 0.3), (3.028, 0.28),
+        ],
+        decay_rates=[8, 9, 14, 15, 22, 23],
+        grain_duration=0.07,
+        attack_noise=0.2,
+        noise_freq=3000,
+        detune_amount=4,
+        reverb_amount=0.6,
+        reverb_damping=0.2,
+        room_size=1.5,
+        pitch_drop=1.0,
+        attack_ms=1.5,
+        freq_spread=2.0,
+        volume=0.75,
+        description="Swirly ocean interference, dense phase beating",
+    ),
+
+    "moss": Material(
+        name="moss",
+        base_freq=220,
+        partials=[(1.0, 1.0), (2.1, 0.25), (3.3, 0.08)],
+        decay_rates=[28, 42, 58],
+        grain_duration=0.035,
+        attack_noise=0.15,
+        noise_freq=1200,
+        detune_amount=12,
+        reverb_amount=0.3,
+        reverb_damping=0.8,
+        room_size=0.5,
+        pitch_drop=0.996,
+        attack_ms=3.0,
+        freq_spread=4.0,
+        volume=0.7,
+        description="Ultra-soft muffled earth, mossy dampness",
+    ),
+}
+
+
+def get_material(name: str) -> Material:
+    """Get a material by name."""
+    if name not in MATERIALS:
+        raise ValueError(f"Unknown material: {name}. Available: {list(MATERIALS.keys())}")
+    return MATERIALS[name]
+
+
+def get_random_material() -> Material:
+    """Get a random material."""
+    return random.choice(list(MATERIALS.values()))
+
+
+def list_materials() -> List[str]:
+    """List all available material names."""
+    return list(MATERIALS.keys())

claudible/monitor.py

@@ -0,0 +1,119 @@
+"""I/O activity tracking and event detection."""
+
+import time
+from typing import Callable, Optional
+import threading
+
+
+class ActivityMonitor:
+    """Monitors text output and triggers audio events."""
+
+    MAX_GRAINS_PER_SEC = 30
+    NEWLINE_THRESHOLD = 3  # Consecutive newlines to trigger completion chime
+
+    # Reverse mode: ambient grain rate when idle
+    REVERSE_GRAINS_PER_SEC = 12
+    REVERSE_IDLE_DELAY = 3.0  # Seconds of silence before ambient grains start
+
+    def __init__(
+        self,
+        on_grain: Callable[[], None],
+        on_chime: Callable[[], None],
+        on_attention: Callable[[], None],
+        attention_seconds: float = 30.0,
+        reverse: bool = False,
+    ):
+        self.on_grain = on_grain
+        self.on_chime = on_chime
+        self.on_attention = on_attention
+        self.attention_seconds = attention_seconds
+        self.reverse = reverse
+
+        self._last_grain_time = 0.0
+        self._min_grain_interval = 1.0 / self.MAX_GRAINS_PER_SEC
+        self._consecutive_newlines = 0
+        self._last_activity_time = time.time()
+        self._attention_triggered = False
+        self._running = False
+        self._bg_thread: Optional[threading.Thread] = None
+        self._lock = threading.Lock()
+
+        # Reverse mode state
+        self._reverse_playing = False
+        self._was_active = False
+
+    def start(self):
+        """Start monitoring."""
+        self._running = True
+        self._last_activity_time = time.time()
+        self._bg_thread = threading.Thread(target=self._background_loop, daemon=True)
+        self._bg_thread.start()
+
+    def stop(self):
+        """Stop monitoring."""
+        self._running = False
+        if self._bg_thread:
+            self._bg_thread.join(timeout=1.0)
+
+    def _background_loop(self):
+        """Background thread for attention signals and reverse-mode ambient grains."""
+        reverse_interval = 1.0 / self.REVERSE_GRAINS_PER_SEC
+
+        while self._running:
+            if self.reverse:
+                with self._lock:
+                    elapsed = time.time() - self._last_activity_time
+
+                if elapsed >= self.REVERSE_IDLE_DELAY:
+                    if not self._reverse_playing:
+                        self._reverse_playing = True
+                        self.on_chime()
+                    self.on_grain()
+                    time.sleep(reverse_interval)
+                else:
+                    if self._reverse_playing:
+                        self._reverse_playing = False
+                    time.sleep(0.1)
+            else:
+                time.sleep(1.0)
+                with self._lock:
+                    elapsed = time.time() - self._last_activity_time
+                    if elapsed >= self.attention_seconds and not self._attention_triggered:
+                        self._attention_triggered = True
+                        self.on_attention()
+
+    def process_chunk(self, data: bytes):
+        """Process a chunk of output data."""
+        if not data:
+            return
+
+        with self._lock:
+            self._last_activity_time = time.time()
+            self._attention_triggered = False
+
+        if self.reverse:
+            # In reverse mode, activity = silence. Just update the timestamp.
+            return
+
+        # Normal mode: trigger sounds on output
+        try:
+            text = data.decode('utf-8', errors='replace')
+        except Exception:
+            text = str(data)
+
+        for char in text:
+            if char == '\n':
+                self._consecutive_newlines += 1
+                if self._consecutive_newlines >= self.NEWLINE_THRESHOLD:
+                    self.on_chime()
+                    self._consecutive_newlines = 0
+            else:
+                self._consecutive_newlines = 0
+                self._maybe_trigger_grain()
+
+    def _maybe_trigger_grain(self):
+        """Trigger a grain if enough time has passed (throttling)."""
+        now = time.time()
+        if now - self._last_grain_time >= self._min_grain_interval:
+            self._last_grain_time = now
+            self.on_grain()

claudible-0.1.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: claudible
+Version: 0.1.0
+Summary: Ambient audio soundscape feedback for terminal output - an opus for your terminals
+License: MIT
+Project-URL: Homepage, https://github.com/qwertykeith/claudible
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: sounddevice>=0.4.0
+
+# claudible
+
+*An opus for your terminals.*
+
+Possibly the most annoying Claude utility ever made but here it is anyway. Ambient audio soundscape feedback for terminal output.
+
+## The Idea
+
+Imagine you are working in a factory. Each Claude Code session is a machine that must be attended to. When it's working, you hear it - crystalline sparkles as text flows, soft chimes when tasks complete. When it goes quiet, you know something needs your attention.
+
+## Installation
+
+```bash
+pip install claudible
+```
+
+## Usage
+
+```bash
+# Run claude with audio feedback (default)
+claudible
+
+# Run a different command
+claudible "python my_script.py"
+
+# Pipe mode
+some-command 2>&1 | claudible --pipe
+
+# Choose a sound character
+claudible --character crystal
+
+# Adjust volume
+claudible --volume 0.3
+
+# List available characters
+claudible --list-characters
+```
+
+### Reverse Mode
+
+In reverse mode, claudible is silent while output is flowing and plays ambient sound during silence. Useful when you want to know a task is *waiting* rather than *working*.
+
+```bash
+# Ambient grains play when Claude is idle/waiting for you
+claudible --reverse
+
+# Combine with a character
+claudible --reverse -c shell
+```
+
+## Works With Any CLI
+
+Built for Claude Code, but claudible works with anything that produces terminal output.
+
+```bash
+# Aider
+claudible "aider"
+
+# Watch a dev server
+npm run dev 2>&1 | claudible --pipe
+
+# Monitor logs
+tail -f /var/log/app.log | claudible --pipe -c droplet
+```
+
+## Sound Characters
+
+| Character | Description |
+|-----------|-------------|
+| `ice` | Brittle, very high, fast decay with pitch drop |
+| `glass` | Classic wine glass ping |
+| `crystal` | Pure lead crystal with beating from close partial pairs |
+| `ceramic` | Duller muted earthenware tap |
+| `bell` | Small metallic bell, classic ratios, long ring |
+| `droplet` | Water droplet, pitch bend down, liquid |
+| `click` | Sharp mechanical click, keyboard-like |
+| `wood` | Hollow wooden tap, warm marimba-like resonance |
+| `stone` | Dense slate tap, heavy and earthy |
+| `bamboo` | Hollow tube resonance, odd harmonics, breathy and airy |
+| `ember` | Warm crackling ember, fire-like with wide pitch scatter |
+| `silk` | Soft breathy whisper, delicate airy texture |
+| `shell` | Swirly ocean interference, dense phase beating |
+| `moss` | Ultra-soft muffled earth, mossy dampness |
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--pipe` | Read from stdin instead of wrapping |
+| `--character`, `-c` | Sound character |
+| `--volume`, `-v` | Volume 0.0-1.0 (default: 0.5) |
+| `--attention`, `-a` | Silence alert seconds (default: 30) |
+| `--reverse`, `-r` | Reverse mode: sound during silence, quiet during output |
+| `--list-characters` | Show presets |
+
+## Development
+
+Test locally without installing:
+
+```bash
+cd claudible
+
+# Run wrapping claude (Ctrl+C to stop)
+PYTHONPATH=src python3 -m claudible
+
+# Wrap a different command
+PYTHONPATH=src python3 -m claudible "ls -la"
+
+# Pipe mode
+echo "test" | PYTHONPATH=src python3 -m claudible --pipe -c glass
+
+# List characters
+PYTHONPATH=src python3 -m claudible --list-characters
+```
+
+## License
+
+MIT

claudible-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+claudible/__init__.py,sha256=xSLL4yfc1p79BWVb65PJBTFMxyJ2PWuu7pCLYcCuOVM,96
+claudible/__main__.py,sha256=5mFnPjtOjk5Hw-mvUhRYtwXVnXFR7ZbXKC27VIXu_dI,106
+claudible/audio.py,sha256=6Do7_g5SUfJkMGSH_c_XGG4YiC2uakhaDTy8xYAp7rE,12043
+claudible/cli.py,sha256=j14ZnHT7L_efA67U-3hLSqUsgf2rvlMYgs1b6w3X2pU,4803
+claudible/materials.py,sha256=6OsobcWOFvLBCuvzkeWi9C7fYHFnW9RED6nEElK-Ki4,9517
+claudible/monitor.py,sha256=iPCaqdO-CDp1CoIie2VtddUUjG1A_xucbFJ1DPk3MKk,4070
+claudible-0.1.0.dist-info/METADATA,sha256=HXc1eXgzZECcs0cx7ZCWj4-m7Lz5aOUP2t002GZd4oI,4100
+claudible-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+claudible-0.1.0.dist-info/entry_points.txt,sha256=4tBIsIGcdtJ-1N9YZ3MrADyNvPBDcUxVgAnt9IuC7TA,49
+claudible-0.1.0.dist-info/top_level.txt,sha256=4ZB16Aa5ZDS12bmxzrQmAJejjsTgQ9Yozwc0Z3qpJp4,10
+claudible-0.1.0.dist-info/RECORD,,

claudible-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

claudible-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+claudible = claudible.cli:main

claudible-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+claudible