srtforge 0.2.0__tar.gz → 0.2.1__tar.gz

{srtforge-0.2.0/src/srtforge.egg-info → srtforge-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: srtforge
-Version: 0.2.0
+Version: 0.2.1
 Summary: Generate, translate, and burn SRT subtitles locally with MLX Whisper.
 Author: rromanv
 License-Expression: MIT
@@ -203,6 +203,8 @@ srtforge merge video.mp4 video.es.srt --crf 16
 
 Existing outputs are not overwritten by default. Pass `--force` when you intend
 to replace an existing `.srt` or merged video output.
+Subtitle files are published atomically, so a failed write preserves any
+existing destination instead of leaving a partial file.
 
 Run:
 
@@ -222,8 +224,9 @@ so they are easier to read:
 - cues are paced around 17 characters per second
 - cues are adjusted to avoid overlap
 
-Translated subtitles are re-fitted after translation because translated text can
-be longer or shorter than the source.
+Translated subtitles receive Cue Fit after normal Cue Planning because translated
+text can be longer or shorter than the source. With `--no-resegment`, translated
+subtitles retain the raw Whisper Cue shape.
 
 ## ffmpeg Notes
 
@@ -247,7 +250,7 @@ src/srtforge/
   transcript.py  # reference transcript reading + correction
   _types.py      # shared typed subtitle data shapes
   merge.py       # burn subtitles into video with ffmpeg/libass
-  srt.py         # SRT rendering
+  srt.py         # SRT rendering and safe publication
   cli.py         # argparse CLI
 tests/
   test_cli.py

{srtforge-0.2.0 → srtforge-0.2.1}/README.md

@@ -175,6 +175,8 @@ srtforge merge video.mp4 video.es.srt --crf 16
 
 Existing outputs are not overwritten by default. Pass `--force` when you intend
 to replace an existing `.srt` or merged video output.
+Subtitle files are published atomically, so a failed write preserves any
+existing destination instead of leaving a partial file.
 
 Run:
 
@@ -194,8 +196,9 @@ so they are easier to read:
 - cues are paced around 17 characters per second
 - cues are adjusted to avoid overlap
 
-Translated subtitles are re-fitted after translation because translated text can
-be longer or shorter than the source.
+Translated subtitles receive Cue Fit after normal Cue Planning because translated
+text can be longer or shorter than the source. With `--no-resegment`, translated
+subtitles retain the raw Whisper Cue shape.
 
 ## ffmpeg Notes
 
@@ -219,7 +222,7 @@ src/srtforge/
   transcript.py  # reference transcript reading + correction
   _types.py      # shared typed subtitle data shapes
   merge.py       # burn subtitles into video with ffmpeg/libass
-  srt.py         # SRT rendering
+  srt.py         # SRT rendering and safe publication
   cli.py         # argparse CLI
 tests/
   test_cli.py

{srtforge-0.2.0 → srtforge-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "srtforge"
-version = "0.2.0"
+version = "0.2.1"
 description = "Generate, translate, and burn SRT subtitles locally with MLX Whisper."
 readme = "README.md"
 requires-python = ">=3.10,<3.13"

{srtforge-0.2.0 → srtforge-0.2.1}/src/srtforge/__init__.py

@@ -1,3 +1,3 @@
 """srtforge: generate SRT subtitles from video using local Whisper (MLX)."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"

{srtforge-0.2.0 → srtforge-0.2.1}/src/srtforge/cli.py

@@ -10,11 +10,12 @@ from pathlib import Path
 from . import __version__
 from .audio import FFmpegError, extract_audio
 from .merge import burn_subtitles
-from .segment import Opts, fit_cues, resegment
-from .srt import segments_to_srt
+from .segment import Opts, resegment
+from .srt import SubtitlePublicationError, publish_srt
 from .transcribe import DEFAULT_MODEL, transcribe
 from .transcript import correct_segments, initial_prompt_from_transcript, read_transcript
-from .translate import DEFAULT_TRANSLATE_MODEL, TranslationError, translate_segments
+from .translate import DEFAULT_TRANSLATE_MODEL, TranslationError
+from .translation_completion import TranslationSkipped, complete_translation
 
 
 class CliError(RuntimeError):
@@ -39,6 +40,17 @@ def _positive_float(value: str) -> float:
     return parsed
 
 
+def _translation_tag(language: str) -> str:
+    return re.sub(r"[^\w.-]+", "-", language.strip().lower()).strip(".-_")
+
+
+def _translation_language(value: str) -> str:
+    tag = _translation_tag(value)
+    if not tag:
+        raise argparse.ArgumentTypeError("translation language must not be blank")
+    return value
+
+
 def _crf(value: str) -> int:
     parsed = int(value)
     if not 0 <= parsed <= 51:
@@ -48,8 +60,9 @@ def _crf(value: str) -> int:
 
 def _translated_path(output: Path, language: str) -> Path:
     """Insert a language tag before the suffix: video.srt -> video.<lang>.srt."""
-    tag = re.sub(r"[^\w.-]+", "-", language.strip().lower()).strip(".-_")
-    tag = tag or "translated"
+    tag = _translation_tag(language)
+    if not tag:
+        raise CliError("Translation language must not be blank.")
     return output.with_suffix(f".{tag}{output.suffix}")
 
 
@@ -126,7 +139,7 @@ def build_parser() -> argparse.ArgumentParser:
         help=f"Reading speed in characters/second (default: {Opts.reading_cps}).",
     )
     p.add_argument(
-        "-t", "--translate", default=None, metavar="LANG",
+        "-t", "--translate", type=_translation_language, default=None, metavar="LANG",
         help="Also translate subtitles into LANG (e.g. es, Spanish, Japanese) "
              "using a local MLX LLM. Writes a second .<lang>.srt file.",
     )
@@ -152,6 +165,7 @@ def _gen_main(argv: list[str] | None = None) -> int:
     # Sentence-aware re-cueing needs word-level timestamps.
     need_words = args.word_timestamps or args.resegment
     wav_path = None
+    translation_output: Path | None = None
     try:
         _ensure_srt_output(output)
         _ensure_can_write_output(
@@ -161,10 +175,10 @@ def _gen_main(argv: list[str] | None = None) -> int:
             kind="video",
         )
         if translating:
-            t_out = _translated_path(output, args.translate)
-            _ensure_srt_output(t_out)
+            translation_output = _translated_path(output, args.translate)
+            _ensure_srt_output(translation_output)
             _ensure_can_write_output(
-                t_out,
+                translation_output,
                 force=args.force,
                 protected=[args.video, output],
                 kind="video or subtitle output",
@@ -188,39 +202,46 @@ def _gen_main(argv: list[str] | None = None) -> int:
 
         if args.resegment:
             segments = resegment(segments, opts)
+        cues = segments
 
         _log(f"[3/{total}] Writing {output} ...")
-        srt_text = segments_to_srt(segments)
-        output.write_text(srt_text, encoding="utf-8")
-        if not srt_text:
+        has_cues = any((cue.get("text") or "").strip() for cue in cues)
+        publish_srt(cues, output, replace_existing=args.force)
+        if not has_cues:
             _log("Warning: no speech detected; wrote an empty SRT file.")
         else:
-            _log(f"  {srt_text.count('-->')} subtitle entries written.")
+            _log("  Subtitle file written.")
 
-        if translating:
-            if not srt_text:
-                _log("Skipping translation: no speech to translate.")
-            else:
-                t_out = _translated_path(output, args.translate)
+        if translation_output is not None:
+            if has_cues:
                 _log(
                     f"[4/{total}] Translating to {args.translate} with "
                     f"{args.translate_model} (downloads model on first run) ..."
                 )
-                t_segments = translate_segments(
-                    segments,
-                    target_language=args.translate,
-                    model=args.translate_model,
-                )
-                if args.resegment:
-                    # Translated text length differs; fit/split to line limits.
-                    t_segments = fit_cues(t_segments, opts)
-                t_out.write_text(segments_to_srt(t_segments), encoding="utf-8")
-                _log(f"  Translated subtitles written to {t_out}")
+            completion = complete_translation(
+                cues,
+                target_language=args.translate,
+                model=args.translate_model,
+                output=translation_output,
+                apply_cue_fit=args.resegment,
+                replace_existing=args.force,
+                opts=opts,
+            )
+            if isinstance(completion, TranslationSkipped):
+                _log("Skipping translation: no speech to translate.")
+            else:
+                _log(f"  Translated subtitles written to {completion.output}")
 
         _log("Done.")
         return 0
 
-    except (CliError, FFmpegError, FileNotFoundError, TranslationError) as e:
+    except (
+        CliError,
+        FFmpegError,
+        FileNotFoundError,
+        SubtitlePublicationError,
+        TranslationError,
+    ) as e:
         _log(f"Error: {e}")
         return 1
     except KeyboardInterrupt:

{srtforge-0.2.0 → srtforge-0.2.1}/src/srtforge/segment.py

@@ -10,6 +10,7 @@ module rebuilds cues from word-level timestamps so that:
 
 from __future__ import annotations
 
+from collections import deque
 import re
 from dataclasses import dataclass, field
 
@@ -22,6 +23,7 @@ READING_CPS = 17.0    # characters per second a viewer can comfortably read
 MIN_DURATION = 0.8    # seconds
 MAX_DURATION = 7.0    # seconds
 MIN_GAP = 0.084       # ~2 frames @ 24fps, gap between consecutive cues
+SUBSTANTIAL_SPEECH_GAP = 1.0  # seconds; starts a new cue during planning
 
 # Sentence-final punctuation (incl. Spanish/CJK variants).
 _SENT_END = tuple(".!?…。！？")
@@ -55,6 +57,7 @@ class _Word:
 @dataclass
 class _Sentence:
     words: list[_Word] = field(default_factory=list)
+    force_break_after: bool = False
 
     @property
     def text(self) -> str:
@@ -107,6 +110,20 @@ def _split_sentences(words: list[_Word]) -> list[_Sentence]:
     return sentences
 
 
+def _split_speech_gaps(words: list[_Word]) -> list[list[_Word]]:
+    """Split timestamped words at substantial gaps in speech."""
+    groups: list[list[_Word]] = []
+    current: list[_Word] = []
+    for word in words:
+        if current and word.start - current[-1].end >= SUBSTANTIAL_SPEECH_GAP:
+            groups.append(current)
+            current = []
+        current.append(word)
+    if current:
+        groups.append(current)
+    return groups
+
+
 # --------------------------------------------------------------------------- #
 # Line wrapping
 # --------------------------------------------------------------------------- #
@@ -171,30 +188,50 @@ def wrap_lines(text: str, max_cpl: int = MAX_CPL, max_lines: int = MAX_LINES) ->
 # --------------------------------------------------------------------------- #
 # Cue construction
 # --------------------------------------------------------------------------- #
+def _split_words_to_fit(words: list[str], opts: Opts) -> list[list[str]]:
+    """Plan Cue Fit chunks, preferring clause punctuation when possible."""
+    chunks: list[list[str]] = []
+    pending = deque(words)
+    current: list[str] = []
+    last_clause_break = -1
+
+    while pending:
+        word = pending.popleft()
+        prospective = current + [word]
+        if current and not _fits(" ".join(prospective), opts):
+            if 0 <= last_clause_break < len(current) - 1:
+                chunks.append(current[: last_clause_break + 1])
+                tail = current[last_clause_break + 1 :]
+            else:
+                chunks.append(current)
+                tail = []
+            current = []
+            last_clause_break = -1
+            pending.extendleft(reversed(tail + [word]))
+            continue
+
+        current.append(word)
+        if word.endswith(_CLAUSE_PUNCT):
+            last_clause_break = len(current) - 1
+
+    if current:
+        chunks.append(current)
+    return chunks
+
+
 def _split_long_sentence(sent: _Sentence, opts: Opts) -> list[_Sentence]:
     """Split a sentence that exceeds one block into word-aligned chunks,
     preferring clause-punctuation break points near the limit."""
     chunks: list[_Sentence] = []
-    cur = _Sentence()
-    last_clause_break = -1  # index within cur.words after a clause punct
-    for w in sent.words:
-        prospective = _Sentence(cur.words + [w])
-        if cur.words and not _fits(prospective.text, opts):
-            # Prefer to break at the last clause punctuation if we have one.
-            if 0 <= last_clause_break < len(cur.words) - 1:
-                head = _Sentence(cur.words[: last_clause_break + 1])
-                tail_words = cur.words[last_clause_break + 1 :]
-                chunks.append(head)
-                cur = _Sentence(list(tail_words))
-            else:
-                chunks.append(cur)
-                cur = _Sentence()
-            last_clause_break = -1
-        cur.words.append(w)
-        if w.text.endswith(_CLAUSE_PUNCT):
-            last_clause_break = len(cur.words) - 1
-    if cur.words:
-        chunks.append(cur)
+    offset = 0
+    for text_chunk in _split_words_to_fit([word.text for word in sent.words], opts):
+        next_offset = offset + len(text_chunk)
+        chunks.append(_Sentence(sent.words[offset:next_offset]))
+        offset = next_offset
+    if chunks:
+        for chunk in chunks[:-1]:
+            chunk.force_break_after = True
+        chunks[-1].force_break_after = sent.force_break_after
     return chunks
 
 
@@ -215,6 +252,8 @@ def _build_cues(sentences: list[_Sentence], opts: Opts) -> list[Cue]:
         merged_words = list(cur.words)
         j = i + 1
         while j < len(units):
+            if units[j - 1].force_break_after:
+                break
             nxt = units[j]
             combined = _Sentence(merged_words + nxt.words).text
             combined_dur = nxt.end - merged_words[0].start
@@ -272,8 +311,9 @@ def fit_cues(cues: list[Segment], opts: Opts | None = None) -> list[Cue]:
     """Fit each cue's text within the line limits, splitting over-capacity cues.
 
     Used for translated text, whose length differs from the source. A cue whose
-    text does not fit within the line limits is split into multiple cues at word
-    boundaries, with the original time span apportioned by character count.
+    text does not fit within the line limits is split at clause punctuation
+    where possible, otherwise word boundaries, with time apportioned by
+    character count.
     """
     opts = opts or Opts()
     out: list[Cue] = []
@@ -282,22 +322,7 @@ def fit_cues(cues: list[Segment], opts: Opts | None = None) -> list[Cue]:
         if not text:
             continue
         start, end = float(c["start"]), float(c["end"])
-        if _fits(text, opts):
-            out.append({"start": start, "end": end,
-                        "text": wrap_lines(text, opts.max_cpl, opts.max_lines)})
-            continue
-        # Split into chunks that each fit the line limits, at word boundaries.
-        chunks: list[str] = []
-        cur = ""
-        for w in text.split(" "):
-            cand = (cur + " " + w).strip()
-            if cur and not _fits(cand, opts):
-                chunks.append(cur)
-                cur = w
-            else:
-                cur = cand
-        if cur:
-            chunks.append(cur)
+        chunks = [" ".join(chunk) for chunk in _split_words_to_fit(text.split(), opts)]
         span = max(end - start, 0.001)
         total = sum(len(ch) for ch in chunks) or 1
         t = start
@@ -310,7 +335,13 @@ def fit_cues(cues: list[Segment], opts: Opts | None = None) -> list[Cue]:
 
 
 def _resegment_words(words: list[_Word], opts: Opts) -> list[Cue]:
-    sentences = _split_sentences(words)
+    sentences: list[_Sentence] = []
+    groups = _split_speech_gaps(words)
+    for i, group in enumerate(groups):
+        group_sentences = _split_sentences(group)
+        if group_sentences and i + 1 < len(groups):
+            group_sentences[-1].force_break_after = True
+        sentences.extend(group_sentences)
     cues = _build_cues(sentences, opts)
     cues = _apply_pacing(cues, opts)
     for cue in cues:

srtforge-0.2.1/src/srtforge/srt.py

@@ -0,0 +1,110 @@
+"""Render and publish completed Cues as SRT subtitle documents."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import Iterable
+
+from ._types import Segment
+
+MIN_CUE_DURATION = 0.001
+
+
+class SubtitlePublicationError(RuntimeError):
+    """Raised when a complete SRT document cannot be published."""
+
+
+def _format_timestamp(seconds: float) -> str:
+    """Format seconds as SRT timestamp: HH:MM:SS,mmm."""
+    if seconds < 0:
+        seconds = 0.0
+    millis = round(seconds * 1000)
+    hours, millis = divmod(millis, 3_600_000)
+    minutes, millis = divmod(millis, 60_000)
+    secs, millis = divmod(millis, 1000)
+    return f"{hours:02d}:{minutes:02d}:{secs:02d},{millis:03d}"
+
+
+def _normalize_timing(start: float, end: float, previous_end: float) -> tuple[float, float]:
+    start = max(0.0, start, previous_end)
+    end = max(start + MIN_CUE_DURATION, end)
+    return start, end
+
+
+def _render_srt(cues: Iterable[Segment]) -> str:
+    """Render completed Cues to an SRT document string."""
+    blocks: list[str] = []
+    index = 1
+    previous_end = 0.0
+    for cue in cues:
+        text = (cue.get("text") or "").strip()
+        if not text:
+            continue
+        start_seconds, end_seconds = _normalize_timing(
+            float(cue.get("start", 0.0)),
+            float(cue.get("end", 0.0)),
+            previous_end,
+        )
+        previous_end = end_seconds
+        start = _format_timestamp(start_seconds)
+        end = _format_timestamp(end_seconds)
+        blocks.append(f"{index}\n{start} --> {end}\n{text}\n")
+        index += 1
+    return "\n".join(blocks)
+
+
+def publish_srt(
+    cues: Iterable[Segment],
+    destination: Path,
+    *,
+    replace_existing: bool = False,
+) -> Path:
+    """Publish completed Cues as an SRT document."""
+    if destination.suffix.lower() != ".srt":
+        raise SubtitlePublicationError(
+            f"Subtitle destination must end in .srt: {destination}"
+        )
+    if not destination.parent.exists():
+        raise SubtitlePublicationError(
+            f"Subtitle parent directory does not exist: {destination.parent}"
+        )
+    if destination.exists() and not replace_existing:
+        raise SubtitlePublicationError(
+            f"Subtitle destination already exists: {destination}"
+        )
+
+    temporary: Path | None = None
+    try:
+        with NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=destination.parent,
+            prefix=f".{destination.stem}.",
+            suffix=destination.suffix,
+            delete=False,
+        ) as stream:
+            temporary = Path(stream.name)
+            stream.write(_render_srt(cues))
+            stream.flush()
+            os.fsync(stream.fileno())
+        if replace_existing:
+            temporary.replace(destination)
+        else:
+            os.link(temporary, destination)
+        return destination
+    except FileExistsError as exc:
+        raise SubtitlePublicationError(
+            f"Subtitle destination already exists: {destination}"
+        ) from exc
+    except Exception as exc:
+        raise SubtitlePublicationError(
+            f"Failed to publish subtitles to {destination}: {exc}"
+        ) from exc
+    finally:
+        if temporary is not None:
+            try:
+                temporary.unlink(missing_ok=True)
+            except OSError:
+                pass

srtforge-0.2.1/src/srtforge/translation_completion.py

@@ -0,0 +1,84 @@
+"""Publish the outcome of a requested Cue translation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from ._types import Segment
+from .segment import Opts, fit_cues
+from .srt import publish_srt
+from .translate import DEFAULT_TRANSLATE_MODEL, TranslationError, translate_segments
+
+
+class TranslationAdapter(Protocol):
+    """Translate Cues while keeping their source order and timing."""
+
+    def __call__(
+        self,
+        segments: list[Segment],
+        *,
+        target_language: str,
+        model: str,
+    ) -> list[Segment]: ...
+
+
+@dataclass(frozen=True)
+class TranslationWritten:
+    """A Translation Completion that published a translated subtitle file."""
+
+    output: Path
+
+
+@dataclass(frozen=True)
+class TranslationSkipped:
+    """A Translation Completion with no translatable Cues."""
+
+
+TranslationCompletion = TranslationWritten | TranslationSkipped
+
+
+def complete_translation(
+    segments: list[Segment],
+    *,
+    target_language: str,
+    output: Path,
+    model: str = DEFAULT_TRANSLATE_MODEL,
+    apply_cue_fit: bool = False,
+    replace_existing: bool = False,
+    opts: Opts | None = None,
+    translate: TranslationAdapter = translate_segments,
+) -> TranslationCompletion:
+    """Translate Cues and publish the resulting SRT, or skip empty input."""
+    if not any((segment.get("text") or "").strip() for segment in segments):
+        return TranslationSkipped()
+
+    try:
+        translated = translate(
+            segments,
+            target_language=target_language,
+            model=model,
+        )
+    except TranslationError:
+        raise
+    except Exception as exc:
+        raise TranslationError(f"Translation failed: {exc}") from exc
+
+    if len(translated) != len(segments):
+        raise TranslationError(
+            "Translation failed: Cue count differs from the source Cues."
+        )
+
+    completed = [dict(segment) for segment in translated]
+    for source, target in zip(segments, completed):
+        if (source.get("text") or "").strip() and not (target.get("text") or "").strip():
+            target["text"] = source["text"]
+
+    completed_cues = fit_cues(completed, opts) if apply_cue_fit else completed
+    published = publish_srt(
+        completed_cues,
+        output,
+        replace_existing=replace_existing,
+    )
+    return TranslationWritten(published)

{srtforge-0.2.0 → srtforge-0.2.1/src/srtforge.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: srtforge
-Version: 0.2.0
+Version: 0.2.1
 Summary: Generate, translate, and burn SRT subtitles locally with MLX Whisper.
 Author: rromanv
 License-Expression: MIT
@@ -203,6 +203,8 @@ srtforge merge video.mp4 video.es.srt --crf 16
 
 Existing outputs are not overwritten by default. Pass `--force` when you intend
 to replace an existing `.srt` or merged video output.
+Subtitle files are published atomically, so a failed write preserves any
+existing destination instead of leaving a partial file.
 
 Run:
 
@@ -222,8 +224,9 @@ so they are easier to read:
 - cues are paced around 17 characters per second
 - cues are adjusted to avoid overlap
 
-Translated subtitles are re-fitted after translation because translated text can
-be longer or shorter than the source.
+Translated subtitles receive Cue Fit after normal Cue Planning because translated
+text can be longer or shorter than the source. With `--no-resegment`, translated
+subtitles retain the raw Whisper Cue shape.
 
 ## ffmpeg Notes
 
@@ -247,7 +250,7 @@ src/srtforge/
   transcript.py  # reference transcript reading + correction
   _types.py      # shared typed subtitle data shapes
   merge.py       # burn subtitles into video with ffmpeg/libass
-  srt.py         # SRT rendering
+  srt.py         # SRT rendering and safe publication
   cli.py         # argparse CLI
 tests/
   test_cli.py

{srtforge-0.2.0 → srtforge-0.2.1}/src/srtforge.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ src/srtforge/srt.py
 src/srtforge/transcribe.py
 src/srtforge/transcript.py
 src/srtforge/translate.py
+src/srtforge/translation_completion.py
 src/srtforge.egg-info/PKG-INFO
 src/srtforge.egg-info/SOURCES.txt
 src/srtforge.egg-info/dependency_links.txt
@@ -22,4 +23,5 @@ tests/test_merge.py
 tests/test_segment.py
 tests/test_srt.py
 tests/test_transcript.py
-tests/test_translate.py
+tests/test_translate.py
+tests/test_translation_completion.py