Metadata-Version: 2.4
Name: twat-speech
Version: 2.7.7
Summary: Speech, subtitle, TTS, and dubbing helpers for the twat plugin ecosystem
Project-URL: Documentation, https://github.com/twardoch/twat-speech#readme
Project-URL: Issues, https://github.com/twardoch/twat-speech/issues
Project-URL: Source, https://github.com/twardoch/twat-speech
Author-email: Adam Twardoch <adam+github@twardoch.com>
License-Expression: MIT
License-File: LICENSE
Keywords: speech,subtitles,transcription,tts,twat-plugin
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Requires-Dist: twat>=1.8.1
Provides-Extra: all
Requires-Dist: twat>=1.8.1; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.15.0; extra == 'dev'
Requires-Dist: pre-commit>=4.1.0; extra == 'dev'
Requires-Dist: ruff>=0.9.6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.27.0; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest-benchmark[histogram]>=5.1.0; extra == 'test'
Requires-Dist: pytest-cov>=6.0.0; extra == 'test'
Requires-Dist: pytest-xdist>=3.6.1; extra == 'test'
Requires-Dist: pytest>=8.3.4; extra == 'test'
Description-Content-Type: text/markdown

# twat-speech

`twat-speech` is the speech-domain package for the `twat` ecosystem. It owns transcription orchestration, subtitle repair, TTS calls, and deterministic dubbing plans while leaving provider clients in `twat_genai` and audio-file transforms in `twat_audio`.

## Python API

```python
from twat_speech import repair_subtitles, dub_plan, transcribe, synthesize

fixed = repair_subtitles(open("captions.srt").read())
plan = dub_plan("movie.mp4", fixed, language="de")
transcript = transcribe("speech.wav")
speech_file = synthesize("Hello", "hello.wav")
```

Implemented helpers:

- `parse_srt`, `format_srt`, `repair_srt`, `repair_subtitles`.
- `subtitle_transcript` for plain transcript extraction.
- `transcribe` and `synthesize` as thin `twat_genai` provider adapters.
- `dub_plan` / `create_dub_plan` for deterministic dubbing orchestration.
- optional `transcribe(..., preprocess=True)` delegates resampling to `twat_audio` before provider transcription.

## CLI

```bash
python -m twat_speech --help
python -m twat_speech repair-srt captions.srt captions.fixed.srt
python -m twat_speech dub movie.mp4 captions.fixed.srt --language de
python -m twat_speech transcribe speech.wav
python -m twat_speech synthesize "Hello" hello.wav
```

## Boundaries

- `twat_genai` owns speech providers for STT/TTS and future dubbing engines.
- `twat_audio` owns audio-file transforms such as resampling, trimming, normalization, and audio extraction.
- `twat_speech` owns speech-specific orchestration, subtitles, transcripts, and dubbing plans.

## Reference scripts

Reusable subtitle repair ideas from `srtmultifix.py`, extraction workflows from `mkv2srt.py`, and planning ideas from `vidpredub.py`/`viddub-*` are represented here as package APIs. Provider-specific or workstation-specific batch dubbing scripts remain in `reference/bin-img-vid/` because they combine local credentials, shell glue, and one-off media workflows.
