generic-audio-transcriber 0.1.0__py3-none-any.whl

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"]

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()

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())

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)

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+audio_transcriber/__init__.py,sha256=csz215f2487u2IV6QZlleCPHdBO8UxR1g_WfsCjq2nQ,241
+audio_transcriber/_model.py,sha256=D0eoBLKMuvWF0FCbVLuoaBj-pIDMBmU-mRD2M2Xa09o,958
+audio_transcriber/cli.py,sha256=sdPMxvx-Xzv4DIQPJYGHcxJUf1Z7Uy6YrJUas2j1r3g,1385
+audio_transcriber/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+audio_transcriber/result.py,sha256=ljMlkIA-nN3d4ya9GcnDkPLD-z-LHMMHZeTN1_q8zbs,928
+audio_transcriber/transcriber.py,sha256=WPnkyVSyK6h0ECNDOUDR5vFIHCPkA-RqqorLYHAngpE,2646
+generic_audio_transcriber-0.1.0.dist-info/licenses/LICENSE,sha256=kAmtq-Jj2Hm1y9c4SDWwgaWyptnE6aOXUpZ8tyGfpa0,1071
+generic_audio_transcriber-0.1.0.dist-info/METADATA,sha256=4tKHk8w9KQ_xpLW6qGYP2xidgcObx8M_MLA-TpKi0S0,4857
+generic_audio_transcriber-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+generic_audio_transcriber-0.1.0.dist-info/entry_points.txt,sha256=3KxjmWj9RBiMgOhhq0NRbxZmlJLSyUTLi42Vw9husOE,65
+generic_audio_transcriber-0.1.0.dist-info/top_level.txt,sha256=1VoY9Hc8Rydt3ZgX1wBf0SeukQk-X2yjSr5nCAwAjm0,18
+generic_audio_transcriber-0.1.0.dist-info/RECORD,,

generic_audio_transcriber-0.1.0.dist-info/WHEEL

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

generic_audio_transcriber-0.1.0.dist-info/entry_points.txt

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

generic_audio_transcriber-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

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