Dubbing: per-language subtitle scripts and export_srt

[spencer-zqian]

POST /v1/dubbing gained two parameters, both live in production. This brings them to the client and the CLI.

subtitles — one script per target language

A dubbing job can now carry the exact lines you want spoken, instead of the pipeline translating for you. One script per language being dubbed into, as subtitles[<language>] on the wire.

result = client.dubbing.generate(
    video="ep1.mp4",
    languages=["ja", "tr"],
    subtitles={"ja": "ep1.ja.vtt", "tr": "https://cdn.example.com/ep1.tr.srt"},
    export_srt=True,
)
result.save_all("./dubbed")
result.save_all_subtitles("./dubbed")

A value is a string or a Path: one starting with https:// is sent as a URL, anything else is a local path, opened and uploaded. A suffix that is not .srt or .vtt is refused before the request goes out.

The set of languages must match languages exactly, but that rule is not copied client-side: the server owns it and its message names the offending code. Language codes are likewise not validated here, for the same reason the existing code gives.

export_srt

Off by default, and requires subtitles. On, each language's final audio is force-aligned against its script and a re-timed SRT comes back with the lines preserved verbatim. save_subtitle and save_all_subtitles fetch them, mirroring save and save_all, with async twins.

An export can be blocked for one language without failing the job. That language keeps its video and simply has no SRT. save_all_subtitles skips it; save_subtitle raises naming the language and its status.

The CLI writes the SRT beside the video: --output clip.mp4 gives clip.ja.mp4 and clip.ja.srt. An --output ending in .srt is refused with --export-srt, since the subtitle would land on the video's own path.

File handles

build_dubbing_parts can now open several files instead of one, so its third return value went from an opened bool to the MultiClose that build_ducking_parts already uses. Every path was checked for leaks: a raise partway through the opens, a raise from the HTTP call, and the routine 422 all close every handle, in both the sync and async clients.

Numbers arrive as strings

The finished task carries cue_count and alignment_loss as strings rather than numbers. The reports are passed through as received rather than coerced, so the values are whatever the server sent, and the CLI formats the loss defensively.

Preflight

submit() now returns a DubbingTask, which adds the per-language preflight report the 202 has always carried. A review_required status means the pipeline changed lines in the script you sent. SfxTask is untouched — it is shared with every other endpoint.

--ducking on the CLI

sonilo dubbing never exposed it, though the JavaScript CLI has since the ducking round. Added here so the two CLIs mirror each other.

Tests

Core 316 passing, CLI 167 passing, on both Python 3.9 and 3.12. The new tests were checked against the pre-change code and fail there.

sonilo 0.17.0, sonilo-cli 0.16.0, and the CLI's pin widened to match. Publish sonilo first — the CLI hard-requires sonilo>=0.17.0, so the reverse order leaves a window where pip install sonilo-cli cannot resolve.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WWHfnbRaXRdAH2sjm8mApk

[lightsage-app]

Lightsage docs evals

Waiting for the staging docs URL before running evals.

Lightsage will start the selected PR evals automatically when GitHub reports a successful docs deployment for this PR. This usually happens within 15 minutes.

Commit: 8b9e877
Status: waiting for staging docs URL