srtspeak
Multilingual SRT TTS. Forces each cue into its exact start/end window (xAI Grok TTS + ffmpeg).
Also includes SRT→SRT translation (translate) and glossary suggestion (glossary-suggest) via xAI's Responses REST API (default model grok-4.7, same XAI_API_KEY).
Authoritative design: DESIGN.md (implementation-aligned).
Translate design: docs/SRT_TRANSLATE_DESIGN.md.
Requirements
| Item | Detail |
|---|---|
| OS | Windows / macOS / Linux (developed and verified on Windows) |
| Python | 3.11+ |
| ffmpeg / ffprobe | Prefer on PATH; optional fallback via imageio-ffmpeg |
| API key | XAI_API_KEY only for real TTS / translate / glossary / ja_yomi (dry-run makes no text-model request) |
Package version: 0.1.7 (pyproject.toml).
Install
From PyPI:
python -m pip install srtspeak
Optional ffmpeg fallback via pip:
python -m pip install "srtspeak[ffmpeg]"
Core install already includes PySide6 (GUI) and keyring (OS credential store).
After install, the srtspeak command is available:
srtspeak --help
srtspeak doctor
From source (development)
Clone the repository, then editable install from the repo root:
git clone https://github.com/awaku7/srtspeak.git
cd srtspeak
python -m pip install -e ".[ffmpeg,dev]"
Dev extras ([dev]): pytest / ruff / Babel / keyring.
Without install (repo checkout only):
set PYTHONPATH=src
python -m srtspeak --help
There is no [ja] extra. Japanese kanji→hiragana preprocess (ja_yomi) uses the Responses REST API with the same XAI_API_KEY (default on for lang=ja). Text generation defaults to grok-4.7; TTS continues to use the separate /v1/tts endpoint. Responses are sent with store: false. No xAI SDK or gRPC dependency is required.
Launch
After pip install (PyPI or editable), use the srtspeak entry point:
srtspeak gui
srtspeak doctor
srtspeak --help
srtspeak dry-run --srt GRAN_TENKU_japan.srt --lang ja
python -m srtspeak gui
When ffmpeg is missing
Resolution order (core/ffmpeg_resolve.py):
ffmpeg/ffprobeonPATH(shutil.which)- Optional dependency
imageio-ffmpegbundled binary (get_ffmpeg_exe()) - Otherwise
FFmpegNotFoundError
| Situation | Behavior |
|---|---|
srtspeak doctor |
Prints ffmpeg: MISSING (...). Exit code 0 (diagnostics only) |
dry-run (build) |
ffmpeg not required (parse + char count + cost estimate only) |
Real build / build-all |
Fails at fit stage. CLI exit code 2 |
translate / glossary-suggest |
ffmpeg not required |
imageio-ffmpeg only |
Works, but ffprobe may be (none). Full PATH ffmpeg is recommended |
Install examples (Windows)
WinGet (recommended):
winget install Gyan.FFmpeg
Then in a new terminal:
ffmpeg -version
ffprobe -version
srtspeak doctor
If you prefer not to change PATH:
python -m pip install "srtspeak[ffmpeg]"
srtspeak doctor
doctor shows source: path for system ffmpeg, or source: imageio_ffmpeg for the pip bundle.
xAI (Grok TTS / Responses API) signup and API key
TTS is xAI Grok only (POST https://api.x.ai/v1/tts).
Japanese yomi, SRT translate, glossary-suggest, and language detection use Grok 4.7 via the Responses REST API (POST /v1/responses, store: false). TTS remains on the separate /v1/tts endpoint. Create the key in the console.
1. Account
- Open https://console.x.ai/
- Sign up / log in (xAI account)
- Accept terms and set up billing / credits as guided
- TTS is usage-based. dry-run estimate uses $15 / 1M characters (implementation unit price)
- ja_yomi / translate / glossary Chat calls are additional usage when enabled
2. Create an API key
- Open API Keys (or equivalent) in the console
- Create a new key
- Copy the value (often starts with
xai-)- It may not be shown again — put it in an env var immediately
- Do not put the key in chat, Git,
report.json, or screenshots
Official docs:
- Text to Speech
- Voice
- API:
https://api.x.ai/v1/tts/ voices:https://api.x.ai/v1/tts/voices
3. How this tool reads the key
| Rule | Detail |
|---|---|
| Variable | XAI_API_KEY only |
| CLI flag | No --api-key (avoids shell history) |
| Persistence | No .env; never written to report/logs/gui_settings.json |
| Resolve order | env → session → OS keyring → legacy Windows DPAPI (migrate) → CLI getpass / GUI mask |
| dry-run | Key optional (text-model requests are skipped if missing) |
| Real TTS / translate / glossary | resolve chain; missing → exit code 2 |
| GUI | Key-ready state locks the field; Change / Override enables a session override. Save on this PC writes to OS storage; Clear saved removes only the stored key, not environment/session keys. |
Windows cmd (current window only):
set "XAI_API_KEY=xai-..."
srtspeak doctor
PowerShell:
$env:XAI_API_KEY = "xai-..."
srtspeak doctor
Persist for new terminals (cmd):
setx XAI_API_KEY "xai-..."
doctor shows presence only (source label):
XAI_API_KEY: set (env)
XAI_API_KEY: set (keyring)
XAI_API_KEY: set (dpapi)
or:
XAI_API_KEY: missing
Invalid key / insufficient balance surfaces as TTS error: ... / translate error: ... during run (exit code 1).
Commands
srtspeak --help
srtspeak doctor
srtspeak languages
srtspeak voices
srtspeak gui
srtspeak build --help
srtspeak build-all --help
srtspeak dry-run --help
srtspeak translate --help
srtspeak glossary-suggest --help
| Command | Purpose |
|---|---|
doctor |
Check XAI_API_KEY, ffmpeg/ffprobe, ja_yomi, translate, glossary-suggest, PySide6 |
languages |
Language codes sendable to the API |
voices |
Grok voices (API if key present, else builtin; male + female) |
dry-run |
Parse + char count + TTS cost estimate (no ffmpeg) |
build |
Generate one language (TTS) |
build-all |
Generate multiple languages in sequence |
translate |
SRT→SRT multi-target translation (Grok 4.7 Responses; timing-locked) |
glossary-suggest |
Propose glossary JSON from source SRT via Grok 4.7 Responses |
gui |
PySide6 GUI (Build + Translate tabs) |
Global options:
--locale en|ja UI locale (default: SRTSPEAK_LOCALE → LC_ALL/LANG → system → en)
--verbose / --quiet
Place --quiet / --verbose before the subcommand:
srtspeak --locale ja doctor
srtspeak --verbose build --srt sample.srt --lang ja --dry-run
Input / output layout
TTS build
--out is the output root. Artifacts always go under {out}/{lang}/.
out/{lang}/
cues/{source_token}/ per-cue audio (normalized), per input SRT
fitted/{source_token}/ duration-fitted audio, per input SRT
{output_stem}_{source_id}_{lang}.wav
{output_stem}_{source_id}_{lang}.mp3 # if --also-mp3
report_{source_token}.json # report for this input SRT
report.json # latest-run compatibility report
out/work/{lang}/
raw/{source_token}/
cache/
ja_yomi_cache.json when ja + ja_yomi
- Default root:
out→ e.g.out/ja/ {source_id}is the first 12 hex digits of SHA-256 over the normalized absolute SRT path;{source_token}is{input_stem}_{source_id}.{output_stem}is the input filename stem with a trailing_{lang}removed, if present.--out out/enwith--lang en→out/en/(no double nesting)--out artifactswith--lang pt→artifacts/pt/build-allwritessummary.jsonat the out root
Translate
--out default: out/srt_gen. Work cache under out/work/translate/by_out/ (keyed by output SRT file name).
out/srt_gen/
translate_report.json
{target}/ # BCP-47 token (e.g. en, pt-BR)
{source_stem}_{target}.srt # naming=stem (default)
GRAN_TENKU_{target}.srt # naming=gran_tenku
out/work/translate/by_out/
{target}__{out_srt_name}.json # e.g. en__GRAN_TENKU_en.srt.json
Usage
Environment check
srtspeak doctor
Before a real build you typically want:
XAI_API_KEY: set (env)ffmpeg:path withsource: path(orimageio_ffmpeg)ja_yomi: xAI Responses REST (Grok 4.7)translate: xAI Responses REST (same XAI_API_KEY)glossary-suggest: xAI Responses REST (same XAI_API_KEY)
Cost estimate (no ffmpeg)
srtspeak dry-run --srt GRAN_TENKU_japan.srt --lang ja
Single-language build
set "XAI_API_KEY=xai-..."
srtspeak build --srt GRAN_TENKU_japan.srt --lang ja --voice-id leo
srtspeak build --srt GRAN_TENKU_English.srt --lang en --voice-id leo --out out
srtspeak build --srt GRAN_TENKU_Portugus.srt --lang pt --voice-id leo
Main options:
| Option | Meaning | Default |
|---|---|---|
--srt |
Input SRT | required |
--lang |
Internal key ja / en / pt … |
may be guessed from filename |
--language-code |
BCP-47 sent to API | lang default (pt→pt-BR) |
--out |
Output root (lang appended) | out |
--work-dir |
Work root | out/work |
--voice-id |
Voice ID (or lang=id for build-all) |
leo |
--short-mode |
pad / stretch |
pad |
--max-speed |
Cap on atempo product; over → hard_trim | none |
--tail-pad-ms |
Silence after last cue end (no base_wav) | 0 |
--base-wav |
Mix narration onto this WAV (keeps base rate/ch) | none |
--ja-yomi / --no-ja-yomi |
JA kanji→hiragana via Grok 4.7 Responses REST API | on |
--strip-emoticons / --no-strip-emoticons |
Strip kaomoji for TTS only; emoji kept; SRT unchanged | on |
--no-cache |
Ignore existing TTS/ja_yomi caches (still write after success) | off |
--limit N |
First N cues only | all |
--dry-run |
Estimate only | off |
--also-mp3 |
Also write mp3 of final track | off |
--jobs |
Parallelism (MVP: 1 only) | 1 |
Smoke a few cues:
srtspeak build --srt GRAN_TENKU_japan.srt --lang ja --limit 3 --voice-id leo
Portuguese as pt-PT:
srtspeak build --srt GRAN_TENKU_Portugus.srt --lang pt --language-code pt-PT --voice-id leo
Mix onto an existing bed:
srtspeak build --srt GRAN_TENKU_japan.srt --lang ja --base-wav bed.wav --voice-id leo
Disable Japanese yomi:
srtspeak build --srt GRAN_TENKU_japan.srt --lang ja --no-ja-yomi --voice-id leo
Force fresh TTS (ignore caches):
srtspeak build --srt GRAN_TENKU_japan.srt --lang ja --no-cache --voice-id leo
Multi-language batch
srtspeak build-all ^
--map ja=GRAN_TENKU_japan.srt ^
--map en=GRAN_TENKU_English.srt ^
--map pt=GRAN_TENKU_Portugus.srt ^
--voice-id leo ^
--out out
Per-language voices:
srtspeak build-all ^
--map ja=GRAN_TENKU_japan.srt ^
--map en=GRAN_TENKU_English.srt ^
--voice-id ja=leo --voice-id en=orion
Translate (SRT→SRT)
Timing-locked multi-target translation. Cue count / index / start-end ms stay identical; only text changes. Provider: xAI Responses REST with structured JSON (grok-4.7 default, store: false). Separate from the TTS pipeline. Existing translation cache/output may contain results from the previous model; pass --no-cache to regenerate through Grok 4.7.
set "XAI_API_KEY=xai-..."
srtspeak translate ^
--srt GRAN_TENKU_japan.srt ^
--source-lang ja ^
--to en --to pt-BR --to es ^
--out out/srt_gen ^
--glossary glossary.json ^
--length-mode hint
| Option | Meaning | Default |
|---|---|---|
--srt |
Source SRT | required |
--source-lang |
Source language | filename guess / ja |
--to |
Target BCP-47 (repeat or comma-separated) | required (≥1) |
--out |
Output root | out/srt_gen |
--work-dir |
Work root | out/work |
--glossary |
Glossary JSON path | none |
--length-mode |
off / hint / enforce / report-only |
hint |
--on-empty |
fail / keep-source |
fail |
--batch-size |
Cues per Responses request | 8 |
--model |
Grok model id | grok-4.7 |
--limit N |
First N cues only | all |
--dry-run |
Cue/character counts, budget-over estimate and batch count only; no API or token/cost estimate | off |
--fail-fast |
Stop on first target error | off |
--no-cache |
Ignore existing translate caches (still write) | off |
--naming |
stem → {source_stem}_{lang}.srt / gran_tenku → GRAN_TENKU_{lang}.srt |
stem |
Dry-run:
srtspeak translate --srt GRAN_TENKU_japan.srt --to en,pt-BR --dry-run
Then TTS the generated SRT:
srtspeak build-all ^
--map ja=GRAN_TENKU_japan.srt ^
--map en=out/srt_gen/en/GRAN_TENKU_japan_en.srt ^
--voice-id leo --out out
(With --naming gran_tenku, paths become out/srt_gen/en/GRAN_TENKU_en.srt.)
Glossary suggest
srtspeak glossary-suggest ^
--srt GRAN_TENKU_japan.srt ^
--source-lang ja ^
--to en --to pt-BR ^
--out glossary.json
| Option | Meaning | Default |
|---|---|---|
--srt |
Source SRT | required |
--source-lang |
Source language | filename guess / ja |
--to |
Target BCP-47 (repeat or comma-separated) | required |
--out |
Output glossary JSON | glossary.json |
--merge |
Merge into existing glossary (existing wins on conflict) | none |
--force |
Overwrite --out without merge |
off |
--min-count |
Min local term frequency for candidates | 2 |
--model |
Grok model id | grok-4.7 |
--limit N |
First N cues only | all |
If --out already exists and --force is not set, new suggestions are merged with existing terms (existing preferred).
GUI
srtspeak gui
- Tabs: Build (TTS) and Translate
- Build: SRT, language (BCP-47 + Detect), voice, absolute output folder + directory picker, base WAV, max cues, dry-run, ja_yomi, strip kaomoji, no-cache
- Translate: source SRT, source lang, multi-target checkboxes, absolute output folder + directory picker, glossary path + Suggest, length mode, batch size, naming (
stem/gran_tenku), fail-fast, no-cache, dry-run - Shared: API key (masked) + status/placeholder showing load source (env / keyring / DPAPI / session) + Save on this PC / Clear saved
- Key input: whitespace/newlines stripped (
normalize_api_key); language detect uses the same resolve chain as build/translate - Completion: non-modal result dialog; main window stays open
- Browse / path confirm: filename → source language guess (
guess_lang_from_filename) - Progress: bottom status + bar (0–1000); worker → thread-safe queue + ~80ms drain; Cancel via
CancellationToken - Optional diag:
SRTSPEAK_GUI_PROGRESS_LOG=1→out/work/gui_progress.logonly - Non-secret settings in
gui_settings.json(never the key plaintext) - UTF-8 defaults: CLI/GUI set
PYTHONUTF8=1andPYTHONIOENCODING=utf-8when unset
Processing notes
TTS build
- Pipeline: parse → limit → ja_yomi (ja) → TTS/cache → normalize → fit → timeline → report
- TTS: xAI Grok unary REST only (
speedalways 1.0) - ja_yomi: Grok 4.7 Responses REST structured JSON, batch 5, cache under
out/work/{lang}/ - strip_emoticons: kaomoji stripped for TTS speak text only; emoji kept; stored SRT cues unchanged; default on
- Fit: ffmpeg CLI only (
atempo0.5–2.0 multi-stage; short cues default to pad) - Timeline: silence canvas or base_wav; place in half-open
[start, end); PCM add-mix (clip ±32767) - Track length: last cue end +
tail_pad_ms, or base_wav length when--base-wavis set - Audio (no base): mono s16le 24 kHz WAV; with base: base native rate/channels preserved
- Cost estimate (dry-run): $15 / 1M chars (TTS text; Chat yomi not included in that figure)
- Voices: builtin catalog includes male and female; default
leo --no-cache: skip reading TTS/ja_yomi caches; still write after success
Translate
- Pipeline: parse → limit → per target: cache → Responses API batches → structure lock → write SRT →
translate_report.json - Structure lock: cue count / index / start_ms / end_ms identical to source
- Glossary optional (
terms/do_not_translate/tone) - length_mode
hint(default) injects budget into prompt;enforcemay run a 2nd compress pass - Model default
grok-4.7; batch_size default 8
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success (doctor is 0 even if ffmpeg is missing) |
| 1 | Runtime errors (e.g. TTS / translate / glossary) |
| 2 | Config/args/invalid SRT/ffmpeg missing/key missing |
| 130 | Cancelled (Ctrl+C) |
Development
git clone https://github.com/awaku7/srtspeak.git
cd srtspeak
python -m pip install -e ".[dev,ffmpeg]"
set PYTHONPATH=src
python -m pytest -q
python -m ruff check src tests
python -m ruff format src tests
i18n (when messages change):
python scripts/update_i18n.py
Sample inputs (expected alongside the repo)
| File | lang | Notes |
|---|---|---|
GRAN_TENKU_japan.srt |
ja |
ja_yomi default on |
GRAN_TENKU_English.srt |
en |
|
GRAN_TENKU_Portugus.srt |
pt |
API default pt-BR if unspecified |
Timecodes are assumed aligned across the three files (design-time: 293 cues, 00:00:07,600–00:12:44,000).
License
Apache License 2.0 (see LICENSE)
Author
Hirofumi Ukawa hirofumi@ukawa.biz
Metadata
Release files for srtspeak 0.1.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| srtspeak-0.1.7-py3-none-any.whl | Python 3 | none | any | Details for srtspeak-0.1.7-py3-none-any.whl |
Release files / srtspeak-0.1.7-py3-none-any.whl
| Download URL | srtspeak-0.1.7-py3-none-any.whl |
|---|---|
| Size | 130.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9a9950b9419124fefff8866754e5b1eaf19a524222ef7f8a5f9d5eb6a2827303
|
|
BLAKE2b-256 checksum How to use checksums |
24546add1f5c70fd3f9cca6fdac20ff8dbef8a5d2d2cf73cb7afac9da1b06547
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.10
|
Security for srtspeak 0.1.7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.