par-cli-tts 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- par_cli_tts-0.1.0.dist-info/METADATA +611 -0
- par_cli_tts-0.1.0.dist-info/RECORD +16 -0
- par_cli_tts-0.1.0.dist-info/WHEEL +4 -0
- par_cli_tts-0.1.0.dist-info/entry_points.txt +3 -0
- par_cli_tts-0.1.0.dist-info/licenses/LICENSE +21 -0
- src/__init__.py +3 -0
- src/kokoro_cli.py +113 -0
- src/model_downloader.py +196 -0
- src/providers/__init__.py +14 -0
- src/providers/base.py +124 -0
- src/providers/elevenlabs.py +151 -0
- src/providers/kokoro_onnx.py +213 -0
- src/providers/openai.py +202 -0
- src/py.typed +0 -0
- src/tts_cli.py +494 -0
- src/voice_cache.py +259 -0
|
@@ -0,0 +1,611 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: par-cli-tts
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: PAR CLI TTS - Command line text-to-speech tool using ElevenLabs with voice caching and name resolution
|
|
5
|
+
Project-URL: Homepage, https://github.com/paulrobello/par-cli-tts
|
|
6
|
+
Project-URL: Documentation, https://github.com/paulrobello/par-cli-tts/blob/main/README.md
|
|
7
|
+
Project-URL: Repository, https://github.com/paulrobello/par-cli-tts
|
|
8
|
+
Project-URL: Issues, https://github.com/paulrobello/par-cli-tts/issues
|
|
9
|
+
Project-URL: Discussions, https://github.com/paulrobello/par-cli-tts/discussions
|
|
10
|
+
Project-URL: Wiki, https://github.com/paulrobello/par-cli-tts/wiki
|
|
11
|
+
Author-email: Paul Robello <probello@gmail.com>
|
|
12
|
+
Maintainer-email: Paul Robello <probello@gmail.com>
|
|
13
|
+
License: MIT License
|
|
14
|
+
|
|
15
|
+
Copyright (c) 2024 Paul Robello
|
|
16
|
+
|
|
17
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
18
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
19
|
+
in the Software without restriction, including without limitation the rights
|
|
20
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
21
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
22
|
+
furnished to do so, subject to the following conditions:
|
|
23
|
+
|
|
24
|
+
The above copyright notice and this permission notice shall be included in all
|
|
25
|
+
copies or substantial portions of the Software.
|
|
26
|
+
|
|
27
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
28
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
29
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
30
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
31
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
32
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
33
|
+
SOFTWARE.
|
|
34
|
+
License-File: LICENSE
|
|
35
|
+
Keywords: audio,cli,elevenlabs,text-to-speech,tts
|
|
36
|
+
Classifier: Development Status :: 4 - Beta
|
|
37
|
+
Classifier: Environment :: Console
|
|
38
|
+
Classifier: Intended Audience :: Developers
|
|
39
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
40
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
41
|
+
Classifier: Operating System :: MacOS
|
|
42
|
+
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
|
|
43
|
+
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
|
|
44
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
45
|
+
Classifier: Programming Language :: Python :: 3
|
|
46
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
47
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
48
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
49
|
+
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
|
|
50
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
51
|
+
Classifier: Typing :: Typed
|
|
52
|
+
Requires-Python: >=3.11
|
|
53
|
+
Requires-Dist: elevenlabs>=1.0.0
|
|
54
|
+
Requires-Dist: kokoro-onnx>=0.4.9
|
|
55
|
+
Requires-Dist: openai>=1.100.1
|
|
56
|
+
Requires-Dist: platformdirs>=4.3.0
|
|
57
|
+
Requires-Dist: python-dotenv>=1.0.0
|
|
58
|
+
Requires-Dist: pyyaml>=6.0.0
|
|
59
|
+
Requires-Dist: rich>=13.0.0
|
|
60
|
+
Requires-Dist: soundfile>=0.13.1
|
|
61
|
+
Requires-Dist: typer>=0.12.0
|
|
62
|
+
Description-Content-Type: text/markdown
|
|
63
|
+
|
|
64
|
+
# PAR CLI TTS
|
|
65
|
+
|
|
66
|
+
[](https://python.org)
|
|
67
|
+

|
|
68
|
+

|
|
69
|
+
|
|
70
|
+

|
|
71
|
+

|
|
72
|
+

|
|
73
|
+
|
|
74
|
+
A powerful command-line text-to-speech tool supporting multiple TTS providers (ElevenLabs, OpenAI, and Kokoro ONNX) with intelligent voice caching, name resolution, and flexible output options.
|
|
75
|
+
|
|
76
|
+
[](https://buymeacoffee.com/probello3)
|
|
77
|
+
|
|
78
|
+
## 🆕 What's New in v0.1.0
|
|
79
|
+
|
|
80
|
+
**✨ Initial Release**: Multi-provider TTS with ElevenLabs, OpenAI, and Kokoro ONNX support
|
|
81
|
+
- 🎭 **Multiple Providers** - Seamless switching between ElevenLabs, OpenAI, and Kokoro ONNX
|
|
82
|
+
- 🎯 **Voice Name Resolution** - Use friendly names instead of IDs
|
|
83
|
+
- ⚡ **Smart Caching** - 7-day voice cache for ElevenLabs
|
|
84
|
+
- 🎨 **Rich Terminal Output** - Beautiful colored output with progress
|
|
85
|
+
- 🔊 **Flexible Audio Output** - Play directly or save to file
|
|
86
|
+
- 🚀 **Offline Support** - Kokoro ONNX runs locally without API requirements
|
|
87
|
+
|
|
88
|
+
## Features
|
|
89
|
+
|
|
90
|
+
- 🎭 **Multiple TTS Providers** - Support for ElevenLabs, OpenAI, and Kokoro ONNX with easy provider switching
|
|
91
|
+
- 🎯 **Voice Name Support** - Use voice names like "Rachel" or "nova" instead of cryptic IDs
|
|
92
|
+
- ⚡ **Smart Voice Caching** - ElevenLabs voice data cached for 7 days for faster lookups
|
|
93
|
+
- 🔍 **Partial Name Matching** - Type "char" to match "Charlotte" (ElevenLabs)
|
|
94
|
+
- 💾 **XDG-Compliant Cache** - Proper cache directory management across platforms
|
|
95
|
+
- 🎨 **Rich Terminal Output** - Beautiful colored output with progress indicators
|
|
96
|
+
- 🔊 **Flexible Audio Output** - Play directly or save to file with custom locations
|
|
97
|
+
- 🎚️ **Provider-Specific Options** - Stability/similarity for ElevenLabs, speed/format for OpenAI
|
|
98
|
+
- 🛠️ **Debug Mode** - Comprehensive debugging with --debug and --dump options
|
|
99
|
+
- 📁 **Smart File Management** - Automatic cleanup or preservation of audio files
|
|
100
|
+
|
|
101
|
+
## Technology Stack
|
|
102
|
+
|
|
103
|
+
- **Python 3.11+** - Modern Python with type hints and async support
|
|
104
|
+
- **ElevenLabs SDK** - Official ElevenLabs API client for high-quality voices
|
|
105
|
+
- **OpenAI SDK** - Official OpenAI API client for TTS
|
|
106
|
+
- **Kokoro ONNX** - Offline TTS with ONNX Runtime for fast inference
|
|
107
|
+
- **Typer** - Modern CLI framework with automatic help generation
|
|
108
|
+
- **Rich** - Terminal formatting and beautiful output
|
|
109
|
+
- **Pydantic** - Data validation and settings management
|
|
110
|
+
- **Platformdirs** - Cross-platform directory management
|
|
111
|
+
- **Python-dotenv** - Environment variable management
|
|
112
|
+
|
|
113
|
+
## Prerequisites
|
|
114
|
+
|
|
115
|
+
To install PAR CLI TTS, make sure you have Python 3.11+ installed.
|
|
116
|
+
|
|
117
|
+
### [uv](https://pypi.org/project/uv/) is recommended
|
|
118
|
+
|
|
119
|
+
#### Linux and Mac
|
|
120
|
+
```bash
|
|
121
|
+
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
#### Windows
|
|
125
|
+
```bash
|
|
126
|
+
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## Installation
|
|
130
|
+
|
|
131
|
+
### Installation from PyPI (Recommended)
|
|
132
|
+
|
|
133
|
+
Install the latest stable version using uv:
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
uv tool install par-cli-tts
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Or using pip:
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
pip install par-cli-tts
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
After installation, you can run the tool directly:
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
# Simple text-to-speech
|
|
149
|
+
par-tts "Hello, world!"
|
|
150
|
+
|
|
151
|
+
# Show help
|
|
152
|
+
par-tts --help
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### Installation From Source
|
|
156
|
+
|
|
157
|
+
For development or to get the latest features:
|
|
158
|
+
|
|
159
|
+
1. Clone the repository:
|
|
160
|
+
```bash
|
|
161
|
+
git clone https://github.com/paulrobello/par-cli-tts.git
|
|
162
|
+
cd par-cli-tts
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
2. Install the package dependencies using uv:
|
|
166
|
+
```bash
|
|
167
|
+
uv sync
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
3. Run using uv:
|
|
171
|
+
```bash
|
|
172
|
+
uv run par-tts "Hello, world!"
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### Kokoro ONNX Setup
|
|
176
|
+
|
|
177
|
+
Kokoro ONNX models are automatically downloaded on first use! The models are stored in an XDG-compliant data directory:
|
|
178
|
+
|
|
179
|
+
- **macOS**: `~/Library/Application Support/par-tts/par-tts-kokoro/`
|
|
180
|
+
- **Linux**: `~/.local/share/par-tts-kokoro/`
|
|
181
|
+
- **Windows**: `%LOCALAPPDATA%\par-tts\par-tts-kokoro\`
|
|
182
|
+
|
|
183
|
+
#### Automatic Download
|
|
184
|
+
|
|
185
|
+
When you first use the Kokoro ONNX provider, it will automatically download the required models (~106 MB total using quantized model):
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
# Models download automatically on first use
|
|
189
|
+
par-tts "Hello" --provider kokoro-onnx
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
#### Manual Model Management
|
|
193
|
+
|
|
194
|
+
You can also manage models manually using the `par-tts-kokoro` command:
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
# Download models manually
|
|
198
|
+
par-tts-kokoro download
|
|
199
|
+
|
|
200
|
+
# Show model information
|
|
201
|
+
par-tts-kokoro info
|
|
202
|
+
|
|
203
|
+
# Show model storage paths
|
|
204
|
+
par-tts-kokoro path
|
|
205
|
+
|
|
206
|
+
# Clear downloaded models
|
|
207
|
+
par-tts-kokoro clear
|
|
208
|
+
|
|
209
|
+
# Force re-download models
|
|
210
|
+
par-tts-kokoro download --force
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
#### Using Custom Model Paths
|
|
214
|
+
|
|
215
|
+
If you prefer to use models from a custom location, set environment variables:
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
export KOKORO_MODEL_PATH=/path/to/kokoro-v1.0.onnx
|
|
219
|
+
export KOKORO_VOICE_PATH=/path/to/voices-v1.0.bin
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
When these environment variables are set, automatic download is disabled.
|
|
223
|
+
|
|
224
|
+
## Configuration
|
|
225
|
+
|
|
226
|
+
Create a `.env` file in your project directory with your API keys:
|
|
227
|
+
|
|
228
|
+
```bash
|
|
229
|
+
# Required API keys (at least one for cloud providers)
|
|
230
|
+
ELEVENLABS_API_KEY=your_elevenlabs_key_here
|
|
231
|
+
OPENAI_API_KEY=your_openai_key_here
|
|
232
|
+
|
|
233
|
+
# Optional: Kokoro ONNX model paths (auto-downloads if not set)
|
|
234
|
+
# Set these only if you want to use custom model locations
|
|
235
|
+
# KOKORO_MODEL_PATH=/path/to/kokoro-v1.0.onnx
|
|
236
|
+
# KOKORO_VOICE_PATH=/path/to/voices-v1.0.bin
|
|
237
|
+
|
|
238
|
+
# Optional: Default provider (elevenlabs, openai, or kokoro-onnx)
|
|
239
|
+
TTS_PROVIDER=elevenlabs
|
|
240
|
+
|
|
241
|
+
# Optional: Default voices
|
|
242
|
+
ELEVENLABS_VOICE_ID=Rachel # or use voice ID
|
|
243
|
+
OPENAI_VOICE_ID=nova # alloy, echo, fable, onyx, nova, shimmer
|
|
244
|
+
KOKORO_VOICE_ID=af_sarah # See available voices with --list
|
|
245
|
+
|
|
246
|
+
# Optional: General voice (overrides provider-specific)
|
|
247
|
+
TTS_VOICE_ID=Rachel
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
## Usage
|
|
251
|
+
|
|
252
|
+
### Quick Start
|
|
253
|
+
|
|
254
|
+
If installed from PyPI:
|
|
255
|
+
```bash
|
|
256
|
+
# Simple text-to-speech with default provider
|
|
257
|
+
par-tts "Hello, world!"
|
|
258
|
+
|
|
259
|
+
# Use OpenAI provider
|
|
260
|
+
par-tts "Hello" --provider openai --voice nova
|
|
261
|
+
|
|
262
|
+
# Use ElevenLabs with voice by name
|
|
263
|
+
par-tts "Hello" --voice Rachel
|
|
264
|
+
|
|
265
|
+
# Use Kokoro ONNX (offline, auto-downloads models on first use)
|
|
266
|
+
par-tts "Hello" --provider kokoro-onnx --voice af_sarah
|
|
267
|
+
|
|
268
|
+
# Save to file
|
|
269
|
+
par-tts "Save this" --output audio.mp3
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
If running from source:
|
|
273
|
+
```bash
|
|
274
|
+
# Simple text-to-speech with default provider
|
|
275
|
+
uv run par-tts "Hello, world!"
|
|
276
|
+
|
|
277
|
+
# Use OpenAI provider
|
|
278
|
+
uv run par-tts "Hello" --provider openai --voice nova
|
|
279
|
+
|
|
280
|
+
# Use ElevenLabs with voice by name
|
|
281
|
+
uv run par-tts "Hello" --voice Rachel
|
|
282
|
+
|
|
283
|
+
# Use Kokoro ONNX (offline, auto-downloads models on first use)
|
|
284
|
+
uv run par-tts "Hello" --provider kokoro-onnx --voice af_sarah
|
|
285
|
+
|
|
286
|
+
# Save to file
|
|
287
|
+
uv run par-tts "Save this" --output audio.mp3
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
### Basic Examples
|
|
291
|
+
|
|
292
|
+
```bash
|
|
293
|
+
# Simple text-to-speech with default provider (ElevenLabs)
|
|
294
|
+
par-tts "Hello, world!"
|
|
295
|
+
|
|
296
|
+
# Use OpenAI provider
|
|
297
|
+
par-tts "Hello from OpenAI" --provider openai --voice nova
|
|
298
|
+
|
|
299
|
+
# Use ElevenLabs with voice by name
|
|
300
|
+
par-tts "Hello from ElevenLabs" --provider elevenlabs --voice Rachel
|
|
301
|
+
|
|
302
|
+
# Use Kokoro ONNX with language specification
|
|
303
|
+
par-tts "Hello from Kokoro" --provider kokoro-onnx --voice af_sarah --lang en-us
|
|
304
|
+
|
|
305
|
+
# Use partial name matching (ElevenLabs)
|
|
306
|
+
par-tts "Hello" --voice char # matches Charlotte
|
|
307
|
+
|
|
308
|
+
# Save to file without playing
|
|
309
|
+
par-tts "Save this audio" --output audio.mp3 --no-play
|
|
310
|
+
|
|
311
|
+
# Adjust ElevenLabs voice settings
|
|
312
|
+
par-tts "Stable voice" --stability 0.8 --similarity 0.7
|
|
313
|
+
|
|
314
|
+
# Adjust OpenAI speech speed
|
|
315
|
+
par-tts "Fast speech" --provider openai --speed 1.5
|
|
316
|
+
|
|
317
|
+
# Keep temp files after playback
|
|
318
|
+
par-tts "Keep this" --keep-temp
|
|
319
|
+
|
|
320
|
+
# Specify custom temp directory (files are kept)
|
|
321
|
+
par-tts "Custom location" --temp-dir ./my_audio
|
|
322
|
+
|
|
323
|
+
# Combine output filename with temp directory
|
|
324
|
+
par-tts "Save here" --output my_file.mp3 --temp-dir ./audio_files
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
### Advanced Usage
|
|
328
|
+
|
|
329
|
+
#### Provider Management
|
|
330
|
+
|
|
331
|
+
```bash
|
|
332
|
+
# List available providers
|
|
333
|
+
par-tts "dummy" --list-providers
|
|
334
|
+
|
|
335
|
+
# List voices for a specific provider
|
|
336
|
+
par-tts "dummy" --provider openai --list
|
|
337
|
+
par-tts "dummy" --provider elevenlabs --list
|
|
338
|
+
par-tts "dummy" --provider kokoro-onnx --list
|
|
339
|
+
|
|
340
|
+
# Show debug information
|
|
341
|
+
par-tts "Test" --debug
|
|
342
|
+
|
|
343
|
+
# Show configuration
|
|
344
|
+
par-tts "Test" --dump
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
#### Output File Behavior
|
|
348
|
+
|
|
349
|
+
- **With `--output full/path.mp3`**: Saves to exact path specified
|
|
350
|
+
- **With `--output filename.mp3 --temp-dir dir`**: Saves to `dir/filename.mp3`
|
|
351
|
+
- **With `--temp-dir dir` only**: Saves to `dir/tts_TIMESTAMP.mp3` (kept)
|
|
352
|
+
- **With `--keep-temp`**: Temporary files are not deleted after playback
|
|
353
|
+
- **Default behavior**: Temp files are auto-deleted after playback
|
|
354
|
+
|
|
355
|
+
## Command Line Options
|
|
356
|
+
|
|
357
|
+
### Core Options
|
|
358
|
+
|
|
359
|
+
| Option | Short | Description | Default |
|
|
360
|
+
|--------|-------|-------------|---------|
|
|
361
|
+
| `text` | | Text to convert to speech (required) | |
|
|
362
|
+
| `--provider` | `-P` | TTS provider to use (elevenlabs, openai, kokoro-onnx) | elevenlabs |
|
|
363
|
+
| `--voice` | `-v` | Voice name or ID to use | Provider default |
|
|
364
|
+
| `--output` | `-o` | Output file path | None (temp file) |
|
|
365
|
+
| `--model` | `-m` | Model to use (provider-specific) | Provider default |
|
|
366
|
+
| `--play/--no-play` | `-p` | Play audio after generation | --play |
|
|
367
|
+
|
|
368
|
+
### ElevenLabs Options
|
|
369
|
+
|
|
370
|
+
| Option | Short | Description | Default |
|
|
371
|
+
|--------|-------|-------------|---------|
|
|
372
|
+
| `--stability` | `-s` | Voice stability (0.0 to 1.0) | 0.5 |
|
|
373
|
+
| `--similarity` | `-S` | Voice similarity boost (0.0 to 1.0) | 0.5 |
|
|
374
|
+
|
|
375
|
+
### OpenAI Options
|
|
376
|
+
|
|
377
|
+
| Option | Short | Description | Default |
|
|
378
|
+
|--------|-------|-------------|---------|
|
|
379
|
+
| `--speed` | | Speech speed (0.25 to 4.0) | 1.0 |
|
|
380
|
+
| `--format` | `-f` | Audio format (mp3, opus, aac, flac, wav) | mp3 |
|
|
381
|
+
|
|
382
|
+
### Kokoro ONNX Options
|
|
383
|
+
|
|
384
|
+
| Option | Short | Description | Default |
|
|
385
|
+
|--------|-------|-------------|---------|
|
|
386
|
+
| `--lang` | | Language code (e.g., en-us) | en-us |
|
|
387
|
+
| `--speed` | | Speech speed multiplier | 1.0 |
|
|
388
|
+
|
|
389
|
+
### File Management
|
|
390
|
+
|
|
391
|
+
| Option | Short | Description | Default |
|
|
392
|
+
|--------|-------|-------------|---------|
|
|
393
|
+
| `--keep-temp` | `-k` | Keep temporary audio files after playback | False |
|
|
394
|
+
| `--temp-dir` | `-t` | Directory for temporary audio files | System temp |
|
|
395
|
+
|
|
396
|
+
### Utility Options
|
|
397
|
+
|
|
398
|
+
| Option | Short | Description | Default |
|
|
399
|
+
|--------|-------|-------------|---------|
|
|
400
|
+
| `--debug` | `-d` | Show debug information | False |
|
|
401
|
+
| `--dump` | `-D` | Dump configuration and exit | False |
|
|
402
|
+
| `--list` | `-l` | List available voices for provider | False |
|
|
403
|
+
| `--list-providers` | `-L` | List available TTS providers | False |
|
|
404
|
+
|
|
405
|
+
## Providers
|
|
406
|
+
|
|
407
|
+
### ElevenLabs
|
|
408
|
+
|
|
409
|
+
- **Models**: eleven_monolingual_v1, eleven_multilingual_v1, eleven_multilingual_v2
|
|
410
|
+
- **Voices**: 25+ voices with different accents and styles
|
|
411
|
+
- **Features**: Voice cloning, stability control, similarity boost
|
|
412
|
+
- **Caching**: Automatic 7-day cache for voice listings
|
|
413
|
+
- **API Key**: Set `ELEVENLABS_API_KEY` in your .env file
|
|
414
|
+
|
|
415
|
+
### OpenAI
|
|
416
|
+
|
|
417
|
+
- **Models**: tts-1 (optimized for speed), tts-1-hd (optimized for quality)
|
|
418
|
+
- **Voices**:
|
|
419
|
+
- alloy - Neutral and balanced
|
|
420
|
+
- echo - Smooth and articulate
|
|
421
|
+
- fable - Expressive and animated
|
|
422
|
+
- onyx - Deep and authoritative
|
|
423
|
+
- nova - Warm and friendly (default)
|
|
424
|
+
- shimmer - Soft and gentle
|
|
425
|
+
- **Features**: Speed control (0.25x to 4x), multiple output formats
|
|
426
|
+
- **Output Formats**: mp3, opus, aac, flac, wav, pcm
|
|
427
|
+
- **API Key**: Set `OPENAI_API_KEY` in your .env file
|
|
428
|
+
|
|
429
|
+
### Kokoro ONNX
|
|
430
|
+
|
|
431
|
+
- **Models**: kokoro-v1.0 (ONNX format, runs locally)
|
|
432
|
+
- **Voices**: Multiple voices including af_sarah (default) and others
|
|
433
|
+
- **Features**:
|
|
434
|
+
- Offline operation - no API key required
|
|
435
|
+
- Fast CPU/GPU inference with ONNX Runtime
|
|
436
|
+
- Language support with phoneme-based synthesis
|
|
437
|
+
- Speed control
|
|
438
|
+
- **Output Formats**: wav, flac, ogg
|
|
439
|
+
- **Requirements**:
|
|
440
|
+
- Models auto-download on first use (~106 MB)
|
|
441
|
+
- Uses int8 quantized model for efficiency
|
|
442
|
+
- Stored in XDG-compliant data directory
|
|
443
|
+
- No API key needed - runs entirely locally
|
|
444
|
+
- Manual download available via `par-tts-kokoro download`
|
|
445
|
+
|
|
446
|
+
## Cache Locations
|
|
447
|
+
|
|
448
|
+
The ElevenLabs voice cache is stored in platform-specific directories:
|
|
449
|
+
|
|
450
|
+
- **macOS**: `~/Library/Caches/par-tts-elevenlabs/voice_cache.yaml`
|
|
451
|
+
- **Linux**: `~/.cache/par-tts-elevenlabs/voice_cache.yaml`
|
|
452
|
+
- **Windows**: `%LOCALAPPDATA%\par-tts-elevenlabs\Cache\voice_cache.yaml`
|
|
453
|
+
|
|
454
|
+
Cache entries expire after 7 days and are automatically refreshed when needed.
|
|
455
|
+
|
|
456
|
+
## Development
|
|
457
|
+
|
|
458
|
+
### Setup Development Environment
|
|
459
|
+
|
|
460
|
+
```bash
|
|
461
|
+
# Clone repository
|
|
462
|
+
git clone https://github.com/paulrobello/par-cli-tts.git
|
|
463
|
+
cd par-cli-tts
|
|
464
|
+
|
|
465
|
+
# Install dependencies
|
|
466
|
+
uv sync
|
|
467
|
+
|
|
468
|
+
# Run tests
|
|
469
|
+
uv run pytest
|
|
470
|
+
|
|
471
|
+
# Run linting and formatting
|
|
472
|
+
make checkall
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
### Development Commands
|
|
476
|
+
|
|
477
|
+
```bash
|
|
478
|
+
# Format, lint, and type check
|
|
479
|
+
make checkall
|
|
480
|
+
|
|
481
|
+
# Individual commands
|
|
482
|
+
make format # Format with ruff
|
|
483
|
+
make lint # Lint with ruff
|
|
484
|
+
make typecheck # Type check with pyright
|
|
485
|
+
|
|
486
|
+
# Run the app
|
|
487
|
+
make run # Run with test message
|
|
488
|
+
make app_help # Show app help
|
|
489
|
+
|
|
490
|
+
# Voice management
|
|
491
|
+
make list-voices # List available voices
|
|
492
|
+
make update-cache # Update voice cache
|
|
493
|
+
make clear-cache # Clear voice cache
|
|
494
|
+
|
|
495
|
+
# Kokoro ONNX model management
|
|
496
|
+
make kokoro-download # Download Kokoro models
|
|
497
|
+
make kokoro-info # Show model information
|
|
498
|
+
make kokoro-clear # Clear Kokoro models
|
|
499
|
+
make kokoro-path # Show model paths
|
|
500
|
+
|
|
501
|
+
# Build and package
|
|
502
|
+
make package # Build distribution packages
|
|
503
|
+
make clean # Clean build artifacts
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
### Project Structure
|
|
507
|
+
|
|
508
|
+
```
|
|
509
|
+
par-cli-tts/
|
|
510
|
+
├── src/
|
|
511
|
+
│ ├── __init__.py
|
|
512
|
+
│ ├── tts_cli.py # Main CLI application
|
|
513
|
+
│ ├── voice_cache.py # Voice caching system
|
|
514
|
+
│ └── providers/ # TTS provider implementations
|
|
515
|
+
│ ├── __init__.py
|
|
516
|
+
│ ├── base.py # Abstract base provider
|
|
517
|
+
│ ├── elevenlabs.py # ElevenLabs implementation
|
|
518
|
+
│ └── openai.py # OpenAI implementation
|
|
519
|
+
├── .env.example # Example environment file
|
|
520
|
+
├── pyproject.toml # Project configuration
|
|
521
|
+
├── Makefile # Development commands
|
|
522
|
+
└── README.md # This file
|
|
523
|
+
```
|
|
524
|
+
|
|
525
|
+
## Troubleshooting
|
|
526
|
+
|
|
527
|
+
### Common Issues
|
|
528
|
+
|
|
529
|
+
1. **API Key Not Found**
|
|
530
|
+
- Ensure your `.env` file contains the correct API keys
|
|
531
|
+
- Check that the `.env` file is in the current directory
|
|
532
|
+
- Verify environment variable names match exactly
|
|
533
|
+
|
|
534
|
+
2. **Voice Not Found**
|
|
535
|
+
- Use `--list` to see available voices for your provider
|
|
536
|
+
- Check spelling and capitalization of voice names
|
|
537
|
+
- For ElevenLabs, wait for cache to update or run `make update-cache`
|
|
538
|
+
|
|
539
|
+
3. **Audio Not Playing**
|
|
540
|
+
- Ensure you have audio output devices connected
|
|
541
|
+
- Check system volume settings
|
|
542
|
+
- On Linux, verify audio subsystem (ALSA/PulseAudio) is working
|
|
543
|
+
|
|
544
|
+
4. **Slow Response Times**
|
|
545
|
+
- ElevenLabs voice cache may be updating (happens every 7 days)
|
|
546
|
+
- Network connection may be slow
|
|
547
|
+
- Try using `--debug` to see detailed timing information
|
|
548
|
+
|
|
549
|
+
5. **File Not Saved**
|
|
550
|
+
- Check write permissions for the output directory
|
|
551
|
+
- Ensure the path exists or parent directories can be created
|
|
552
|
+
- Use absolute paths to avoid confusion
|
|
553
|
+
|
|
554
|
+
### Debug Mode
|
|
555
|
+
|
|
556
|
+
Enable debug mode for detailed information:
|
|
557
|
+
|
|
558
|
+
```bash
|
|
559
|
+
# Show debug information during execution
|
|
560
|
+
par-tts "Test message" --debug
|
|
561
|
+
|
|
562
|
+
# Dump configuration without executing
|
|
563
|
+
par-tts "Test" --dump
|
|
564
|
+
```
|
|
565
|
+
|
|
566
|
+
## Contributing
|
|
567
|
+
|
|
568
|
+
Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.
|
|
569
|
+
|
|
570
|
+
### How to Contribute
|
|
571
|
+
|
|
572
|
+
1. Fork the repository
|
|
573
|
+
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
574
|
+
3. Make your changes
|
|
575
|
+
4. Run tests and checks (`make checkall`)
|
|
576
|
+
5. Commit your changes (`git commit -m 'Add amazing feature'`)
|
|
577
|
+
6. Push to the branch (`git push origin feature/amazing-feature`)
|
|
578
|
+
7. Open a Pull Request
|
|
579
|
+
|
|
580
|
+
### Development Guidelines
|
|
581
|
+
|
|
582
|
+
- Use type hints for all function parameters and returns
|
|
583
|
+
- Follow Google-style docstrings
|
|
584
|
+
- Ensure all tests pass before submitting PR
|
|
585
|
+
- Update documentation for new features
|
|
586
|
+
- Keep commits atomic and well-described
|
|
587
|
+
|
|
588
|
+
## License
|
|
589
|
+
|
|
590
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
591
|
+
|
|
592
|
+
## Author
|
|
593
|
+
|
|
594
|
+
**Paul Robello**
|
|
595
|
+
Email: [probello@gmail.com](mailto:probello@gmail.com)
|
|
596
|
+
GitHub: [@paulrobello](https://github.com/paulrobello)
|
|
597
|
+
|
|
598
|
+
## Acknowledgments
|
|
599
|
+
|
|
600
|
+
- [ElevenLabs](https://elevenlabs.io/) for their excellent TTS API
|
|
601
|
+
- [OpenAI](https://openai.com/) for their TTS capabilities
|
|
602
|
+
- [Typer](https://typer.tiangolo.com/) for the elegant CLI framework
|
|
603
|
+
- [Rich](https://rich.readthedocs.io/) for beautiful terminal formatting
|
|
604
|
+
|
|
605
|
+
## Support
|
|
606
|
+
|
|
607
|
+
If you find this tool useful, consider:
|
|
608
|
+
- ⭐ Starring the repository
|
|
609
|
+
- 🐛 Reporting bugs or requesting features
|
|
610
|
+
- 📖 Improving documentation
|
|
611
|
+
- ☕ [Buying me a coffee](https://buymeacoffee.com/probello3)
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
src/__init__.py,sha256=T1XIK5yehR2nz0MIB_4NaX2pIUo1wqMDZ7r4oOqL7PA,94
|
|
2
|
+
src/kokoro_cli.py,sha256=zMAzy_cpZ_eUm97lTFOj_mRopFiYxnh_lWX2vN4P158,3509
|
|
3
|
+
src/model_downloader.py,sha256=4CKWAfQi1j2QssVwtbfVzfkygxtoAPXInhP_PtqcwHk,7652
|
|
4
|
+
src/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
5
|
+
src/tts_cli.py,sha256=MyVJrHACFfVt3cpuRtVZymYpsK4UC6v66gqFpqWNDT0,15252
|
|
6
|
+
src/voice_cache.py,sha256=fRHEN5T8iXI0585S-h6tVwnw0RS0w8FTCGu3IUOf8Rw,8540
|
|
7
|
+
src/providers/__init__.py,sha256=ztde87-39uDmx6CpOlZIauDlCvfv8rxjN-WBb7l2k9w,470
|
|
8
|
+
src/providers/base.py,sha256=gzNDRM6qytClHoG3J-7moKYXVG_wHsmZ9gC8RSAHw88,2768
|
|
9
|
+
src/providers/elevenlabs.py,sha256=fzwUBVmdBm7kTxwywUM7lkgf0OpMygNKyGZ9ED9zfMc,4202
|
|
10
|
+
src/providers/kokoro_onnx.py,sha256=L2DASKrPseyxhOF9P1PEgzU1PzEbEBLkGobQC5FdhFw,7532
|
|
11
|
+
src/providers/openai.py,sha256=5T9PdnedY9XH-HZ4EuZRCD8fI3Tz57LgbtkePpN7qLg,6288
|
|
12
|
+
par_cli_tts-0.1.0.dist-info/METADATA,sha256=CiEvb7cA7FJHWVQt3Zqg5vnG6wDQZAymHtGzGohUPGo,20035
|
|
13
|
+
par_cli_tts-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
|
|
14
|
+
par_cli_tts-0.1.0.dist-info/entry_points.txt,sha256=pK16eZGkqH1iAseDW2vHedlujJcR6_O9OgN0f24zlwM,80
|
|
15
|
+
par_cli_tts-0.1.0.dist-info/licenses/LICENSE,sha256=mM7wR5vvvL5avX6RGqhwhOGjxyojbty3pmJSEHOqeFM,1069
|
|
16
|
+
par_cli_tts-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 Paul Robello
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
src/__init__.py
ADDED