Copy the files in the new repo for public release

2026-01-12 11:25:16 +01:00
commit f5fa328a58
54 changed files with 6411 additions and 0 deletions
@@ -0,0 +1,83 @@
+# Generate Command Documentation
+
+The `generate` command allows you to generate speech from text directly from the command line using Kyutai Pocket TTS.
+
+## Basic Usage
+
+```bash
+uvx pocket-tts generate
+# or if installed manually:
+pocket-tts generate
+```
+
+This will generate a WAV file `./tts_output.wav` with the default text and voice.
+
+## Command Options
+
+### Core Options
+
+- `--text TEXT`: Text to generate (default: "Hello world! I am Kyutai Pocket TTS. I'm fast enough to run on small CPUs. I hope you'll like me.")
+- `--voice VOICE`: Path to audio conditioning file (voice to clone) (default: "hf://kyutai/tts-voices/alba-mackenna/casual.wav"). Urls and local paths are supported.
+- `--output-path OUTPUT_PATH`: Output path for generated audio (default: "./tts_output.wav")
+
+### Generation Parameters
+
+- `--variant VARIANT`: Model signature (default: "b6369a24")
+- `--lsd-decode-steps LSD_DECODE_STEPS`: Number of generation steps (default: 1)
+- `--temperature TEMPERATURE`: Temperature for generation (default: 0.7)
+- `--noise-clamp NOISE_CLAMP`: Noise clamp value (default: None)
+- `--eos-threshold EOS_THRESHOLD`: EOS threshold (default: -4.0)
+- `--frames-after-eos FRAMES_AFTER_EOS`: Number of frames to generate after EOS (default: None, auto-calculated based on the text length). Each frame is 80ms.
+
+### Performance Options
+
+- `--device DEVICE`: Device to use (default: "cpu", you may not get a speedup by using a gpu since it's a small model)
+- `--quiet`, `-q`: Disable logging output
+
+## Examples
+
+### Basic Generation
+
+```bash
+# Generate with default settings
+pocket-tts generate
+
+# Custom text
+pocket-tts generate --text "Hello, this is a custom message."
+
+# Custom output path
+pocket-tts generate --output-path "./my_audio.wav"
+```
+
+### Voice Selection
+
+```bash
+# Use different voice from HuggingFace
+pocket-tts generate --voice "hf://kyutai/tts-voices/jessica-jian/casual.wav"
+
+# Use local voice file
+pocket-tts generate --voice "./my_voice.wav"
+```
+
+### Quality Tuning
+
+```bash
+# Higher quality (more steps)
+pocket-tts generate --lsd-decode-steps 5 --temperature 0.5
+
+# More expressive (higher temperature)
+pocket-tts generate --temperature 1.0
+
+# Adjust EOS threshold, smaller means finishing earlier.
+pocket-tts generate --eos-threshold -3.0
+```
+
+## Output Format
+
+The generate command always outputs WAV files in the following format:
+- **Sample Rate**: 24kHz
+- **Channels**: Mono
+- **Bit Depth**: 16-bit PCM
+- **Format**: Standard WAV file
+
+For more advanced usage, see the [Python API documentation](python-api.md) or consider using the [serve command](serve.md) for web-based generation and quick iteration.
@@ -0,0 +1,223 @@
+# Python API Documentation
+
+Kyutai Pocket TTS provides a Python API for integrating text-to-speech capabilities into your applications.
+
+## Installation
+
+```bash
+pip install pocket-tts
+```
+
+## Quick Start
+
+```python
+from pocket_tts import TTSModel
+import scipy.io.wavfile
+
+# Load the model
+tts_model = TTSModel.load_model()
+
+# Get voice state from an audio file
+voice_state = tts_model.get_state_for_audio_prompt(
+    "hf://kyutai/tts-voices/alba-mackenna/casual.wav"
+)
+
+# Generate audio
+audio = tts_model.generate_audio(voice_state, "Hello world, this is a test.")
+
+# Save to file
+scipy.io.wavfile.write("output.wav", tts_model.sample_rate, audio.numpy())
+```
+
+## Core Classes
+
+### TTSModel
+
+The main class for text-to-speech generation.
+
+#### Class Methods
+
+##### `load_model(variant="b6369a24", temp=0.7, lsd_decode_steps=1, noise_clamp=None, eos_threshold=-4.0)`
+
+Load and return a TTSModel instance with pre-trained weights.
+
+**Parameters:**
+- `variant` (str): Model variant identifier (default: "b6369a24")
+- `temp` (float): Sampling temperature for generation (default: 0.7)
+- `lsd_decode_steps` (int): Number of generation steps (default: 1)
+- `noise_clamp` (float | None): Maximum value for noise sampling (default: None)
+- `eos_threshold` (float): Threshold for end-of-sequence detection (default: -4.0)
+
+**Returns:**
+- `TTSModel`: Loaded model instance on CPU
+
+**Example:**
+```python
+from pocket_tts import TTSModel
+
+# Load with default settings
+model = TTSModel.load_model()
+
+# Load with custom parameters
+model = TTSModel.load_model(variant="b6369a24", temp=0.5, lsd_decode_steps=5, eos_threshold=-3.0)
+```
+
+#### Properties
+
+##### `device` (str)
+
+Returns the device type where the model is running ("cpu" or "cuda").
+By default, the model runs on CPU.
+
+```python
+from pocket_tts import TTSModel
+
+model = TTSModel.load_model()
+print(f"Model running on: {model.device}")
+```
+
+##### `sample_rate` (int)
+
+Returns the generated audio sample rate (typically 24000 Hz).
+
+```python
+from pocket_tts import TTSModel
+
+model = TTSModel.load_model()
+print(f"Sample rate: {model.sample_rate} Hz")
+```
+
+#### Methods
+
+##### `get_state_for_audio_prompt(audio_conditioning, truncate=False)`
+
+Extract model state for a given audio file or URL (voice cloning).
+
+**Parameters:**
+- `audio_conditioning` (Path | str | torch.Tensor): Audio file path, URL, or tensor
+- `truncate` (bool): Whether to truncate the audio (default: False)
+
+**Returns:**
+- `dict`: Model state dictionary containing hidden states and positional information
+
+**Example:**
+```python
+from pocket_tts import TTSModel
+
+model = TTSModel.load_model()
+# From HuggingFace URL
+voice_state = model.get_state_for_audio_prompt("hf://kyutai/tts-voices/alba-mackenna/casual.wav")
+
+# From local file
+voice_state = model.get_state_for_audio_prompt("./my_voice.wav")
+
+# From HTTP URL
+voice_state = model.get_state_for_audio_prompt(
+    "https://huggingface.co/kyutai/tts-voices/resolve"
+    "/main/expresso/ex01-ex02_default_001_channel1_168s.wav"
+)
+```
+
+##### `generate_audio(model_state, text_to_generate, frames_after_eos=None, copy_state=True)`
+
+Generate complete audio tensor from text input.
+
+**Parameters:**
+- `model_state` (dict): Model state from `get_state_for_audio_prompt()`
+- `text_to_generate` (str): Text to convert to speech
+- `frames_after_eos` (int | None): Frames to generate after EOS detection (default: None)
+- `copy_state` (bool): Whether to copy the state (default: True)
+
+**Returns:**
+- `torch.Tensor`: Audio 1D tensor with shape [samples]
+
+**Example:**
+```python
+from pocket_tts import TTSModel
+
+model = TTSModel.load_model()
+
+voice_state = model.get_state_for_audio_prompt("hf://kyutai/tts-voices/alba-mackenna/casual.wav")
+
+# Generate audio
+audio = model.generate_audio(voice_state, "Hello world!", frames_after_eos=2, copy_state=True)
+
+print(f"Generated audio shape: {audio.shape}")
+print(f"Audio duration: {audio.shape[-1] / model.sample_rate:.2f} seconds")
+```
+
+##### `generate_audio_stream(model_state, text_to_generate, frames_after_eos=None, copy_state=True)`
+
+Generate audio streaming chunks from text input.
+
+**Parameters:** Same as `generate_audio()`
+
+**Yields:**
+- `torch.Tensor`: Audio chunks with shape [samples]
+
+**Example:**
+```python
+from pocket_tts import TTSModel
+
+model = TTSModel.load_model()
+
+voice_state = model.get_state_for_audio_prompt("hf://kyutai/tts-voices/alba-mackenna/casual.wav")
+# Stream generation
+for chunk in model.generate_audio_stream(voice_state, "Long text content..."):
+    # Process each chunk as it's generated
+    print(f"Generated chunk: {chunk.shape[0]} samples")
+    # Could save chunks to file or play in real-time
+```
+
+## Advanced Usage
+
+### Voice Management
+
+```python
+from pocket_tts import TTSModel
+
+model = TTSModel.load_model()
+# Preload multiple voices
+voices = {
+    "casual": model.get_state_for_audio_prompt("hf://kyutai/tts-voices/alba-mackenna/casual.wav"),
+    "funny": model.get_state_for_audio_prompt(
+        "https://huggingface.co/kyutai/tts-voices/resolve/main/expresso/ex01-ex02_default_001_channel1_168s.wav"
+    ),
+}
+
+# Generate with different voices
+casual_audio = model.generate_audio(voices["casual"], "Hey there!")
+funny_audio = model.generate_audio(voices["funny"], "Good morning.")
+```
+
+### Batch Processing
+
+```python
+from pocket_tts import TTSModel
+import scipy.io.wavfile
+import torch
+
+model = TTSModel.load_model()
+
+voice_state = model.get_state_for_audio_prompt("hf://kyutai/tts-voices/alba-mackenna/casual.wav")
+# Process multiple texts efficiently by re-using the same voice state
+texts = [
+    "First sentence to generate.",
+    "Second sentence to generate.",
+    "Third sentence to generate.",
+]
+
+audios = []
+for text in texts:
+    audio = model.generate_audio(voice_state, text)
+    audios.append(audio)
+
+# Concatenate all audio
+full_audio = torch.cat(audios, dim=0)
+scipy.io.wavfile.write("batch_output.wav", model.sample_rate, full_audio.numpy())
+```
+
+### Streaming to File
+You can refer to our CLI implementation which can stream audio to a wav file.
+
+For more information about the command-line interface, see the [Generate Documentation](generate.md) or [Serve Documentation](serve.md).
@@ -0,0 +1,48 @@
+# Serve Command Documentation
+
+The `serve` command starts a FastAPI web server that provides both a web interface and HTTP API for text-to-speech generation.
+
+## Basic Usage
+
+```bash
+uvx pocket-tts serve
+# or if installed manually:
+pocket-tts serve
+```
+
+This starts a server on `http://localhost:8000` with the default voice model.
+
+## Command Options
+
+- `--voice VOICE`: Path to voice prompt audio file (voice to clone) (default: "hf://kyutai/tts-voices/alba-mackenna/casual.wav")
+- `--host HOST`: Host to bind to (default: "localhost")
+- `--port PORT`: Port to bind to (default: 8000)
+- `--reload`: Enable auto-reload for development
+
+## Examples
+
+### Basic Server
+
+```bash
+# Start with default settings
+pocket-tts serve
+
+# Custom host and port
+pocket-tts serve --host "localhost" --port 8080
+```
+
+### Custom Voice
+
+```bash
+# Use different voice
+pocket-tts serve --default-voice "hf://kyutai/tts-voices/jessica-jian/casual.wav"
+
+# Use local voice file
+pocket-tts serve --default-voice "./my_voice.wav"
+```
+
+## Web Interface
+
+Once the server is running, navigate to `http://localhost:8000` to access the web interface.
+
+For more advanced usage, see the [Python API documentation](python-api.md) for direct integration with the TTS model.