Metadata-Version: 2.4
Name: kinescript-kokoro
Version: 0.1.0
Summary: Kokoro voices for kine voice: speaks a scene's text and times each word
Author: Dr. Know How
License-Expression: MIT
Project-URL: Homepage, https://github.com/drknowhow/kinescript/tree/main/plugins/kinescript-kokoro
Project-URL: Documentation, https://drknowhow.github.io/kinescript/
Project-URL: Source, https://github.com/drknowhow/kinescript/tree/main/plugins/kinescript-kokoro
Project-URL: Issues, https://github.com/drknowhow/kinescript/issues
Project-URL: Changelog, https://github.com/drknowhow/kinescript/blob/main/CHANGELOG.md
Keywords: kinescript,kokoro,text to speech,tts,voice-over,word timestamps,captions
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Multimedia :: Video
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: kokoro>=0.9.4
Requires-Dist: misaki[en]>=0.9.4
Dynamic: license-file

# kinescript-kokoro

[Kokoro](https://github.com/hexgrad/kokoro) voices for `kine voice`. It speaks the `text` of a scene's sounds
into WAV files and writes the time of each word, so layers can start on a word and captions follow the voice.

```json
{"id": "vo1", "role": "voice", "text": "Write a scene. Check it. [[go]]Render it.", "speaker": "af_heart"}
```

```bash
kine voice scene.json     # writes voice/vo1.wav and voice/vo1.words.json
kine check scene.json
```

## Install

Kokoro needs Python 3.10 to 3.12 and PyTorch. Into the same environment as Kinescript:

```bash
pip install kinescript-kokoro
```

From a checkout of [Kinescript](https://github.com/drknowhow/kinescript), `pip install ./plugins/kinescript-kokoro`
does the same.

Kinescript itself runs on newer Pythons than Kokoro. If yours is one, install the plugin into another Python
and point `KINE_VOICE_CMD` at it; `kine voice` sends it the lines as JSON on stdin and never through a shell:

```bash
python3.12 -m venv ~/kokoro-env
~/kokoro-env/bin/pip install kinescript-kokoro
export KINE_VOICE_CMD="$HOME/kokoro-env/bin/python -m kinescript_kokoro"
```

On Windows, `set KINE_VOICE_CMD=C:\kokoro-env\Scripts\python.exe -m kinescript_kokoro`. A JSON list such as
`["C:/kokoro env/python.exe", "-m", "kinescript_kokoro"]` also works and keeps a path with spaces whole.

The first run downloads the model (327 MB, plus about 0.5 MB per voice) from Hugging Face. On the development
machine's CPU, a 4 s line took 9 s and 39 s of speech took 14 s, each including about 7 s to load the model.

## Voices and speed

`speaker` is a Kokoro voice, `af_heart` unless the sound names one. Its first letter is the language: `a`
American English, `b` British English (`af_bella`, `am_adam`, `am_michael`, `bf_emma`, `bm_george`, and the
rest of the list in Kokoro's VOICES.md). `rate` is Kokoro's speed, 1 by default.

Word times come with English voices only. Other languages are spoken, but their sounds have no words, so
word cues and voice captions do not work with them.

## Device

It runs on the GPU when the installed PyTorch was built for it, and on the CPU otherwise (a GPU newer than the
PyTorch build, such as an RTX 50 series card with a CUDA 12.4 build, would fail on the first line).
`KOKORO_DEVICE=cpu` or `KOKORO_DEVICE=cuda` picks one.
