voxora 1.0.0__tar.gz

voxora-1.0.0/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Voxora contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

voxora-1.0.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: voxora
+Version: 1.0.0
+Summary: A lightweight, microphone-based speech-to-text SDK for Python.
+Author: Prakhar Parikh
+License-Expression: MIT
+Keywords: speech-to-text,speech-recognition,voice-activity-detection,audio,microphone,groq,whisper,python-sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyAudio>=0.2.13
+Requires-Dist: webrtcvad-wheels>=2.0.14.post1
+Requires-Dist: groq>=0.31.0
+Requires-Dist: openai>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# Voxora
+
+**A lightweight, microphone-based speech-to-text SDK for Python.**
+
+Voxora makes it easy to add speech recognition to Python applications with automatic voice detection, manual recording controls, and optional AI-powered transcript formatting.
+
+## Features
+
+- **Automatic recording:** Detect speech and automatically stop after silence.
+- **Manual recording:** Control recording with `start()` and `stop()`.
+- **Speech-to-text:** Transcribe audio using Groq Whisper.
+- **Transcript formatting:** Optionally improve punctuation, capitalization, and paragraph structure.
+- **In-memory processing:** Audio is processed in memory without writing recordings to disk.
+- **Simple API:** A single `STT` class for both recording modes.
+
+## Installation
+
+```bash
+pip install voxora
+```
+
+Set your Groq API key:
+
+```bash
+export GROQ_API_KEY="your-groq-api-key"
+```
+
+Voxora requires Python 3.10 or newer and microphone/audio dependencies. PyAudio may require platform-specific system libraries.
+
+## Quick Start
+
+### Automatic recording (VAD)
+
+Voxora automatically detects speech and stops recording after the configured silence duration.
+
+```python
+from voxora import STT
+
+stt = STT(
+    api_key="YOUR_GROQ_API_KEY",
+    vad=True
+)
+
+text = stt.listen()
+
+print(text)
+```
+
+### Manual recording
+
+For applications that need explicit recording controls:
+
+```python
+from voxora import STT
+
+stt = STT(
+    api_key="YOUR_GROQ_API_KEY",
+    vad=False
+)
+
+stt.start()
+
+input("Press Enter to stop recording...")
+
+text = stt.stop()
+
+print(text)
+```
+
+## Transcript Formatting
+
+Voxora can optionally format transcribed text using a compatible chat-completions API.
+
+Formatting improves punctuation, capitalization, and paragraph breaks while preserving the original spoken words and meaning.
+
+```python
+from voxora import STT
+
+stt = STT(
+    api_key="YOUR_GROQ_API_KEY",
+    vad=True,
+    format=True,
+    format_model="openai/gpt-oss-120b",
+    format_base_url="https://api.groq.com/openai/v1"
+)
+
+text = stt.listen()
+
+print(text)
+```
+
+Formatting is disabled by default. The formatter receives the transcript after speech recognition; it does not receive the audio.
+
+## Configuration
+
+| Parameter | Description |
+|---|---|
+| `api_key` | Groq API key. Defaults to `GROQ_API_KEY`. |
+| `stt_model` | Groq transcription model. |
+| `language` | Optional ISO-639-1 language hint. |
+| `vad` | Enables automatic voice activity detection. |
+| `vad_mode` | WebRTC VAD aggressiveness (0–3). |
+| `silence_duration` | Silence duration before automatic recording stops. |
+| `pre_speech_duration` | Audio retained before speech detection. |
+| `max_recording_duration` | Maximum recording duration. |
+| `speech_start_timeout` | Maximum wait for speech to begin. |
+| `format` | Enables optional transcript formatting. |
+| `format_base_url` | Compatible formatting API endpoint. |
+| `format_model` | Formatting model. |
+| `format_api_key` | Formatting API key; defaults to `api_key`. |
+
+## Error Handling
+
+Voxora exposes exceptions for configuration, recording, transcription, and formatting failures.
+
+Provider authentication, network, rate-limit, and other API errors may propagate from the underlying SDK.
+
+## Requirements
+
+- Python 3.10+
+- PyAudio
+- WebRTC VAD
+- Groq API key
+- Internet connection for transcription and optional formatting
+
+Voxora uses Groq's cloud transcription API and is not an offline speech recognition engine.
+
+## License
+
+See [LICENSE](LICENSE).
+
+---
+
+**Voxora** — Speech recognition, made simple.

voxora-1.0.0/README.md

@@ -0,0 +1,134 @@
+# Voxora
+
+**A lightweight, microphone-based speech-to-text SDK for Python.**
+
+Voxora makes it easy to add speech recognition to Python applications with automatic voice detection, manual recording controls, and optional AI-powered transcript formatting.
+
+## Features
+
+- **Automatic recording:** Detect speech and automatically stop after silence.
+- **Manual recording:** Control recording with `start()` and `stop()`.
+- **Speech-to-text:** Transcribe audio using Groq Whisper.
+- **Transcript formatting:** Optionally improve punctuation, capitalization, and paragraph structure.
+- **In-memory processing:** Audio is processed in memory without writing recordings to disk.
+- **Simple API:** A single `STT` class for both recording modes.
+
+## Installation
+
+```bash
+pip install voxora
+```
+
+Set your Groq API key:
+
+```bash
+export GROQ_API_KEY="your-groq-api-key"
+```
+
+Voxora requires Python 3.10 or newer and microphone/audio dependencies. PyAudio may require platform-specific system libraries.
+
+## Quick Start
+
+### Automatic recording (VAD)
+
+Voxora automatically detects speech and stops recording after the configured silence duration.
+
+```python
+from voxora import STT
+
+stt = STT(
+    api_key="YOUR_GROQ_API_KEY",
+    vad=True
+)
+
+text = stt.listen()
+
+print(text)
+```
+
+### Manual recording
+
+For applications that need explicit recording controls:
+
+```python
+from voxora import STT
+
+stt = STT(
+    api_key="YOUR_GROQ_API_KEY",
+    vad=False
+)
+
+stt.start()
+
+input("Press Enter to stop recording...")
+
+text = stt.stop()
+
+print(text)
+```
+
+## Transcript Formatting
+
+Voxora can optionally format transcribed text using a compatible chat-completions API.
+
+Formatting improves punctuation, capitalization, and paragraph breaks while preserving the original spoken words and meaning.
+
+```python
+from voxora import STT
+
+stt = STT(
+    api_key="YOUR_GROQ_API_KEY",
+    vad=True,
+    format=True,
+    format_model="openai/gpt-oss-120b",
+    format_base_url="https://api.groq.com/openai/v1"
+)
+
+text = stt.listen()
+
+print(text)
+```
+
+Formatting is disabled by default. The formatter receives the transcript after speech recognition; it does not receive the audio.
+
+## Configuration
+
+| Parameter | Description |
+|---|---|
+| `api_key` | Groq API key. Defaults to `GROQ_API_KEY`. |
+| `stt_model` | Groq transcription model. |
+| `language` | Optional ISO-639-1 language hint. |
+| `vad` | Enables automatic voice activity detection. |
+| `vad_mode` | WebRTC VAD aggressiveness (0–3). |
+| `silence_duration` | Silence duration before automatic recording stops. |
+| `pre_speech_duration` | Audio retained before speech detection. |
+| `max_recording_duration` | Maximum recording duration. |
+| `speech_start_timeout` | Maximum wait for speech to begin. |
+| `format` | Enables optional transcript formatting. |
+| `format_base_url` | Compatible formatting API endpoint. |
+| `format_model` | Formatting model. |
+| `format_api_key` | Formatting API key; defaults to `api_key`. |
+
+## Error Handling
+
+Voxora exposes exceptions for configuration, recording, transcription, and formatting failures.
+
+Provider authentication, network, rate-limit, and other API errors may propagate from the underlying SDK.
+
+## Requirements
+
+- Python 3.10+
+- PyAudio
+- WebRTC VAD
+- Groq API key
+- Internet connection for transcription and optional formatting
+
+Voxora uses Groq's cloud transcription API and is not an offline speech recognition engine.
+
+## License
+
+See [LICENSE](LICENSE).
+
+---
+
+**Voxora** — Speech recognition, made simple.

voxora-1.0.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "voxora"
+version = "1.0.0"
+description = "A lightweight, microphone-based speech-to-text SDK for Python."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Prakhar Parikh" }
+]
+keywords = [
+    "speech-to-text",
+    "speech-recognition",
+    "voice-activity-detection",
+    "audio",
+    "microphone",
+    "groq",
+    "whisper",
+    "python-sdk"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+]
+dependencies = [
+    "PyAudio>=0.2.13",
+    "webrtcvad-wheels>=2.0.14.post1",
+    "groq>=0.31.0",
+    "openai>=2.31.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

voxora-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

voxora-1.0.0/src/voxora/__init__.py

@@ -0,0 +1,25 @@
+"""Public package interface for Voxora."""
+
+from .exceptions import (
+    AudioCaptureError,
+    ConfigurationError,
+    FormattingError,
+    NoSpeechError,
+    RecordingStateError,
+    RecordingTimeoutError,
+    TranscriptionError,
+    VoxoraError,
+)
+from .stt import STT
+
+__all__ = [
+    "STT",
+    "VoxoraError",
+    "ConfigurationError",
+    "RecordingStateError",
+    "AudioCaptureError",
+    "NoSpeechError",
+    "RecordingTimeoutError",
+    "FormattingError",
+    "TranscriptionError",
+]

voxora-1.0.0/src/voxora/audio.py

@@ -0,0 +1,198 @@
+"""Internal microphone capture, buffering, and WebRTC VAD."""
+
+from __future__ import annotations
+
+import math
+import threading
+import time
+from collections import deque
+from dataclasses import dataclass
+from typing import Callable, Deque, List
+
+from .exceptions import AudioCaptureError, NoSpeechError
+
+
+@dataclass(frozen=True)
+class AudioResult:
+    """Internal PCM recording result for the future transcription layer."""
+
+    pcm_data: bytes
+    sample_rate: int
+    channels: int = 1
+    sample_width: int = 2
+
+
+class AudioRecorder:
+    """Capture mono 16-bit PCM from the default microphone."""
+
+    def __init__(self, config, logger, *, pyaudio_module=None, vad_factory=None, clock: Callable[[], float] = time.monotonic):
+        self.config = config
+        self.logger = logger
+        self._pyaudio_module = pyaudio_module
+        self._vad_factory = vad_factory
+        self._clock = clock
+        self._audio = None
+        self._stream = None
+        self.samples_per_frame = config.sample_rate * config.frame_duration_ms // 1000
+        if self.samples_per_frame * 1000 != config.sample_rate * config.frame_duration_ms:
+            raise AudioCaptureError("frame duration does not produce a whole number of samples")
+        self.frame_bytes = self.samples_per_frame * 2
+
+    def _load_pyaudio(self):
+        if self._pyaudio_module is None:
+            try:
+                import pyaudio
+            except Exception as exc:
+                raise AudioCaptureError("PyAudio is required for microphone recording") from exc
+            self._pyaudio_module = pyaudio
+        return self._pyaudio_module
+
+    def _load_vad(self):
+        if self._vad_factory is None:
+            try:
+                import webrtcvad
+            except Exception as exc:
+                raise AudioCaptureError("WebRTC VAD is required for VAD recording") from exc
+            self._vad_factory = webrtcvad.Vad
+        return self._vad_factory
+
+    def open(self) -> None:
+        if self._stream is not None:
+            raise AudioCaptureError("microphone stream is already open")
+        pyaudio = self._load_pyaudio()
+        try:
+            self._audio = pyaudio.PyAudio()
+            self._stream = self._audio.open(
+                format=pyaudio.paInt16,
+                channels=1,
+                rate=self.config.sample_rate,
+                input=True,
+                frames_per_buffer=self.samples_per_frame,
+            )
+            self.logger.debug("microphone initialized")
+        except Exception as exc:
+            self.close()
+            raise AudioCaptureError("could not initialize microphone") from exc
+
+    def close(self) -> None:
+        stream, audio = self._stream, self._audio
+        self._stream = None
+        self._audio = None
+        cleanup_errors = []
+        try:
+            if stream is not None:
+                try:
+                    stream.stop_stream()
+                except Exception as exc:
+                    cleanup_errors.append(exc)
+                try:
+                    stream.close()
+                except Exception as exc:
+                    cleanup_errors.append(exc)
+        finally:
+            if audio is not None:
+                try:
+                    audio.terminate()
+                except Exception as exc:
+                    cleanup_errors.append(exc)
+        self.logger.debug("microphone resources cleaned up")
+        if cleanup_errors:
+            self.logger.error("microphone cleanup encountered an error")
+
+    def _read_frame(self) -> bytes:
+        if self._stream is None:
+            raise AudioCaptureError("microphone stream is not open")
+        try:
+            frame = self._stream.read(self.samples_per_frame, exception_on_overflow=False)
+        except Exception as exc:
+            raise AudioCaptureError("microphone read failed") from exc
+        if not isinstance(frame, bytes) or len(frame) != self.frame_bytes:
+            raise AudioCaptureError("microphone returned an invalid audio frame")
+        return frame
+
+    def _new_vad(self):
+        try:
+            return self._load_vad()(self.config.vad_mode)
+        except Exception as exc:
+            raise AudioCaptureError("invalid WebRTC VAD configuration") from exc
+
+    def record_vad(self) -> AudioResult:
+        """Record until speech followed by configured silence is detected."""
+        self.open()
+        frames: List[bytes] = []
+        pre_speech_frames: Deque[bytes] = deque(
+            maxlen=max(0, math.ceil(self.config.pre_speech_duration * 1000 / self.config.frame_duration_ms))
+        )
+        frame_seconds = self.config.frame_duration_ms / 1000.0
+        silence_frames_needed = max(1, math.ceil(self.config.silence_duration / frame_seconds))
+        speech_started = False
+        consecutive_silence = 0
+        started_at = self._clock()
+        vad = None
+        try:
+            vad = self._new_vad()
+            self.logger.debug("recording started with VAD")
+            while True:
+                frame = self._read_frame()
+                elapsed = self._clock() - started_at
+                if self.config.max_recording_duration is not None and elapsed >= self.config.max_recording_duration:
+                    self.logger.debug("maximum recording duration reached")
+                    if not speech_started:
+                        raise NoSpeechError("no speech detected before maximum recording duration")
+                    break
+
+                if not speech_started and (
+                    self.config.speech_start_timeout is not None
+                    and elapsed >= self.config.speech_start_timeout
+                ):
+                    raise NoSpeechError("no speech detected before speech_start_timeout")
+
+                try:
+                    speaking = vad.is_speech(frame, self.config.sample_rate)
+                except Exception as exc:
+                    raise AudioCaptureError("WebRTC VAD processing failed") from exc
+                if not speech_started:
+                    if speaking:
+                        speech_started = True
+                        frames.extend(pre_speech_frames)
+                        frames.append(frame)
+                        self.logger.debug("speech detected")
+                    else:
+                        pre_speech_frames.append(frame)
+                    continue
+
+                frames.append(frame)
+                if speaking:
+                    consecutive_silence = 0
+                else:
+                    consecutive_silence += 1
+                    if consecutive_silence >= silence_frames_needed:
+                        self.logger.debug("silence detected; recording stopped")
+                        break
+
+            if not frames:
+                raise NoSpeechError("no usable audio was captured")
+            return AudioResult(b"".join(frames), self.config.sample_rate)
+        finally:
+            self.close()
+            self.logger.debug("audio preparation completed")
+
+    def record_manual(self, stop_event: threading.Event) -> AudioResult:
+        """Record until stopped or the configured maximum duration is reached."""
+        if self._stream is None:
+            raise AudioCaptureError("microphone stream is not open")
+        frames: List[bytes] = []
+        started_at = self._clock()
+        self.logger.debug("manual recording started")
+        try:
+            while not stop_event.is_set():
+                if self.config.max_recording_duration is not None and self._clock() - started_at >= self.config.max_recording_duration:
+                    self.logger.debug("maximum recording duration reached")
+                    break
+                frames.append(self._read_frame())
+            if not frames:
+                raise NoSpeechError("no usable audio was captured")
+            return AudioResult(b"".join(frames), self.config.sample_rate)
+        finally:
+            self.close()
+            self.logger.debug("manual recording stopped")