legendaria 0.1.0.dev1__tar.gz → 0.1.0.dev3__tar.gz

{legendaria-0.1.0.dev1 → legendaria-0.1.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: legendaria
-Version: 0.1.0.dev1
+Version: 0.1.0.dev3
 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.dev1 → legendaria-0.1.0.dev3}/legendaria_engine/__init__.py

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

{legendaria-0.1.0.dev1 → legendaria-0.1.0.dev3}/legendaria_engine/cli.py

@@ -44,6 +44,17 @@ def write_outputs(
     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"]
@@ -78,6 +89,10 @@ def cmd_transcribe(args: argparse.Namespace, reporter: Reporter) -> int:
         }
     )
     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
 
@@ -95,10 +110,14 @@ 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"], config, style)
     reporter.emit(
@@ -180,6 +199,11 @@ def build_parser() -> argparse.ArgumentParser:
         "--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="turn a transcript JSON into cues/SRT/VTT")

{legendaria-0.1.0.dev1 → legendaria-0.1.0.dev3}/legendaria_engine/config.py

@@ -16,6 +16,8 @@ STYLE_NUMBERS = (
     "max_duration",
     "min_duration",
     "pause_break",
+    "join_short",
+    "fill_gaps",
 )
 
 

{legendaria-0.1.0.dev1 → legendaria-0.1.0.dev3}/legendaria_engine/cues.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 
 import json
 from dataclasses import asdict, dataclass, field
+from itertools import pairwise
 from pathlib import Path
 from typing import Any
 
@@ -56,12 +57,30 @@ def _ends_with(word: Word, chars: str) -> bool:
     return bool(text) and bool(chars) and text[-1] in chars
 
 
+def _is_attached(word: Word) -> bool:
+    """A piece Whisper glued to the previous word (no leading space): "-vindas", "'s"."""
+    return bool(word.word) and not word.word[0].isspace()
+
+
+def _units(words: list[Word]) -> int:
+    """Readable words: attached pieces do not count ("bem" + "-vindas" is one)."""
+    return 1 + sum(1 for w in words[1:] if not _is_attached(w)) if words else 0
+
+
+def _letters(words: list[Word]) -> int:
+    return sum(ch.isalnum() for ch in _join(words))
+
+
 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).
+    Style keys (all optional): max_words (readable words; attached pieces like "-vindas"
+    never split from their word), 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), join_short (a single
+    word with at most this many letters, like "a", "de", "no", may take the next word
+    even beyond max_words), fill_gaps (extend a cue to the next one when the silence
+    between them is at most this many seconds, so the screen does not blink).
     """
     max_words = style.get("max_words")
     max_chars = style.get("max_chars")
@@ -69,6 +88,7 @@ def make_cues(transcript: Transcript, style: dict[str, Any], style_name: str = "
     pause_break = style.get("pause_break")
     break_after = style.get("break_after", "")
     break_on_segment = style.get("break_on_segment", True)
+    join_short = style.get("join_short")
 
     cues: list[Cue] = []
     current: list[Word] = []
@@ -87,8 +107,22 @@ def make_cues(transcript: Transcript, style: dict[str, Any], style_name: str = "
         if break_on_segment:
             flush()
         for word in segment.words:
+            if current and _is_attached(word):
+                current.append(word)  # glued piece: never starts a new cue
+                if _ends_with(word, break_after):
+                    flush()
+                continue
             if current:
-                too_many = max_words is not None and len(current) + 1 > max_words
+                allowed = max_words
+                if (
+                    allowed is not None
+                    and join_short
+                    and _units(current) == 1
+                    and _letters(current) <= join_short
+                    and not _ends_with(current[-1], break_after)
+                ):
+                    allowed += 1  # short word ("de", "a") takes the next one
+                too_many = allowed is not None and _units(current) + 1 > allowed
                 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
@@ -98,12 +132,22 @@ def make_cues(transcript: Transcript, style: dict[str, Any], style_name: str = "
             if _ends_with(word, break_after):
                 flush()
     flush()
+    _fill_gaps(cues, style.get("fill_gaps"))
     _apply_min_duration(cues, style.get("min_duration"))
     return CueList(
         style=style_name, source=transcript.source, language=transcript.language, cues=cues
     )
 
 
+def _fill_gaps(cues: list[Cue], max_gap: float | None) -> None:
+    """Extend each cue to the next one's start when the silence between them is short."""
+    if not max_gap:
+        return
+    for cue, nxt in pairwise(cues):
+        if 0 < nxt.start - cue.end <= max_gap:
+            cue.end = nxt.start
+
+
 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:

{legendaria-0.1.0.dev1 → legendaria-0.1.0.dev3}/legendaria_engine/defaults/config.json

@@ -13,6 +13,17 @@
   "word_timestamps": true,
   "style": "subtitles",
   "styles": {
+    "pop": {
+      "max_words": 1,
+      "join_short": 3,
+      "max_chars": 24,
+      "max_duration": 1.6,
+      "min_duration": 0.25,
+      "pause_break": 0.6,
+      "fill_gaps": 0.35,
+      "break_after": ".,!?;:…",
+      "break_on_segment": true
+    },
     "subtitles": {
       "max_chars": 84,
       "line_length": 42,

{legendaria-0.1.0.dev1 → legendaria-0.1.0.dev3}/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.dev1 → legendaria-0.1.0.dev3}/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.dev1 → legendaria-0.1.0.dev3}/pyproject.toml

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

{legendaria-0.1.0.dev1 → legendaria-0.1.0.dev3}/schemas/config.schema.json

@@ -96,7 +96,7 @@
     },
     "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.",
+      "description": "Cue styles: how words are grouped into on-screen text. 'pop' = one word at a time (two when the first is very short), for pop animations; 'captions' = short CapCut-style phrases (Blender default); 'subtitles' = film-style lines (SRT/VTT default). Add your own.",
       "additionalProperties": {
         "type": "object",
         "properties": {
@@ -155,6 +155,22 @@
           "break_on_segment": {
             "type": "boolean",
             "description": "Start a new cue at each Whisper segment."
+          },
+          "join_short": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "minimum": 1,
+            "description": "A single word with at most this many letters (\"a\", \"de\", \"no\") may take the next word, even beyond max_words."
+          },
+          "fill_gaps": {
+            "type": [
+              "number",
+              "null"
+            ],
+            "minimum": 0,
+            "description": "Extend a cue to the next one when the silence between them is at most this many seconds (avoids blinking)."
           }
         },
         "additionalProperties": false

{legendaria-0.1.0.dev1 → legendaria-0.1.0.dev3}/tests/test_cli.py

@@ -87,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.dev1 → legendaria-0.1.0.dev3}/tests/test_cues.py

@@ -108,3 +108,53 @@ def test_attached_pieces_stay_glued():
         Word(0.5, 0.7, " Tom's"),
     ]
     assert texts(make_cues(transcript(segment(ws)), {})) == ["Descreve-se o Tom's"]
+
+
+def test_attached_pieces_never_start_a_cue():
+    ws = [
+        Word(0, 0.3, " bem"),
+        Word(0.3, 0.6, "-vindas"),
+        Word(0.7, 1.0, " ao"),
+        Word(1.0, 1.3, " canal"),
+    ]
+    result = make_cues(transcript(segment(ws)), {"max_words": 1})
+    assert texts(result) == ["bem-vindas", "ao", "canal"]
+
+
+def test_short_words_pair_with_the_next():
+    ws = words(
+        ("a", 0, 0.1),
+        ("bolsa", 0.1, 0.5),
+        ("de", 0.5, 0.6),
+        ("crochê", 0.6, 1.0),
+        ("linda", 1.0, 1.4),
+    )
+    result = make_cues(transcript(segment(ws)), {"max_words": 1, "join_short": 3})
+    assert texts(result) == ["a bolsa", "de crochê", "linda"]
+
+
+def test_short_word_ending_a_sentence_does_not_pair():
+    ws = words(("é.", 0, 0.2), ("Agora", 0.3, 0.6))
+    result = make_cues(
+        transcript(segment(ws)), {"max_words": 1, "join_short": 3, "break_after": "."}
+    )
+    assert texts(result) == ["é.", "Agora"]
+
+
+def test_fill_gaps_closes_short_silences_only():
+    ws = words(("um", 0.0, 0.2), ("dois", 0.4, 0.6), ("três", 2.0, 2.2))
+    result = make_cues(transcript(segment(ws)), {"max_words": 1, "fill_gaps": 0.35})
+    assert [(c.start, c.end) for c in result.cues] == [(0.0, 0.4), (0.4, 0.6), (2.0, 2.2)]
+
+
+def test_pop_style_on_defaults():
+    config = load_config()
+    ws = words(
+        *[
+            (w, i * 0.3, i * 0.3 + 0.25)
+            for i, w in enumerate(["e", "hoje", "eu", "trouxe", "a", "bolsa"])
+        ]
+    )
+    result = make_cues(transcript(segment(ws)), config["styles"]["pop"], "pop")
+    assert texts(result) == ["e hoje", "eu trouxe", "a bolsa"]
+    assert all(len(c.text.split()) <= 2 for c in result.cues)

legendaria-0.1.0.dev3/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.dev1 → legendaria-0.1.0.dev3}/uv.lock

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

legendaria-0.1.0.dev1/tests/test_schema.py

@@ -1,35 +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)
-
-
-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)