legendaria 0.1.0.dev0__tar.gz

legendaria-0.1.0.dev0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+
+# Node
+node_modules/
+
+# Environment
+.env
+.env.*
+
+# Media / outputs
+*.mp4
+*.mov
+*.mkv
+*.wav
+*.mp3
+output/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+
+# Local-only notes (contain private data, never pushed)
+docs/whisper-blender-brainstorm.md
+docs/local/

legendaria-0.1.0.dev0/.python-version

@@ -0,0 +1 @@
+3.11

legendaria-0.1.0.dev0/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-0.1.0.dev0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,25 @@
+# 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/legendaria_engine/__init__.py

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

legendaria-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-0.1.0.dev0/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-0.1.0.dev0/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-0.1.0.dev0/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-0.1.0.dev0/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-0.1.0.dev0/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-0.1.0.dev0/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-0.1.0.dev0/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}