Upload README.md

README.md

@@ -48,9 +48,12 @@ This is not a training checkpoint meant to be unpacked and rebuilt from ingredie
 - Voice selection by name
 - Emotion selection by name
 - Fuzzy matching for names
+- Default voice and emotion fallback
 - Optional reference-audio overrides
 - Packed voices and emotions inside one artifact
 - CLI usage for quick testing
+- Python API usage
+- Hugging Face Space friendly
 
 ## Requirements
 
@@ -80,7 +83,7 @@ If you are using the Hugging Face repo, download the bundle and place it next to
 python PackedTTS.py --bundle tts.pt --list
 ```
 
-### 4) Generate speech
+### 4) Generate speech with an explicit voice and emotion
 
 ```bash
 python PackedTTS.py \
@@ -91,21 +94,168 @@ python PackedTTS.py \
   --output output.wav
 ```
 
-## Reference-audio overrides
+---
+
+## Command-line examples
+
+### List mode
+
+Print all packed voices and emotions without generating audio:
+
+```bash
+python PackedTTS.py --bundle tts.pt --list
+```
+
+### Basic generation
+
+Generate speech with explicit voice and emotion:
+
+```bash
+python PackedTTS.py \
+  --bundle tts.pt \
+  --text "This is a normal synthesis test." \
+  --voice "Sarah" \
+  --emotion "Disgust" \
+  --output output.wav
+```
+
+### Voice only
+
+Let the bundle choose the emotion from the packed voice defaults or fallback rules:
+
+```bash
+python PackedTTS.py \
+  --bundle tts.pt \
+  --text "This is voice-only generation." \
+  --voice "Sarah" \
+  --output output.wav
+```
+
+### Emotion only
+
+Let the bundle choose a default or fallback voice while forcing an emotion:
+
+```bash
+python PackedTTS.py \
+  --bundle tts.pt \
+  --text "This is emotion-only generation." \
+  --emotion "Happy" \
+  --output output.wav
+```
+
+### No voice and no emotion
 
-You can override the packed voice or emotion at runtime using reference audio:
+Use the bundle defaults or random fallback selection:
 
 ```bash
 python PackedTTS.py \
   --bundle tts.pt \
-  --text "Hi, this is a custom test." \
+  --text "This uses the bundle defaults." \
+  --output output.wav
+```
+
+### Custom sampling parameters
+
+Adjust guidance, temperature, and style strength:
+
+```bash
+python PackedTTS.py \
+  --bundle tts.pt \
+  --text "More expressive speech with custom sampling." \
+  --voice "Sarah" \
+  --emotion "Angry" \
+  --cfg-weight 0.7 \
+  --temperature 0.9 \
+  --exaggeration 0.6 \
+  --seed 123 \
+  --output output.wav
+```
+
+### Different output path
+
+Write the result anywhere you want:
+
+```bash
+python PackedTTS.py \
+  --bundle tts.pt \
+  --text "Saving to a custom file." \
+  --voice "Sarah" \
+  --emotion "Calm" \
+  --output results/custom_output.wav
+```
+
+### Fuzzy matching for names
+
+If the voice or emotion name is close but not exact, PackedTTS will try normalized matching and then fuzzy matching.
+
+Example:
+
+```bash
+python PackedTTS.py \
+  --bundle tts.pt \
+  --text "This uses fuzzy matching." \
+  --voice "sara" \
+  --emotion "angr" \
+  --output output.wav
+```
+
+### Reference voice override
+
+Use a reference voice file instead of a packed voice:
+
+```bash
+python PackedTTS.py \
+  --bundle tts.pt \
+  --text "This voice comes from reference audio." \
   --voice-ref path/to/voice_reference.wav \
+  --output output.wav
+```
+
+### Reference emotion override
+
+Use a reference emotion file instead of a packed emotion:
+
+```bash
+python PackedTTS.py \
+  --bundle tts.pt \
+  --text "This emotion comes from reference audio." \
   --emo-ref path/to/emotion_reference.wav \
   --output output.wav
 ```
 
+### Both reference overrides
+
+Override both the voice and emotion with reference audio:
+
+```bash
+python PackedTTS.py \
+  --bundle tts.pt \
+  --text "Both voice and emotion are driven by reference audio." \
+  --voice-ref path/to/voice_reference.wav \
+  --emo-ref path/to/emotion_reference.wav \
+  --output output.wav
+```
+
+### Seeded generation
+
+Use a fixed seed to make results more repeatable:
+
+```bash
+python PackedTTS.py \
+  --bundle tts.pt \
+  --text "Seeded generation example." \
+  --voice "Sarah" \
+  --emotion "Disgust" \
+  --seed 42 \
+  --output output.wav
+```
+
+---
+
 ## Python usage
 
+### Basic API usage
+
 ```python
 from pathlib import Path
 import soundfile as sf
@@ -128,6 +278,158 @@ sf.write("output.wav", audio, sr)
 print(meta)
 ```
 
+### Python usage with defaults
+
+Let the model choose the default voice and emotion:
+
+```python
+from pathlib import Path
+import soundfile as sf
+
+from PackedTTS import PackedTTS
+
+tts = PackedTTS.load(Path("tts.pt"))
+
+sr, audio, meta = tts.generate(
+    text="This uses the bundle defaults.",
+    seed=7,
+)
+
+sf.write("default_output.wav", audio, sr)
+print(meta)
+```
+
+### Python usage with voice only
+
+```python
+from pathlib import Path
+import soundfile as sf
+
+from PackedTTS import PackedTTS
+
+tts = PackedTTS.load(Path("tts.pt"))
+
+sr, audio, meta = tts.generate(
+    text="Voice selected, emotion resolved by the bundle.",
+    voice="Sarah",
+    seed=12,
+)
+
+sf.write("voice_only.wav", audio, sr)
+print(meta)
+```
+
+### Python usage with emotion only
+
+```python
+from pathlib import Path
+import soundfile as sf
+
+from PackedTTS import PackedTTS
+
+tts = PackedTTS.load(Path("tts.pt"))
+
+sr, audio, meta = tts.generate(
+    text="Emotion selected, voice resolved by the bundle.",
+    emotion="Happy",
+    seed=12,
+)
+
+sf.write("emotion_only.wav", audio, sr)
+print(meta)
+```
+
+### Python usage with reference voice override
+
+```python
+from pathlib import Path
+import soundfile as sf
+
+from PackedTTS import PackedTTS
+
+tts = PackedTTS.load(Path("tts.pt"))
+
+sr, audio, meta = tts.generate(
+    text="This uses voice reference audio.",
+    voice_ref="path/to/voice_reference.wav",
+    emotion="Calm",
+    seed=42,
+)
+
+sf.write("voice_ref_output.wav", audio, sr)
+print(meta)
+```
+
+### Python usage with reference emotion override
+
+```python
+from pathlib import Path
+import soundfile as sf
+
+from PackedTTS import PackedTTS
+
+tts = PackedTTS.load(Path("tts.pt"))
+
+sr, audio, meta = tts.generate(
+    text="This uses emotion reference audio.",
+    voice="Sarah",
+    emo_ref="path/to/emotion_reference.wav",
+    seed=42,
+)
+
+sf.write("emo_ref_output.wav", audio, sr)
+print(meta)
+```
+
+### Python usage with both reference overrides
+
+```python
+from pathlib import Path
+import soundfile as sf
+
+from PackedTTS import PackedTTS
+
+tts = PackedTTS.load(Path("tts.pt"))
+
+sr, audio, meta = tts.generate(
+    text="This uses both reference audio inputs.",
+    voice_ref="path/to/voice_reference.wav",
+    emo_ref="path/to/emotion_reference.wav",
+    seed=42,
+)
+
+sf.write("both_refs_output.wav", audio, sr)
+print(meta)
+```
+
+### Python usage through the `forward` alias
+
+`forward` is an alias for `generate`, so the model can be used like a callable runtime component:
+
+```python
+from pathlib import Path
+import soundfile as sf
+
+from PackedTTS import PackedTTS
+
+tts = PackedTTS.load(Path("tts.pt"))
+
+sr, audio, meta = tts.forward(
+    text="This uses the forward alias.",
+    voice="Sarah",
+    emotion="Disgust",
+    cfg_weight=0.5,
+    temperature=0.8,
+    exaggeration=0.5,
+    seed=42,
+)
+
+sf.write("forward_output.wav", audio, sr)
+print(meta)
+```
+
+---
+
 ## How it works
 
 PackedTTS restores the full runtime bundle and then runs synthesis in three stages:
@@ -137,6 +439,7 @@ PackedTTS restores the full runtime bundle and then runs synthesis in three stag
    * The bundle stores named voices and emotions.
    * A voice can be selected by name or replaced with reference audio.
    * An emotion can be selected by name or replaced with reference audio.
+   * If exact matching fails, the runtime tries normalized matching and then fuzzy matching.
 
 2. **Build conditionals**
 
@@ -152,6 +455,8 @@ PackedTTS restores the full runtime bundle and then runs synthesis in three stag
 
 The result is a single packed synthesis workflow that does not require rebuilding the voice/emotion registry at runtime.
 
+---
+
 ## Expected file behavior
 
 The script expects the bundle to contain:
@@ -167,6 +472,8 @@ The script expects the bundle to contain:
 
 If a voice or emotion is not found by exact name, PackedTTS will try normalized matching and then fuzzy matching.
 
+---
+
 ## Example command-line options
 
 * `--bundle` — path to `tts.pt`
@@ -182,6 +489,8 @@ If a voice or emotion is not found by exact name, PackedTTS will try normalized
 * `--output` — output WAV path
 * `--list` — print packed voices and emotions
 
+---
+
 ## Notes
 
 * This repo is meant for inference and testing.
@@ -189,6 +498,8 @@ If a voice or emotion is not found by exact name, PackedTTS will try normalized
 * If the underlying model architecture, tokenizer, or conditioning schema changes, rebuild `tts.pt`.
 * Voice and emotion names depend on the bundle version.
 
+---
+
 ## Hugging Face usage
 
 This repo is designed to work well as a Hugging Face model repository and as a Hugging Face Space backend:
@@ -198,6 +509,8 @@ This repo is designed to work well as a Hugging Face model repository and as a H
 * the runtime can load `PackedTTS.py`
 * users can generate speech without rebuilding the bundle
 
+---
+
 ## Credits
 
 Built on top of: