vocalis 0.1.0__py3-none-any.whl

vocalis/__init__.py

@@ -0,0 +1,6 @@
+"""Vocalis: Wispr Flow-inspired AI voice dictation CLI."""
+
+from vocalis.cli import cli, main
+
+__version__ = "0.1.0"
+__all__ = ["cli", "main", "__version__"]

vocalis/audio/__init__.py

@@ -0,0 +1,7 @@
+"""Audio recording, processing, and sound effects module."""
+
+from vocalis.audio.chime import ChimePlayer
+from vocalis.audio.recorder import AudioRecorder
+from vocalis.audio.vad import SpeechState, VADDetector
+
+__all__ = ["AudioRecorder", "ChimePlayer", "SpeechState", "VADDetector"]

vocalis/audio/chime.py

@@ -0,0 +1,77 @@
+"""Non-blocking audio cues and earcons for Vocalis."""
+
+from __future__ import annotations
+
+import io
+import shutil
+import subprocess
+import threading
+from typing import Optional
+
+import numpy as np
+from scipy.io import wavfile
+
+
+class ChimePlayer:
+    """Generates and plays lightweight audio chimes for voice state transitions."""
+
+    def __init__(self, enabled: bool = True) -> None:
+        self.enabled = enabled
+        self._start_wav: Optional[bytes] = None
+        self._done_wav: Optional[bytes] = None
+        if self.enabled:
+            self._prepare_chimes()
+
+    def _generate_tone(self, freq: float, duration: float, volume: float = 0.12) -> bytes:
+        """Synthesize a soft sine wave chime with smooth cosine envelope."""
+        sample_rate = 16000
+        num_samples = int(sample_rate * duration)
+        t = np.linspace(0, duration, num_samples, endpoint=False)
+
+        # Smooth bell envelope (raised cosine) to eliminate clicks
+        envelope = np.sin(np.pi * t / duration)
+        signal = (envelope * volume * np.sin(2 * np.pi * freq * t) * 32767.0).astype(np.int16)
+
+        buf = io.BytesIO()
+        wavfile.write(buf, sample_rate, signal)
+        return buf.getvalue()
+
+    def _prepare_chimes(self) -> None:
+        """Pre-generate in-memory WAV bytes so playback has zero computational latency."""
+        try:
+            # Start chime: Pleasant high A5 (880 Hz, 35ms)
+            self._start_wav = self._generate_tone(880.0, 0.035, volume=0.10)
+            # Done chime: Bright C6 (1046.5 Hz, 45ms)
+            self._done_wav = self._generate_tone(1046.5, 0.045, volume=0.10)
+        except Exception:
+            self.enabled = False
+
+    def _play_raw(self, wav_bytes: Optional[bytes]) -> None:
+        """Play WAV audio in a subprocess without blocking the main thread."""
+        if not self.enabled or not wav_bytes:
+            return
+
+        def worker():
+            for cmd in (["aplay", "-q"], ["pw-play", "-"]):
+                if shutil.which(cmd[0]):
+                    try:
+                        proc = subprocess.Popen(
+                            cmd,
+                            stdin=subprocess.PIPE,
+                            stdout=subprocess.DEVNULL,
+                            stderr=subprocess.DEVNULL,
+                        )
+                        proc.communicate(input=wav_bytes, timeout=0.6)
+                        return
+                    except Exception:
+                        continue
+
+        threading.Thread(target=worker, daemon=True).start()
+
+    def play_start(self) -> None:
+        """Play cue when speech starts."""
+        self._play_raw(self._start_wav)
+
+    def play_done(self) -> None:
+        """Play cue when processing completes and text is typed."""
+        self._play_raw(self._done_wav)

vocalis/audio/recorder.py

@@ -0,0 +1,169 @@
+"""Audio recording using native system sound interfaces."""
+
+from __future__ import annotations
+
+import collections
+import io
+import sys
+import threading
+from typing import Callable, Optional
+
+import numpy as np
+from scipy.io import wavfile
+
+# Guard against soundcard's sys.argv inspection in unusual environments
+if not hasattr(sys, "argv") or len(sys.argv) < 2:
+    if not hasattr(sys, "argv"):
+        sys.argv = ["vocalis"]
+    elif len(sys.argv) == 1 and sys.argv[0] == "-c":
+        sys.argv.append("vocalis")
+
+import soundcard as sc
+
+from vocalis.audio.vad import SpeechState, VADDetector
+
+
+class AudioRecorder:
+    """Manages microphone input capture and voice activity listening."""
+
+    def __init__(
+        self,
+        sample_rate: int = 16000,
+        device_name: Optional[str] = None,
+        block_size: int = 1600,  # 100ms at 16kHz
+        silence_duration: float = 0.9,
+        energy_threshold: float = 0.012,
+    ) -> None:
+        self.sample_rate = sample_rate
+        self.device_name = device_name
+        self.block_size = block_size
+        self.silence_duration = silence_duration
+        self.energy_threshold = energy_threshold
+
+    @staticmethod
+    def list_devices() -> list[str]:
+        """List all available microphone device names."""
+        try:
+            mics = sc.all_microphones()
+            return [m.name for m in mics]
+        except Exception:
+            return []
+
+    def get_microphone(self) -> sc.Microphone:
+        """Get the configured or default microphone."""
+        if self.device_name:
+            for mic in sc.all_microphones():
+                if self.device_name.lower() in mic.name.lower():
+                    return mic
+        return sc.default_microphone()
+
+    @staticmethod
+    def to_mono(audio_chunk: np.ndarray) -> np.ndarray:
+        """Convert multi-channel audio to mono 1D array."""
+        if audio_chunk.ndim > 1:
+            if audio_chunk.shape[1] > 1:
+                return np.mean(audio_chunk, axis=1)
+            return audio_chunk[:, 0]
+        return audio_chunk
+
+    @classmethod
+    def to_wav_bytes(cls, audio_data: np.ndarray, sample_rate: int = 16000) -> bytes:
+        """Convert float32/int16 numpy audio to in-memory WAV file bytes."""
+        audio_mono = cls.to_mono(audio_data)
+
+        # Normalize and convert float32 to 16-bit PCM for universal speech API compatibility
+        if audio_mono.dtype != np.int16:
+            # Clip between -1.0 and 1.0, scale to int16 range
+            clipped = np.clip(audio_mono, -1.0, 1.0)
+            pcm16 = (clipped * 32767.0).astype(np.int16)
+        else:
+            pcm16 = audio_mono
+
+        buf = io.BytesIO()
+        wavfile.write(buf, sample_rate, pcm16)
+        return buf.getvalue()
+
+    def record_utterance(
+        self,
+        on_chunk: Optional[Callable[[SpeechState, float, float], None]] = None,
+        on_speech_started: Optional[Callable[[], None]] = None,
+        stop_event: Optional[threading.Event] = None,
+        manual_mode: bool = False,
+    ) -> tuple[np.ndarray, float, bool]:
+        """Record until speech ends (VAD) or stop_event is set.
+
+        Args:
+            on_chunk: Callback(state, rms, elapsed_sec) called every 100ms.
+            on_speech_started: Callback called once when voice activity begins.
+            stop_event: Threading event to externally signal stop.
+            manual_mode: If True, only stop_event or timeout terminates recording.
+
+        Returns:
+            Tuple of (recorded_mono_numpy_array, duration_seconds, speech_started)
+        """
+        mic = self.get_microphone()
+        vad = VADDetector(
+            sample_rate=self.sample_rate,
+            energy_threshold=self.energy_threshold,
+            silence_duration=self.silence_duration,
+        )
+
+        # Pre-roll ring buffer: store last ~400ms before speech detected
+        # so initial consonants are preserved perfectly
+        preroll_count = 4
+        preroll_buffer: collections.deque[np.ndarray] = collections.deque(maxlen=preroll_count)
+
+        recorded_chunks: list[np.ndarray] = []
+        speech_started = False
+        start_time: float | None = None
+
+        with mic.recorder(samplerate=self.sample_rate, channels=1, blocksize=self.block_size) as rec:
+            import time
+
+            start_time = time.time()
+            while True:
+                if stop_event and stop_event.is_set():
+                    break
+
+                # Read 100ms audio chunk
+                raw_chunk = rec.record(numframes=self.block_size)
+                mono_chunk = self.to_mono(raw_chunk)
+
+                if manual_mode:
+                    if not speech_started:
+                        speech_started = True
+                        if on_speech_started:
+                            on_speech_started()
+                    recorded_chunks.append(mono_chunk)
+                    rms = vad.calculate_rms(mono_chunk)
+                    elapsed = time.time() - start_time
+                    if on_chunk:
+                        on_chunk(SpeechState.SPEAKING, rms, elapsed)
+                    continue
+
+                state, rms = vad.process_chunk(mono_chunk)
+                elapsed = time.time() - start_time
+
+                if state in (SpeechState.SPEAKING, SpeechState.PAUSED):
+                    if not speech_started:
+                        speech_started = True
+                        if on_speech_started:
+                            on_speech_started()
+                        # Include pre-roll chunks
+                        recorded_chunks.extend(list(preroll_buffer))
+                    recorded_chunks.append(mono_chunk)
+                elif not speech_started:
+                    preroll_buffer.append(mono_chunk)
+
+                if on_chunk:
+                    on_chunk(state, rms, elapsed)
+
+                if state in (SpeechState.COMPLETED, SpeechState.TIMEOUT):
+                    break
+
+        if not recorded_chunks:
+            return np.array([], dtype=np.float32), 0.0, speech_started
+
+        full_audio = np.concatenate(recorded_chunks, axis=0)
+        duration = len(full_audio) / self.sample_rate
+        return full_audio, duration, speech_started

vocalis/audio/vad.py

@@ -0,0 +1,112 @@
+"""Voice Activity Detection and energy analysis."""
+
+from __future__ import annotations
+
+import enum
+import time
+import numpy as np
+
+
+class SpeechState(str, enum.Enum):
+    """Current state of voice activity."""
+    IDLE = "idle"                        # Waiting for initial speech
+    SPEAKING = "speaking"                # Speech in progress
+    PAUSED = "paused"                    # Speech occurred, currently silent (counting down timeout)
+    COMPLETED = "completed"              # Silence duration reached after speech
+    TIMEOUT = "timeout"                  # Max duration reached
+
+
+class VADDetector:
+    """Energy-based voice activity detector with adaptive noise floor and silence hangover."""
+
+    def __init__(
+        self,
+        sample_rate: int = 16000,
+        energy_threshold: float = 0.012,
+        silence_duration: float = 0.9,
+        min_record_seconds: float = 0.4,
+        max_record_seconds: float = 90.0,
+    ) -> None:
+        self.sample_rate = sample_rate
+        self.base_threshold = energy_threshold
+        self.silence_duration = silence_duration
+        self.min_record_seconds = min_record_seconds
+        self.max_record_seconds = max_record_seconds
+
+        self.state = SpeechState.IDLE
+        self.noise_floor = 0.005
+        self.speech_start_time: float | None = None
+        self.silence_start_time: float | None = None
+        self.total_speech_frames: int = 0
+        self.calibration_chunks: int = 0
+
+    @staticmethod
+    def calculate_rms(audio_chunk: np.ndarray) -> float:
+        """Calculate Root Mean Square (RMS) energy of an audio chunk."""
+        if audio_chunk.size == 0:
+            return 0.0
+        # If stereo, flatten or take mean across channels
+        if audio_chunk.ndim > 1:
+            audio_chunk = np.mean(audio_chunk, axis=1)
+        return float(np.sqrt(np.mean(audio_chunk.astype(np.float32) ** 2)))
+
+    def get_effective_threshold(self) -> float:
+        """Dynamic threshold based on base setting and tracked noise floor."""
+        return max(self.base_threshold, self.noise_floor * 2.5)
+
+    def process_chunk(self, audio_chunk: np.ndarray) -> tuple[SpeechState, float]:
+        """Process an incoming audio chunk (e.g. 100ms) and return (new_state, rms)."""
+        rms = self.calculate_rms(audio_chunk)
+        now = time.time()
+
+        # Initial calibration of ambient noise floor (first 4 chunks)
+        if self.calibration_chunks < 4:
+            self.noise_floor = (self.noise_floor * self.calibration_chunks + rms) / (self.calibration_chunks + 1)
+            self.calibration_chunks += 1
+            return SpeechState.IDLE, rms
+
+        effective_threshold = self.get_effective_threshold()
+        is_speech = rms >= effective_threshold
+
+        # Adapt ambient noise floor slowly if not speaking
+        if not is_speech and self.state == SpeechState.IDLE:
+            self.noise_floor = 0.95 * self.noise_floor + 0.05 * rms
+
+        if is_speech:
+            if self.state in (SpeechState.IDLE, SpeechState.PAUSED):
+                if self.speech_start_time is None:
+                    self.speech_start_time = now
+                self.silence_start_time = None
+                self.state = SpeechState.SPEAKING
+            self.total_speech_frames += len(audio_chunk)
+
+        else:
+            # Silence detected
+            if self.state == SpeechState.SPEAKING:
+                self.state = SpeechState.PAUSED
+                self.silence_start_time = now
+
+            elif self.state == SpeechState.PAUSED and self.silence_start_time is not None:
+                elapsed_silence = now - self.silence_start_time
+                speech_duration = (self.total_speech_frames / self.sample_rate)
+
+                # Check if we have spoken enough and silence exceeded threshold
+                if elapsed_silence >= self.silence_duration:
+                    if speech_duration >= self.min_record_seconds:
+                        self.state = SpeechState.COMPLETED
+                    else:
+                        # Spurious noise, reset
+                        self.reset()
+
+        # Check max recording duration
+        if self.speech_start_time and (now - self.speech_start_time) >= self.max_record_seconds:
+            self.state = SpeechState.TIMEOUT
+
+        return self.state, rms
+
+    def reset(self) -> None:
+        """Reset the detector state for next utterance."""
+        self.state = SpeechState.IDLE
+        self.speech_start_time = None
+        self.silence_start_time = None
+        self.total_speech_frames = 0