srt2speech 1.0.0__tar.gz

srt2speech-1.0.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 nbr23
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

srt2speech-1.0.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: srt2speech
+Version: 1.0.0
+Summary: Synthesize a timestamp-synced speech track from a subtitle file and mux it into video
+Author: nbr23
+Author-email: nbr23 <max@23.tf>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: pysubs2>=1.7
+Requires-Dist: httpx>=0.27
+Requires-Dist: typer>=0.12
+Requires-Dist: pydub>=0.25
+Requires-Dist: rich>=13.7
+Requires-Dist: audioop-lts>=0.2 ; python_full_version >= '3.13'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/nbr23/srt2speech
+Project-URL: Repository, https://github.com/nbr23/srt2speech
+Description-Content-Type: text/markdown
+
+# srt2speech
+
+Turn a subtitle file into a **timestamp-synced speech track** and mux it into a video.
+
+Give it a video + an `.srt` (or `.vtt`/`.ass`); it synthesizes audio where each subtitle is spoken
+at its timestamp, then optionally muxes the track back in with ffmpeg. Useful for restoring lost
+audio, rough translation dubs, narrating silent videos, or adding **audio description** by reading
+only the descriptive/SDH cues.
+
+It does the SRT→audio part well and nothing else: **no translation, no transcription** — bring an
+already-final subtitle file.
+
+## Requirements
+
+- Python ≥ 3.11, [uv](https://docs.astral.sh/uv/)
+- `ffmpeg` / `ffprobe` on `PATH`
+- A TTS backend:
+  - **piper** — a local [gopipertts](https://github.com/nbr23/gopipertts) server (free, default;
+    set `SRT2SPEECH_PIPER_URL` if not on `http://localhost:8080`)
+  - **openai** — `gpt-4o-mini-tts` (set `OPENAI_API_KEY`)
+  - **elevenlabs** — `eleven_multilingual_v2` (set `ELEVENLABS_API_KEY`)
+
+## Install
+
+```sh
+uv sync
+```
+
+## Usage
+
+```sh
+# generate a synced track with the local piper backend, sized to the video
+uv run srt2speech generate subs.srt --video clip.mp4 -o track.wav
+
+# generate + mux into the video in one step
+uv run srt2speech run clip.mp4 subs.srt -o dubbed.mp4
+
+# paid backend with delivery guidance
+OPENAI_API_KEY=... uv run srt2speech generate subs.srt \
+    --backend openai --voice coral --instructions "calm documentary narration" -o track.wav
+
+# audio description: only descriptive/SDH cues, mixed over the existing audio
+uv run srt2speech run movie.mkv subs.srt --mode descriptive --mux-mode mix -o described.mkv
+
+# mux an existing track yourself
+uv run srt2speech mux clip.mp4 track.wav -o dubbed.mp4
+
+# list a backend's voices
+uv run srt2speech voices --backend openai
+```
+
+### Docker Compose
+
+Runs a local piper server plus an on-demand CLI; no host Python or ffmpeg needed. Put your video
+and subtitles in `./data` (mounted at `/data`); pulled voices are cached in `./voices`.
+
+```sh
+# 1. start the piper TTS server (preloads the default voice)
+docker compose up -d gopipertts
+
+# 2. run the CLI against files in ./data
+docker compose run --rm srt2speech run /data/clip.mp4 /data/subs.srt -o /data/dubbed.mp4
+
+# 3. tear down when done
+docker compose down
+```
+
+For the OpenAI backend, put `OPENAI_API_KEY=sk-...` in a `.env` file (gitignored) — Compose loads it
+automatically and passes it through to the CLI container.
+
+### Sync strategies (`--strategy`)
+
+Speech rarely fits a cue's window exactly. The fit engine offers:
+
+- `hybrid` *(default)* — fit into the cue window plus the silent gap before the next cue; only then
+  speed up, capped by `--max-speedup` (default `1.15`).
+- `overflow` — never speed up; let speech run into following silence (best quality, can drift).
+- `precise` — fit the exact cue window, speeding up to the cap.
+
+### Modes (`--mode`)
+
+`all` (default) · `descriptive` (SDH/audio-description only) · `dialogue` (drop sound cues).
+
+## Development
+
+```sh
+uv run pytest
+uv run ruff check
+```

srt2speech-1.0.0/README.md

@@ -0,0 +1,89 @@
+# srt2speech
+
+Turn a subtitle file into a **timestamp-synced speech track** and mux it into a video.
+
+Give it a video + an `.srt` (or `.vtt`/`.ass`); it synthesizes audio where each subtitle is spoken
+at its timestamp, then optionally muxes the track back in with ffmpeg. Useful for restoring lost
+audio, rough translation dubs, narrating silent videos, or adding **audio description** by reading
+only the descriptive/SDH cues.
+
+It does the SRT→audio part well and nothing else: **no translation, no transcription** — bring an
+already-final subtitle file.
+
+## Requirements
+
+- Python ≥ 3.11, [uv](https://docs.astral.sh/uv/)
+- `ffmpeg` / `ffprobe` on `PATH`
+- A TTS backend:
+  - **piper** — a local [gopipertts](https://github.com/nbr23/gopipertts) server (free, default;
+    set `SRT2SPEECH_PIPER_URL` if not on `http://localhost:8080`)
+  - **openai** — `gpt-4o-mini-tts` (set `OPENAI_API_KEY`)
+  - **elevenlabs** — `eleven_multilingual_v2` (set `ELEVENLABS_API_KEY`)
+
+## Install
+
+```sh
+uv sync
+```
+
+## Usage
+
+```sh
+# generate a synced track with the local piper backend, sized to the video
+uv run srt2speech generate subs.srt --video clip.mp4 -o track.wav
+
+# generate + mux into the video in one step
+uv run srt2speech run clip.mp4 subs.srt -o dubbed.mp4
+
+# paid backend with delivery guidance
+OPENAI_API_KEY=... uv run srt2speech generate subs.srt \
+    --backend openai --voice coral --instructions "calm documentary narration" -o track.wav
+
+# audio description: only descriptive/SDH cues, mixed over the existing audio
+uv run srt2speech run movie.mkv subs.srt --mode descriptive --mux-mode mix -o described.mkv
+
+# mux an existing track yourself
+uv run srt2speech mux clip.mp4 track.wav -o dubbed.mp4
+
+# list a backend's voices
+uv run srt2speech voices --backend openai
+```
+
+### Docker Compose
+
+Runs a local piper server plus an on-demand CLI; no host Python or ffmpeg needed. Put your video
+and subtitles in `./data` (mounted at `/data`); pulled voices are cached in `./voices`.
+
+```sh
+# 1. start the piper TTS server (preloads the default voice)
+docker compose up -d gopipertts
+
+# 2. run the CLI against files in ./data
+docker compose run --rm srt2speech run /data/clip.mp4 /data/subs.srt -o /data/dubbed.mp4
+
+# 3. tear down when done
+docker compose down
+```
+
+For the OpenAI backend, put `OPENAI_API_KEY=sk-...` in a `.env` file (gitignored) — Compose loads it
+automatically and passes it through to the CLI container.
+
+### Sync strategies (`--strategy`)
+
+Speech rarely fits a cue's window exactly. The fit engine offers:
+
+- `hybrid` *(default)* — fit into the cue window plus the silent gap before the next cue; only then
+  speed up, capped by `--max-speedup` (default `1.15`).
+- `overflow` — never speed up; let speech run into following silence (best quality, can drift).
+- `precise` — fit the exact cue window, speeding up to the cap.
+
+### Modes (`--mode`)
+
+`all` (default) · `descriptive` (SDH/audio-description only) · `dialogue` (drop sound cues).
+
+## Development
+
+```sh
+uv run pytest
+uv run ruff check
+```

srt2speech-1.0.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "srt2speech"
+version = "1.0.0"
+description = "Synthesize a timestamp-synced speech track from a subtitle file and mux it into video"
+readme = "README.md"
+authors = [{ name = "nbr23", email = "max@23.tf" }]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = [
+    "pysubs2>=1.7",
+    "httpx>=0.27",
+    "typer>=0.12",
+    "pydub>=0.25",
+    "rich>=13.7",
+    "audioop-lts>=0.2; python_version>='3.13'",
+]
+
+[project.urls]
+Homepage = "https://github.com/nbr23/srt2speech"
+Repository = "https://github.com/nbr23/srt2speech"
+
+[project.scripts]
+srt2speech = "srt2speech.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.23,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ruff.lint.per-file-ignores]
+# typer requires Option()/Argument() calls in parameter defaults.
+"src/srt2speech/cli.py" = ["B008"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

srt2speech-1.0.0/src/srt2speech/__init__.py

@@ -0,0 +1,3 @@
+"""srt2speech: synthesize a timestamp-synced speech track from subtitles."""
+
+__version__ = "0.1.0"

srt2speech-1.0.0/src/srt2speech/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

srt2speech-1.0.0/src/srt2speech/assemble.py

@@ -0,0 +1,31 @@
+"""Lay rendered segments onto a silent timeline at their exact start offsets.
+
+Overlapping audio (from overflow that exceeds even the gap) is mixed rather than ducked or pushed;
+collision handling is a deliberate v2 refinement. The hybrid strategy keeps such overlaps rare.
+"""
+
+from __future__ import annotations
+
+from pydub import AudioSegment
+
+from .models import Segment
+
+Rendered = list[tuple[Segment, AudioSegment]]
+
+
+def assemble(
+    rendered: Rendered,
+    *,
+    total_ms: int | None = None,
+    sample_rate: int = 24000,
+    channels: int = 1,
+) -> AudioSegment:
+    """Mix rendered segments onto a silent base sized to `total_ms` (or the content extent)."""
+    content_end = max((seg.start_ms + len(audio) for seg, audio in rendered), default=0)
+    length = max(total_ms or 0, content_end)
+
+    base = AudioSegment.silent(duration=length, frame_rate=sample_rate).set_channels(channels)
+    for seg, audio in rendered:
+        audio = audio.set_frame_rate(sample_rate).set_channels(channels)
+        base = base.overlay(audio, position=max(0, seg.start_ms))
+    return base

srt2speech-1.0.0/src/srt2speech/cli.py

@@ -0,0 +1,156 @@
+"""Command-line interface."""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.progress import Progress
+
+from .mux import mux as mux_audio
+from .pipeline import generate_track
+from .probe import media_duration_ms
+from .tts import BACKENDS, get_backend
+
+app = typer.Typer(
+    add_completion=False,
+    help="Synthesize a timestamp-synced speech track from subtitles and mux it into video.",
+)
+console = Console()
+
+
+def _build_backend(name: str, voice: str | None, piper_url: str | None, speed: float | None):
+    extra: dict[str, object] = {}
+    if name == "piper" and piper_url:
+        extra["base_url"] = piper_url
+    if speed is not None:
+        extra["speed"] = speed
+    return get_backend(name, voice=voice, **extra)
+
+
+def _render_track(
+    srt: Path,
+    output: Path,
+    *,
+    video: Path | None,
+    backend: str,
+    voice: str | None,
+    strategy: str,
+    max_speedup: float,
+    merge_threshold: int,
+    mode: str,
+    instructions: str | None,
+    piper_url: str | None,
+    speed: float | None,
+) -> Path:
+    try:
+        engine = _build_backend(backend, voice, piper_url, speed)
+    except (ValueError, RuntimeError) as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+    total_ms = media_duration_ms(video) if video else None
+
+    with Progress(console=console, transient=True) as progress:
+        task = progress.add_task("Synthesizing", total=None)
+
+        def on_progress(done: int, total: int) -> None:
+            progress.update(task, completed=done, total=total)
+
+        track = generate_track(
+            srt, engine,
+            mode=mode, strategy=strategy, max_speedup=max_speedup,
+            merge_threshold_ms=merge_threshold, voice=voice,
+            instructions=instructions, total_ms=total_ms, progress=on_progress,
+        )
+
+    fmt = output.suffix.lstrip(".") or "wav"
+    track.export(output, format=fmt)
+    console.print(f"[green]Wrote[/] {output} ({len(track) / 1000:.1f}s)")
+    return output
+
+
+@app.command()
+def generate(
+    srt: Path = typer.Argument(..., exists=True, dir_okay=False, help="Subtitle file"),
+    output: Path = typer.Option(Path("out.wav"), "-o", "--output", help="Output audio file"),
+    video: Path | None = typer.Option(None, "--video", help="Match this media's duration"),
+    backend: str = typer.Option("piper", "--backend", help=f"One of: {', '.join(BACKENDS)}"),
+    voice: str | None = typer.Option(None, "--voice"),
+    strategy: str = typer.Option("hybrid", "--strategy", help="hybrid | overflow | precise"),
+    max_speedup: float = typer.Option(1.15, "--max-speedup", help="Cap on speech speed-up"),
+    merge_threshold: int = typer.Option(250, "--merge-threshold", help="Cue merge gap (ms)"),
+    mode: str = typer.Option("all", "--mode", help="all | descriptive | dialogue"),
+    instructions: str | None = typer.Option(None, "--instructions", help="OpenAI delivery hint"),
+    speed: float | None = typer.Option(None, "--speed", help="Base rate (piper default 1.2)"),
+    piper_url: str | None = typer.Option(None, "--piper-url", help="gopipertts base URL"),
+) -> None:
+    """Generate a synced speech track from a subtitle file."""
+    _render_track(
+        srt, output, video=video, backend=backend, voice=voice, strategy=strategy,
+        max_speedup=max_speedup, merge_threshold=merge_threshold, mode=mode,
+        instructions=instructions, piper_url=piper_url, speed=speed,
+    )
+
+
+@app.command()
+def mux(
+    video: Path = typer.Argument(..., exists=True, dir_okay=False),
+    audio: Path = typer.Argument(..., exists=True, dir_okay=False),
+    output: Path = typer.Option(..., "-o", "--output"),
+    mode: str = typer.Option("replace", "--mode", help="replace | mix"),
+) -> None:
+    """Mux an audio track into a video."""
+    mux_audio(video, audio, output, mode=mode)
+    console.print(f"[green]Wrote[/] {output}")
+
+
+@app.command()
+def run(
+    video: Path = typer.Argument(..., exists=True, dir_okay=False),
+    srt: Path = typer.Argument(..., exists=True, dir_okay=False),
+    output: Path = typer.Option(..., "-o", "--output", help="Output video file"),
+    backend: str = typer.Option("piper", "--backend", help=f"One of: {', '.join(BACKENDS)}"),
+    voice: str | None = typer.Option(None, "--voice"),
+    strategy: str = typer.Option("hybrid", "--strategy", help="hybrid | overflow | precise"),
+    max_speedup: float = typer.Option(1.15, "--max-speedup"),
+    merge_threshold: int = typer.Option(250, "--merge-threshold"),
+    mode: str = typer.Option("all", "--mode", help="all | descriptive | dialogue"),
+    instructions: str | None = typer.Option(None, "--instructions"),
+    speed: float | None = typer.Option(None, "--speed", help="Base rate (piper default 1.2)"),
+    mux_mode: str = typer.Option("replace", "--mux-mode", help="replace | mix"),
+    piper_url: str | None = typer.Option(None, "--piper-url"),
+) -> None:
+    """Generate the track and mux it into the video in one step."""
+    with tempfile.TemporaryDirectory() as tmp:
+        track = Path(tmp) / "track.wav"
+        _render_track(
+            srt, track, video=video, backend=backend, voice=voice, strategy=strategy,
+            max_speedup=max_speedup, merge_threshold=merge_threshold, mode=mode,
+            instructions=instructions, piper_url=piper_url, speed=speed,
+        )
+        mux_audio(video, track, output, mode=mux_mode)
+    console.print(f"[green]Wrote[/] {output}")
+
+
+@app.command()
+def voices(
+    backend: str = typer.Option("piper", "--backend", help=f"One of: {', '.join(BACKENDS)}"),
+    piper_url: str | None = typer.Option(None, "--piper-url"),
+) -> None:
+    """List available voices for a backend."""
+    try:
+        engine = _build_backend(backend, None, piper_url, None)
+        for v in engine.list_voices():
+            console.print(v)
+    except (ValueError, RuntimeError) as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

srt2speech-1.0.0/src/srt2speech/filters.py

@@ -0,0 +1,50 @@
+"""Cue filtering for accessibility modes.
+
+SDH (subtitles for the deaf and hard-of-hearing) mark non-dialogue sound information as
+bracketed/parenthesized cues (``[door creaks]``, ``(ominous music)``) or all-caps sound effects
+(``THUNDER RUMBLES``). Keeping only those yields an audio-description-style track; dropping them
+yields a clean dialogue dub.
+
+The heuristics are whole-cue and intentionally simple; partial cues ("He runs. [gunshot]") are
+treated by their dominant form. Tune the regexes here if a corpus needs it.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+from .models import Cue
+
+_WRAPPED_RE = re.compile(r"^\s*[\[(].*[\])]\s*$", re.DOTALL)
+
+
+def is_descriptive(text: str) -> bool:
+    """True for bracketed/parenthesized cues or all-caps sound effects."""
+    stripped = text.strip()
+    if not stripped:
+        return False
+    if _WRAPPED_RE.match(stripped):
+        return True
+    letters = [c for c in stripped if c.isalpha()]
+    return bool(letters) and all(c.isupper() for c in letters)
+
+
+def keep_descriptive(cues: Iterable[Cue]) -> list[Cue]:
+    return [c for c in cues if is_descriptive(c.text)]
+
+
+def keep_dialogue(cues: Iterable[Cue]) -> list[Cue]:
+    return [c for c in cues if not is_descriptive(c.text)]
+
+
+def apply_mode(cues: Iterable[Cue], mode: str) -> list[Cue]:
+    """Select cues for a CLI ``--mode``: ``all`` | ``descriptive`` | ``dialogue``."""
+    cues = list(cues)
+    if mode == "all":
+        return cues
+    if mode == "descriptive":
+        return keep_descriptive(cues)
+    if mode == "dialogue":
+        return keep_dialogue(cues)
+    raise ValueError(f"unknown mode: {mode!r}")

srt2speech-1.0.0/src/srt2speech/fit.py

@@ -0,0 +1,106 @@
+"""The fit engine: make synthesized speech land inside a subtitle's time window.
+
+This is the heart of the tool. Each strategy is a different answer to "the speech is longer than
+the cue window":
+
+- ``overflow``  : never speed up; let speech run past the window into following silence. Best
+                  voice quality, timing can drift on dense subtitles.
+- ``hybrid``    : (default) allow natural overflow into the window plus the silent gap before the
+                  next segment; only when still too long, speed up, capped at ``max_speedup``.
+- ``precise``   : fit to the exact cue window (ignores the gap), speeding up to ``max_speedup``.
+
+Speed-up is achieved by re-synthesizing at a faster rate when the backend reports reliable speed
+control, otherwise by deterministic ffmpeg ``atempo`` time-stretching of the natural audio.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from pathlib import Path
+
+from pydub import AudioSegment
+
+from .models import Segment
+from .probe import require_tool
+from .tts.base import TTSBackend
+
+STRATEGIES = ("hybrid", "overflow", "precise")
+
+
+def _atempo_chain(factor: float) -> str:
+    """Build an atempo filter chain; a single atempo only accepts 0.5-2.0."""
+    parts: list[str] = []
+    f = factor
+    while f > 2.0:
+        parts.append("atempo=2.0")
+        f /= 2.0
+    while f < 0.5:
+        parts.append("atempo=0.5")
+        f /= 0.5
+    parts.append(f"atempo={f:.6f}")
+    return ",".join(parts)
+
+
+def time_stretch(audio: AudioSegment, factor: float) -> AudioSegment:
+    """Change tempo by `factor` (>1 faster) without altering pitch, via ffmpeg."""
+    if abs(factor - 1.0) < 1e-3:
+        return audio
+    ffmpeg = require_tool("ffmpeg")
+    with tempfile.TemporaryDirectory() as tmp:
+        src = Path(tmp) / "in.wav"
+        dst = Path(tmp) / "out.wav"
+        audio.export(src, format="wav")
+        subprocess.run(
+            [ffmpeg, "-y", "-i", str(src), "-filter:a", _atempo_chain(factor), str(dst)],
+            check=True, capture_output=True,
+        )
+        return AudioSegment.from_file(dst, format="wav")
+
+
+def _compress_to(
+    backend: TTSBackend,
+    segment: Segment,
+    natural: AudioSegment,
+    target_ms: int,
+    *,
+    voice: str | None,
+    instructions: str | None,
+    max_speedup: float,
+) -> AudioSegment:
+    target_ms = max(1, target_ms)
+    if len(natural) <= target_ms:
+        return natural
+    factor = min(len(natural) / target_ms, max_speedup)
+    if factor <= 1.0:
+        return natural
+    if backend.supports_reliable_speed:
+        return backend.synthesize(
+            segment.text, voice=voice, speed=factor, instructions=instructions
+        )
+    return time_stretch(natural, factor)
+
+
+def fit_segment(
+    backend: TTSBackend,
+    segment: Segment,
+    *,
+    voice: str | None = None,
+    strategy: str = "hybrid",
+    max_speedup: float = 1.15,
+    instructions: str | None = None,
+) -> AudioSegment:
+    """Synthesize `segment` and shape it to its window per `strategy`."""
+    if strategy not in STRATEGIES:
+        raise ValueError(f"unknown strategy {strategy!r}; choose from {', '.join(STRATEGIES)}")
+
+    natural = backend.synthesize(segment.text, voice=voice, instructions=instructions)
+    if strategy == "overflow":
+        return natural
+
+    window = segment.duration_ms
+    target = window if strategy == "precise" else window + segment.gap_after_ms
+    return _compress_to(
+        backend, segment, natural, target,
+        voice=voice, instructions=instructions, max_speedup=max_speedup,
+    )

srt2speech-1.0.0/src/srt2speech/models.py

@@ -0,0 +1,38 @@
+"""Core data structures: subtitle cues and the synthesis segments derived from them."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Cue:
+    """A single subtitle entry with millisecond timing."""
+
+    index: int
+    start_ms: int
+    end_ms: int
+    text: str
+
+    @property
+    def duration_ms(self) -> int:
+        return self.end_ms - self.start_ms
+
+
+@dataclass
+class Segment:
+    """A unit of speech to synthesize, spanning one or more merged cues.
+
+    `start_ms`/`end_ms` define the target window the synthesized audio should fit into.
+    `gap_after_ms` is the silence until the next segment starts, usable for overflow.
+    """
+
+    text: str
+    start_ms: int
+    end_ms: int
+    cues: list[Cue] = field(default_factory=list)
+    gap_after_ms: int = 0
+
+    @property
+    def duration_ms(self) -> int:
+        return self.end_ms - self.start_ms

srt2speech-1.0.0/src/srt2speech/mux.py

@@ -0,0 +1,43 @@
+"""Mux a generated audio track into a video with ffmpeg.
+
+- ``replace`` : drop any existing audio and use the generated track (restore/narrate use cases).
+- ``mix``     : blend the generated track over the existing audio (audio-description use case;
+                requires the source to already have an audio stream).
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from .probe import require_tool
+
+MODES = ("replace", "mix")
+
+
+def mux(
+    video: str | Path,
+    audio: str | Path,
+    out: str | Path,
+    *,
+    mode: str = "replace",
+) -> None:
+    if mode not in MODES:
+        raise ValueError(f"unknown mux mode {mode!r}; choose from {', '.join(MODES)}")
+    ffmpeg = require_tool("ffmpeg")
+    video, audio, out = str(video), str(audio), str(out)
+
+    if mode == "replace":
+        cmd = [
+            ffmpeg, "-y", "-i", video, "-i", audio,
+            "-map", "0:v:0", "-map", "1:a:0",
+            "-c:v", "copy", "-c:a", "aac", "-shortest", out,
+        ]
+    else:
+        cmd = [
+            ffmpeg, "-y", "-i", video, "-i", audio,
+            "-filter_complex", "[0:a][1:a]amix=inputs=2:duration=first[a]",
+            "-map", "0:v:0", "-map", "[a]",
+            "-c:v", "copy", "-c:a", "aac", out,
+        ]
+    subprocess.run(cmd, check=True, capture_output=True)

srt2speech-1.0.0/src/srt2speech/parse.py

@@ -0,0 +1,36 @@
+"""Subtitle loading. Delegates format handling (SRT/VTT/ASS/SSA) to pysubs2."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pysubs2
+
+from .models import Cue
+
+# pysubs2 keeps override tags out of `plaintext`, but ASS draws and stray markup can remain.
+_TAG_RE = re.compile(r"\{[^}]*\}|<[^>]+>")
+_WS_RE = re.compile(r"\s+")
+
+
+def _clean(text: str) -> str:
+    text = _TAG_RE.sub("", text)
+    text = text.replace("\\N", " ").replace("\\n", " ")
+    return _WS_RE.sub(" ", text).strip()
+
+
+def load_subtitles(path: str | Path) -> list[Cue]:
+    """Load a subtitle file into time-ordered cues with empty entries dropped."""
+    subs = pysubs2.load(str(path))
+    cues: list[Cue] = []
+    for event in sorted(subs, key=lambda e: e.start):
+        if event.is_comment:
+            continue
+        text = _clean(event.plaintext or event.text)
+        if not text:
+            continue
+        cues.append(
+            Cue(index=len(cues), start_ms=int(event.start), end_ms=int(event.end), text=text)
+        )
+    return cues

srt2speech-1.0.0/src/srt2speech/pipeline.py

@@ -0,0 +1,47 @@
+"""Orchestrates parse -> filter -> segment -> fit -> assemble into a single audio track."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+
+from pydub import AudioSegment
+
+from .assemble import assemble
+from .filters import apply_mode
+from .fit import fit_segment
+from .parse import load_subtitles
+from .segment import merge_cues
+from .tts.base import TTSBackend
+
+ProgressFn = Callable[[int, int], None]
+
+
+def generate_track(
+    subtitles: str | Path,
+    backend: TTSBackend,
+    *,
+    mode: str = "all",
+    strategy: str = "hybrid",
+    max_speedup: float = 1.15,
+    merge_threshold_ms: int = 250,
+    voice: str | None = None,
+    instructions: str | None = None,
+    total_ms: int | None = None,
+    progress: ProgressFn | None = None,
+) -> AudioSegment:
+    cues = apply_mode(load_subtitles(subtitles), mode)
+    segments = merge_cues(cues, merge_threshold_ms=merge_threshold_ms)
+
+    rendered = []
+    for i, seg in enumerate(segments):
+        audio = fit_segment(
+            backend, seg,
+            voice=voice, strategy=strategy,
+            max_speedup=max_speedup, instructions=instructions,
+        )
+        rendered.append((seg, audio))
+        if progress:
+            progress(i + 1, len(segments))
+
+    return assemble(rendered, total_ms=total_ms, sample_rate=backend.sample_rate)

srt2speech-1.0.0/src/srt2speech/probe.py

@@ -0,0 +1,27 @@
+"""Thin ffprobe wrapper for media duration."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+
+def require_tool(tool: str) -> str:
+    path = shutil.which(tool)
+    if path is None:
+        raise RuntimeError(f"{tool} not found on PATH; install ffmpeg")
+    return path
+
+
+def media_duration_ms(path: str | Path) -> int:
+    """Return the container duration in milliseconds via ffprobe."""
+    ffprobe = require_tool("ffprobe")
+    out = subprocess.run(
+        [ffprobe, "-v", "error", "-show_entries", "format=duration",
+         "-of", "json", str(path)],
+        capture_output=True, text=True, check=True,
+    )
+    duration = json.loads(out.stdout)["format"]["duration"]
+    return int(float(duration) * 1000)

srt2speech-1.0.0/src/srt2speech/segment.py

@@ -0,0 +1,45 @@
+"""Merge cues into sentence-sized synthesis segments.
+
+SRT often splits one sentence across several cues. Synthesizing each cue independently produces
+choppy prosody, so we merge consecutive cues into a single segment unless they are separated by a
+real pause or the earlier cue ends a sentence. The merged segment's window spans the union of its
+cues; per-cue timing is intentionally collapsed into one target window.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .models import Cue, Segment
+
+_SENTENCE_END_RE = re.compile(r"[.!?…][\"')\]]?\s*$")
+
+
+def _make_segment(buf: list[Cue]) -> Segment:
+    return Segment(
+        text=" ".join(c.text for c in buf),
+        start_ms=buf[0].start_ms,
+        end_ms=buf[-1].end_ms,
+        cues=list(buf),
+    )
+
+
+def merge_cues(cues: list[Cue], merge_threshold_ms: int = 250) -> list[Segment]:
+    """Group cues into segments, splitting on pauses or sentence boundaries."""
+    segments: list[Segment] = []
+    buf: list[Cue] = []
+    for cue in cues:
+        if buf:
+            prev = buf[-1]
+            gap = cue.start_ms - prev.end_ms
+            if gap > merge_threshold_ms or _SENTENCE_END_RE.search(prev.text):
+                segments.append(_make_segment(buf))
+                buf = []
+        buf.append(cue)
+    if buf:
+        segments.append(_make_segment(buf))
+
+    for i, seg in enumerate(segments):
+        nxt = segments[i + 1] if i + 1 < len(segments) else None
+        seg.gap_after_ms = max(0, nxt.start_ms - seg.end_ms) if nxt else 0
+    return segments

srt2speech-1.0.0/src/srt2speech/tts/__init__.py

@@ -0,0 +1,28 @@
+"""Backend registry. Add a backend by subclassing TTSBackend and registering it here."""
+
+from __future__ import annotations
+
+from .base import TTSBackend
+from .elevenlabs import ElevenLabsBackend
+from .openai import OpenAIBackend
+from .piper import PiperBackend
+
+BACKENDS: dict[str, type[TTSBackend]] = {
+    "piper": PiperBackend,
+    "openai": OpenAIBackend,
+    "elevenlabs": ElevenLabsBackend,
+}
+
+
+def get_backend(name: str, *, voice: str | None = None, **extra: object) -> TTSBackend:
+    cls = BACKENDS.get(name)
+    if cls is None:
+        available = ", ".join(sorted(BACKENDS))
+        raise ValueError(f"unknown backend {name!r}; available: {available}")
+    kwargs = dict(extra)
+    if voice is not None:
+        kwargs["voice"] = voice
+    return cls(**kwargs)
+
+
+__all__ = ["TTSBackend", "BACKENDS", "get_backend"]

srt2speech-1.0.0/src/srt2speech/tts/base.py

@@ -0,0 +1,35 @@
+"""The backend contract. The fit engine depends only on this interface."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from pydub import AudioSegment
+
+
+class TTSBackend(ABC):
+    """A text-to-speech engine.
+
+    `supports_reliable_speed` tells the fit engine whether asking the backend to re-synthesize at
+    a given `speed` is trustworthy. When True, the fit engine prefers a second-pass re-synthesis to
+    hit a target duration (higher quality); when False, it falls back to deterministic ffmpeg
+    time-stretching of the natural audio.
+    """
+
+    name: str = "base"
+    supports_reliable_speed: bool = False
+    sample_rate: int = 24000
+
+    @abstractmethod
+    def synthesize(
+        self,
+        text: str,
+        *,
+        voice: str | None = None,
+        speed: float = 1.0,
+        instructions: str | None = None,
+    ) -> AudioSegment:
+        """Synthesize `text` to a pydub AudioSegment."""
+
+    def list_voices(self) -> list[str]:
+        return []

srt2speech-1.0.0/src/srt2speech/tts/elevenlabs.py

@@ -0,0 +1,84 @@
+"""Paid TTS via ElevenLabs (/v1/text-to-speech).
+
+ElevenLabs leads on naturalness and is purpose-built for dubbing. Its delivery is shaped by the
+voice and ``voice_settings`` rather than natural-language instructions, and its ``speed`` knob is
+range-limited (0.7-1.2) and quality-affecting, so we set ``supports_reliable_speed = False`` and
+let the fit engine handle timing via ffmpeg time-stretch. ``--voice`` accepts a voice name (resolved
+against the account's library) or a raw voice id.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+
+import httpx
+from pydub import AudioSegment
+
+from .base import TTSBackend
+
+API_BASE = "https://api.elevenlabs.io/v1"
+MODEL = "eleven_multilingual_v2"
+OUTPUT_FORMAT = "mp3_44100_128"
+DEFAULT_VOICE = "21m00Tcm4TlvDq8ikWAM"  # Rachel, a stock voice present on every account.
+SPEED_RANGE = (0.7, 1.2)
+
+
+class ElevenLabsBackend(TTSBackend):
+    name = "elevenlabs"
+    supports_reliable_speed = False
+    sample_rate = 44100
+
+    def __init__(
+        self,
+        voice: str = DEFAULT_VOICE,
+        model: str = MODEL,
+        speed: float = 1.0,
+        api_key: str | None = None,
+        timeout: float = 120.0,
+    ) -> None:
+        key = api_key or os.environ.get("ELEVENLABS_API_KEY")
+        if not key:
+            raise RuntimeError("ELEVENLABS_API_KEY is not set")
+        self.default_voice = voice
+        self.model = model
+        self.base_speed = speed
+        self._voice_index: dict[str, str] | None = None
+        self._client = httpx.Client(timeout=timeout, headers={"xi-api-key": key})
+
+    def synthesize(
+        self,
+        text: str,
+        *,
+        voice: str | None = None,
+        speed: float = 1.0,
+        instructions: str | None = None,
+    ) -> AudioSegment:
+        voice_id = self._resolve_voice(voice or self.default_voice)
+        payload: dict[str, object] = {"text": text, "model_id": self.model}
+        effective_speed = self.base_speed * speed
+        if effective_speed != 1.0:
+            lo, hi = SPEED_RANGE
+            payload["voice_settings"] = {"speed": min(max(effective_speed, lo), hi)}
+        resp = self._client.post(
+            f"{API_BASE}/text-to-speech/{voice_id}",
+            params={"output_format": OUTPUT_FORMAT},
+            json=payload,
+        )
+        resp.raise_for_status()
+        return AudioSegment.from_file(io.BytesIO(resp.content), format="mp3")
+
+    def list_voices(self) -> list[str]:
+        return sorted(self._voice_map())
+
+    def _resolve_voice(self, voice: str) -> str:
+        return self._voice_map().get(voice, voice)
+
+    def _voice_map(self) -> dict[str, str]:
+        if self._voice_index is None:
+            resp = self._client.get(f"{API_BASE}/voices")
+            resp.raise_for_status()
+            self._voice_index = {
+                v["name"]: v["voice_id"] for v in resp.json().get("voices", [])
+            }
+        return self._voice_index

srt2speech-1.0.0/src/srt2speech/tts/openai.py

@@ -0,0 +1,77 @@
+"""Paid TTS via OpenAI's /v1/audio/speech (gpt-4o-mini-tts).
+
+gpt-4o-mini-tts steers delivery through the natural-language ``instructions`` parameter rather than
+a numeric rate; its ``speed`` parameter is reported as unreliable/quality-degrading. We therefore
+set ``supports_reliable_speed = False`` so the fit engine handles timing via ffmpeg time-stretch
+instead of trusting backend re-pacing. Input is capped around 2000 tokens, which sentence-sized
+segments stay well under.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+
+import httpx
+from pydub import AudioSegment
+
+from .base import TTSBackend
+
+API_URL = "https://api.openai.com/v1/audio/speech"
+MODEL = "gpt-4o-mini-tts"
+VOICES = [
+    "alloy", "ash", "ballad", "coral", "echo",
+    "fable", "nova", "onyx", "sage", "shimmer",
+]
+DEFAULT_VOICE = "coral"
+
+
+class OpenAIBackend(TTSBackend):
+    name = "openai"
+    supports_reliable_speed = False
+    sample_rate = 24000
+
+    def __init__(
+        self,
+        voice: str = DEFAULT_VOICE,
+        model: str = MODEL,
+        speed: float = 1.0,
+        api_key: str | None = None,
+        timeout: float = 120.0,
+    ) -> None:
+        key = api_key or os.environ.get("OPENAI_API_KEY")
+        if not key:
+            raise RuntimeError("OPENAI_API_KEY is not set")
+        self.default_voice = voice
+        self.model = model
+        self.base_speed = speed
+        self._client = httpx.Client(
+            timeout=timeout,
+            headers={"Authorization": f"Bearer {key}"},
+        )
+
+    def synthesize(
+        self,
+        text: str,
+        *,
+        voice: str | None = None,
+        speed: float = 1.0,
+        instructions: str | None = None,
+    ) -> AudioSegment:
+        payload: dict[str, object] = {
+            "model": self.model,
+            "input": text,
+            "voice": voice or self.default_voice,
+            "response_format": "wav",
+        }
+        if instructions:
+            payload["instructions"] = instructions
+        effective_speed = self.base_speed * speed
+        if effective_speed != 1.0:
+            payload["speed"] = effective_speed
+        resp = self._client.post(API_URL, json=payload)
+        resp.raise_for_status()
+        return AudioSegment.from_file(io.BytesIO(resp.content), format="wav")
+
+    def list_voices(self) -> list[str]:
+        return list(VOICES)

srt2speech-1.0.0/src/srt2speech/tts/piper.py

@@ -0,0 +1,70 @@
+"""Local TTS via a gopipertts server (https://github.com/nbr23/gopipertts).
+
+gopiper exposes ``GET/POST /api/tts`` with ``text``, ``voice``, ``speed`` (a reliable rate
+multiplier) and ``outputFormat``, plus ``GET /api/voices``. Its ``speed`` is a genuine re-pacing,
+so this backend advertises reliable speed control.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+
+import httpx
+from pydub import AudioSegment
+
+from .base import TTSBackend
+
+DEFAULT_URL = "http://localhost:8080"
+DEFAULT_VOICE = "en_US-ryan-high"
+# Piper at 1.0 is slow and flat; a small baseline lift makes narration livelier.
+DEFAULT_SPEED = 1.2
+
+
+class PiperBackend(TTSBackend):
+    name = "piper"
+    supports_reliable_speed = True
+    sample_rate = 22050
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        voice: str = DEFAULT_VOICE,
+        speed: float = DEFAULT_SPEED,
+        timeout: float = 120.0,
+    ) -> None:
+        url = base_url or os.environ.get("SRT2SPEECH_PIPER_URL", DEFAULT_URL)
+        self.base_url = url.rstrip("/")
+        self.default_voice = voice
+        self.base_speed = speed
+        self._client = httpx.Client(timeout=timeout)
+
+    def synthesize(
+        self,
+        text: str,
+        *,
+        voice: str | None = None,
+        speed: float = 1.0,
+        instructions: str | None = None,
+    ) -> AudioSegment:
+        params = {
+            "text": text,
+            "voice": voice or self.default_voice,
+            "speed": self.base_speed * speed,
+            "outputFormat": "wav",
+        }
+        resp = self._client.get(f"{self.base_url}/api/tts", params=params)
+        resp.raise_for_status()
+        return AudioSegment.from_file(io.BytesIO(resp.content), format="wav")
+
+    def list_voices(self) -> list[str]:
+        resp = self._client.get(f"{self.base_url}/api/voices")
+        resp.raise_for_status()
+        data = resp.json()
+        voices: list[str] = []
+        for item in data:
+            if isinstance(item, str):
+                voices.append(item)
+            elif isinstance(item, dict):
+                voices.append(str(item.get("key") or item.get("name") or item.get("id") or item))
+        return voices