legendaria 0.1.0.dev0__py3-none-any.whl

legendaria-0.1.0.dev0.dist-info/METADATA

@@ -0,0 +1,53 @@
+Metadata-Version: 2.5
+Name: legendaria
+Version: 0.1.0.dev0
+Summary: Legendária transcription engine: local Whisper transcription with word timings (CLI: flosub).
+Project-URL: Homepage, https://github.com/flou-ainan/Legendaria
+Project-URL: Issues, https://github.com/flou-ainan/Legendaria/issues
+Author: flou-ainan
+License-Expression: MIT
+License-File: LICENSE
+Keywords: captions,srt,subtitles,transcription,vtt,whisper
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Requires-Dist: faster-whisper<2,>=1.2
+Requires-Dist: platformdirs>=4
+Provides-Extra: cuda
+Requires-Dist: nvidia-cublas-cu12>=12.1; (sys_platform == 'linux' or sys_platform == 'win32') and extra == 'cuda'
+Requires-Dist: nvidia-cudnn-cu12<10,>=9; (sys_platform == 'linux' or sys_platform == 'win32') and extra == 'cuda'
+Provides-Extra: test
+Requires-Dist: jsonschema>=4; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Legendária engine (`flosub`)
+
+The transcription engine of [Legendária](https://github.com/flou-ainan/Legendaria): it runs Whisper (faster-whisper) locally and writes subtitles with per-word timings. The Blender add-on uses it, and it also works on its own:
+
+```bash
+flosub transcribe video.mp4                  # writes video.json, video.srt, video.vtt
+flosub transcribe talk.mp3 --language pt --model medium --format srt
+flosub export video.json --format vtt
+flosub models list
+flosub models download medium
+flosub config show
+```
+
+GPU acceleration works on NVIDIA cards (Linux and Windows) with the `cuda` extra; everything else runs on the CPU.
+
+## Development
+
+```bash
+cd engine
+uv sync --extra test             # add --extra cuda for NVIDIA GPUs
+uv run flosub --help
+uv run pytest
+```
+
+License: MIT.

legendaria-0.1.0.dev0.dist-info/RECORD

@@ -0,0 +1,18 @@
+legendaria_engine/__init__.py,sha256=MPAwSSVJZYAAb3BiB2icS6JDIIUx4XASImZnl02Pzrw,68
+legendaria_engine/__main__.py,sha256=ehub8H7TSg1vaWOEpxRpoUvrSGtWqyezQmbALhLzdbg,109
+legendaria_engine/cli.py,sha256=zyPVYRTD-BuJAqKtA9t6aAQPJ-J6Lu5sMYWojAwJqf0,7518
+legendaria_engine/config.py,sha256=KPOsLvbeqMu2ELroYFTCjPHXeSMcmJvm6hfrm6Ey09Q,3394
+legendaria_engine/cuda_libs.py,sha256=qM0aledDWNvRdhh0C-PKyVpj1S0WdV1IBQmf5Stzf_s,2130
+legendaria_engine/events.py,sha256=w5_1RqjVpABAPKIiU5F1-f0x42ZYDyUcDAkHHSs-1T8,4181
+legendaria_engine/formats.py,sha256=VC0kKrw-wYyicbywyLSCvYxDC2I6oTollmPYM6ZeJ8Y,1285
+legendaria_engine/models.py,sha256=jmboG325nOG3Kuo8AAjHfURuyG6sKyMGACTRZIn6dls,3763
+legendaria_engine/paths.py,sha256=zmheUq0xUszXjafHJM-sSqb4FAhkso3Xe_G4btJS_gw,1277
+legendaria_engine/schema.py,sha256=HrH8SyWt0dIfxk1scLzZny8csI5Cr5Int1i3lGWuPHs,2261
+legendaria_engine/transcriber.py,sha256=8YTo8OONDdi49ovOTG_QK-baKYXNNJqTQxIltjK0SOo,4627
+legendaria_engine/defaults/config.json,sha256=drJf1ulVDsy1DrsVIjOBEBfm3EvDXCYum91oSNZHVUY,402
+legendaria_engine/defaults/models.json,sha256=mF7pq7KOPXA34DDMb_B7LB2thwgG2eKq4JQyhoxxEl0,1098
+legendaria-0.1.0.dev0.dist-info/METADATA,sha256=guhlqGJJoxc0MksWElmuEce_tNx_y7dxS0i5wLR4tz8,2048
+legendaria-0.1.0.dev0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+legendaria-0.1.0.dev0.dist-info/entry_points.txt,sha256=Id1pLQ07QxLpnLa9x05Hz9D6xwlnxYpOUSIrJ0oezBU,54
+legendaria-0.1.0.dev0.dist-info/licenses/LICENSE,sha256=tLprFKV4YZ3aIIwJcfMGx4iKfPJbBA0hP0XOBNAtm8s,1067
+legendaria-0.1.0.dev0.dist-info/RECORD,,

legendaria-0.1.0.dev0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

legendaria-0.1.0.dev0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+flosub = legendaria_engine.cli:main

legendaria-0.1.0.dev0.dist-info/licenses/LICENSE

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

legendaria_engine/__init__.py

@@ -0,0 +1,3 @@
+"""Legendária transcription engine."""
+
+__version__ = "0.1.0.dev0"

legendaria_engine/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m legendaria_engine`."""
+
+from legendaria_engine.cli import main
+
+raise SystemExit(main())

legendaria_engine/cli.py

@@ -0,0 +1,194 @@
+"""`flosub` command line: transcribe, export, models, config."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from legendaria_engine import __version__, paths
+from legendaria_engine.config import ConfigError, load_config
+from legendaria_engine.events import Reporter, make_reporter
+from legendaria_engine.formats import FORMATS, WRITERS
+from legendaria_engine.schema import Transcript
+
+
+def write_outputs(transcript: Transcript, stem: Path, formats: list[str]) -> list[str]:
+    """Write the requested formats next to `stem` (no extension); returns the paths."""
+    stem.parent.mkdir(parents=True, exist_ok=True)
+    written = []
+    for fmt in formats:
+        target = stem.with_suffix(f".{fmt}")
+        if fmt == "json":
+            transcript.save(target)
+        else:
+            target.write_text(WRITERS[fmt](transcript), encoding="utf-8")
+        written.append(str(target))
+    return written
+
+
+def parse_formats(value: str | None) -> list[str] | None:
+    """argparse type: comma-separated format list, validated against FORMATS."""
+    if value is None:
+        return None
+    formats = [f.strip().lower() for f in value.split(",") if f.strip()]
+    unknown = [f for f in formats if f not in FORMATS]
+    if unknown:
+        raise argparse.ArgumentTypeError(f"unknown format(s): {', '.join(unknown)}")
+    return formats
+
+
+def cmd_transcribe(args: argparse.Namespace, reporter: Reporter) -> int:
+    """`flosub transcribe`: resolve config and model, transcribe, write the outputs."""
+    media = Path(args.file).expanduser().resolve()
+    if not media.is_file():
+        reporter.error(f"File not found: {media}")
+        return 2
+    config = load_config(
+        {
+            "model": args.model,
+            "language": args.language,
+            "device": args.device,
+            "formats": args.format,
+        }
+    )
+    if config["device"] != "cpu":  # make pip-installed CUDA libraries loadable (may re-exec)
+        from legendaria_engine.cuda_libs import ensure_cuda_libs
+
+        ensure_cuda_libs()
+    from legendaria_engine import models
+    from legendaria_engine.transcriber import Options, get_backend
+
+    language = None if config["language"] == "auto" else config["language"]
+    options = Options(
+        model=config["model"],
+        model_path=models.resolve(config["model"], reporter),
+        language=language,
+        device=config["device"],
+        compute_type=config["compute_type"],
+        beam_size=config["beam_size"],
+        vad_filter=config["vad_filter"],
+        word_timestamps=config["word_timestamps"],
+    )
+    transcript = get_backend(config.get("backend", "faster-whisper")).transcribe(
+        media, options, reporter
+    )
+    out_dir = Path(args.output_dir).expanduser() if args.output_dir else media.parent
+    outputs = write_outputs(transcript, out_dir / media.stem, config["formats"])
+    reporter.emit(
+        "done", outputs=outputs, segments=len(transcript.segments), language=transcript.language
+    )
+    return 0
+
+
+def cmd_export(args: argparse.Namespace, reporter: Reporter) -> int:
+    """`flosub export`: convert a transcript JSON to SRT/VTT."""
+    source = Path(args.file).expanduser()
+    transcript = Transcript.load(source)
+    stem = Path(args.output).with_suffix("") if args.output else source.with_suffix("")
+    outputs = write_outputs(transcript, stem, args.format)
+    reporter.emit("done", outputs=outputs, segments=len(transcript.segments))
+    return 0
+
+
+def cmd_models(args: argparse.Namespace, reporter: Reporter) -> int:
+    """`flosub models list|download`."""
+    from legendaria_engine import models
+
+    if args.action == "download":
+        path = models.download(args.name, reporter)
+        reporter.emit("done", outputs=[str(path)])
+        return 0
+    entries = models.list_models()
+    if args.json:
+        print(
+            json.dumps(
+                {"models_dir": str(paths.models_dir()), "models": entries}, ensure_ascii=False
+            )
+        )
+    else:
+        default = load_config()["model"]
+        for m in entries:
+            mark = "✓" if m["installed"] else " "
+            star = " (default)" if m["name"] == default else ""
+            print(
+                f"[{mark}] {m['name']:<16} {m.get('size_mb', '?'):>5} MB  {m.get('notes', '')}{star}"
+            )
+        print(f"\nModels folder: {paths.models_dir()}")
+    return 0
+
+
+def cmd_config(args: argparse.Namespace, reporter: Reporter) -> int:
+    """`flosub config show|path`."""
+    if args.action == "path":
+        print(paths.user_config_file())
+    else:
+        print(json.dumps(load_config(), ensure_ascii=False, indent=2))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """The argparse tree for all subcommands."""
+    parser = argparse.ArgumentParser(
+        prog="flosub", description="Legendária: local automatic subtitles."
+    )
+    parser.add_argument("--version", action="version", version=f"flosub {__version__}")
+    parser.add_argument(
+        "--progress",
+        choices=["auto", "json", "human"],
+        default="auto",
+        help="progress output: JSON lines (for programs) or human-readable (default: human in a terminal)",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    t = sub.add_parser("transcribe", help="transcribe an audio or video file")
+    t.add_argument("file")
+    t.add_argument("--model", help="model name (see `flosub models list`) or a model folder")
+    t.add_argument("--language", help="language code (pt, en, ...) or 'auto'")
+    t.add_argument("--device", choices=["auto", "cuda", "cpu"])
+    t.add_argument("--format", type=parse_formats, help="comma-separated: json,srt,vtt")
+    t.add_argument("--output-dir", help="where to write the files (default: next to the input)")
+    t.set_defaults(func=cmd_transcribe)
+
+    e = sub.add_parser("export", help="convert a transcript JSON to SRT/VTT")
+    e.add_argument("file")
+    e.add_argument("--format", type=parse_formats, default=["srt"], help="comma-separated: srt,vtt")
+    e.add_argument("--output", help="output path without extension (default: next to the JSON)")
+    e.set_defaults(func=cmd_export)
+
+    m = sub.add_parser("models", help="list or download Whisper models")
+    m_sub = m.add_subparsers(dest="action", required=True)
+    m_list = m_sub.add_parser("list")
+    m_list.add_argument("--json", action="store_true", help="machine-readable output")
+    m_dl = m_sub.add_parser("download")
+    m_dl.add_argument("name")
+    m.set_defaults(func=cmd_models)
+
+    c = sub.add_parser("config", help="show the merged config or the user config path")
+    c.add_argument("action", choices=["show", "path"])
+    c.set_defaults(func=cmd_config)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point: run a subcommand and turn every failure into an `error` event."""
+    args = build_parser().parse_args(argv)
+    reporter = make_reporter(args.progress)
+    try:
+        return args.func(args, reporter)
+    except (ConfigError, KeyError, ValueError, RuntimeError, OSError) as exc:
+        reporter.error(str(exc).strip("'\""))
+        return 1
+    except KeyboardInterrupt:
+        reporter.error("Cancelled.")
+        return 130
+    except Exception as exc:  # unexpected: still report it as an event the add-on can show
+        reporter.error(f"{type(exc).__name__}: {exc}")
+        return 1
+    finally:
+        reporter.close()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

legendaria_engine/config.py

@@ -0,0 +1,88 @@
+"""Layered JSON configuration: shipped defaults → user file → command-line values."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from legendaria_engine import paths
+
+DEVICES = ("auto", "cuda", "cpu")
+
+
+class ConfigError(ValueError):
+    """A config file is malformed or holds an invalid value."""
+
+
+def read_json(path: Path) -> dict[str, Any]:
+    """Read a JSON object from a file, dropping `$schema`; raise ConfigError on bad JSON."""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ConfigError(f"{path}: invalid JSON at line {exc.lineno}: {exc.msg}") from exc
+    if not isinstance(data, dict):
+        raise ConfigError(f"{path}: the top level must be a JSON object")
+    data.pop("$schema", None)
+    return data
+
+
+def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Return `base` updated with `override`; nested objects are merged key by key."""
+    merged = dict(base)
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = deep_merge(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def validate(config: dict[str, Any], source: str = "config") -> None:
+    """Check the values the engine relies on, with errors that name the bad key."""
+    checks: list[tuple[str, type | tuple[type, ...]]] = [
+        ("model", str),
+        ("language", str),
+        ("device", str),
+        ("compute_type", dict),
+        ("beam_size", int),
+        ("vad_filter", bool),
+        ("word_timestamps", bool),
+        ("formats", list),
+    ]
+    for key, expected in checks:
+        if not isinstance(config.get(key), expected):
+            raise ConfigError(
+                f"{source}: '{key}' must be of type {getattr(expected, '__name__', expected)}"
+            )
+    if config["device"] not in DEVICES:
+        raise ConfigError(f"{source}: 'device' must be one of {', '.join(DEVICES)}")
+    from legendaria_engine.formats import FORMATS
+
+    unknown = [f for f in config["formats"] if f not in FORMATS]
+    if unknown:
+        raise ConfigError(f"{source}: unknown format(s) {unknown}; use {', '.join(FORMATS)}")
+
+
+def load_config(overrides: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Defaults, then the user's `config.json` if present, then non-None `overrides`."""
+    config = read_json(paths.defaults_dir() / "config.json")
+    user_file = paths.user_config_file()
+    if user_file.is_file():
+        config = deep_merge(config, read_json(user_file))
+    if overrides:
+        config = deep_merge(config, {k: v for k, v in overrides.items() if v is not None})
+    validate(config)
+    return config
+
+
+def load_models() -> dict[str, dict[str, Any]]:
+    """The model catalog: shipped `models.json` plus the user's additions or changes."""
+    catalog = read_json(paths.defaults_dir() / "models.json")["models"]
+    user_file = paths.user_models_file()
+    if user_file.is_file():
+        catalog = deep_merge(catalog, read_json(user_file).get("models", {}))
+    for name, entry in catalog.items():
+        if not isinstance(entry, dict) or not isinstance(entry.get("repo"), str):
+            raise ConfigError(f"models.json: model '{name}' needs a 'repo' string")
+    return catalog

legendaria_engine/cuda_libs.py

@@ -0,0 +1,56 @@
+"""Make the NVIDIA libraries installed by pip (cuBLAS, cuDNN) visible to CTranslate2.
+
+The `nvidia-*-cu12` wheels put their shared libraries inside site-packages, where the
+dynamic loader does not look. Without this, GPU transcription aborts with
+"Unable to load libcudnn_ops.so.9".
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import sys
+from pathlib import Path
+
+_REEXEC_FLAG = "LEGENDARIA_CUDA_LIBS_SET"
+
+
+def nvidia_lib_dirs() -> list[Path]:
+    """Library folders of the installed `nvidia.*` packages (empty when not installed)."""
+    spec = importlib.util.find_spec("nvidia")
+    if spec is None or not spec.submodule_search_locations:
+        return []
+    sub = "bin" if sys.platform == "win32" else "lib"
+    dirs = []
+    for root in spec.submodule_search_locations:
+        for pkg in ("cublas", "cudnn"):
+            candidate = Path(root) / pkg / sub
+            if candidate.is_dir():
+                dirs.append(candidate)
+    return dirs
+
+
+def ensure_cuda_libs() -> None:
+    """Expose the NVIDIA libraries to the current process. Call before importing ctranslate2.
+
+    - Linux: `LD_LIBRARY_PATH` is only read at process start, so the process re-executes
+      itself once with the folders added.
+    - Windows: register the DLL folders and prepend them to PATH.
+    - macOS / no NVIDIA packages: nothing to do.
+    """
+    dirs = nvidia_lib_dirs()
+    if not dirs:
+        return
+    if sys.platform == "win32":
+        for d in dirs:
+            os.add_dll_directory(str(d))
+        os.environ["PATH"] = os.pathsep.join([*map(str, dirs), os.environ.get("PATH", "")])
+    elif sys.platform.startswith("linux"):
+        current = os.environ.get("LD_LIBRARY_PATH", "")
+        missing = [str(d) for d in dirs if str(d) not in current.split(os.pathsep)]
+        if missing and not os.environ.get(_REEXEC_FLAG):
+            os.environ["LD_LIBRARY_PATH"] = os.pathsep.join(
+                [*missing, current] if current else missing
+            )
+            os.environ[_REEXEC_FLAG] = "1"
+            os.execv(sys.executable, [sys.executable, "-m", "legendaria_engine", *sys.argv[1:]])

legendaria_engine/defaults/config.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://raw.githubusercontent.com/flou-ainan/Legendaria/main/engine/schemas/config.schema.json",
+  "version": 1,
+  "model": "small",
+  "language": "auto",
+  "device": "auto",
+  "compute_type": {
+    "cuda": "float16",
+    "cpu": "int8"
+  },
+  "beam_size": 5,
+  "vad_filter": true,
+  "word_timestamps": true,
+  "formats": ["json", "srt", "vtt"],
+  "ui_languages": ["auto", "pt", "en"]
+}

legendaria_engine/defaults/models.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://raw.githubusercontent.com/flou-ainan/Legendaria/main/engine/schemas/models.schema.json",
+  "version": 1,
+  "models": {
+    "tiny": {"repo": "Systran/faster-whisper-tiny", "size_mb": 75, "vram_mb": 1000, "notes": "Fastest, lowest accuracy. Good for quick drafts."},
+    "base": {"repo": "Systran/faster-whisper-base", "size_mb": 145, "vram_mb": 1000, "notes": "Fast, fair accuracy."},
+    "small": {"repo": "Systran/faster-whisper-small", "size_mb": 485, "vram_mb": 2000, "notes": "Default: good balance of speed and accuracy."},
+    "medium": {"repo": "Systran/faster-whisper-medium", "size_mb": 1530, "vram_mb": 5000, "notes": "More accurate, especially for technical terms. Needs a GPU for comfortable speed."},
+    "large-v3": {"repo": "Systran/faster-whisper-large-v3", "size_mb": 3100, "vram_mb": 10000, "notes": "Most accurate. Slow on CPU; in fp16 needs about 4.5 GB of VRAM."},
+    "large-v3-turbo": {"repo": "mobiuslabsgmbh/faster-whisper-large-v3-turbo", "size_mb": 1620, "vram_mb": 6000, "notes": "Near large-v3 accuracy, much faster. Great on 8 GB GPUs."}
+  }
+}

legendaria_engine/events.py

@@ -0,0 +1,111 @@
+"""Progress reporting: JSON lines for programs (the Blender add-on), a progress bar for humans.
+
+Every JSON event is one object per line on stdout with an `event` key:
+`start`, `progress`, `model_download`, `log`, `warning`, `done`, `error`.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, TextIO
+
+
+class Reporter:
+    """Base reporter. Subclasses decide how events are shown."""
+
+    def emit(self, event: str, **data: Any) -> None:
+        """Send one event."""
+        raise NotImplementedError
+
+    def progress(self, current: float, total: float) -> None:
+        """Transcription progress in seconds of media."""
+        self.emit("progress", t=round(current, 2), total=round(total, 2))
+
+    def log(self, message: str) -> None:
+        """Informational message."""
+        self.emit("log", message=message)
+
+    def warning(self, message: str) -> None:
+        """Non-fatal problem (e.g. GPU fallback)."""
+        self.emit("warning", message=message)
+
+    def error(self, message: str) -> None:
+        """Fatal problem; the command exits with a non-zero code."""
+        self.emit("error", message=message)
+
+    def close(self) -> None:
+        """Release any resource (e.g. a progress bar)."""
+
+
+class JsonReporter(Reporter):
+    """Machine-readable events, one JSON object per line."""
+
+    def __init__(self, stream: TextIO | None = None) -> None:
+        self.stream = stream or sys.stdout
+
+    def emit(self, event: str, **data: Any) -> None:
+        """Write the event as one JSON line and flush, so readers see it at once."""
+        self.stream.write(json.dumps({"event": event, **data}, ensure_ascii=False) + "\n")
+        self.stream.flush()
+
+
+class HumanReporter(Reporter):
+    """Readable output on stderr, with a tqdm bar for transcription progress."""
+
+    def __init__(self, stream: TextIO | None = None) -> None:
+        self.stream = stream or sys.stderr
+        self._bar = None
+        self._last = 0.0
+
+    def emit(self, event: str, **data: Any) -> None:
+        """Render the event as text: progress bar, messages, saved files."""
+        if event == "progress":
+            self._progress(data["t"], data["total"])
+        elif event == "model_download":
+            if data.get("finished"):
+                self.stream.write(f"\rDownloading model {data.get('model', '')}: done   \n")
+            else:
+                done, total = data.get("downloaded", 0), data.get("total") or 0
+                pct = f"{100 * done / total:.0f}%" if total else f"{done / 1e6:.0f} MB"
+                self.stream.write(f"\rDownloading model {data.get('model', '')}: {pct}   ")
+            self.stream.flush()
+        elif event in ("log", "warning", "error"):
+            self._close_bar()
+            prefix = {"log": "", "warning": "Warning: ", "error": "Error: "}[event]
+            self.stream.write(f"{prefix}{data.get('message', '')}\n")
+        elif event == "done":
+            self._close_bar()
+            for path in data.get("outputs", []):
+                self.stream.write(f"Saved: {path}\n")
+        elif event == "start":
+            self.stream.write(
+                f"Model {data.get('model')} on {data.get('device')} ({data.get('compute_type')}), "
+                f"language: {data.get('language') or 'auto'}\n"
+            )
+
+    def _progress(self, current: float, total: float) -> None:
+        from tqdm import tqdm
+
+        if self._bar is None:
+            self._bar = tqdm(total=round(total), unit="s", desc="Transcribing", file=self.stream)
+        step = round(current) - round(self._last)
+        if step > 0:
+            self._bar.update(step)
+        self._last = current
+
+    def _close_bar(self) -> None:
+        if self._bar is not None:
+            self._bar.close()
+            self._bar = None
+
+    def close(self) -> None:
+        """Close the progress bar, if any."""
+        self._close_bar()
+
+
+def make_reporter(mode: str = "auto") -> Reporter:
+    """`json`, `human`, or `auto` (human when stdout is a terminal, JSON otherwise)."""
+    if mode == "auto":
+        mode = "human" if sys.stdout.isatty() else "json"
+    return HumanReporter() if mode == "human" else JsonReporter()

legendaria_engine/formats.py

@@ -0,0 +1,37 @@
+"""Subtitle writers: transcript → SRT / VTT text."""
+
+from __future__ import annotations
+
+from legendaria_engine.schema import Transcript
+
+FORMATS = ("json", "srt", "vtt")
+
+
+def format_timestamp(seconds: float, separator: str = ",") -> str:
+    """`HH:MM:SS,mmm` (SRT) or `HH:MM:SS.mmm` (VTT). Hours keep counting past 24."""
+    total_ms = max(0, round(seconds * 1000))
+    hours, rest = divmod(total_ms, 3_600_000)
+    minutes, rest = divmod(rest, 60_000)
+    secs, ms = divmod(rest, 1000)
+    return f"{hours:02d}:{minutes:02d}:{secs:02d}{separator}{ms:03d}"
+
+
+def to_srt(transcript: Transcript) -> str:
+    """Numbered SRT cues, one per segment."""
+    blocks = []
+    for index, seg in enumerate(transcript.segments, start=1):
+        start, end = format_timestamp(seg.start), format_timestamp(seg.end)
+        blocks.append(f"{index}\n{start} --> {end}\n{seg.text.strip()}\n")
+    return "\n".join(blocks)
+
+
+def to_vtt(transcript: Transcript) -> str:
+    """WebVTT cues, one per segment."""
+    blocks = ["WEBVTT\n"]
+    for seg in transcript.segments:
+        start, end = format_timestamp(seg.start, "."), format_timestamp(seg.end, ".")
+        blocks.append(f"{start} --> {end}\n{seg.text.strip()}\n")
+    return "\n".join(blocks)
+
+
+WRITERS = {"srt": to_srt, "vtt": to_vtt}

legendaria_engine/models.py

@@ -0,0 +1,105 @@
+"""List, download and locate Whisper models (stored in the per-OS data dir)."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any
+
+from legendaria_engine import paths
+from legendaria_engine.config import load_models
+from legendaria_engine.events import Reporter
+
+REQUIRED_FILES = ("config.json", "model.bin", "tokenizer.json")
+ALLOW_PATTERNS = [
+    "config.json",
+    "preprocessor_config.json",
+    "model.bin",
+    "tokenizer.json",
+    "vocabulary.*",
+]
+
+
+def model_path(name: str) -> Path:
+    """Folder where a catalog model is (or will be) stored."""
+    return paths.models_dir() / name
+
+
+def is_installed(name: str) -> bool:
+    """True when the model folder has all the files CTranslate2 needs."""
+    folder = model_path(name)
+    return all((folder / f).is_file() for f in REQUIRED_FILES)
+
+
+def list_models() -> list[dict[str, Any]]:
+    """Catalog entries with an `installed` flag, in catalog order."""
+    return [
+        {"name": name, **entry, "installed": is_installed(name)}
+        for name, entry in load_models().items()
+    ]
+
+
+def _progress_class(reporter: Reporter, name: str, expected_bytes: int | None):
+    """A tqdm-compatible class that turns Hugging Face download progress into events.
+
+    It never draws anything; it counts bytes and emits `model_download` events at most
+    every 0.25 s. Hugging Face grows the byte total while it discovers files, so the
+    catalog size is used until the real total is known.
+    """
+    from tqdm.auto import tqdm
+
+    class EventTqdm(tqdm):
+        def __init__(self, *args, **kwargs):
+            self._is_bytes = kwargs.get("unit") == "B"  # skip the per-file counter
+            self._done = kwargs.get("initial", 0) or 0
+            self._last_emit = 0.0
+            kwargs["disable"] = True
+            super().__init__(*args, **kwargs)
+
+        def update(self, n=1):
+            self._done += n or 0
+            now = time.monotonic()
+            if self._is_bytes and now - self._last_emit >= 0.25:
+                self._last_emit = now
+                total = max(getattr(self, "total", None) or 0, expected_bytes or 0) or None
+                reporter.emit("model_download", model=name, downloaded=self._done, total=total)
+
+    return EventTqdm
+
+
+def download(name: str, reporter: Reporter) -> Path:
+    """Download a catalog model into the data dir; returns its folder."""
+    catalog = load_models()
+    if name not in catalog:
+        raise KeyError(f"Unknown model '{name}'. Available: {', '.join(catalog)}")
+    from huggingface_hub import snapshot_download
+    from huggingface_hub.utils import logging as hf_logging
+
+    hf_logging.set_verbosity_error()  # hide hub notices (e.g. about tokens) on stderr
+
+    target = model_path(name)
+    target.mkdir(parents=True, exist_ok=True)
+    expected = int(catalog[name]["size_mb"] * 1_000_000) if catalog[name].get("size_mb") else None
+    reporter.log(f"Downloading model '{name}' ({catalog[name].get('size_mb', '?')} MB)...")
+    snapshot_download(
+        catalog[name]["repo"],
+        local_dir=target,
+        allow_patterns=ALLOW_PATTERNS,
+        tqdm_class=_progress_class(reporter, name, expected),
+    )
+    if not is_installed(name):
+        raise RuntimeError(f"Download of '{name}' finished but files are missing in {target}")
+    reporter.emit("model_download", model=name, finished=True)
+    return target
+
+
+def resolve(name: str, reporter: Reporter) -> Path:
+    """Folder of an installed model, downloading it first when needed.
+
+    A path to an existing folder is accepted too, for custom CTranslate2 models.
+    """
+    if Path(name).is_dir():
+        return Path(name)
+    if not is_installed(name):
+        download(name, reporter)
+    return model_path(name)

legendaria_engine/paths.py

@@ -0,0 +1,42 @@
+"""Per-OS locations for user config, data and models."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from platformdirs import user_config_path, user_data_path
+
+APP_NAME = "legendaria"
+
+
+def config_dir() -> Path:
+    """Directory of the user config file; `LEGENDARIA_CONFIG_DIR` overrides it."""
+    override = os.environ.get("LEGENDARIA_CONFIG_DIR")
+    return Path(override) if override else user_config_path(APP_NAME, appauthor=False)
+
+
+def data_dir() -> Path:
+    """Directory for downloaded models and other data; `LEGENDARIA_DATA_DIR` overrides it."""
+    override = os.environ.get("LEGENDARIA_DATA_DIR")
+    return Path(override) if override else user_data_path(APP_NAME, appauthor=False)
+
+
+def user_config_file() -> Path:
+    """The user config overrides: `<config dir>/config.json`."""
+    return config_dir() / "config.json"
+
+
+def user_models_file() -> Path:
+    """User additions to the model catalog: `<config dir>/models.json`."""
+    return config_dir() / "models.json"
+
+
+def models_dir() -> Path:
+    """Where downloaded models live: `<data dir>/models`."""
+    return data_dir() / "models"
+
+
+def defaults_dir() -> Path:
+    """Shipped default JSON files inside the package."""
+    return Path(__file__).resolve().parent / "defaults"

legendaria_engine/schema.py

@@ -0,0 +1,79 @@
+"""Transcript format (JSON v1): the contract between the engine and the Blender add-on."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+SCHEMA_VERSION = 1
+
+
+@dataclass
+class Word:
+    """One recognized word with its timing (seconds) and confidence."""
+
+    start: float
+    end: float
+    word: str
+    probability: float = 1.0
+
+
+@dataclass
+class Segment:
+    """A sentence-like chunk of speech; becomes one subtitle cue."""
+
+    start: float
+    end: float
+    text: str
+    words: list[Word] = field(default_factory=list)
+
+
+@dataclass
+class Transcript:
+    """The whole transcription of one media file (JSON v1)."""
+
+    source: str
+    language: str | None
+    duration: float
+    model: str
+    device: str
+    segments: list[Segment] = field(default_factory=list)
+    language_probability: float | None = None
+    version: int = SCHEMA_VERSION
+
+    def to_dict(self) -> dict[str, Any]:
+        """Plain dict ready for JSON."""
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Transcript:
+        """Build from a dict, rejecting other schema versions."""
+        version = data.get("version")
+        if version != SCHEMA_VERSION:
+            raise ValueError(
+                f"Unsupported transcript version {version!r} (expected {SCHEMA_VERSION})"
+            )
+        segments = [
+            Segment(
+                start=s["start"],
+                end=s["end"],
+                text=s["text"],
+                words=[Word(**w) for w in s.get("words", [])],
+            )
+            for s in data["segments"]
+        ]
+        fields = {k: data[k] for k in ("source", "language", "duration", "model", "device")}
+        return cls(
+            **fields, segments=segments, language_probability=data.get("language_probability")
+        )
+
+    def save(self, path: Path) -> None:
+        """Write as pretty UTF-8 JSON."""
+        path.write_text(json.dumps(self.to_dict(), ensure_ascii=False, indent=2), encoding="utf-8")
+
+    @classmethod
+    def load(cls, path: Path) -> Transcript:
+        """Read a transcript JSON file."""
+        return cls.from_dict(json.loads(path.read_text(encoding="utf-8")))

legendaria_engine/transcriber.py

@@ -0,0 +1,133 @@
+"""Speech-to-text. A small backend interface keeps room for other engines (e.g. Apple Silicon)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from legendaria_engine.events import Reporter
+from legendaria_engine.schema import Segment, Transcript, Word
+
+
+@dataclass
+class Options:
+    """Everything a backend needs to run one transcription."""
+
+    model: str
+    model_path: Path
+    language: str | None  # None = auto-detect
+    device: str  # auto | cuda | cpu
+    compute_type: dict[str, str]
+    beam_size: int = 5
+    vad_filter: bool = True
+    word_timestamps: bool = True
+
+
+class Backend(Protocol):
+    """Interface for speech-to-text engines (faster-whisper today; Apple Silicon later)."""
+
+    name: str
+
+    def transcribe(self, media: Path, options: Options, reporter: Reporter) -> Transcript:
+        """Transcribe `media`, reporting progress, and return the transcript."""
+        ...
+
+
+def cuda_available() -> bool:
+    """True when CTranslate2 sees at least one CUDA device."""
+    try:
+        import ctranslate2
+
+        return ctranslate2.get_cuda_device_count() > 0
+    except Exception:
+        return False
+
+
+class FasterWhisperBackend:
+    """faster-whisper (CTranslate2): CUDA on NVIDIA GPUs, int8 on CPU."""
+
+    name = "faster-whisper"
+
+    def _devices(self, options: Options) -> list[str]:
+        if options.device != "auto":
+            return [options.device]
+        return ["cuda", "cpu"] if cuda_available() else ["cpu"]
+
+    def transcribe(self, media: Path, options: Options, reporter: Reporter) -> Transcript:
+        """Try each device in turn; in `auto` mode a GPU failure falls back to the CPU.
+
+        CUDA problems (missing libraries, out of memory) can surface when the model loads
+        or only once decoding starts, so the whole run is retried.
+        """
+        devices = self._devices(options)
+        for i, device in enumerate(devices):
+            try:
+                return self._run(media, options, device, reporter)
+            except Exception as exc:
+                if i == len(devices) - 1:
+                    raise RuntimeError(f"Transcription failed on {device}: {exc}") from exc
+                reporter.warning(f"GPU unavailable ({exc}); falling back to CPU, which is slower.")
+        raise AssertionError("unreachable")
+
+    def _run(self, media: Path, options: Options, device: str, reporter: Reporter) -> Transcript:
+        from faster_whisper import WhisperModel
+
+        compute_type = options.compute_type.get(device, "default")
+        model = WhisperModel(str(options.model_path), device=device, compute_type=compute_type)
+        segments_iter, info = model.transcribe(
+            str(media),
+            language=options.language,
+            beam_size=options.beam_size,
+            vad_filter=options.vad_filter,
+            word_timestamps=options.word_timestamps,
+        )
+        reporter.emit(
+            "start",
+            model=options.model,
+            device=device,
+            compute_type=compute_type,
+            language=info.language,
+            language_probability=round(info.language_probability, 4),
+            duration=round(info.duration, 2),
+        )
+        segments = []
+        for seg in segments_iter:  # lazy: decoding happens while iterating
+            words = [
+                Word(
+                    start=round(w.start, 3),
+                    end=round(w.end, 3),
+                    word=w.word,
+                    probability=round(w.probability, 4),
+                )
+                for w in (seg.words or [])
+            ]
+            segments.append(
+                Segment(
+                    start=round(seg.start, 3),
+                    end=round(seg.end, 3),
+                    text=seg.text.strip(),
+                    words=words,
+                )
+            )
+            reporter.progress(seg.end, info.duration)
+        reporter.progress(info.duration, info.duration)
+        return Transcript(
+            source=media.name,
+            language=info.language,
+            language_probability=round(info.language_probability, 4),
+            duration=round(info.duration, 2),
+            model=options.model,
+            device=device,
+            segments=segments,
+        )
+
+
+BACKENDS: dict[str, type] = {"faster-whisper": FasterWhisperBackend}
+
+
+def get_backend(name: str = "faster-whisper") -> Backend:
+    """Instantiate a backend by name."""
+    if name not in BACKENDS:
+        raise KeyError(f"Unknown backend '{name}'. Available: {', '.join(BACKENDS)}")
+    return BACKENDS[name]()