srtforge 0.1.2__tar.gz → 0.2.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: srtforge
-Version: 0.1.2
+Version: 0.2.1
 Summary: Generate, translate, and burn SRT subtitles locally with MLX Whisper.
 Author: rromanv
 License-Expression: MIT
@@ -22,7 +22,8 @@ Requires-Python: <3.13,>=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: mlx-whisper>=0.4
-Requires-Dist: mlx-lm>=0.20
+Provides-Extra: translate
+Requires-Dist: mlx-lm>=0.20; extra == "translate"
 Dynamic: license-file
 
 # srtforge
@@ -76,6 +77,12 @@ From PyPI:
 pipx install --python python3.11 srtforge
 ```
 
+If you want local LLM translation support, install the translation extra:
+
+```bash
+pipx install --python python3.11 'srtforge[translate]'
+```
+
 `srtforge` currently supports Python 3.10-3.12. If your default Python is newer
 than that, such as Python 3.14, pass a supported interpreter explicitly with
 `--python`.
@@ -86,6 +93,12 @@ From GitHub:
 pipx install --python python3.11 git+https://github.com/rromanv/srtforge.git
 ```
 
+With translation support from GitHub:
+
+```bash
+pipx install --python python3.11 'srtforge[translate] @ git+https://github.com/rromanv/srtforge.git'
+```
+
 For local development:
 
 ```bash
@@ -94,6 +107,7 @@ cd srtforge
 python3.11 -m venv .venv
 source .venv/bin/activate
 pip install -e .
+pip install -e '.[translate]'  # optional, for `srtforge -t ...`
 ```
 
 Or into a virtual environment:
@@ -102,6 +116,7 @@ Or into a virtual environment:
 python3.11 -m venv .venv
 source .venv/bin/activate
 pip install srtforge
+pip install 'srtforge[translate]'  # optional, for `srtforge -t ...`
 ```
 
 ## Troubleshooting
@@ -177,6 +192,8 @@ srtforge video.mp4 -t "Brazilian Portuguese"
 srtforge video.mp4 -t ja --translate-model mlx-community/Qwen3.5-9B-OptiQ-4bit
 ```
 
+Translation requires installing `srtforge[translate]`.
+
 Burn subtitles into a video:
 
 ```bash
@@ -184,6 +201,11 @@ srtforge merge video.mp4 video.srt -o final.mp4
 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:
 
 ```bash
@@ -202,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
 
@@ -225,8 +248,9 @@ src/srtforge/
   segment.py     # sentence-aware re-cueing, wrapping, pacing
   translate.py   # context-aware local-LLM translation
   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
@@ -234,6 +258,7 @@ tests/
   test_segment.py
   test_srt.py
   test_transcript.py
+  test_translate.py
 ```
 
 ## Development

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

@@ -49,6 +49,12 @@ From PyPI:
 pipx install --python python3.11 srtforge
 ```
 
+If you want local LLM translation support, install the translation extra:
+
+```bash
+pipx install --python python3.11 'srtforge[translate]'
+```
+
 `srtforge` currently supports Python 3.10-3.12. If your default Python is newer
 than that, such as Python 3.14, pass a supported interpreter explicitly with
 `--python`.
@@ -59,6 +65,12 @@ From GitHub:
 pipx install --python python3.11 git+https://github.com/rromanv/srtforge.git
 ```
 
+With translation support from GitHub:
+
+```bash
+pipx install --python python3.11 'srtforge[translate] @ git+https://github.com/rromanv/srtforge.git'
+```
+
 For local development:
 
 ```bash
@@ -67,6 +79,7 @@ cd srtforge
 python3.11 -m venv .venv
 source .venv/bin/activate
 pip install -e .
+pip install -e '.[translate]'  # optional, for `srtforge -t ...`
 ```
 
 Or into a virtual environment:
@@ -75,6 +88,7 @@ Or into a virtual environment:
 python3.11 -m venv .venv
 source .venv/bin/activate
 pip install srtforge
+pip install 'srtforge[translate]'  # optional, for `srtforge -t ...`
 ```
 
 ## Troubleshooting
@@ -150,6 +164,8 @@ srtforge video.mp4 -t "Brazilian Portuguese"
 srtforge video.mp4 -t ja --translate-model mlx-community/Qwen3.5-9B-OptiQ-4bit
 ```
 
+Translation requires installing `srtforge[translate]`.
+
 Burn subtitles into a video:
 
 ```bash
@@ -157,6 +173,11 @@ srtforge merge video.mp4 video.srt -o final.mp4
 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:
 
 ```bash
@@ -175,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
 
@@ -198,8 +220,9 @@ src/srtforge/
   segment.py     # sentence-aware re-cueing, wrapping, pacing
   translate.py   # context-aware local-LLM translation
   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
@@ -207,6 +230,7 @@ tests/
   test_segment.py
   test_srt.py
   test_transcript.py
+  test_translate.py
 ```
 
 ## Development

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

@@ -1,6 +1,6 @@
 [project]
 name = "srtforge"
-version = "0.1.2"
+version = "0.2.1"
 description = "Generate, translate, and burn SRT subtitles locally with MLX Whisper."
 readme = "README.md"
 requires-python = ">=3.10,<3.13"
@@ -23,6 +23,10 @@ classifiers = [
 ]
 dependencies = [
     "mlx-whisper>=0.4",
+]
+
+[project.optional-dependencies]
+translate = [
     "mlx-lm>=0.20",
 ]
 

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

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

srtforge-0.2.1/src/srtforge/_types.py

@@ -0,0 +1,24 @@
+"""Shared subtitle data shapes used across the pipeline."""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class WhisperWord(TypedDict, total=False):
+    word: str
+    start: float
+    end: float
+
+
+class Segment(TypedDict, total=False):
+    start: float
+    end: float
+    text: str
+    words: list[WhisperWord]
+
+
+class Cue(TypedDict, total=False):
+    start: float
+    end: float
+    text: str

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

@@ -10,11 +10,16 @@ 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):
+    """Raised for invalid CLI arguments that argparse cannot express alone."""
 
 
 def _log(msg: str) -> None:
@@ -35,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:
@@ -44,11 +60,35 @@ 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}")
 
 
+def _same_path(a: Path, b: Path) -> bool:
+    return a.resolve(strict=False) == b.resolve(strict=False)
+
+
+def _ensure_srt_output(path: Path) -> None:
+    if path.suffix.lower() != ".srt":
+        raise CliError(f"Subtitle output must end in .srt: {path}")
+
+
+def _ensure_can_write_output(
+    output: Path,
+    *,
+    force: bool,
+    protected: list[Path],
+    kind: str,
+) -> None:
+    for path in protected:
+        if _same_path(output, path):
+            raise CliError(f"Refusing to overwrite input {kind}: {output}")
+    if output.exists() and not force:
+        raise CliError(f"Output already exists: {output}. Pass --force to overwrite.")
+
+
 def build_parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(
         prog="srtforge",
@@ -61,6 +101,10 @@ def build_parser() -> argparse.ArgumentParser:
         "-o", "--output", type=Path, default=None,
         help="Output .srt path (default: alongside the video).",
     )
+    p.add_argument(
+        "--force", action="store_true",
+        help="Overwrite existing output files.",
+    )
     p.add_argument(
         "-m", "--model", default=DEFAULT_MODEL,
         help=f"Whisper model / HF repo (default: {DEFAULT_MODEL}).",
@@ -95,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.",
     )
@@ -121,7 +165,25 @@ 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(
+            output,
+            force=args.force,
+            protected=[args.video],
+            kind="video",
+        )
+        if translating:
+            translation_output = _translated_path(output, args.translate)
+            _ensure_srt_output(translation_output)
+            _ensure_can_write_output(
+                translation_output,
+                force=args.force,
+                protected=[args.video, output],
+                kind="video or subtitle output",
+            )
+
         transcript_text = read_transcript(args.transcript) if args.transcript else ""
         _log(f"[1/{total}] Extracting audio from {args.video} ...")
         wav_path = extract_audio(args.video)
@@ -140,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 (FFmpegError, FileNotFoundError, TranslationError) as e:
+    except (
+        CliError,
+        FFmpegError,
+        FileNotFoundError,
+        SubtitlePublicationError,
+        TranslationError,
+    ) as e:
         _log(f"Error: {e}")
         return 1
     except KeyboardInterrupt:
@@ -202,6 +271,10 @@ def build_merge_parser() -> argparse.ArgumentParser:
         "--preset", default="slow",
         help="x264 speed/efficiency preset (default: slow).",
     )
+    p.add_argument(
+        "--force", action="store_true",
+        help="Overwrite the output video if it already exists.",
+    )
     return p
 
 
@@ -209,6 +282,12 @@ def _merge_main(argv: list[str]) -> int:
     args = build_merge_parser().parse_args(argv)
     output = args.output or args.video.with_suffix(f".subbed{args.video.suffix}")
     try:
+        _ensure_can_write_output(
+            output,
+            force=args.force,
+            protected=[args.video, args.subtitles],
+            kind="video or subtitle file",
+        )
         _log(f"Burning {args.subtitles} into {args.video} (crf={args.crf}, preset={args.preset}) ...")
         burn_subtitles(
             args.video,
@@ -219,7 +298,7 @@ def _merge_main(argv: list[str]) -> int:
         )
         _log(f"Done. Wrote {output}")
         return 0
-    except (FFmpegError, FileNotFoundError) as e:
+    except (CliError, FFmpegError, FileNotFoundError) as e:
         _log(f"Error: {e}")
         return 1
     except KeyboardInterrupt: