claudible 0.1.1__tar.gz → 0.1.3__tar.gz

claudible-0.1.3/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: claudible
+Version: 0.1.3
+Summary: Ambient audio soundscape feedback for terminal output - an opus for your terminals
+License: MIT
+Project-URL: Homepage, https://github.com/anthropics/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
+
+```
+        ♪ ♫ ♪
+      ┌─────────┐
+      │ ╭─────╮ │ ♩
+      │ │ ▓▓▓ │ │
+      │ │ ▓▓▓ │ │  ♬    ┈┈┈╮
+      │ ╰─────╯ │     ♪    │
+      │  claude  │ ♫       │
+      └────┬────┘    ♩    ≋≋≋
+     ══════╧══════       ≋≋≋≋≋
+      ♪  audible  ♫       ≋≋≋
+```
+
+# 🎵 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
+# Recommended (handles PATH automatically)
+brew install pipx && pipx ensurepath  # macOS
+# or: pip install --user pipx && pipx ensurepath
+
+pipx install claudible
+
+# Or with pip
+pip install claudible
+```
+
+> **`claudible` command not found?** If you used `pip install --user`, the script directory may not be on your PATH. Use `python3 -m claudible` instead, or switch to `pipx`.
+
+## 🎹 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
+
+# Demo all sound characters
+claudible --demo
+```
+
+### 🔇 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 |
+| `--demo` | 🔊 Play a short demo of each sound character |
+
+## 🛠️ 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
+
+# Demo all characters
+PYTHONPATH=src python3 -m claudible --demo
+```
+
+## 📜 License
+
+MIT

claudible-0.1.3/README.md

@@ -0,0 +1,147 @@
+```
+        ♪ ♫ ♪
+      ┌─────────┐
+      │ ╭─────╮ │ ♩
+      │ │ ▓▓▓ │ │
+      │ │ ▓▓▓ │ │  ♬    ┈┈┈╮
+      │ ╰─────╯ │     ♪    │
+      │  claude  │ ♫       │
+      └────┬────┘    ♩    ≋≋≋
+     ══════╧══════       ≋≋≋≋≋
+      ♪  audible  ♫       ≋≋≋
+```
+
+# 🎵 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
+# Recommended (handles PATH automatically)
+brew install pipx && pipx ensurepath  # macOS
+# or: pip install --user pipx && pipx ensurepath
+
+pipx install claudible
+
+# Or with pip
+pip install claudible
+```
+
+> **`claudible` command not found?** If you used `pip install --user`, the script directory may not be on your PATH. Use `python3 -m claudible` instead, or switch to `pipx`.
+
+## 🎹 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
+
+# Demo all sound characters
+claudible --demo
+```
+
+### 🔇 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 |
+| `--demo` | 🔊 Play a short demo of each sound character |
+
+## 🛠️ 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
+
+# Demo all characters
+PYTHONPATH=src python3 -m claudible --demo
+```
+
+## 📜 License
+
+MIT

{claudible-0.1.1 → claudible-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "claudible"
-version = "0.1.1"
+version = "0.1.3"
 description = "Ambient audio soundscape feedback for terminal output - an opus for your terminals"
 readme = "README.md"
 license = {text = "MIT"}

{claudible-0.1.1 → claudible-0.1.3}/src/claudible/audio.py

@@ -33,8 +33,8 @@ class SoundEngine:
         self._write_pos = 0
         self._read_pos = 0
 
-        # Pre-generate grain variations for efficiency
-        self._grain_cache = [self._generate_grain() for _ in range(8)]
+        # Pre-generate grains spread across registers for tonal variety
+        self._grain_cache = self._build_grain_cache()
         self._cache_index = 0
 
     def start(self):
@@ -141,77 +141,147 @@ class SoundEngine:
 
     # --- Sound generation ---
 
-    def _generate_grain(self) -> np.ndarray:
+    def _build_grain_cache(self) -> list:
+        """Build grain cache with voices at full-octave intervals, biased low + high."""
+        # Each register is a full octave apart.
+        # (octave_shift, noise_mult, decay_mult, duration_mult)
+        # Multiple character variations per register.
+        voices = [
+            # --- oct -3: sub rumble (3 voices) ---
+            (-3, 3.5, 2.5, 1.8),   # sub thump
+            (-3, 2.0, 3.0, 2.0),   # sub knock
+            (-3, 2.8, 2.0, 1.6),   # sub punch
+
+            # --- oct -2: deep (3 voices) ---
+            (-2, 2.8, 1.8, 1.5),   # deep percussive
+            (-2, 1.2, 2.0, 1.4),   # deep tonal
+            (-2, 2.0, 1.5, 1.3),   # deep knock
+
+            # --- oct -1: low (3 voices) ---
+            (-1, 1.8, 1.4, 1.2),   # low thump
+            (-1, 0.8, 1.2, 1.1),   # low warm
+            (-1, 1.4, 1.6, 1.2),   # low snap
+
+            # --- oct 0: mid (2 voices) ---
+            ( 0, 1.0, 1.0, 1.0),   # mid click
+            ( 0, 0.6, 0.8, 0.9),   # mid soft
+
+            # --- oct +1: high (3 voices) ---
+            ( 1, 0.5, 0.6, 0.7),   # high ping
+            ( 1, 0.8, 0.5, 0.7),   # high tick
+            ( 1, 0.3, 0.7, 0.8),   # high ring
+
+            # --- oct +2: bright (3 voices) ---
+            ( 2, 0.2, 0.4, 0.55),  # bright ting
+            ( 2, 0.5, 0.3, 0.6),   # bright click
+            ( 2, 0.15, 0.5, 0.5),  # bright shimmer
+
+            # --- oct +3: air (3 voices) ---
+            ( 3, 0.1, 0.25, 0.4),  # air sparkle
+            ( 3, 0.3, 0.2, 0.45),  # air tick
+            ( 3, 0.05, 0.3, 0.35), # air wisp
+        ]
+        cache = []
+        for octave, noise_m, decay_m, dur_m in voices:
+            cache.append(self._generate_grain(
+                octave_shift=octave,
+                noise_mult=noise_m,
+                decay_mult=decay_m,
+                duration_mult=dur_m,
+            ))
+        return cache
+
+    def _generate_grain(self, octave_shift: float = 0.0, noise_mult: float = 1.0,
+                        decay_mult: float = 1.0, duration_mult: float = 1.0) -> 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)
+        duration = m.grain_duration * duration_mult * 0.5 * 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))
+        # Base frequency shifted by register
+        base_freq = m.base_freq * (2 ** octave_shift)
+        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]
+            decay_rate *= decay_mult
             envelope = np.exp(-decay_rate * t)
 
             grain += amp * envelope * np.sin(2 * np.pi * freq * t + phase)
 
-        # Noise transient (the "tick" of physical impact)
+        # Noise transient — louder for low percussive grains
         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_cutoff = max(m.noise_freq * (0.5 if octave_shift < -0.5 else 1.0), 200)
+            noise = self._highpass(noise, noise_cutoff)
+            noise_env = np.exp(-150 * t / max(decay_mult, 0.5))
             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
+            grain += m.attack_noise * noise_mult * 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)
+        # Pitch drop — more dramatic for low grains
+        pitch_drop = m.pitch_drop if octave_shift >= 0 else m.pitch_drop ** (1.0 + abs(octave_shift) * 0.3)
+        if pitch_drop != 1.0:
+            pitch_env = np.linspace(1.0, 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)
+        # Reverb — less for percussive lows (tighter), more for highs
+        reverb_amt = m.reverb_amount * (0.6 if octave_shift < -0.5 else 1.0 + max(octave_shift, 0) * 0.2)
+        grain = self._apply_reverb(grain, reverb_amt, m.room_size, m.reverb_damping)
 
-        # Truncate reverb tail back to grain length
-        grain = grain[:n]
+        # Small pre-delay + extra tail reverb
+        delay_ms = 15
+        delay_samples = int(delay_ms * self.SAMPLE_RATE / 1000)
+        tail_len = n + delay_samples + int(0.08 * self.SAMPLE_RATE)
+        out = np.zeros(tail_len, dtype=np.float32)
+        out[delay_samples:delay_samples + len(grain)] = grain
+        # Light tail reverb on top
+        out = self._apply_reverb(out, 0.15, room_size=1.2, damping=0.4)
 
-        # Normalise with per-material volume
-        peak = np.max(np.abs(grain))
+        peak = np.max(np.abs(out))
         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))
+            out = out / peak * 0.4 * m.volume
+
+        return out.astype(np.float32)
+
+    @staticmethod
+    def _token_hash(token: str) -> int:
+        """Deterministic hash from token content, stable across sessions."""
+        h = 5381
+        for c in token:
+            h = ((h * 33) ^ ord(c)) & 0xFFFFFFFF
+        return h
+
+    def play_grain(self, token: str = ""):
+        """Play a grain/sparkle sound, deterministic for a given token."""
+        if token:
+            h = self._token_hash(token)
+            rng = np.random.RandomState(h)
+        else:
+            rng = np.random
+
+        idx = rng.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)
+        # Narrow pitch micro-variation (±1.5 semitones) — stays in its register
+        pitch_shift = 2 ** (rng.uniform(-1.5, 1.5) / 12)
         if abs(pitch_shift - 1.0) > 0.001:
             new_len = int(len(grain) / pitch_shift)
             if new_len > 0:
@@ -221,12 +291,7 @@ class SoundEngine:
                     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()
+        grain *= rng.uniform(0.7, 1.0)
 
         self._add_to_buffer(grain)
 

{claudible-0.1.1 → claudible-0.1.3}/src/claudible/cli.py

@@ -14,6 +14,24 @@ from .materials import get_material, get_random_material, list_materials, MATERI
 from .monitor import ActivityMonitor
 
 
+def run_demo(volume: float):
+    """Play a short demo of every sound character."""
+    print("Claudible character demo\n", file=sys.stderr)
+    for name, mat in MATERIALS.items():
+        print(f"  {name:10} - {mat.description}", file=sys.stderr)
+        engine = SoundEngine(material=mat, volume=volume)
+        engine.start()
+        # Play a burst of grains then a chime
+        for i in range(8):
+            engine.play_grain(chr(ord('a') + i))
+            time.sleep(0.06)
+        time.sleep(0.15)
+        engine.play_chime()
+        time.sleep(0.6)
+        engine.stop()
+    print("\nDone.", file=sys.stderr)
+
+
 def run_pipe_mode(engine: SoundEngine, monitor: ActivityMonitor):
     """Run in pipe mode, reading from stdin."""
     engine.start()
@@ -138,6 +156,11 @@ def main():
         action='store_true',
         help='List available sound characters',
     )
+    parser.add_argument(
+        '--demo',
+        action='store_true',
+        help='Play a short demo of each sound character',
+    )
 
     args = parser.parse_args()
 
@@ -147,6 +170,11 @@ def main():
             print(f"  {name:10} - {mat.description}")
         return
 
+    if args.demo:
+        volume = max(0.0, min(1.0, args.volume))
+        run_demo(volume)
+        return
+
     if args.character:
         material = get_material(args.character)
     else:

{claudible-0.1.1 → claudible-0.1.3}/src/claudible/monitor.py

@@ -1,7 +1,7 @@
 """I/O activity tracking and event detection."""
 
 import time
-from typing import Callable, Optional
+from typing import Callable, Optional, Union
 import threading
 
 
@@ -17,7 +17,7 @@ class ActivityMonitor:
 
     def __init__(
         self,
-        on_grain: Callable[[], None],
+        on_grain: Callable[[str], None],
         on_chime: Callable[[], None],
         on_attention: Callable[[], None],
         attention_seconds: float = 30.0,
@@ -68,7 +68,7 @@ class ActivityMonitor:
                     if not self._reverse_playing:
                         self._reverse_playing = True
                         self.on_chime()
-                    self.on_grain()
+                    self.on_grain("")
                     time.sleep(reverse_interval)
                 else:
                     if self._reverse_playing:
@@ -109,11 +109,11 @@ class ActivityMonitor:
                     self._consecutive_newlines = 0
             else:
                 self._consecutive_newlines = 0
-                self._maybe_trigger_grain()
+                self._maybe_trigger_grain(char)
 
-    def _maybe_trigger_grain(self):
+    def _maybe_trigger_grain(self, char: str = ""):
         """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()
+            self.on_grain(char)

claudible-0.1.3/src/claudible.egg-info/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: claudible
+Version: 0.1.3
+Summary: Ambient audio soundscape feedback for terminal output - an opus for your terminals
+License: MIT
+Project-URL: Homepage, https://github.com/anthropics/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
+
+```
+        ♪ ♫ ♪
+      ┌─────────┐
+      │ ╭─────╮ │ ♩
+      │ │ ▓▓▓ │ │
+      │ │ ▓▓▓ │ │  ♬    ┈┈┈╮
+      │ ╰─────╯ │     ♪    │
+      │  claude  │ ♫       │
+      └────┬────┘    ♩    ≋≋≋
+     ══════╧══════       ≋≋≋≋≋
+      ♪  audible  ♫       ≋≋≋
+```
+
+# 🎵 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
+# Recommended (handles PATH automatically)
+brew install pipx && pipx ensurepath  # macOS
+# or: pip install --user pipx && pipx ensurepath
+
+pipx install claudible
+
+# Or with pip
+pip install claudible
+```
+
+> **`claudible` command not found?** If you used `pip install --user`, the script directory may not be on your PATH. Use `python3 -m claudible` instead, or switch to `pipx`.
+
+## 🎹 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
+
+# Demo all sound characters
+claudible --demo
+```
+
+### 🔇 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 |
+| `--demo` | 🔊 Play a short demo of each sound character |
+
+## 🛠️ 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
+
+# Demo all characters
+PYTHONPATH=src python3 -m claudible --demo
+```
+
+## 📜 License
+
+MIT

claudible-0.1.1/PKG-INFO

@@ -1,143 +0,0 @@
-Metadata-Version: 2.4
-Name: claudible
-Version: 0.1.1
-Summary: Ambient audio soundscape feedback for terminal output - an opus for your terminals
-License: MIT
-Project-URL: Homepage, https://github.com/anthropics/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.1/README.md

@@ -1,118 +0,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.1/src/claudible.egg-info/PKG-INFO

@@ -1,143 +0,0 @@
-Metadata-Version: 2.4
-Name: claudible
-Version: 0.1.1
-Summary: Ambient audio soundscape feedback for terminal output - an opus for your terminals
-License: MIT
-Project-URL: Homepage, https://github.com/anthropics/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