smart-srt-translator 0.1.2

Smart SRT subtitle translation with optional audio probing and provider abstraction

Smart SRT Translator

A lightweight, extensible Python package for translating SRT subtitle files, with optional audio probe support and pluggable providers (OpenAI, etc.).

Features

• Smart SRT in/out: preserves timing and structure.
• Provider abstraction: start with a no-op Dummy, optionally use OpenAI.
• Optional audio probe flow: generate JSON requests for uncertain segments.
• CLI srt-translate for quick usage; programmatic API for embedding.

Quick Start

• Create venv (choose one, depending on your setup):
  • Windows: py -m venv .venv or python -m venv .venv
  • macOS/Linux: python3 -m venv .venv (or python -m venv .venv)
  • Activate:
    • PowerShell: .venv\Scripts\Activate.ps1
    • CMD: .venv\Scripts\activate.bat
    • bash/zsh: source .venv/bin/activate
• Install (local): python -m pip install -e .[openai] (omit [openai] to skip OpenAI extra)
• Translate (CLI):
  • Smart (default): srt-translate translate Sample/firstdayinnewhospital.srt en de
  • Provider is openai by default; mode smart by default.
  • The CLI auto-loads .env with OPENAI_API_KEY and optional OPENAI_MODEL.
  • Note: Inside the venv prefer python -m pip ... (on Unix you may use python3 -m pip ...).

Quick Start (DE)

• Minimal: srt-translate translate <input.srt> en de (language-aware preset applies for DE).
• Timing-critical (burn-in/live): srt-translate translate <input.srt> en de --preserve-timing --wrap-width 120
• Improve readability (long clips): srt-translate translate <input.srt> en de --expand-timing --expansion-factor 1.3 --min-seg-dur 2.0
• Both (recommended for DE video): srt-translate translate <input.srt> en de --preserve-timing --wrap-width 120 --expand-timing

Preserve Timing Mode

• For timing-critical SRT where segments must never exchange words across boundaries:
  • Use --preserve-timing to translate per-segment with a higher wrap width (>=100), no balancing, and no cross-boundary reflow.
  • Example: srt-translate translate input.srt en de --preserve-timing
  • Tip: Combine with a larger --wrap-width 120 if needed.

Timing Expansion (Prototype)

• Expands segment durations to improve readability (longer target texts like DE):
  • --expand-timing --expansion-factor 1.3 --min-seg-dur 2.0 --reading-wpm 200 --min-gap-ms 120
  • Works with both smart and preserve-timing modes; keeps segment order, shifts subsequent segments forward.
  • Recommended for DE: --preserve-timing --expand-timing --wrap-width 120 --expansion-factor 1.3
  • Basic per-segment: srt-translate translate Sample/firstdayinnewhospital.srt auto de --provider dummy --mode basic

Recommended Defaults

• Wrap width: 40 (--wrap-width 40)
• Review: on, thresholds ASCII=0.6, STOP=0.15 (override with --no-review, --review-*)
• Strict review: on with 2 passes (disable via --no-strict-review)
• Smoothing: on (disable via --no-smooth)
• Balancing: on, ratio=1.8 (disable via --no-balance, tune with --balance-ratio)

Minimal Usage

srt-translate translate Sample/firstdayinnewhospital.srt en de

Programmatic API

from smart_srt_translator import translate_srt_file, translate_srt_smart, TranslateOptions

res = translate_srt_file(
    "Sample/firstdayinnewhospital.srt",
    src_lang=None,  # auto
    tgt_lang="de",
    options=TranslateOptions(probe_mode="off")
)
print(res.output_path)

# or Smart mode (uses recommended defaults)
out = translate_srt_smart(
    "Sample/firstdayinnewhospital.srt",
    src_lang="en",
    tgt_lang="de",
    # wrap_width=40,
    # review=True,
    # review_ascii_threshold=0.6,
    # review_stop_threshold=0.15,
    # strict_review=True,
    # strict_max_passes=2,
    # smooth=True,
    # balance=True,
    # balance_ratio=1.8,
)
print(out)

Audio Probe Flow (Concept)

• --probe ask: creates <output>.requests.json with segment time windows needing audio review.
• Provide resolutions.json later (same IDs) to finalize improved translations (planned finalize).
• --probe auto: will require a transcriber provider and audio source (roadmap).

Configuration

• OpenAI provider needs OPENAI_API_KEY and optional OPENAI_MODEL.
• The CLI auto-loads .env from the repo root or VidScalerSubtitleAdder/.env if present.

Status

• MVP scaffold ready. OpenAI provider implemented at a minimal prompt level.
• Finalization flow and advanced sentence-grouping/caching from the app are planned to be ported.

License

MIT

Further Docs

• Parameter reference: see PARAMS.md for a concise overview of modes, flags, defaults, and recipes.
• Readability guide: see READABILITY.md for DE presets and timing expansion tips.