scribed 0.0.1__py3-none-any.whl

scribed/__init__.py

@@ -0,0 +1,173 @@
+"""scribed — one facade over many speech-to-text engines, plus a ledger to choose.
+
+Transcription ("turn this audio into text") is solved a dozen different ways:
+local engines (Whisper, faster-whisper, whisper.cpp, Vosk), fast cheap cloud APIs
+(Groq, OpenAI), and feature-rich premium services (Deepgram, AssemblyAI, Google,
+ElevenLabs) — each with its own install, API, pricing, latency, language coverage,
+diarization support, and quirks. scribed gives you:
+
+1. **A uniform facade.** Call :func:`transcribe` and get the same
+   :class:`~scribed.base.Transcript` back no matter which backend ran::
+
+       import scribed
+       t = scribed.transcribe("talk.mp3")          # default (first installed) backend
+       print(t)                                     # -> the transcript text
+       t = scribed.transcribe("talk.mp3", backend="deepgram", diarize=True)
+       print(t.srt)                                 # -> SRT subtitles
+       for seg in t:
+           print(seg.start, seg.speaker, seg.text)
+
+   Convenience: :func:`transcribe_text` returns just the string.
+
+2. **A ledger / gallery** of *every* engine we researched — not only the ones
+   with a working facade — so you can choose with eyes open::
+
+       scribed.catalog                                  # the whole ledger
+       scribed.find(is_local=True, open_source=True)    # filter it
+       scribed.find(diarization="yes", is_remote=True)
+       scribed.catalog.to_dataframe()                   # browse as a table
+
+   The ledger lives in data (``scribed/data/backends.json``), not code.
+
+3. **Tools to build new facades.** The catalog is large; scribed ships a facade
+   for a curated subset and gives you the machinery (and a SKILL) to add any
+   other one in minutes::
+
+       from scribed.make_backend import scaffold_backend, validate_adapter
+       scaffold_backend("speechmatics")   # generate a backend package from the ledger
+       validate_adapter("faster-whisper") # smoke-test an adapter end to end
+
+Three tiers of access, from simplest to most powerful::
+
+    scribed.transcribe(audio)                              # facade, default backend
+    scribed.services.deepgram.transcribe(audio, diarize=True)  # pick a backend
+    scribed.services.deepgram.adapter                      # raw engine adapter
+"""
+
+from scribed.base import (
+    AudioInput,
+    LEVELS,
+    Segment,
+    TimeSpan,
+    Transcript,
+    Word,
+)
+from scribed.catalog import BackendInfo, Catalog, catalog
+from scribed.registry import (
+    get_config,
+    get_default_backend,
+    list_backends,
+    register_backend,
+)
+from scribed.services import ServiceCollection
+from scribed.make_backend import (
+    BaseTranscriberAdapter,
+    make_segment,
+    make_word,
+    scaffold_backend,
+    validate_adapter,
+)
+from scribed.install import (
+    Requirements,
+    available_backends,
+    check,
+    doctor,
+    install,
+    requirements,
+)
+from scribed.status import (
+    backend_ids,
+    backend_info,
+    is_set_up,
+    is_tested,
+    names_with_sites,
+    status_table,
+)
+
+__all__ = [
+    "transcribe",
+    "transcribe_text",
+    "services",
+    "catalog",
+    "find",
+    "list_backends",
+    "register_backend",
+    "get_default_backend",
+    "get_config",
+    "Transcript",
+    "Segment",
+    "Word",
+    "TimeSpan",
+    "AudioInput",
+    "LEVELS",
+    "BackendInfo",
+    "Catalog",
+    "ServiceCollection",
+    "BaseTranscriberAdapter",
+    "make_segment",
+    "make_word",
+    "scaffold_backend",
+    "validate_adapter",
+    "requirements",
+    "check",
+    "doctor",
+    "install",
+    "available_backends",
+    "Requirements",
+    "backend_ids",
+    "backend_info",
+    "status_table",
+    "names_with_sites",
+    "is_set_up",
+    "is_tested",
+    "__version__",
+]
+
+# Derive the version from installed package metadata (the pyproject SSOT, which CI
+# auto-bumps) so __version__ never drifts from a hardcoded literal.
+from importlib.metadata import PackageNotFoundError as _PNFE, version as _version
+
+try:
+    __version__ = _version("scribed")
+except _PNFE:  # running from a source tree without install metadata
+    __version__ = "0.0.0+source"
+del _version, _PNFE
+
+#: Singleton service collection for per-backend access (``services.deepgram``).
+services = ServiceCollection()
+
+
+def transcribe(audio: AudioInput, *, backend: str = None, **kwargs) -> Transcript:
+    """Transcribe audio with any backend, returning a normalized result.
+
+    Args:
+        audio: A path, ``http(s)`` URL, ``bytes``, file-like object, or numpy
+            waveform.
+        backend: Backend id (see :func:`list_backends`). Defaults to the first
+            *installed* implemented backend (see :func:`get_default_backend`).
+        **kwargs: Normalized, backend-translated options (e.g. ``language``,
+            ``diarize``, ``word_timestamps``). Unknown options for the chosen
+            backend are warned about and dropped.
+
+    Returns:
+        A :class:`~scribed.base.Transcript` (``str(t)`` is the text; ``t.srt`` /
+        ``t.vtt`` give subtitles; iterate it for segments).
+    """
+    backend = backend or get_default_backend()
+    return services[backend].transcribe(audio, **kwargs)
+
+
+def transcribe_text(audio: AudioInput, *, backend: str = None, **kwargs) -> str:
+    """Like :func:`transcribe` but returns just the transcript text string."""
+    return transcribe(audio, backend=backend, **kwargs).text
+
+
+def find(**criteria) -> Catalog:
+    """Filter the ledger; shorthand for :meth:`scribed.catalog.Catalog.filter`.
+
+    Example::
+
+        scribed.find(is_local=True, open_source=True, diarization="yes")
+        scribed.find(implemented=True)        # only backends scribed can run now
+    """
+    return catalog.filter(**criteria)

scribed/__main__.py

@@ -0,0 +1,45 @@
+# PYTHON_ARGCOMPLETE_OK
+"""scribed command-line interface.
+
+Exposes the tools in :mod:`scribed.tools` as subcommands via ``argh``::
+
+    scribed transcribe talk.mp3 --backend faster-whisper --output srt
+    scribed backends --capability diarize
+    scribed find --local --free --diarization
+    scribed info deepgram
+    scribed scaffold speechmatics
+    scribed validate faster-whisper
+    scribed status
+
+The CLI dependency (``argh``) is optional — ``import scribed`` stays dependency-free.
+Install it with ``pip install 'scribed[cli]'``.
+"""
+
+
+def main() -> None:
+    try:
+        import argh
+    except ImportError:  # pragma: no cover - exercised only without the extra
+        import sys
+
+        sys.exit(
+            "The scribed CLI requires 'argh'. Install it with: pip install 'scribed[cli]'"
+        )
+
+    from scribed.tools import _dispatch_funcs
+
+    parser = argh.ArghParser()
+    parser.add_commands(_dispatch_funcs)
+
+    try:  # optional shell tab-completion
+        import argcomplete
+
+        argcomplete.autocomplete(parser)
+    except ImportError:
+        pass
+
+    parser.dispatch()
+
+
+if __name__ == "__main__":
+    main()

scribed/backends/__init__.py

@@ -0,0 +1,13 @@
+"""Implemented speech-to-text backends.
+
+Each real backend is a subpackage with a ``config.py`` (``BACKEND_CONFIG``) and an
+``adapter.py`` (``Adapter`` with a ``transcribe`` method). The registry
+(:mod:`scribed.registry`) discovers them automatically. Subpackages whose name
+starts with ``_`` (e.g. :mod:`scribed.backends._template`) are scaffolding
+helpers, not real backends, and are skipped by discovery.
+
+To add a backend, scaffold one from the template::
+
+    from scribed.make_backend import scaffold_backend
+    scaffold_backend("speechmatics")   # creates scribed/backends/speechmatics/ from the template
+"""

scribed/backends/_template/__init__.py

@@ -0,0 +1 @@
+"""Template backend for scribed (copy-me)."""

scribed/backends/_template/adapter.py

@@ -0,0 +1,48 @@
+"""Adapter for the Template backend (copy-me).
+
+An adapter turns scribed's normalized request into a native engine call and the
+native response into a :class:`scribed.base.Transcript`. Subclassing
+:class:`scribed.make_backend.BaseTranscriberAdapter` gives you kwarg translation
+for free: implement :meth:`_transcribe`, which receives the audio and the
+already-translated *native* kwargs, and return a ``Transcript``.
+
+Three jobs in ``_transcribe``:
+
+1. Get the audio into the form the engine wants
+   (``scribed.util.ensure_file_path`` / ``load_audio_bytes`` / ``to_waveform``).
+2. Call the engine (import it *inside* ``_transcribe`` so importing scribed stays light).
+3. Normalize the output — use ``scribed.make_backend.make_segment`` /
+   ``Transcript.from_segments`` / ``Transcript.from_text``, and stash the engine's
+   native response in ``raw=``.
+"""
+
+from scribed.base import Transcript  # noqa: F401  (commonly needed)
+from scribed.make_backend import (  # noqa: F401
+    BaseTranscriberAdapter,
+    make_segment,
+    make_word,
+)
+
+
+class Adapter(BaseTranscriberAdapter):
+    """Template adapter — replace the body of ``_transcribe``."""
+
+    def _transcribe(self, audio, **native_kwargs) -> Transcript:
+        # 1. import the engine here (lazy)
+        # import the_engine
+        #
+        # 2. normalize the input and call the engine
+        # from scribed.util import ensure_file_path, cleanup_temp
+        # path, is_temp = ensure_file_path(audio)
+        # try:
+        #     native = the_engine.transcribe(path, **native_kwargs)
+        # finally:
+        #     cleanup_temp(path, is_temp)
+        #
+        # 3. build a normalized result
+        # segments = [
+        #     make_segment(s.text, start=s.start, end=s.end, confidence=s.conf)
+        #     for s in native.segments
+        # ]
+        # return Transcript.from_segments(segments, backend=self.backend_id, raw=native)
+        raise NotImplementedError("Implement _transcribe for this backend.")

scribed/backends/_template/config.py

@@ -0,0 +1,33 @@
+"""Configuration for the Template backend (copy-me).
+
+``scaffold_backend`` rewrites the lines tagged ``# TEMPLATE`` from a ledger entry.
+Everything else you fill in by hand: the ``param_map`` is where you map scribed's
+normalized argument names (``language``, ``diarize``, ``word_timestamps``, ...)
+onto the engine's native parameter names. See ``scribed/data/SCHEMA.md`` for field
+meanings.
+"""
+
+BACKEND_CONFIG = {
+    "id": "__template__",  # TEMPLATE
+    "name": "__template__",  # TEMPLATE
+    "display_name": "Template Backend",  # TEMPLATE
+    "pip_install": "PACKAGE",  # TEMPLATE  e.g. "faster-whisper"
+    "import_name": "PACKAGE",  # TEMPLATE  module used to probe availability
+    "license": "unknown",  # TEMPLATE
+    "is_local": False,  # TEMPLATE
+    "is_remote": False,  # TEMPLATE
+    # Capabilities BEYOND the implied primary "transcribe" (audio -> text):
+    # e.g. "diarize", "stream", "translate", "word_timestamps".
+    "capabilities": [],
+    # Capabilities this backend should be the *default* for (usually
+    # ["transcribe"] for your first/most general engine).
+    "default_for": [],
+    # For remote backends: the env var(s) holding the credential, else "".
+    "api_env_var": "",
+    "description": "One-line description of the engine.",  # TEMPLATE
+    # Map normalized kwarg -> native kwarg config (or None if unsupported):
+    #   {"native_name": "language", "default": None, "coerce": <callable>}
+    "param_map": {
+        "language": {"native_name": "language"},
+    },
+}

scribed/backends/assemblyai/__init__.py

@@ -0,0 +1 @@
+"""AssemblyAI backend for scribed."""

scribed/backends/assemblyai/adapter.py

@@ -0,0 +1,117 @@
+"""Adapter for the AssemblyAI (Universal) transcription backend.
+
+Maps scribed's normalized request onto ``assemblyai.Transcriber.transcribe`` and
+the returned transcript onto a :class:`scribed.base.Transcript`. When speaker
+labels are requested AssemblyAI returns ``utterances`` (one diarized speaker
+turn each, with nested words); otherwise we build a single segment from the full
+text and its word stream. AssemblyAI reports times in **milliseconds**, so we
+divide by 1000 to get scribed's seconds. The SDK and credential are resolved
+lazily so ``import scribed`` stays dependency-free.
+"""
+
+from __future__ import annotations
+
+from scribed.base import Transcript
+from scribed.make_backend import BaseTranscriberAdapter, make_segment, make_word
+
+
+def _ms_to_s(value):
+    """Convert an AssemblyAI millisecond time to seconds (``None`` passes through)."""
+    return None if value is None else float(value) / 1000.0
+
+
+def _speaker_str(speaker):
+    """Normalize a speaker label to a non-empty ``str`` or ``None``."""
+    s = str(speaker) if speaker is not None else ""
+    return s or None
+
+
+class Adapter(BaseTranscriberAdapter):
+    """AssemblyAI (Universal) transcription adapter."""
+
+    def __init__(self, config: dict):
+        super().__init__(config)
+        self._configured = False
+
+    def _ensure_configured(self):
+        """Set the SDK's global API key once (lazy import + lazy credential)."""
+        if not self._configured:
+            import assemblyai as aai
+
+            from scribed.credentials import resolve_credential
+
+            key = resolve_credential(
+                "assemblyai",
+                env_var=self.config.get("api_env_var") or None,
+                required=True,
+            )
+            aai.settings.api_key = key
+            self._configured = True
+
+    def _transcribe(self, audio, **native_kwargs) -> Transcript:
+        import assemblyai as aai
+
+        from scribed.util import cleanup_temp, ensure_file_path
+
+        self._ensure_configured()
+
+        config = aai.TranscriptionConfig(**native_kwargs)
+        transcriber = aai.Transcriber()
+
+        # The SDK accepts a local path (it uploads) or a URL; give it a path.
+        path, is_temp = ensure_file_path(audio)
+        try:
+            t = transcriber.transcribe(path, config=config)
+        finally:
+            cleanup_temp(path, is_temp)
+
+        # Surface a failed transcription as an exception (validate_adapter catches it).
+        status = getattr(t, "status", None)
+        error = getattr(t, "error", None)
+        if error or (status is not None and str(status).lower().endswith("error")):
+            raise RuntimeError(f"AssemblyAI transcription failed: {error or status}")
+
+        language = getattr(t, "language_code", None)
+        utterances = getattr(t, "utterances", None)
+
+        if utterances:
+            segments = [
+                make_segment(
+                    u.text or "",
+                    start=_ms_to_s(u.start),
+                    end=_ms_to_s(u.end),
+                    confidence=u.confidence,
+                    speaker=_speaker_str(u.speaker),
+                    words=[
+                        make_word(
+                            w.text,
+                            start=_ms_to_s(w.start),
+                            end=_ms_to_s(w.end),
+                            confidence=w.confidence,
+                            speaker=_speaker_str(getattr(w, "speaker", None)),
+                        )
+                        for w in (getattr(u, "words", None) or [])
+                    ],
+                )
+                for u in utterances
+            ]
+        else:
+            words = [
+                make_word(
+                    w.text,
+                    start=_ms_to_s(w.start),
+                    end=_ms_to_s(w.end),
+                    confidence=w.confidence,
+                    speaker=_speaker_str(getattr(w, "speaker", None)),
+                )
+                for w in (getattr(t, "words", None) or [])
+            ]
+            segments = [make_segment(t.text or "", words=words)]
+
+        return Transcript.from_segments(
+            segments,
+            backend=self.backend_id,
+            raw=t,
+            text=getattr(t, "text", None),
+            language=language,
+        )

scribed/backends/assemblyai/config.py

@@ -0,0 +1,37 @@
+"""Configuration for the AssemblyAI (Universal) transcription backend.
+
+AssemblyAI is a hosted speech-to-text API built on its Universal model. It
+provides speaker diarization (``speaker_labels``), word-level timestamps, and a
+suite of audio-intelligence features (sentiment, topics, summarization, ...).
+The SDK uploads local files for you, so a transcribe call accepts either a local
+file path or a publicly reachable URL.
+
+The two normalized params scribed exposes here map onto
+``assemblyai.TranscriptionConfig`` fields: ``language`` -> ``language_code`` and
+``diarize`` -> ``speaker_labels``. Additional native config (sentiment_analysis,
+iab_categories, summarization, ...) can be passed through and is forwarded to
+``TranscriptionConfig`` verbatim.
+"""
+
+BACKEND_CONFIG = {
+    "id": "assemblyai",
+    "name": "AssemblyAI",
+    "display_name": "AssemblyAI (Universal)",
+    "pip_install": "assemblyai",
+    "import_name": "assemblyai",
+    "license": "proprietary",
+    "is_local": False,
+    "is_remote": True,
+    "capabilities": ["diarize", "word_timestamps"],
+    "default_for": [],
+    "api_env_var": "ASSEMBLYAI_API_KEY",
+    "description": (
+        "AssemblyAI hosted transcription (Universal model) with speaker "
+        "diarization, word timestamps, and audio intelligence."
+    ),
+    "param_map": {
+        # Feed native kwargs to assemblyai.TranscriptionConfig(**native_kwargs).
+        "language": {"native_name": "language_code"},  # None => auto-detect
+        "diarize": {"native_name": "speaker_labels"},  # bool
+    },
+}

scribed/backends/deepgram/__init__.py

@@ -0,0 +1 @@
+"""Deepgram (Nova-3) backend for scribed."""

scribed/backends/deepgram/adapter.py

@@ -0,0 +1,207 @@
+"""Adapter for the Deepgram (Nova-3) transcription backend.
+
+Maps scribed's normalized request onto Deepgram's pre-recorded REST endpoint and
+the returned JSON onto a :class:`scribed.base.Transcript`. The SDK and credential
+are resolved lazily so ``import scribed`` stays dependency-free.
+
+When ``utterances=True`` (always, here) Deepgram returns
+``results.utterances`` — one diarized speaker turn each, with nested words — and
+we build one :class:`~scribed.base.Segment` per utterance (carrying
+``speaker=str(utt.speaker)``). When utterances are absent we fall back to a single
+segment built from ``channels[0].alternatives[0]``. Deepgram reports times in
+**seconds** and confidence already in ``[0, 1]``, so no rescaling is needed.
+
+The Deepgram Python SDK surface has shifted across major versions, so both the
+SDK accessor and the response parsing here are deliberately defensive: we try the
+v3 ``listen.rest.v("1")`` accessor first, fall back to the older
+``listen.prerecorded.v("1")`` one, and read response fields through ``.to_dict()``
+(falling back to ``getattr``) so plain dicts and SDK objects are handled alike.
+"""
+
+from __future__ import annotations
+
+from scribed.base import Transcript
+from scribed.make_backend import BaseTranscriberAdapter, make_segment, make_word
+
+
+def _get(obj, key, default=None):
+    """Read ``key`` from a plain dict or a pydantic-ish SDK object."""
+    if obj is None:
+        return default
+    if isinstance(obj, dict):
+        return obj.get(key, default)
+    return getattr(obj, key, default)
+
+
+def _as_dict(resp):
+    """Best-effort convert a Deepgram response object to a plain dict.
+
+    The SDK returns rich objects across versions; ``.to_dict()`` gives a stable,
+    uniform shape to parse. Falls back to the object itself (handled by ``_get``)
+    when no converter is available.
+    """
+    for attr in ("to_dict", "to_json"):
+        fn = getattr(resp, attr, None)
+        if callable(fn):
+            try:
+                out = fn()
+            except Exception:  # noqa: BLE001 - fall through to next strategy
+                continue
+            if isinstance(out, dict):
+                return out
+            if isinstance(out, str):
+                import json
+
+                try:
+                    return json.loads(out)
+                except Exception:  # noqa: BLE001
+                    continue
+    return resp
+
+
+def _speaker_str(speaker):
+    """Normalize a Deepgram (int) speaker label to a non-empty ``str`` or ``None``."""
+    if speaker is None:
+        return None
+    s = str(speaker)
+    return s or None
+
+
+class Adapter(BaseTranscriberAdapter):
+    """Deepgram (Nova-3) transcription adapter."""
+
+    def __init__(self, config: dict):
+        super().__init__(config)
+        self._client = None
+
+    def _get_client(self):
+        if self._client is None:
+            from deepgram import DeepgramClient
+
+            from scribed.credentials import resolve_credential
+
+            key = resolve_credential(
+                "deepgram",
+                env_var=self.config.get("api_env_var") or None,
+                required=True,
+            )
+            self._client = DeepgramClient(key)
+        return self._client
+
+    def _call_transcribe_file(self, client, payload, options):
+        """Call the SDK's pre-recorded transcribe across known accessor paths.
+
+        v3 exposes ``listen.rest.v("1").transcribe_file``; older versions expose
+        ``listen.prerecorded.v("1").transcribe_file``. Try them in turn.
+        """
+        listen = client.listen
+        for accessor in ("rest", "prerecorded"):
+            namespace = getattr(listen, accessor, None)
+            if namespace is None:
+                continue
+            try:
+                versioned = namespace.v("1")
+            except Exception:  # noqa: BLE001 - try the next accessor
+                continue
+            return versioned.transcribe_file(payload, options)
+        raise RuntimeError(
+            "Could not find a Deepgram pre-recorded transcribe accessor "
+            "(tried client.listen.rest.v('1') and "
+            "client.listen.prerecorded.v('1')). The installed deepgram-sdk "
+            "version may have an incompatible API surface."
+        )
+
+    def _transcribe(
+        self, audio, *, model="nova-3", diarize=False, language=None, **native_kwargs
+    ) -> Transcript:
+        from deepgram import PrerecordedOptions
+
+        from scribed.util import load_audio_bytes
+
+        client = self._get_client()
+        audio_bytes = load_audio_bytes(audio)
+        payload = {"buffer": audio_bytes}
+
+        options = PrerecordedOptions(
+            model=model,
+            smart_format=True,
+            punctuate=True,
+            diarize=bool(diarize),
+            utterances=True,
+            language=language,
+            **native_kwargs,
+        )
+
+        resp = self._call_transcribe_file(client, payload, options)
+        data = _as_dict(resp)
+
+        results = _get(data, "results")
+        channels = _get(results, "channels") or []
+        alternative = None
+        if channels:
+            alternatives = _get(channels[0], "alternatives") or []
+            if alternatives:
+                alternative = alternatives[0]
+
+        language_out = None
+        meta = _get(data, "metadata")
+        if meta is not None:
+            detected = _get(meta, "detected_language") or _get(meta, "language")
+            language_out = detected or language
+        else:
+            language_out = language
+
+        utterances = _get(results, "utterances")
+
+        if utterances:
+            segments = [
+                make_segment(
+                    _get(u, "transcript") or "",
+                    start=_get(u, "start"),
+                    end=_get(u, "end"),
+                    confidence=_get(u, "confidence"),
+                    speaker=_speaker_str(_get(u, "speaker")),
+                    words=[
+                        make_word(
+                            _get(w, "punctuated_word") or _get(w, "word") or "",
+                            start=_get(w, "start"),
+                            end=_get(w, "end"),
+                            confidence=_get(w, "confidence"),
+                            speaker=_speaker_str(_get(w, "speaker")),
+                        )
+                        for w in (_get(u, "words") or [])
+                    ],
+                )
+                for u in utterances
+            ]
+            text = " ".join(
+                (_get(u, "transcript") or "").strip() for u in utterances
+            ).strip()
+        else:
+            transcript_text = _get(alternative, "transcript") or ""
+            words = [
+                make_word(
+                    _get(w, "punctuated_word") or _get(w, "word") or "",
+                    start=_get(w, "start"),
+                    end=_get(w, "end"),
+                    confidence=_get(w, "confidence"),
+                    speaker=_speaker_str(_get(w, "speaker")),
+                )
+                for w in (_get(alternative, "words") or [])
+            ]
+            segments = [
+                make_segment(
+                    transcript_text,
+                    confidence=_get(alternative, "confidence"),
+                    words=words,
+                )
+            ]
+            text = transcript_text
+
+        return Transcript.from_segments(
+            segments,
+            backend=self.backend_id,
+            raw=resp,
+            text=text,
+            language=language_out,
+        )