clear-record 0.1.1__py3-none-any.whl

clear_record/__init__.py

@@ -0,0 +1,15 @@
+"""clear-record: a local-first multitrack transcription and record-reconstruction tool.
+
+The published distribution is a single package with four internal layers:
+
+- :mod:`clear_record.core` — backend-agnostic domain model (no third-party deps);
+- :mod:`clear_record.engine` — audio I/O, alignment, reconcile (numpy/soundfile);
+- :mod:`clear_record.providers` — per-vendor ASR backend adapters;
+- :mod:`clear_record.cli` — the ``clear-record`` command implementation.
+
+This module is deliberately light (a docstring only) so that importing
+``clear_record`` does not pull in the heavy CLI or audio stack. The console
+script targets :func:`clear_record.cli.main` directly.
+"""
+
+__all__: list[str] = []

clear_record/cli/__init__.py

@@ -0,0 +1,7 @@
+"""clear_record.cli: the CLI implementation for the `clear-record` command."""
+
+from __future__ import annotations
+
+from clear_record.cli.cli import main
+
+__all__ = ["main"]

clear_record/cli/__main__.py

@@ -0,0 +1,4 @@
+from clear_record.cli.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

clear_record/cli/cli.py

@@ -0,0 +1,403 @@
+"""The `clear-record` CLI.
+
+One subcommand per pipeline stage (plus `run`/`calibrate` conveniences). The
+subcommand surface is derived from the pipeline spec so the CLI and domain cannot
+drift; the heavy per-stage logic lives in :mod:`clear_record.cli.stages`.
+
+Recordings and model weights are environment-local data — never commit them.
+See docs/architecture.md §6 and ADR-0006.
+"""
+
+from __future__ import annotations
+
+import argparse
+from typing import Sequence
+
+from clear_record.core import Step, pipeline_spec
+from clear_record.providers import BACKENDS, available_backend_ids, resolve_models_dir
+from clear_record.engine import DEFAULT_CHUNK_S, DEFAULT_OVERLAP_S
+
+from clear_record.cli import stages
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="clear-record",
+        description="clear-record: from many recordings to one clear record.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    def _paths(p: argparse.ArgumentParser) -> None:
+        p.add_argument("directory", help="workspace directory (recordings live here)")
+        p.add_argument(
+            "inputs",
+            nargs="*",
+            help="explicit audio file(s); default: scan the directory",
+        )
+
+    def _backend_args(p: argparse.ArgumentParser) -> None:
+        default_backend = next(iter(BACKENDS))
+        models_dir = resolve_models_dir()
+        p.add_argument(
+            "--backend",
+            "-b",
+            default=default_backend,
+            choices=tuple(BACKENDS),
+            help=f"ASR backend (default {default_backend})",
+        )
+        p.add_argument(
+            "--model",
+            "-m",
+            help="model checkpoint name/size, e.g. tiny/base/small/medium",
+        )
+        p.add_argument("--language", "-l", help="language hint for ASR (default auto)")
+        p.add_argument(
+            "--models-dir",
+            default=models_dir,
+            help=f"model download dir (default {models_dir})",
+        )
+        p.add_argument(
+            "--glossary",
+            help="glossary file (one term/line) used as the ASR initial prompt; "
+            "defaults to <directory>/glossary.txt if present",
+        )
+        p.add_argument(
+            "--chunk-seconds",
+            type=float,
+            default=DEFAULT_CHUNK_S,
+            help=f"chunk length for long tape transcription (default {DEFAULT_CHUNK_S:.0f}s)",
+        )
+        p.add_argument(
+            "--overlap-seconds",
+            type=float,
+            default=DEFAULT_OVERLAP_S,
+            help=f"overlap between chunks (default {DEFAULT_OVERLAP_S:.0f}s)",
+        )
+        p.add_argument(
+            "--no-resume",
+            dest="resume",
+            action="store_false",
+            help="ignore cached chunks and re-transcribe from scratch",
+        )
+        p.set_defaults(resume=True)
+        p.add_argument(
+            "--jobs",
+            "-j",
+            type=int,
+            default=0,
+            help="parallel transcription workers (0 = auto; process-isolated "
+            "backends only, e.g. the AMD/NVIDIA whisper-cli)",
+        )
+        p.add_argument(
+            "--check-plugin",
+            action="store_true",
+            help="one-shot whisper-cli load probe to confirm the ggml GPU plugin "
+            "actually loads before transcribing (opt-in; the default probe only "
+            "checks that the plugin file is present)",
+        )
+
+    def _diarize_args(p: argparse.ArgumentParser) -> None:
+        g = p.add_mutually_exclusive_group()
+        g.add_argument(
+            "--diarize",
+            dest="diarize",
+            action="store_true",
+            help="force multi-speaker diarization",
+        )
+        g.add_argument(
+            "--no-diarize",
+            dest="diarize",
+            action="store_false",
+            help="disable diarization",
+        )
+        p.set_defaults(diarize=None)
+        p.add_argument(
+            "--speakers",
+            type=int,
+            default=None,
+            help="known number of speakers (default: estimate from the audio)",
+        )
+
+    def _attribute_args(p: argparse.ArgumentParser) -> None:
+        p.add_argument(
+            "--attribute-energy",
+            action="store_true",
+            help="attribute speakers by relative source energy (close-mic "
+            "cross-talk) instead of spectral diarization",
+        )
+        p.add_argument(
+            "--mixed-source",
+            default=None,
+            help="manifest source id to use as the mixed/room reference for "
+            "energy attribution",
+        )
+        p.add_argument(
+            "--window-s",
+            dest="window_s",
+            type=float,
+            default=None,
+            help="seconds of causal history for a rolling per-source level "
+            "(tracks drifting gain); omit for the static whole-recording level",
+        )
+
+    def _common_args(p: argparse.ArgumentParser) -> None:
+        p.add_argument(
+            "--reference",
+            dest="reference",
+            help="reference source id for alignment (default: first)",
+        )
+
+    def _directory(p: argparse.ArgumentParser) -> None:
+        p.add_argument("directory", help="workspace directory (recordings live here)")
+
+    def _backend(directory_first: bool):
+        def fn(p: argparse.ArgumentParser) -> None:
+            if directory_first:
+                _directory(p)
+            _backend_args(p)
+
+        return fn
+
+    def _channel_args(p: argparse.ArgumentParser) -> None:
+        g = p.add_mutually_exclusive_group()
+        g.add_argument(
+            "--split-channels",
+            dest="split",
+            action="store_const",
+            const="split",
+            help="split every channel of a multichannel file into its own source",
+        )
+        g.add_argument(
+            "--mix-down",
+            dest="split",
+            action="store_const",
+            const="mix",
+            help="always downmix multichannel audio to mono",
+        )
+        p.set_defaults(split="auto")
+
+    # One CLI arg-builder per declared stage. The stage order, names and help
+    # text come from the spec; only the flags (what a stage accepts) are local.
+    stage_args = {
+        Step.INGEST: lambda p: (_paths(p), _channel_args(p)),
+        Step.ALIGN: _directory,
+        Step.TRANSCRIBE: _backend(directory_first=True),
+        Step.RECONCILE: _directory,
+        Step.EXPORT: _directory,
+    }
+    for stage in pipeline_spec().stages:
+        p = sub.add_parser(stage.step.value, help=stage.help)
+        stage_args[stage.step](p)
+        _common_args(p)
+
+    # pipeline run: every stage above, in spec order
+    run_parser = sub.add_parser("run", help=pipeline_spec().run_help())
+    _backend(directory_first=True)(run_parser)
+    _channel_args(run_parser)
+    _diarize_args(run_parser)
+    _attribute_args(run_parser)
+    _common_args(run_parser)
+
+    # calibration convenience
+    cal = sub.add_parser(
+        "calibrate",
+        help="run the pipeline and report transcript quality against a reference if given",
+    )
+    cal.add_argument("directory", help="workspace directory")
+    _backend_args(cal)
+    _channel_args(cal)
+    _diarize_args(cal)
+    _attribute_args(cal)
+    _common_args(cal)
+    cal.add_argument(
+        "--reference-transcript",
+        help="a reference transcript text file to compare (WER/similarity)",
+    )
+
+    # diarization (multi-speaker attribution for a single mixed stream)
+    dia = sub.add_parser(
+        "diarize", help="assign speaker labels to already-transcribed segments"
+    )
+    dia.add_argument("directory", help="workspace directory")
+    _diarize_args(dia)
+
+    # cross-talk-aware attribution (close mics hear more than one speaker)
+    attr = sub.add_parser(
+        "attribute",
+        help="re-attribute speakers by relative source energy (close-mic cross-talk)",
+    )
+    attr.add_argument("directory", help="workspace directory")
+    attr.add_argument(
+        "--mixed-source",
+        default=None,
+        help="manifest source id to use as the mixed/room reference",
+    )
+    attr.add_argument(
+        "--window-s",
+        dest="window_s",
+        type=float,
+        default=None,
+        help="seconds of causal history for a rolling per-source level "
+        "(tracks drifting gain); omit for the static whole-recording level",
+    )
+
+    # glossary (decoder initial prompt; edit while a pass runs in the background)
+    glo = sub.add_parser(
+        "glossary",
+        help="show or append to the workspace glossary (ASR initial prompt)",
+    )
+    glo.add_argument("directory", help="workspace directory")
+    glo.add_argument(
+        "--add", nargs="*", default=None, help="term(s)/phrase(s) to append"
+    )
+
+    # synthesis (owner strategy: build the badness, keep the ground truth)
+    syn = sub.add_parser(
+        "synth",
+        help="generate a clean scene + degraded per-device recordings with exact ground truth",
+    )
+    syn.add_argument("directory", help="output workspace directory")
+    syn.add_argument(
+        "--devices", type=int, default=4, help="number of recording devices (default 4)"
+    )
+    syn.add_argument(
+        "--duration",
+        type=float,
+        default=20.0,
+        help="scene duration in seconds (default 20)",
+    )
+    syn.add_argument(
+        "--speakers",
+        type=int,
+        default=4,
+        help="number of speakers in the scene (default 4)",
+    )
+    syn.add_argument("--seed", type=int, default=0, help="random seed")
+
+    # backends
+    b = sub.add_parser(
+        "backends", help="list which ASR backends are currently available"
+    )
+    b.add_argument(
+        "--all",
+        action="store_true",
+        help="list all known backends, not only available ones",
+    )
+
+    return parser
+
+
+def _pipeline_options(args: argparse.Namespace) -> stages.PipelineOptions:
+    """Fill the one run-options value from the parsed CLI arguments."""
+    return stages.PipelineOptions(
+        backend=args.backend,
+        model=args.model,
+        language=args.language,
+        model_dir=args.models_dir,
+        split=args.split,
+        glossary=args.glossary,
+        chunk_seconds=args.chunk_seconds,
+        overlap_seconds=args.overlap_seconds,
+        resume=args.resume,
+        do_diarize=args.diarize,
+        speakers=args.speakers,
+        reference=args.reference,
+        attribute_energy=args.attribute_energy,
+        mixed_source=args.mixed_source,
+        window_s=args.window_s,
+        jobs=args.jobs,
+        check_plugin=args.check_plugin,
+    )
+
+
+def _main(args: argparse.Namespace) -> int:
+    command = args.command
+
+    if command == "backends":
+        known = tuple(BACKENDS)
+        available = available_backend_ids()
+        for bid in known:
+            state = "available" if bid in available else "unavailable"
+            if not args.all and state != "available":
+                continue
+            print(f"{bid:8s} {state}")
+        return 0
+
+    if command == "synth":
+        stages.synth(
+            args.directory,
+            devices=args.devices,
+            duration_s=args.duration,
+            speakers=args.speakers,
+            seed=args.seed,
+        )
+        return 0
+
+    if command == "ingest":
+        stages.ingest(args.directory, audio_files=args.inputs or None, split=args.split)
+        return 0
+
+    if command == "align":
+        stages.align(args.directory, reference=args.reference)
+        return 0
+
+    if command == "transcribe":
+        stages.transcribe(
+            args.directory,
+            args.backend,
+            model=args.model,
+            language=args.language,
+            model_dir=args.models_dir,
+            glossary=args.glossary,
+            chunk_seconds=args.chunk_seconds,
+            overlap_seconds=args.overlap_seconds,
+            resume=args.resume,
+            jobs=args.jobs,
+            check_plugin=args.check_plugin,
+        )
+        return 0
+
+    if command == "diarize":
+        stages.diarize(args.directory, speakers=args.speakers)
+        return 0
+
+    if command == "attribute":
+        stages.attribute(
+            args.directory,
+            mixed_source=args.mixed_source,
+            window_s=args.window_s,
+        )
+        return 0
+
+    if command == "glossary":
+        stages.glossary(args.directory, add=args.add)
+        return 0
+
+    if command == "reconcile":
+        stages.reconcile(args.directory, prefer=args.reference)
+        return 0
+
+    if command == "export":
+        stages.export(args.directory)
+        return 0
+
+    if command == "run":
+        stages.run(args.directory, _pipeline_options(args))
+        return 0
+
+    if command == "calibrate":
+        stages.run(args.directory, _pipeline_options(args))
+        stages.calibrate_report(args.directory, reference=args.reference_transcript)
+        return 0
+
+    return 2
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    return _main(args)
+
+
+if __name__ == "__main__":  # pragma: no cover - console-script path
+    raise SystemExit(main())

clear_record/cli/eval.py

@@ -0,0 +1,66 @@
+"""Transcript evaluation helpers used by the `calibrate` command.
+
+These compare an ASR transcript against a reference transcript. For Latin-script
+text we tokenize on whitespace; for CJK text we tokenize per character (no
+reliable word segmentation without a dictionary). The error metric is a Levenshtein
+edit distance over the token sequences, reported as an error rate (0.0 = perfect).
+"""
+
+from __future__ import annotations
+
+import re
+
+_CJK = re.compile(r"[\u4e00-\u9fff\u3400-\u4dbf\uf900-\ufaff]")
+
+
+def _tokenize(text: str) -> list[str]:
+    text = " ".join(text.split()).lower()
+    if _CJK.search(text):
+        # keep CJK chars as tokens, treat runs of non-CJK as tokens
+        tokens: list[str] = []
+        for run in re.findall(
+            r"[\u4e00-\u9fff\u3400-\u4dbf\uf900-\ufaff]+|[^\u4e00-\u9fff\u3400-\u4dbf\uf900-\ufaff]+",
+            text,
+        ):
+            if _CJK.match(run):
+                tokens.extend(list(run))
+            elif run.strip():
+                tokens.append(run.strip())
+        return tokens
+    return text.split()
+
+
+def levenshtein(a: list[str], b: list[str]) -> int:
+    """Classic DP edit distance over token sequences."""
+    if not a:
+        return len(b)
+    if not b:
+        return len(a)
+    prev = list(range(len(b) + 1))
+    for i, ca in enumerate(a, start=1):
+        cur = [i] + [0] * len(b)
+        for j, cb in enumerate(b, start=1):
+            cur[j] = min(
+                prev[j] + 1,  # delete
+                cur[j - 1] + 1,  # insert
+                prev[j - 1] + (0 if ca == cb else 1),  # replace/substitute
+            )
+        prev = cur
+    return prev[len(b)]
+
+
+def error_rates(reference: str, hypothesis: str) -> dict[str, float]:
+    """Return ``wer`` and ``cer``-style error rate + similarity.
+
+    ``wer`` uses word/character tokens (see :func:`_tokenize`); ``similarity`` is
+    a ``1 - error`` score in [0, 1].
+    """
+    ref_tokens = _tokenize(reference)
+    hyp_tokens = _tokenize(hypothesis)
+    err = levenshtein(ref_tokens, hyp_tokens)
+    denom = max(1, len(ref_tokens))
+    wer = err / denom
+    return {"wer": round(wer, 4), "similarity": round(1.0 - wer, 4)}
+
+
+__all__ = ["error_rates", "levenshtein", "_tokenize"]