generic-audio-transcriber 0.1.0__tar.gz

generic_audio_transcriber-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eduardo Milani
+
+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.

generic_audio_transcriber-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: generic-audio-transcriber
+Version: 0.1.0
+Summary: Drop-in speech-to-text for any Python project: audio bytes in, JSON-ready text out.
+Author: Eduardo Milani
+License: MIT
+Project-URL: Repository, https://github.com/EduardoMilani8/generic-audio-transcriber
+Keywords: speech-to-text,transcription,whisper,audio,asr
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: faster-whisper>=1.0
+Requires-Dist: av<19,>=11
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# generic-audio-transcriber
+
+Drop-in speech-to-text for any Python project. Audio bytes in, JSON-ready text out.
+
+```python
+from audio_transcriber import transcribe
+
+result = transcribe(audio_bytes)   # mp3, wav, webm, ogg, m4a... detected automatically
+print(result.text)                 # "Hello, this is a test."
+print(result.to_json())            # {"text": "...", "language": "en", ...}
+```
+
+No API keys, no servers, no cloud. It runs locally on the CPU, and the model is
+downloaded automatically the first time you use it.
+
+## Why
+
+Many apps need the same small feature: the user sends or records audio, and the app
+needs the text. This package is that feature as one function call, so you can add it to
+a project without learning anything about speech recognition.
+
+Under the hood it uses [faster-whisper](https://github.com/SYSTRAN/faster-whisper)
+(OpenAI's Whisper model), which is accurate, supports about 99 languages, and runs well
+on a plain CPU. You never have to train or tune a model.
+
+## Install
+
+```bash
+pip install git+https://github.com/EduardoMilani8/generic-audio-transcriber.git
+```
+
+Requires Python 3.9+. You do **not** need to install ffmpeg: audio decoding is bundled.
+
+## Usage
+
+### From bytes (the main use case)
+
+```python
+from audio_transcriber import transcribe
+
+result = transcribe(audio_bytes)
+```
+
+### From a file path or file object
+
+```python
+transcribe("recording.mp3")
+
+with open("recording.wav", "rb") as f:
+    transcribe(f)
+```
+
+### Inside a web endpoint
+
+```python
+from fastapi import FastAPI, UploadFile
+from audio_transcriber import transcribe
+
+app = FastAPI()
+
+@app.post("/transcribe")
+async def endpoint(file: UploadFile):
+    return transcribe(await file.read()).to_dict()
+```
+
+### The result
+
+```python
+result.text                  # full transcript
+result.language              # detected language code, e.g. "pt"
+result.language_probability  # confidence of the language detection
+result.duration              # audio length in seconds
+result.segments              # timed pieces: .start, .end, .text
+result.to_dict()             # plain dict
+result.to_json()             # JSON string (non-ASCII kept readable)
+```
+
+Silent audio gives an empty `text`, not an error.
+
+## Options
+
+```python
+transcribe(
+    audio,
+    model="small",         # tiny | base | small | medium | large-v3
+    language=None,         # "pt", "en", ... None = auto-detect
+    device="cpu",          # "cpu" | "cuda" | "auto"
+    compute_type="int8",   # "int8" is light; "float16" suits GPUs
+    beam_size=5,
+    vad_filter=True,       # skip silence, reduces made-up text
+)
+```
+
+Choosing a model is a trade-off between weight and accuracy:
+
+| Model | Size on disk | Speed | Accuracy |
+|---|---|---|---|
+| `tiny` | smallest | fastest | lowest |
+| `base` | small | fast | fair |
+| `small` (default) | medium | good | good |
+| `medium` / `large-v3` | large | slow on CPU | best |
+
+The model is loaded once per process and reused, so only the first call is slow.
+Setting `language` explicitly is faster and more accurate than auto-detection.
+
+## Errors
+
+```python
+from audio_transcriber import transcribe, TranscriptionError
+
+try:
+    transcribe(data)
+except TranscriptionError as e:
+    ...  # empty input or audio that cannot be decoded
+```
+
+## Command line
+
+```bash
+audio-transcriber recording.mp3            # prints JSON
+audio-transcriber recording.mp3 --text     # prints plain text
+audio-transcriber recording.mp3 --model base --language pt
+cat recording.mp3 | audio-transcriber -    # read bytes from stdin
+```
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest                                # fast unit tests, no model needed
+RUN_SLOW=1 pytest -m slow             # end-to-end tests, downloads the tiny model
+```
+
+## Notes
+
+- The default device is `cpu` because it works on every machine. Pass `device="cuda"`
+  if you have a working CUDA setup and want GPU speed.
+- `av` is pinned below version 19 because faster-whisper still uses an argument that
+  newer releases removed. The pin can be lifted once faster-whisper fixes it.
+
+## License
+
+MIT

generic_audio_transcriber-0.1.0/README.md

@@ -0,0 +1,144 @@
+# generic-audio-transcriber
+
+Drop-in speech-to-text for any Python project. Audio bytes in, JSON-ready text out.
+
+```python
+from audio_transcriber import transcribe
+
+result = transcribe(audio_bytes)   # mp3, wav, webm, ogg, m4a... detected automatically
+print(result.text)                 # "Hello, this is a test."
+print(result.to_json())            # {"text": "...", "language": "en", ...}
+```
+
+No API keys, no servers, no cloud. It runs locally on the CPU, and the model is
+downloaded automatically the first time you use it.
+
+## Why
+
+Many apps need the same small feature: the user sends or records audio, and the app
+needs the text. This package is that feature as one function call, so you can add it to
+a project without learning anything about speech recognition.
+
+Under the hood it uses [faster-whisper](https://github.com/SYSTRAN/faster-whisper)
+(OpenAI's Whisper model), which is accurate, supports about 99 languages, and runs well
+on a plain CPU. You never have to train or tune a model.
+
+## Install
+
+```bash
+pip install git+https://github.com/EduardoMilani8/generic-audio-transcriber.git
+```
+
+Requires Python 3.9+. You do **not** need to install ffmpeg: audio decoding is bundled.
+
+## Usage
+
+### From bytes (the main use case)
+
+```python
+from audio_transcriber import transcribe
+
+result = transcribe(audio_bytes)
+```
+
+### From a file path or file object
+
+```python
+transcribe("recording.mp3")
+
+with open("recording.wav", "rb") as f:
+    transcribe(f)
+```
+
+### Inside a web endpoint
+
+```python
+from fastapi import FastAPI, UploadFile
+from audio_transcriber import transcribe
+
+app = FastAPI()
+
+@app.post("/transcribe")
+async def endpoint(file: UploadFile):
+    return transcribe(await file.read()).to_dict()
+```
+
+### The result
+
+```python
+result.text                  # full transcript
+result.language              # detected language code, e.g. "pt"
+result.language_probability  # confidence of the language detection
+result.duration              # audio length in seconds
+result.segments              # timed pieces: .start, .end, .text
+result.to_dict()             # plain dict
+result.to_json()             # JSON string (non-ASCII kept readable)
+```
+
+Silent audio gives an empty `text`, not an error.
+
+## Options
+
+```python
+transcribe(
+    audio,
+    model="small",         # tiny | base | small | medium | large-v3
+    language=None,         # "pt", "en", ... None = auto-detect
+    device="cpu",          # "cpu" | "cuda" | "auto"
+    compute_type="int8",   # "int8" is light; "float16" suits GPUs
+    beam_size=5,
+    vad_filter=True,       # skip silence, reduces made-up text
+)
+```
+
+Choosing a model is a trade-off between weight and accuracy:
+
+| Model | Size on disk | Speed | Accuracy |
+|---|---|---|---|
+| `tiny` | smallest | fastest | lowest |
+| `base` | small | fast | fair |
+| `small` (default) | medium | good | good |
+| `medium` / `large-v3` | large | slow on CPU | best |
+
+The model is loaded once per process and reused, so only the first call is slow.
+Setting `language` explicitly is faster and more accurate than auto-detection.
+
+## Errors
+
+```python
+from audio_transcriber import transcribe, TranscriptionError
+
+try:
+    transcribe(data)
+except TranscriptionError as e:
+    ...  # empty input or audio that cannot be decoded
+```
+
+## Command line
+
+```bash
+audio-transcriber recording.mp3            # prints JSON
+audio-transcriber recording.mp3 --text     # prints plain text
+audio-transcriber recording.mp3 --model base --language pt
+cat recording.mp3 | audio-transcriber -    # read bytes from stdin
+```
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest                                # fast unit tests, no model needed
+RUN_SLOW=1 pytest -m slow             # end-to-end tests, downloads the tiny model
+```
+
+## Notes
+
+- The default device is `cpu` because it works on every machine. Pass `device="cuda"`
+  if you have a working CUDA setup and want GPU speed.
+- `av` is pinned below version 19 because faster-whisper still uses an argument that
+  newer releases removed. The pin can be lifted once faster-whisper fixes it.
+
+## License
+
+MIT

generic_audio_transcriber-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "generic-audio-transcriber"
+version = "0.1.0"
+description = "Drop-in speech-to-text for any Python project: audio bytes in, JSON-ready text out."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "Eduardo Milani" }]
+keywords = ["speech-to-text", "transcription", "whisper", "audio", "asr"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+]
+# av<19: faster-whisper still calls av.open(metadata_errors=...), which av 19 rejects.
+dependencies = ["faster-whisper>=1.0", "av>=11,<19"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+audio-transcriber = "audio_transcriber.cli:main"
+
+[project.urls]
+Repository = "https://github.com/EduardoMilani8/generic-audio-transcriber"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+audio_transcriber = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["slow: downloads a real model and runs real inference (set RUN_SLOW=1)"]

generic_audio_transcriber-0.1.0/setup.cfg

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

generic_audio_transcriber-0.1.0/src/audio_transcriber/__init__.py

@@ -0,0 +1,6 @@
+"""Drop-in speech-to-text for any Python project."""
+
+from .result import Segment, TranscriptionResult
+from .transcriber import TranscriptionError, transcribe
+
+__all__ = ["transcribe", "TranscriptionResult", "Segment", "TranscriptionError"]

generic_audio_transcriber-0.1.0/src/audio_transcriber/_model.py

@@ -0,0 +1,32 @@
+"""Lazy, cached loading of the speech recognition model."""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, Dict, Tuple
+
+_cache: Dict[Tuple[str, str, str], Any] = {}
+_lock = threading.Lock()
+
+
+def get_model(name: str, device: str, compute_type: str) -> Any:
+    """Return a loaded model, loading (and downloading) it only the first time.
+
+    ``faster_whisper`` is imported here rather than at module level so that
+    importing this package stays instant and tests can run without it.
+    """
+    key = (name, device, compute_type)
+    with _lock:
+        model = _cache.get(key)
+        if model is None:
+            from faster_whisper import WhisperModel
+
+            model = WhisperModel(name, device=device, compute_type=compute_type)
+            _cache[key] = model
+        return model
+
+
+def clear_cache() -> None:
+    """Drop every loaded model so its memory can be reclaimed."""
+    with _lock:
+        _cache.clear()

generic_audio_transcriber-0.1.0/src/audio_transcriber/cli.py

@@ -0,0 +1,39 @@
+"""Command line entry point: ``audio-transcriber FILE`` prints JSON."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional
+
+from .transcriber import DEFAULT_MODEL, TranscriptionError, transcribe
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="audio-transcriber",
+        description="Transcribe an audio file to text and print the result as JSON.",
+    )
+    parser.add_argument("audio", help="Path to an audio file, or '-' to read bytes from stdin.")
+    parser.add_argument("--model", default=DEFAULT_MODEL, help=f"Model size (default: {DEFAULT_MODEL}).")
+    parser.add_argument("--language", default=None, help="Language code such as 'pt'. Auto-detected if omitted.")
+    parser.add_argument("--text", action="store_true", help="Print only the plain text instead of JSON.")
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    audio = sys.stdin.buffer.read() if args.audio == "-" else args.audio
+
+    try:
+        result = transcribe(audio, model=args.model, language=args.language)
+    except TranscriptionError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    print(result.text if args.text else result.to_json(indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

generic_audio_transcriber-0.1.0/src/audio_transcriber/result.py

@@ -0,0 +1,36 @@
+"""Plain data types returned by :func:`audio_transcriber.transcribe`."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from typing import Any, Dict, Tuple
+
+
+@dataclass(frozen=True)
+class Segment:
+    """A timed piece of the transcript. Times are in seconds."""
+
+    start: float
+    end: float
+    text: str
+
+
+@dataclass(frozen=True)
+class TranscriptionResult:
+    """The outcome of a transcription, easy to turn into JSON."""
+
+    text: str
+    language: str
+    language_probability: float
+    duration: float
+    segments: Tuple[Segment, ...] = field(default_factory=tuple)
+
+    def to_dict(self) -> Dict[str, Any]:
+        data = asdict(self)
+        data["segments"] = [asdict(s) for s in self.segments]
+        return data
+
+    def to_json(self, **kwargs: Any) -> str:
+        kwargs.setdefault("ensure_ascii", False)
+        return json.dumps(self.to_dict(), **kwargs)

generic_audio_transcriber-0.1.0/src/audio_transcriber/transcriber.py

@@ -0,0 +1,82 @@
+"""The public ``transcribe`` function."""
+
+from __future__ import annotations
+
+import io
+import os
+from typing import BinaryIO, Optional, Union
+
+from av.error import FFmpegError
+
+from . import _model
+from .result import Segment, TranscriptionResult
+
+AudioInput = Union[bytes, bytearray, memoryview, str, "os.PathLike[str]", BinaryIO]
+
+DEFAULT_MODEL = "small"
+
+
+class TranscriptionError(Exception):
+    """Raised when the audio is empty or cannot be decoded."""
+
+
+def _prepare_audio(audio: AudioInput) -> Union[str, BinaryIO]:
+    if isinstance(audio, (bytes, bytearray, memoryview)):
+        data = bytes(audio)
+        if not data:
+            raise TranscriptionError("Audio is empty.")
+        return io.BytesIO(data)
+    if isinstance(audio, (str, os.PathLike)):
+        return os.fspath(audio)
+    return audio
+
+
+def transcribe(
+    audio: AudioInput,
+    *,
+    model: str = DEFAULT_MODEL,
+    language: Optional[str] = None,
+    device: str = "cpu",
+    compute_type: str = "int8",
+    beam_size: int = 5,
+    vad_filter: bool = True,
+) -> TranscriptionResult:
+    """Convert speech to text.
+
+    Args:
+        audio: Raw audio bytes (mp3, wav, webm, ogg, m4a, ...), a file path,
+            or a binary file-like object. The format is detected automatically.
+        model: Model size or name: ``tiny``, ``base``, ``small``, ``medium``,
+            ``large-v3``, ... The model is downloaded on first use and cached.
+        language: ISO code such as ``"pt"`` or ``"en"``. ``None`` detects it.
+        device: ``"cpu"`` (works everywhere), ``"cuda"`` or ``"auto"``.
+        compute_type: Quantization, e.g. ``"int8"`` (light) or ``"float16"``.
+        beam_size: Higher is slightly more accurate and slower.
+        vad_filter: Skip silent parts, which also reduces hallucinated text.
+
+    Raises:
+        TranscriptionError: If the audio is empty or cannot be decoded.
+    """
+    source = _prepare_audio(audio)
+    whisper = _model.get_model(model, device, compute_type)
+
+    try:
+        raw_segments, info = whisper.transcribe(
+            source,
+            language=language,
+            beam_size=beam_size,
+            vad_filter=vad_filter,
+        )
+        segments = tuple(
+            Segment(start=s.start, end=s.end, text=s.text.strip()) for s in raw_segments
+        )
+    except FFmpegError as exc:
+        raise TranscriptionError(f"Could not decode audio: {exc}") from exc
+
+    return TranscriptionResult(
+        text=" ".join(s.text for s in segments if s.text),
+        language=info.language,
+        language_probability=info.language_probability,
+        duration=info.duration,
+        segments=segments,
+    )

generic_audio_transcriber-0.1.0/src/generic_audio_transcriber.egg-info/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: generic-audio-transcriber
+Version: 0.1.0
+Summary: Drop-in speech-to-text for any Python project: audio bytes in, JSON-ready text out.
+Author: Eduardo Milani
+License: MIT
+Project-URL: Repository, https://github.com/EduardoMilani8/generic-audio-transcriber
+Keywords: speech-to-text,transcription,whisper,audio,asr
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: faster-whisper>=1.0
+Requires-Dist: av<19,>=11
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# generic-audio-transcriber
+
+Drop-in speech-to-text for any Python project. Audio bytes in, JSON-ready text out.
+
+```python
+from audio_transcriber import transcribe
+
+result = transcribe(audio_bytes)   # mp3, wav, webm, ogg, m4a... detected automatically
+print(result.text)                 # "Hello, this is a test."
+print(result.to_json())            # {"text": "...", "language": "en", ...}
+```
+
+No API keys, no servers, no cloud. It runs locally on the CPU, and the model is
+downloaded automatically the first time you use it.
+
+## Why
+
+Many apps need the same small feature: the user sends or records audio, and the app
+needs the text. This package is that feature as one function call, so you can add it to
+a project without learning anything about speech recognition.
+
+Under the hood it uses [faster-whisper](https://github.com/SYSTRAN/faster-whisper)
+(OpenAI's Whisper model), which is accurate, supports about 99 languages, and runs well
+on a plain CPU. You never have to train or tune a model.
+
+## Install
+
+```bash
+pip install git+https://github.com/EduardoMilani8/generic-audio-transcriber.git
+```
+
+Requires Python 3.9+. You do **not** need to install ffmpeg: audio decoding is bundled.
+
+## Usage
+
+### From bytes (the main use case)
+
+```python
+from audio_transcriber import transcribe
+
+result = transcribe(audio_bytes)
+```
+
+### From a file path or file object
+
+```python
+transcribe("recording.mp3")
+
+with open("recording.wav", "rb") as f:
+    transcribe(f)
+```
+
+### Inside a web endpoint
+
+```python
+from fastapi import FastAPI, UploadFile
+from audio_transcriber import transcribe
+
+app = FastAPI()
+
+@app.post("/transcribe")
+async def endpoint(file: UploadFile):
+    return transcribe(await file.read()).to_dict()
+```
+
+### The result
+
+```python
+result.text                  # full transcript
+result.language              # detected language code, e.g. "pt"
+result.language_probability  # confidence of the language detection
+result.duration              # audio length in seconds
+result.segments              # timed pieces: .start, .end, .text
+result.to_dict()             # plain dict
+result.to_json()             # JSON string (non-ASCII kept readable)
+```
+
+Silent audio gives an empty `text`, not an error.
+
+## Options
+
+```python
+transcribe(
+    audio,
+    model="small",         # tiny | base | small | medium | large-v3
+    language=None,         # "pt", "en", ... None = auto-detect
+    device="cpu",          # "cpu" | "cuda" | "auto"
+    compute_type="int8",   # "int8" is light; "float16" suits GPUs
+    beam_size=5,
+    vad_filter=True,       # skip silence, reduces made-up text
+)
+```
+
+Choosing a model is a trade-off between weight and accuracy:
+
+| Model | Size on disk | Speed | Accuracy |
+|---|---|---|---|
+| `tiny` | smallest | fastest | lowest |
+| `base` | small | fast | fair |
+| `small` (default) | medium | good | good |
+| `medium` / `large-v3` | large | slow on CPU | best |
+
+The model is loaded once per process and reused, so only the first call is slow.
+Setting `language` explicitly is faster and more accurate than auto-detection.
+
+## Errors
+
+```python
+from audio_transcriber import transcribe, TranscriptionError
+
+try:
+    transcribe(data)
+except TranscriptionError as e:
+    ...  # empty input or audio that cannot be decoded
+```
+
+## Command line
+
+```bash
+audio-transcriber recording.mp3            # prints JSON
+audio-transcriber recording.mp3 --text     # prints plain text
+audio-transcriber recording.mp3 --model base --language pt
+cat recording.mp3 | audio-transcriber -    # read bytes from stdin
+```
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest                                # fast unit tests, no model needed
+RUN_SLOW=1 pytest -m slow             # end-to-end tests, downloads the tiny model
+```
+
+## Notes
+
+- The default device is `cpu` because it works on every machine. Pass `device="cuda"`
+  if you have a working CUDA setup and want GPU speed.
+- `av` is pinned below version 19 because faster-whisper still uses an argument that
+  newer releases removed. The pin can be lifted once faster-whisper fixes it.
+
+## License
+
+MIT

generic_audio_transcriber-0.1.0/src/generic_audio_transcriber.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+README.md
+pyproject.toml
+src/audio_transcriber/__init__.py
+src/audio_transcriber/_model.py
+src/audio_transcriber/cli.py
+src/audio_transcriber/py.typed
+src/audio_transcriber/result.py
+src/audio_transcriber/transcriber.py
+src/generic_audio_transcriber.egg-info/PKG-INFO
+src/generic_audio_transcriber.egg-info/SOURCES.txt
+src/generic_audio_transcriber.egg-info/dependency_links.txt
+src/generic_audio_transcriber.egg-info/entry_points.txt
+src/generic_audio_transcriber.egg-info/requires.txt
+src/generic_audio_transcriber.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_integration.py
+tests/test_model.py
+tests/test_result.py
+tests/test_transcribe.py

generic_audio_transcriber-0.1.0/src/generic_audio_transcriber.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

generic_audio_transcriber-0.1.0/src/generic_audio_transcriber.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+audio-transcriber = audio_transcriber.cli:main

generic_audio_transcriber-0.1.0/src/generic_audio_transcriber.egg-info/requires.txt

@@ -0,0 +1,5 @@
+faster-whisper>=1.0
+av<19,>=11
+
+[dev]
+pytest>=8

generic_audio_transcriber-0.1.0/src/generic_audio_transcriber.egg-info/top_level.txt

@@ -0,0 +1 @@
+audio_transcriber

generic_audio_transcriber-0.1.0/tests/test_cli.py

@@ -0,0 +1,62 @@
+import io
+import json
+
+from audio_transcriber import cli
+from audio_transcriber.result import Segment, TranscriptionResult
+from audio_transcriber.transcriber import TranscriptionError
+
+
+def fake_result():
+    return TranscriptionResult(
+        text="hi there",
+        language="en",
+        language_probability=0.9,
+        duration=1.0,
+        segments=(Segment(0.0, 1.0, "hi there"),),
+    )
+
+
+def test_prints_json_by_default(monkeypatch, capsys):
+    monkeypatch.setattr(cli, "transcribe", lambda audio, **kw: fake_result())
+    assert cli.main(["a.wav"]) == 0
+    assert json.loads(capsys.readouterr().out)["text"] == "hi there"
+
+
+def test_text_flag_prints_plain_text(monkeypatch, capsys):
+    monkeypatch.setattr(cli, "transcribe", lambda audio, **kw: fake_result())
+    assert cli.main(["a.wav", "--text"]) == 0
+    assert capsys.readouterr().out.strip() == "hi there"
+
+
+def test_dash_reads_bytes_from_stdin(monkeypatch):
+    seen = {}
+
+    def fake_transcribe(audio, **kw):
+        seen["audio"] = audio
+        return fake_result()
+
+    monkeypatch.setattr(cli, "transcribe", fake_transcribe)
+    monkeypatch.setattr("sys.stdin", type("S", (), {"buffer": io.BytesIO(b"raw")})())
+    cli.main(["-"])
+    assert seen["audio"] == b"raw"
+
+
+def test_options_are_forwarded(monkeypatch):
+    seen = {}
+
+    def fake_transcribe(audio, **kw):
+        seen.update(kw)
+        return fake_result()
+
+    monkeypatch.setattr(cli, "transcribe", fake_transcribe)
+    cli.main(["a.wav", "--model", "base", "--language", "pt"])
+    assert seen == {"model": "base", "language": "pt"}
+
+
+def test_errors_exit_with_status_1(monkeypatch, capsys):
+    def boom(audio, **kw):
+        raise TranscriptionError("bad audio")
+
+    monkeypatch.setattr(cli, "transcribe", boom)
+    assert cli.main(["a.wav"]) == 1
+    assert "bad audio" in capsys.readouterr().err

generic_audio_transcriber-0.1.0/tests/test_integration.py

@@ -0,0 +1,57 @@
+"""End-to-end checks with the real model. Run with: RUN_SLOW=1 pytest -m slow"""
+
+import io
+import math
+import os
+import shutil
+import struct
+import subprocess
+import wave
+
+import pytest
+
+from audio_transcriber import TranscriptionError, TranscriptionResult, transcribe
+
+pytestmark = [
+    pytest.mark.slow,
+    pytest.mark.skipif(not os.environ.get("RUN_SLOW"), reason="set RUN_SLOW=1 to run"),
+]
+
+
+def tone_wav(seconds=1.0, rate=16000, freq=440.0) -> bytes:
+    frames = b"".join(
+        struct.pack("<h", int(8000 * math.sin(2 * math.pi * freq * i / rate)))
+        for i in range(int(seconds * rate))
+    )
+    buffer = io.BytesIO()
+    with wave.open(buffer, "wb") as wav:
+        wav.setnchannels(1)
+        wav.setsampwidth(2)
+        wav.setframerate(rate)
+        wav.writeframes(frames)
+    return buffer.getvalue()
+
+
+def test_wav_bytes_are_decoded_and_transcribed():
+    result = transcribe(tone_wav(), model="tiny", compute_type="int8")
+    assert isinstance(result, TranscriptionResult)
+    assert result.duration == pytest.approx(1.0, abs=0.1)
+    assert isinstance(result.language, str)
+
+
+@pytest.mark.skipif(shutil.which("ffmpeg") is None, reason="ffmpeg needed to build an mp3")
+def test_mp3_bytes_are_decoded_too(tmp_path):
+    wav_path = tmp_path / "tone.wav"
+    wav_path.write_bytes(tone_wav())
+    mp3 = subprocess.run(
+        ["ffmpeg", "-loglevel", "error", "-i", str(wav_path), "-f", "mp3", "-"],
+        check=True,
+        capture_output=True,
+    ).stdout
+    result = transcribe(mp3, model="tiny", compute_type="int8")
+    assert result.duration == pytest.approx(1.0, abs=0.2)
+
+
+def test_garbage_bytes_raise_a_clear_error():
+    with pytest.raises(TranscriptionError):
+        transcribe(b"this is definitely not audio" * 100, model="tiny", compute_type="int8")

generic_audio_transcriber-0.1.0/tests/test_model.py

@@ -0,0 +1,48 @@
+import sys
+import types
+
+import pytest
+
+from audio_transcriber import _model
+
+
+@pytest.fixture(autouse=True)
+def fresh_cache():
+    _model.clear_cache()
+    yield
+    _model.clear_cache()
+
+
+@pytest.fixture
+def fake_faster_whisper(monkeypatch):
+    created = []
+
+    class FakeWhisperModel:
+        def __init__(self, name, device, compute_type):
+            created.append((name, device, compute_type))
+
+    module = types.ModuleType("faster_whisper")
+    module.WhisperModel = FakeWhisperModel
+    monkeypatch.setitem(sys.modules, "faster_whisper", module)
+    return created
+
+
+def test_model_is_loaded_once_per_configuration(fake_faster_whisper):
+    first = _model.get_model("small", "auto", "int8")
+    second = _model.get_model("small", "auto", "int8")
+    assert first is second
+    assert fake_faster_whisper == [("small", "auto", "int8")]
+
+
+def test_different_configurations_load_different_models(fake_faster_whisper):
+    small = _model.get_model("small", "auto", "int8")
+    base = _model.get_model("base", "auto", "int8")
+    assert small is not base
+    assert len(fake_faster_whisper) == 2
+
+
+def test_clear_cache_forces_a_reload(fake_faster_whisper):
+    _model.get_model("small", "auto", "int8")
+    _model.clear_cache()
+    _model.get_model("small", "auto", "int8")
+    assert len(fake_faster_whisper) == 2

generic_audio_transcriber-0.1.0/tests/test_result.py

@@ -0,0 +1,26 @@
+import json
+
+from audio_transcriber.result import Segment, TranscriptionResult
+
+
+def make_result():
+    return TranscriptionResult(
+        text="olá mundo",
+        language="pt",
+        language_probability=0.98,
+        duration=1.5,
+        segments=(Segment(start=0.0, end=1.5, text="olá mundo"),),
+    )
+
+
+def test_to_dict_is_json_serializable_and_nested():
+    data = make_result().to_dict()
+    assert data["text"] == "olá mundo"
+    assert data["segments"] == [{"start": 0.0, "end": 1.5, "text": "olá mundo"}]
+    json.dumps(data)
+
+
+def test_to_json_keeps_non_ascii_characters():
+    raw = make_result().to_json()
+    assert "olá mundo" in raw
+    assert json.loads(raw)["language"] == "pt"

generic_audio_transcriber-0.1.0/tests/test_transcribe.py

@@ -0,0 +1,111 @@
+import io
+from types import SimpleNamespace
+
+import pytest
+from av.error import InvalidDataError
+
+from audio_transcriber import _model, transcriber
+from audio_transcriber.transcriber import TranscriptionError, transcribe
+
+
+class FakeModel:
+    def __init__(self, segments=None, error=None):
+        self.calls = []
+        self._segments = segments if segments is not None else [
+            SimpleNamespace(start=0.0, end=1.0, text=" hello"),
+            SimpleNamespace(start=1.0, end=2.0, text=" world "),
+        ]
+        self._error = error
+
+    def transcribe(self, source, **kwargs):
+        self.calls.append((source, kwargs))
+        if self._error:
+            raise self._error
+        info = SimpleNamespace(language="en", language_probability=0.9, duration=2.0)
+        return iter(self._segments), info
+
+
+@pytest.fixture
+def fake(monkeypatch):
+    model = FakeModel()
+    monkeypatch.setattr(_model, "get_model", lambda name, device, ct: model)
+    return model
+
+
+def test_bytes_are_wrapped_in_a_file_like_object(fake):
+    transcribe(b"fake-audio")
+    source, _ = fake.calls[0]
+    assert isinstance(source, io.BytesIO)
+    assert source.read() == b"fake-audio"
+
+
+def test_path_is_passed_as_string(fake, tmp_path):
+    path = tmp_path / "a.wav"
+    transcribe(path)
+    assert fake.calls[0][0] == str(path)
+
+
+def test_file_like_is_passed_through(fake):
+    buffer = io.BytesIO(b"x")
+    transcribe(buffer)
+    assert fake.calls[0][0] is buffer
+
+
+def test_result_joins_and_strips_segment_text(fake):
+    result = transcribe(b"x")
+    assert result.text == "hello world"
+    assert [s.text for s in result.segments] == ["hello", "world"]
+    assert result.language == "en"
+    assert result.duration == 2.0
+
+
+def test_silence_gives_empty_text(monkeypatch):
+    monkeypatch.setattr(_model, "get_model", lambda *a: FakeModel(segments=[]))
+    result = transcribe(b"x")
+    assert result.text == ""
+    assert result.segments == ()
+
+
+def test_options_are_forwarded(fake):
+    transcribe(b"x", language="pt", beam_size=1, vad_filter=False)
+    assert fake.calls[0][1] == {"language": "pt", "beam_size": 1, "vad_filter": False}
+
+
+def test_model_options_select_the_model(monkeypatch):
+    seen = []
+    monkeypatch.setattr(
+        _model, "get_model", lambda *args: seen.append(args) or FakeModel()
+    )
+    transcribe(b"x", model="base", device="cpu", compute_type="float32")
+    assert seen == [("base", "cpu", "float32")]
+
+
+def test_empty_bytes_raise(fake):
+    with pytest.raises(TranscriptionError, match="empty"):
+        transcribe(b"")
+    assert fake.calls == []
+
+
+def test_decoder_failures_become_transcription_errors(monkeypatch):
+    broken = FakeModel(error=InvalidDataError(1, "invalid data"))
+    monkeypatch.setattr(_model, "get_model", lambda *a: broken)
+    with pytest.raises(TranscriptionError, match="invalid data"):
+        transcribe(b"not audio")
+
+
+def test_default_model_is_small():
+    assert transcriber.DEFAULT_MODEL == "small"
+
+
+def test_non_decoding_failures_are_not_disguised(monkeypatch):
+    broken = FakeModel(error=RuntimeError("cuda library missing"))
+    monkeypatch.setattr(_model, "get_model", lambda *a: broken)
+    with pytest.raises(RuntimeError, match="cuda library missing"):
+        transcribe(b"x")
+
+
+def test_device_defaults_to_cpu(monkeypatch):
+    seen = []
+    monkeypatch.setattr(_model, "get_model", lambda *args: seen.append(args) or FakeModel())
+    transcribe(b"x")
+    assert seen == [("small", "cpu", "int8")]