legendaria 0.1.0.dev0__tar.gz → 0.1.0.dev2__tar.gz

{legendaria-0.1.0.dev0 → legendaria-0.1.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: legendaria
-Version: 0.1.0.dev0
+Version: 0.1.0.dev2
 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

{legendaria-0.1.0.dev0 → legendaria-0.1.0.dev2}/legendaria_engine/__init__.py

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

{legendaria-0.1.0.dev0 → legendaria-0.1.0.dev2}/legendaria_engine/cli.py

@@ -9,25 +9,60 @@ from pathlib import Path
 
 from legendaria_engine import __version__, paths
 from legendaria_engine.config import ConfigError, load_config
+from legendaria_engine.cues import make_cues
 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."""
+def output_path(stem: Path, fmt: str) -> Path:
+    """`<stem>.<fmt>`, or `<stem>.cues.json`; dots in the stem are kept (`a.b.mp4` → `a.b.srt`)."""
+    suffix = "cues.json" if fmt == "cues" else fmt
+    return stem.parent / f"{stem.name}.{suffix}"
+
+
+def write_outputs(
+    transcript: Transcript, stem: Path, formats: list[str], config: dict, style: str
+) -> list[str]:
+    """Write the requested formats next to `stem` (no extension); returns the paths.
+
+    `json` is the full transcript; `cues`, `srt` and `vtt` use the cues of `style`.
+    """
     stem.parent.mkdir(parents=True, exist_ok=True)
+    rules = config["styles"][style]
+    cues = make_cues(transcript, rules, style) if set(formats) - {"json"} else None
     written = []
     for fmt in formats:
-        target = stem.with_suffix(f".{fmt}")
+        target = output_path(stem, fmt)
         if fmt == "json":
             transcript.save(target)
+        elif fmt == "cues":
+            cues.save(target)
         else:
-            target.write_text(WRITERS[fmt](transcript), encoding="utf-8")
+            target.write_text(WRITERS[fmt](cues, rules.get("line_length")), encoding="utf-8")
         written.append(str(target))
     return written
 
 
+def parse_clip(value: str) -> tuple[float, float]:
+    """`START,END` in seconds → (start, end); raises ValueError on bad input."""
+    try:
+        start, end = (float(v) for v in value.split(","))
+    except ValueError as exc:
+        raise ValueError(f"--clip must be START,END in seconds, got '{value}'") from exc
+    if start < 0 or end <= start:
+        raise ValueError(f"--clip end must be after start, got '{value}'")
+    return start, end
+
+
+def check_style(config: dict, style: str | None) -> str:
+    """The style to use: `--style` if given, else the config default; must exist."""
+    style = style or config["style"]
+    if style not in config["styles"]:
+        raise ConfigError(f"Unknown style '{style}'. Available: {', '.join(config['styles'])}")
+    return style
+
+
 def parse_formats(value: str | None) -> list[str] | None:
     """argparse type: comma-separated format list, validated against FORMATS."""
     if value is None:
@@ -53,6 +88,11 @@ def cmd_transcribe(args: argparse.Namespace, reporter: Reporter) -> int:
             "formats": args.format,
         }
     )
+    style = check_style(config, args.style)
+    clip = parse_clip(args.clip) if args.clip else None
+    if args.update and not clip:
+        reporter.error("--update needs --clip (the time range to replace)")
+        return 2
     if config["device"] != "cpu":  # make pip-installed CUDA libraries loadable (may re-exec)
         from legendaria_engine.cuda_libs import ensure_cuda_libs
 
@@ -70,12 +110,16 @@ def cmd_transcribe(args: argparse.Namespace, reporter: Reporter) -> int:
         beam_size=config["beam_size"],
         vad_filter=config["vad_filter"],
         word_timestamps=config["word_timestamps"],
+        clip=clip,
     )
     transcript = get_backend(config.get("backend", "faster-whisper")).transcribe(
         media, options, reporter
     )
+    if args.update:
+        base = Transcript.load(Path(args.update).expanduser())
+        transcript = base.merged_with(transcript, *clip)
     out_dir = Path(args.output_dir).expanduser() if args.output_dir else media.parent
-    outputs = write_outputs(transcript, out_dir / media.stem, config["formats"])
+    outputs = write_outputs(transcript, out_dir / media.stem, config["formats"], config, style)
     reporter.emit(
         "done", outputs=outputs, segments=len(transcript.segments), language=transcript.language
     )
@@ -83,12 +127,15 @@ def cmd_transcribe(args: argparse.Namespace, reporter: Reporter) -> int:
 
 
 def cmd_export(args: argparse.Namespace, reporter: Reporter) -> int:
-    """`flosub export`: convert a transcript JSON to SRT/VTT."""
+    """`flosub export`: turn a transcript JSON into cues / SRT / VTT in a given style."""
     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))
+    config = load_config()
+    style = check_style(config, args.style)
+    default_stem = source.parent / source.name.removesuffix(".json")
+    stem = Path(args.output) if args.output else default_stem
+    outputs = write_outputs(transcript, stem, args.format, config, style)
+    reporter.emit("done", outputs=outputs, segments=len(transcript.segments), style=style)
     return 0
 
 
@@ -147,13 +194,24 @@ def build_parser() -> argparse.ArgumentParser:
     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("--format", type=parse_formats, help="comma-separated: json,cues,srt,vtt")
+    t.add_argument(
+        "--style", help="cue style: subtitles (default), captions, or one from your config"
+    )
     t.add_argument("--output-dir", help="where to write the files (default: next to the input)")
+    t.add_argument("--clip", help="transcribe only START,END (seconds from the media start)")
+    t.add_argument(
+        "--update",
+        help="with --clip: transcript JSON to update; segments in the range are replaced",
+    )
     t.set_defaults(func=cmd_transcribe)
 
-    e = sub.add_parser("export", help="convert a transcript JSON to SRT/VTT")
+    e = sub.add_parser("export", help="turn a transcript JSON into cues/SRT/VTT")
     e.add_argument("file")
-    e.add_argument("--format", type=parse_formats, default=["srt"], help="comma-separated: srt,vtt")
+    e.add_argument(
+        "--format", type=parse_formats, default=["srt"], help="comma-separated: cues,srt,vtt"
+    )
+    e.add_argument("--style", help="cue style: subtitles (default), captions, or your own")
     e.add_argument("--output", help="output path without extension (default: next to the JSON)")
     e.set_defaults(func=cmd_export)
 

{legendaria-0.1.0.dev0 → legendaria-0.1.0.dev2}/legendaria_engine/config.py

@@ -9,6 +9,14 @@ from typing import Any
 from legendaria_engine import paths
 
 DEVICES = ("auto", "cuda", "cpu")
+STYLE_NUMBERS = (
+    "max_words",
+    "max_chars",
+    "line_length",
+    "max_duration",
+    "min_duration",
+    "pause_break",
+)
 
 
 class ConfigError(ValueError):
@@ -62,6 +70,19 @@ def validate(config: dict[str, Any], source: str = "config") -> None:
     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)}")
+    styles = config.get("styles")
+    if not isinstance(styles, dict) or not styles:
+        raise ConfigError(f"{source}: 'styles' must be an object with at least one style")
+    for name, rules in styles.items():
+        if not isinstance(rules, dict):
+            raise ConfigError(f"{source}: style '{name}' must be an object")
+        for key, value in rules.items():
+            if key in STYLE_NUMBERS and value is not None and not isinstance(value, (int, float)):
+                raise ConfigError(f"{source}: styles.{name}.{key} must be a number or null")
+    if config.get("style") not in styles:
+        raise ConfigError(
+            f"{source}: 'style' must be one of the defined styles: {', '.join(styles)}"
+        )
 
 
 def load_config(overrides: dict[str, Any] | None = None) -> dict[str, Any]:

legendaria-0.1.0.dev2/legendaria_engine/cues.py

@@ -0,0 +1,124 @@
+"""Cues: the timed text blocks shown on screen, built from word timings by a style.
+
+`captions` gives short CapCut-style phrases; `subtitles` gives film-style lines.
+Styles are plain dicts from the config's "styles" section (see defaults/config.json).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from legendaria_engine.schema import Transcript, Word
+
+CUES_VERSION = 1
+
+
+@dataclass
+class Cue:
+    """One block of text on screen, with the words it contains."""
+
+    start: float
+    end: float
+    text: str
+    words: list[Word] = field(default_factory=list)
+
+
+@dataclass
+class CueList:
+    """Cues for one media file in one style (cues JSON v1)."""
+
+    style: str
+    source: str
+    language: str | None
+    cues: list[Cue] = field(default_factory=list)
+    version: int = CUES_VERSION
+
+    def to_dict(self) -> dict[str, Any]:
+        """Plain dict ready for JSON."""
+        return asdict(self)
+
+    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")
+
+
+def _join(words: list[Word]) -> str:
+    """Concatenate words as Whisper spells them: a leading space marks a new word,
+    so attached pieces such as "-se" or "'s" stay glued to the previous word."""
+    return " ".join("".join(w.word for w in words).split())
+
+
+def _ends_with(word: Word, chars: str) -> bool:
+    text = word.word.strip()
+    return bool(text) and bool(chars) and text[-1] in chars
+
+
+def make_cues(transcript: Transcript, style: dict[str, Any], style_name: str = "custom") -> CueList:
+    """Chunk the transcript's words into cues that respect the style's limits.
+
+    Style keys (all optional): max_words, max_chars, max_duration, min_duration,
+    pause_break (seconds of silence that force a break), break_after (punctuation
+    characters that end a cue), break_on_segment (start a new cue at each segment).
+    """
+    max_words = style.get("max_words")
+    max_chars = style.get("max_chars")
+    max_duration = style.get("max_duration")
+    pause_break = style.get("pause_break")
+    break_after = style.get("break_after", "")
+    break_on_segment = style.get("break_on_segment", True)
+
+    cues: list[Cue] = []
+    current: list[Word] = []
+
+    def flush() -> None:
+        if current:
+            cues.append(Cue(current[0].start, current[-1].end, _join(current), list(current)))
+            current.clear()
+
+    for segment in transcript.segments:
+        if not segment.words:  # no word timings: keep the whole segment as one cue
+            flush()
+            if segment.text.strip():
+                cues.append(Cue(segment.start, segment.end, segment.text.strip()))
+            continue
+        if break_on_segment:
+            flush()
+        for word in segment.words:
+            if current:
+                too_many = max_words is not None and len(current) + 1 > max_words
+                too_long = max_chars is not None and len(_join([*current, word])) > max_chars
+                too_slow = max_duration is not None and word.end - current[0].start > max_duration
+                paused = pause_break is not None and word.start - current[-1].end > pause_break
+                if too_many or too_long or too_slow or paused:
+                    flush()
+            current.append(word)
+            if _ends_with(word, break_after):
+                flush()
+    flush()
+    _apply_min_duration(cues, style.get("min_duration"))
+    return CueList(
+        style=style_name, source=transcript.source, language=transcript.language, cues=cues
+    )
+
+
+def _apply_min_duration(cues: list[Cue], min_duration: float | None) -> None:
+    """Stretch cues shorter than `min_duration`, without overlapping the next cue."""
+    if not min_duration:
+        return
+    for i, cue in enumerate(cues):
+        if cue.end - cue.start < min_duration:
+            limit = cues[i + 1].start if i + 1 < len(cues) else cue.start + min_duration
+            cue.end = round(max(cue.end, min(cue.start + min_duration, limit)), 3)
+
+
+def wrap_lines(text: str, line_length: int | None) -> str:
+    """Split text into two balanced lines when it is longer than `line_length`."""
+    if not line_length or len(text) <= line_length or " " not in text:
+        return text
+    middle = len(text) // 2
+    spaces = [i for i, ch in enumerate(text) if ch == " "]
+    split = min(spaces, key=lambda i: abs(i - middle))
+    return text[:split] + "\n" + text[split + 1 :]

legendaria-0.1.0.dev2/legendaria_engine/defaults/config.json

@@ -0,0 +1,45 @@
+{
+  "$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,
+  "style": "subtitles",
+  "styles": {
+    "subtitles": {
+      "max_chars": 84,
+      "line_length": 42,
+      "max_duration": 6.0,
+      "min_duration": 1.0,
+      "pause_break": 1.0,
+      "break_after": ".!?…",
+      "break_on_segment": true
+    },
+    "captions": {
+      "max_words": 4,
+      "max_chars": 22,
+      "max_duration": 2.2,
+      "min_duration": 0.3,
+      "pause_break": 0.5,
+      "break_after": ".,!?;:…",
+      "break_on_segment": true
+    }
+  },
+  "formats": [
+    "json",
+    "srt",
+    "vtt"
+  ],
+  "ui_languages": [
+    "auto",
+    "pt",
+    "en"
+  ]
+}

legendaria-0.1.0.dev2/legendaria_engine/formats.py

@@ -0,0 +1,37 @@
+"""Subtitle writers: cues → SRT / VTT text."""
+
+from __future__ import annotations
+
+from legendaria_engine.cues import CueList, wrap_lines
+
+FORMATS = ("json", "cues", "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(cues: CueList, line_length: int | None = None) -> str:
+    """Numbered SRT blocks, one per cue; long cues wrap into two lines."""
+    blocks = []
+    for index, cue in enumerate(cues.cues, start=1):
+        start, end = format_timestamp(cue.start), format_timestamp(cue.end)
+        blocks.append(f"{index}\n{start} --> {end}\n{wrap_lines(cue.text, line_length)}\n")
+    return "\n".join(blocks)
+
+
+def to_vtt(cues: CueList, line_length: int | None = None) -> str:
+    """WebVTT blocks, one per cue; long cues wrap into two lines."""
+    blocks = ["WEBVTT\n"]
+    for cue in cues.cues:
+        start, end = format_timestamp(cue.start, "."), format_timestamp(cue.end, ".")
+        blocks.append(f"{start} --> {end}\n{wrap_lines(cue.text, line_length)}\n")
+    return "\n".join(blocks)
+
+
+WRITERS = {"srt": to_srt, "vtt": to_vtt}

{legendaria-0.1.0.dev0 → legendaria-0.1.0.dev2}/legendaria_engine/schema.py

@@ -69,6 +69,42 @@ class Transcript:
             **fields, segments=segments, language_probability=data.get("language_probability")
         )
 
+    def merged_with(self, update: Transcript, start: float, end: float) -> Transcript:
+        """A copy of this transcript where [start, end] comes from `update`.
+
+        Works word by word, so a segment that crosses a boundary keeps only its words on
+        its own side: no word is lost or duplicated. A word (or a segment without word
+        timings) belongs to the range when its midpoint is inside. Used to regenerate
+        part of a video (plan 02, stage 2c).
+        """
+
+        def inside(a: float, b: float) -> bool:
+            return start <= (a + b) / 2 <= end
+
+        def part(segments: list[Segment], want_inside: bool) -> list[Segment]:
+            out = []
+            for seg in segments:
+                if not seg.words:
+                    if inside(seg.start, seg.end) == want_inside:
+                        out.append(seg)
+                    continue
+                words = [w for w in seg.words if inside(w.start, w.end) == want_inside]
+                if words:
+                    text = " ".join("".join(w.word for w in words).split())
+                    out.append(Segment(words[0].start, words[-1].end, text, words))
+            return out
+
+        merged = part(self.segments, False) + part(update.segments, True)
+        return Transcript(
+            source=self.source,
+            language=self.language,
+            duration=self.duration,
+            model=update.model,
+            device=update.device,
+            segments=sorted(merged, key=lambda s: s.start),
+            language_probability=self.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")

{legendaria-0.1.0.dev0 → legendaria-0.1.0.dev2}/legendaria_engine/transcriber.py

@@ -22,6 +22,7 @@ class Options:
     beam_size: int = 5
     vad_filter: bool = True
     word_timestamps: bool = True
+    clip: tuple[float, float] | None = None  # transcribe only this time range (seconds)
 
 
 class Backend(Protocol):
@@ -75,12 +76,20 @@ class FasterWhisperBackend:
 
         compute_type = options.compute_type.get(device, "default")
         model = WhisperModel(str(options.model_path), device=device, compute_type=compute_type)
+        extra = {"clip_timestamps": list(options.clip)} if options.clip else {}
         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,
+            **extra,
+        )
+        # Progress covers the clip when there is one (times stay absolute, from the media start).
+        offset, total = (
+            (options.clip[0], options.clip[1] - options.clip[0])
+            if options.clip
+            else (0.0, info.duration)
         )
         reporter.emit(
             "start",
@@ -110,8 +119,8 @@ class FasterWhisperBackend:
                     words=words,
                 )
             )
-            reporter.progress(seg.end, info.duration)
-        reporter.progress(info.duration, info.duration)
+            reporter.progress(max(0.0, seg.end - offset), total)
+        reporter.progress(total, total)
         return Transcript(
             source=media.name,
             language=info.language,

{legendaria-0.1.0.dev0 → legendaria-0.1.0.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "legendaria"
-version = "0.1.0.dev0"
+version = "0.1.0.dev2"
 description = "Legendária transcription engine: local Whisper transcription with word timings (CLI: flosub)."
 readme = "README.md"
 license = "MIT"

legendaria-0.1.0.dev2/schemas/config.schema.json

@@ -0,0 +1,165 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/flou-ainan/Legendaria/main/engine/schemas/config.schema.json",
+  "title": "Legendária engine config",
+  "description": "Engine settings. Put only the keys you want to change in your user config.json (see `flosub config path`).",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1,
+      "description": "Config format version."
+    },
+    "model": {
+      "type": "string",
+      "description": "Model name from models.json (e.g. small, medium, large-v3-turbo) or a path to a CTranslate2 model folder."
+    },
+    "language": {
+      "type": "string",
+      "description": "Speech language code (pt, en, es, ...) or 'auto' to detect it."
+    },
+    "device": {
+      "enum": [
+        "auto",
+        "cuda",
+        "cpu"
+      ],
+      "description": "'auto' uses an NVIDIA GPU when available, otherwise the CPU."
+    },
+    "compute_type": {
+      "type": "object",
+      "description": "CTranslate2 compute type per device.",
+      "properties": {
+        "cuda": {
+          "enum": [
+            "float16",
+            "int8_float16",
+            "int8",
+            "float32",
+            "bfloat16"
+          ]
+        },
+        "cpu": {
+          "enum": [
+            "int8",
+            "int8_float32",
+            "float32"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "beam_size": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 10,
+      "description": "Beam search width: higher is slightly more accurate and slower."
+    },
+    "vad_filter": {
+      "type": "boolean",
+      "description": "Skip silent parts with voice activity detection (reduces made-up text)."
+    },
+    "word_timestamps": {
+      "type": "boolean",
+      "description": "Record the timing of every word (needed for CapCut-style captions)."
+    },
+    "formats": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "json",
+          "srt",
+          "vtt"
+        ]
+      },
+      "uniqueItems": true,
+      "description": "Files written by `flosub transcribe`."
+    },
+    "ui_languages": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Languages offered in the Blender add-on's language menu."
+    },
+    "backend": {
+      "enum": [
+        "faster-whisper"
+      ],
+      "description": "Transcription backend."
+    },
+    "style": {
+      "type": "string",
+      "description": "Style used by `flosub transcribe`/`export` when --style is not given (a key of 'styles')."
+    },
+    "styles": {
+      "type": "object",
+      "description": "Cue styles: how words are grouped into on-screen text. 'captions' = short CapCut-style phrases (Blender default); 'subtitles' = film-style lines (SRT/VTT default). Add your own.",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "max_words": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "minimum": 1,
+            "description": "Most words per cue."
+          },
+          "max_chars": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "minimum": 1,
+            "description": "Most characters per cue."
+          },
+          "line_length": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "minimum": 1,
+            "description": "SRT/VTT: wrap cues longer than this into two lines."
+          },
+          "max_duration": {
+            "type": [
+              "number",
+              "null"
+            ],
+            "exclusiveMinimum": 0,
+            "description": "Longest time (s) a cue may cover."
+          },
+          "min_duration": {
+            "type": [
+              "number",
+              "null"
+            ],
+            "minimum": 0,
+            "description": "Shortest time (s) a cue stays on screen (stretched without overlapping the next)."
+          },
+          "pause_break": {
+            "type": [
+              "number",
+              "null"
+            ],
+            "minimum": 0,
+            "description": "A silence longer than this (s) starts a new cue."
+          },
+          "break_after": {
+            "type": "string",
+            "description": "Punctuation characters that end a cue."
+          },
+          "break_on_segment": {
+            "type": "boolean",
+            "description": "Start a new cue at each Whisper segment."
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

legendaria-0.1.0.dev2/schemas/cues.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/flou-ainan/Legendaria/main/engine/schemas/cues.schema.json",
+  "title": "Legendária cues (v1)",
+  "description": "Output of `flosub ... --format cues` (<name>.cues.json): on-screen text blocks in one style, read by the Blender add-on. Times in seconds.",
+  "type": "object",
+  "required": [
+    "version",
+    "style",
+    "source",
+    "language",
+    "cues"
+  ],
+  "properties": {
+    "version": {
+      "const": 1
+    },
+    "style": {
+      "type": "string"
+    },
+    "source": {
+      "type": "string"
+    },
+    "language": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "cues": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "start",
+          "end",
+          "text"
+        ],
+        "properties": {
+          "start": {
+            "type": "number",
+            "minimum": 0
+          },
+          "end": {
+            "type": "number",
+            "minimum": 0
+          },
+          "text": {
+            "type": "string"
+          },
+          "words": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "start",
+                "end",
+                "word"
+              ],
+              "properties": {
+                "start": {
+                  "type": "number"
+                },
+                "end": {
+                  "type": "number"
+                },
+                "word": {
+                  "type": "string"
+                },
+                "probability": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            }
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

{legendaria-0.1.0.dev0 → legendaria-0.1.0.dev2}/tests/test_cli.py

@@ -13,11 +13,28 @@ def run(args, capsys):
 def test_export_writes_srt_and_vtt(transcript, tmp_path, capsys):
     source = tmp_path / "clip.json"
     transcript.save(source)
-    code, events, _ = run(["export", str(source), "--format", "srt,vtt"], capsys)
+    code, events, _ = run(["export", str(source), "--format", "srt,vtt,cues"], capsys)
     assert code == 0
     assert events[-1]["event"] == "done"
     assert (tmp_path / "clip.srt").read_text(encoding="utf-8").startswith("1\n00:00:00,000")
     assert (tmp_path / "clip.vtt").read_text(encoding="utf-8").startswith("WEBVTT")
+    cues = json.loads((tmp_path / "clip.cues.json").read_text(encoding="utf-8"))
+    assert cues["style"] == "subtitles" and cues["version"] == 1
+
+
+def test_export_captions_style_and_dotted_names(transcript, tmp_path, capsys):
+    source = tmp_path / "aula.parte1.json"
+    transcript.save(source)
+    code, events, _ = run(["export", str(source), "--format", "srt", "--style", "captions"], capsys)
+    assert code == 0 and events[-1]["style"] == "captions"
+    assert (tmp_path / "aula.parte1.srt").is_file()  # the ".parte1" part is kept
+
+
+def test_unknown_style_is_an_error(transcript, tmp_path, capsys):
+    source = tmp_path / "clip.json"
+    transcript.save(source)
+    code, events, _ = run(["export", str(source), "--style", "nope"], capsys)
+    assert code == 1 and "Unknown style" in events[-1]["message"]
 
 
 def test_transcribe_missing_file_is_an_error(tmp_path, capsys):
@@ -70,3 +87,19 @@ def test_human_reporter_download_and_done(capsys):
     reporter.emit("done", outputs=["a.srt"])
     err = capsys.readouterr().err
     assert "50%" in err and "done" in err and "Saved: a.srt" in err
+
+
+def test_clip_parsing():
+    import pytest
+
+    assert cli.parse_clip("1.5,3") == (1.5, 3.0)
+    for bad in ("3,1", "x,2", "5", "-1,2"):
+        with pytest.raises(ValueError):
+            cli.parse_clip(bad)
+
+
+def test_update_needs_clip(tmp_path, capsys):
+    media = tmp_path / "a.mp3"
+    media.write_bytes(b"")
+    code, events, _ = run(["transcribe", str(media), "--update", "x.json"], capsys)
+    assert code == 2 and "--clip" in events[-1]["message"]

{legendaria-0.1.0.dev0 → legendaria-0.1.0.dev2}/tests/test_config.py

@@ -69,6 +69,28 @@ def test_user_models_extend_catalog():
     assert "small" in catalog
 
 
+def test_user_can_tune_and_add_styles():
+    write_user(
+        "config.json", {"styles": {"captions": {"max_words": 2}, "karaoke": {"max_words": 1}}}
+    )
+    config = load_config()
+    assert config["styles"]["captions"]["max_words"] == 2
+    assert config["styles"]["captions"]["max_chars"] == 22  # rest of the default kept
+    assert "karaoke" in config["styles"]
+
+
+def test_bad_style_values_are_rejected():
+    write_user("config.json", {"styles": {"captions": {"max_words": "four"}}})
+    with pytest.raises(ConfigError, match=r"styles\.captions\.max_words"):
+        load_config()
+
+
+def test_default_style_must_exist():
+    write_user("config.json", {"style": "nope"})
+    with pytest.raises(ConfigError, match="'style'"):
+        load_config()
+
+
 def test_deep_merge_does_not_mutate():
     base = {"a": {"b": 1}}
     deep_merge(base, {"a": {"c": 2}})

legendaria-0.1.0.dev2/tests/test_cues.py

@@ -0,0 +1,110 @@
+import pytest
+
+from legendaria_engine.config import load_config
+from legendaria_engine.cues import make_cues, wrap_lines
+from legendaria_engine.schema import Segment, Transcript, Word
+
+
+def words(*items):
+    """items: (text, start, end)"""
+    return [Word(start=s, end=e, word=f" {t}") for t, s, e in items]
+
+
+def transcript(*segments):
+    return Transcript(
+        source="a.mp4",
+        language="pt",
+        duration=60,
+        model="small",
+        device="cpu",
+        segments=list(segments),
+    )
+
+
+def segment(ws):
+    return Segment(ws[0].start, ws[-1].end, " ".join(w.word.strip() for w in ws), ws)
+
+
+def texts(cue_list):
+    return [c.text for c in cue_list.cues]
+
+
+def test_max_words():
+    ws = words(*[(f"w{i}", i * 0.2, i * 0.2 + 0.15) for i in range(10)])
+    result = make_cues(transcript(segment(ws)), {"max_words": 4}, "captions")
+    assert texts(result) == ["w0 w1 w2 w3", "w4 w5 w6 w7", "w8 w9"]
+    assert result.style == "captions"
+
+
+def test_max_chars_and_duration():
+    ws = words(("alpha", 0, 0.5), ("beta", 0.5, 1.0), ("gamma", 1.0, 1.5), ("delta", 3.0, 3.5))
+    assert texts(make_cues(transcript(segment(ws)), {"max_chars": 11})) == [
+        "alpha beta",
+        "gamma delta",
+    ]
+    assert texts(make_cues(transcript(segment(ws)), {"max_duration": 1.2})) == [
+        "alpha beta",
+        "gamma",
+        "delta",
+    ]
+
+
+def test_breaks_after_punctuation_and_on_pauses():
+    ws = words(("Oi,", 0, 0.3), ("tudo", 0.35, 0.6), ("bem?", 0.6, 0.9), ("Sim", 2.0, 2.3))
+    result = make_cues(transcript(segment(ws)), {"break_after": ",?", "pause_break": 0.5})
+    assert texts(result) == ["Oi,", "tudo bem?", "Sim"]
+    ws2 = words(("um", 0, 0.2), ("dois", 1.5, 1.7))
+    assert texts(make_cues(transcript(segment(ws2)), {"pause_break": 0.5})) == ["um", "dois"]
+
+
+def test_segments_start_new_cues_unless_disabled():
+    t = transcript(segment(words(("a", 0, 0.1))), segment(words(("b", 0.2, 0.3))))
+    assert texts(make_cues(t, {})) == ["a", "b"]
+    assert texts(make_cues(t, {"break_on_segment": False})) == ["a b"]
+
+
+def test_min_duration_stretches_without_overlap():
+    ws = words(("a", 0.0, 0.1), ("b", 0.25, 0.3), ("c", 2.0, 2.05))
+    result = make_cues(transcript(segment(ws)), {"max_words": 1, "min_duration": 0.5})
+    assert [(c.start, c.end) for c in result.cues] == [(0.0, 0.25), (0.25, 0.75), (2.0, 2.5)]
+
+
+def test_segment_without_words_is_kept_whole():
+    t = transcript(Segment(0, 3, " Sem palavras aqui.", []))
+    result = make_cues(t, {"max_words": 1})
+    assert texts(result) == ["Sem palavras aqui."]
+    assert result.cues[0].words == []
+
+
+def test_default_styles_produce_short_captions_and_long_subtitles():
+    config = load_config()
+    ws = words(*[(f"palavra{i}", i * 0.3, i * 0.3 + 0.25) for i in range(12)])
+    t = transcript(segment(ws))
+    captions = make_cues(t, config["styles"]["captions"], "captions")
+    subtitles = make_cues(t, config["styles"]["subtitles"], "subtitles")
+    assert all(len(c.words) <= 4 and len(c.text) <= 22 for c in captions.cues)
+    assert all(c.end - c.start <= 2.2 + 1e-9 for c in captions.cues)
+    assert len(subtitles.cues) < len(captions.cues)
+
+
+@pytest.mark.parametrize(
+    ("text", "length", "expected"),
+    [
+        ("short", 42, "short"),
+        ("one two three four", 10, "one two\nthree four"),
+        ("nospaceshere", 4, "nospaceshere"),
+        ("any", None, "any"),
+    ],
+)
+def test_wrap_lines(text, length, expected):
+    assert wrap_lines(text, length) == expected
+
+
+def test_attached_pieces_stay_glued():
+    ws = [
+        Word(0, 0.2, " Descreve"),
+        Word(0.2, 0.3, "-se"),
+        Word(0.3, 0.5, " o"),
+        Word(0.5, 0.7, " Tom's"),
+    ]
+    assert texts(make_cues(transcript(segment(ws)), {})) == ["Descreve-se o Tom's"]

{legendaria-0.1.0.dev0 → legendaria-0.1.0.dev2}/tests/test_formats.py

@@ -1,5 +1,6 @@
 import pytest
 
+from legendaria_engine.cues import Cue, CueList
 from legendaria_engine.formats import format_timestamp, to_srt, to_vtt
 
 
@@ -23,14 +24,28 @@ def test_format_timestamp_vtt_separator():
     assert format_timestamp(1.25, ".") == "00:00:01.250"
 
 
-def test_to_srt(transcript):
-    assert to_srt(transcript) == (
+@pytest.fixture
+def cues():
+    return CueList(
+        style="subtitles",
+        source="clip.mp4",
+        language="pt",
+        cues=[Cue(0.0, 2.5, "Olá, este é um teste."), Cue(3723.0, 3725.5, "Hello again.")],
+    )
+
+
+def test_to_srt(cues):
+    assert to_srt(cues) == (
         "1\n00:00:00,000 --> 00:00:02,500\nOlá, este é um teste.\n\n"
         "2\n01:02:03,000 --> 01:02:05,500\nHello again.\n"
     )
 
 
-def test_to_vtt(transcript):
-    text = to_vtt(transcript)
+def test_to_vtt(cues):
+    text = to_vtt(cues)
     assert text.startswith("WEBVTT\n\n00:00:00.000 --> 00:00:02.500\nOlá, este é um teste.\n")
     assert "01:02:03.000 --> 01:02:05.500\nHello again.\n" in text
+
+
+def test_long_cues_wrap_into_two_lines(cues):
+    assert "Olá, este\né um teste." in to_srt(cues, line_length=12)

legendaria-0.1.0.dev2/tests/test_schema.py

@@ -0,0 +1,74 @@
+import json
+from pathlib import Path
+
+import jsonschema
+import pytest
+
+from legendaria_engine.schema import Transcript
+
+SCHEMAS = Path(__file__).resolve().parents[1] / "schemas"
+
+
+def test_round_trip(transcript, tmp_path):
+    path = tmp_path / "t.json"
+    transcript.save(path)
+    assert Transcript.load(path) == transcript
+
+
+def test_matches_json_schema(transcript):
+    schema = json.loads((SCHEMAS / "transcript.schema.json").read_text(encoding="utf-8"))
+    jsonschema.validate(transcript.to_dict(), schema)
+
+
+def test_rejects_other_versions(transcript):
+    data = transcript.to_dict() | {"version": 2}
+    with pytest.raises(ValueError, match="version"):
+        Transcript.from_dict(data)
+
+
+def test_cues_match_json_schema(transcript):
+    from legendaria_engine.config import load_config
+    from legendaria_engine.cues import make_cues
+
+    schema = json.loads((SCHEMAS / "cues.schema.json").read_text(encoding="utf-8"))
+    cues = make_cues(transcript, load_config()["styles"]["captions"], "captions")
+    jsonschema.validate(cues.to_dict(), schema)
+
+
+def test_merge_replaces_only_the_range():
+    from legendaria_engine.schema import Segment
+
+    base = Transcript(
+        "a.mp4",
+        "pt",
+        30.0,
+        "small",
+        "cpu",
+        [Segment(0, 5, "a"), Segment(10, 12, "b"), Segment(20, 25, "c")],
+    )
+    update = Transcript(
+        "a.mp4", "pt", 30.0, "medium", "cuda", [Segment(9.5, 11, "B1"), Segment(11, 13, "B2")]
+    )
+    merged = base.merged_with(update, 8, 15)
+    assert [s.text for s in merged.segments] == ["a", "B1", "B2", "c"]
+    assert merged.model == "medium" and base.segments[1].text == "b"
+
+
+def test_merge_splits_segments_crossing_the_boundary():
+    from legendaria_engine.schema import Segment, Word
+
+    old = Segment(
+        8, 14, "one two three", [Word(8, 9, " one"), Word(10, 11, " two"), Word(13, 14, " three")]
+    )
+    base = Transcript("a.mp4", "pt", 30.0, "small", "cpu", [old])
+    new = Segment(
+        9.5,
+        16,
+        "TWO THREE four",
+        [Word(9.5, 11, " TWO"), Word(13, 14, " THREE"), Word(15, 16, " four")],
+    )
+    update = Transcript("a.mp4", "pt", 30.0, "tiny", "cpu", [new])
+    merged = base.merged_with(update, 10, 14.5)
+    assert [s.text for s in merged.segments] == ["one", "TWO THREE"]
+    words = [w.word.strip() for s in merged.segments for w in s.words]
+    assert words == ["one", "TWO", "THREE"]  # nothing duplicated, "four" stays out

{legendaria-0.1.0.dev0 → legendaria-0.1.0.dev2}/uv.lock

@@ -472,7 +472,7 @@ wheels = [
 
 [[package]]
 name = "legendaria"
-version = "0.1.0.dev0"
+version = "0.1.0.dev2"
 source = { editable = "." }
 dependencies = [
     { name = "faster-whisper" },

legendaria-0.1.0.dev0/legendaria_engine/defaults/config.json

@@ -1,16 +0,0 @@
-{
-  "$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/formats.py

@@ -1,37 +0,0 @@
-"""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-0.1.0.dev0/schemas/config.schema.json

@@ -1,30 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/flou-ainan/Legendaria/main/engine/schemas/config.schema.json",
-  "title": "Legendária engine config",
-  "description": "Engine settings. Put only the keys you want to change in your user config.json (see `flosub config path`).",
-  "type": "object",
-  "properties": {
-    "$schema": {"type": "string"},
-    "version": {"const": 1, "description": "Config format version."},
-    "model": {"type": "string", "description": "Model name from models.json (e.g. small, medium, large-v3-turbo) or a path to a CTranslate2 model folder."},
-    "language": {"type": "string", "description": "Speech language code (pt, en, es, ...) or 'auto' to detect it."},
-    "device": {"enum": ["auto", "cuda", "cpu"], "description": "'auto' uses an NVIDIA GPU when available, otherwise the CPU."},
-    "compute_type": {
-      "type": "object",
-      "description": "CTranslate2 compute type per device.",
-      "properties": {
-        "cuda": {"enum": ["float16", "int8_float16", "int8", "float32", "bfloat16"]},
-        "cpu": {"enum": ["int8", "int8_float32", "float32"]}
-      },
-      "additionalProperties": false
-    },
-    "beam_size": {"type": "integer", "minimum": 1, "maximum": 10, "description": "Beam search width: higher is slightly more accurate and slower."},
-    "vad_filter": {"type": "boolean", "description": "Skip silent parts with voice activity detection (reduces made-up text)."},
-    "word_timestamps": {"type": "boolean", "description": "Record the timing of every word (needed for CapCut-style captions)."},
-    "formats": {"type": "array", "items": {"enum": ["json", "srt", "vtt"]}, "uniqueItems": true, "description": "Files written by `flosub transcribe`."},
-    "ui_languages": {"type": "array", "items": {"type": "string"}, "description": "Languages offered in the Blender add-on's language menu."},
-    "backend": {"enum": ["faster-whisper"], "description": "Transcription backend."}
-  },
-  "additionalProperties": false
-}

legendaria-0.1.0.dev0/tests/test_schema.py

@@ -1,26 +0,0 @@
-import json
-from pathlib import Path
-
-import jsonschema
-import pytest
-
-from legendaria_engine.schema import Transcript
-
-SCHEMAS = Path(__file__).resolve().parents[1] / "schemas"
-
-
-def test_round_trip(transcript, tmp_path):
-    path = tmp_path / "t.json"
-    transcript.save(path)
-    assert Transcript.load(path) == transcript
-
-
-def test_matches_json_schema(transcript):
-    schema = json.loads((SCHEMAS / "transcript.schema.json").read_text(encoding="utf-8"))
-    jsonschema.validate(transcript.to_dict(), schema)
-
-
-def test_rejects_other_versions(transcript):
-    data = transcript.to_dict() | {"version": 2}
-    with pytest.raises(ValueError, match="version"):
-        Transcript.from_dict(data)