par-cli-tts 0.2.2__tar.gz → 0.4.1__tar.gz

par_cli_tts-0.4.1/.claude/output-styles/tts-summary.md

@@ -0,0 +1,78 @@
+---
+name: TTS Summary
+description: Audio task completion announcements with TTS
+---
+
+# TTS Summary Output Style
+
+You are Claude Code with an experimental TTS announcement feature designed to communicate directly with the user about what you've accomplished.
+
+## Variables
+- **USER_NAME**: Paul
+
+## Standard Behavior
+Respond normally to all user requests, using your full capabilities for:
+- Code generation and editing
+- File operations
+- Running commands
+- Analysis and explanations
+- All standard Claude Code features
+
+## Critical Addition: Audio Task Summary
+
+**At the very END of EVERY response**, you MUST provide an audio summary for the user:
+
+1. Write a clear separator: `---`
+2. Add the heading: `## Audio Summary for Paul`
+3. Craft a message that speaks DIRECTLY to Paul about what you did for them
+4. **IMMEDIATELY execute the TTS command using the Bash tool** - do NOT just display it in a code block
+
+### How to Execute the TTS Command
+
+You MUST use the Bash tool to actually run the command. Do NOT wrap it in a markdown code block.
+
+**CORRECT** - Execute with Bash tool:
+```
+[Bash tool call with command: par-tts "Paul, I've completed the task."]
+```
+
+**WRONG** - Just displaying (DO NOT DO THIS):
+```markdown
+```bash
+par-tts "Paul, I've completed the task."
+```
+```
+
+The user should hear the audio playback, not just see the command text.
+
+## Communication Guidelines
+
+- **Address Paul directly** when appropriate: "Paul, I've updated your..." or "Fixed the bug in..."
+- **Focus on outcomes** for the user: what they can now do, what's been improved
+- **Be conversational** - speak as if telling Paul what you just did
+- **Highlight value** - emphasize what's useful about the change
+- **Keep it concise** - one clear sentence (under 20 words)
+
+## Example Response Pattern
+
+[Your normal response content here...]
+
+---
+
+## Audio Summary for Paul
+
+Paul, I've created three new output styles to customize how you receive information.
+
+[Bash tool call: par-tts "Paul, I've created three new output styles to customize how you receive information."]
+
+## Important Rules
+
+- ALWAYS include the audio summary, even for simple queries
+- Speak TO the user, not about abstract tasks
+- Use natural, conversational language
+- Focus on the user benefit or outcome
+- Make it feel like a helpful assistant reporting completion
+- **EXECUTE the command with the Bash tool - do NOT just display it in a code block**
+- The user should HEAR the audio, not just see the command text
+
+This experimental feature provides personalized audio feedback about task completion.

{par_cli_tts-0.2.2 → par_cli_tts-0.4.1}/.gitignore

@@ -269,3 +269,4 @@ junit.xml
 # Documentation builds
 docs/_build/
 docs/.doctrees/
+settings.local.json

{par_cli_tts-0.2.2 → par_cli_tts-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: par-cli-tts
-Version: 0.2.2
+Version: 0.4.1
 Summary: PAR CLI TTS - Command line text-to-speech tool using ElevenLabs with voice caching and name resolution
 Project-URL: Homepage, https://github.com/paulrobello/par-cli-tts
 Project-URL: Documentation, https://github.com/paulrobello/par-cli-tts/blob/main/README.md
@@ -51,7 +51,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: elevenlabs>=1.0.0
-Requires-Dist: kokoro-onnx>=0.4.9
+Requires-Dist: kokoro-onnx>=0.5.0
 Requires-Dist: openai>=1.100.1
 Requires-Dist: platformdirs>=4.3.0
 Requires-Dist: python-dotenv>=1.0.0
@@ -68,15 +68,57 @@ Description-Content-Type: text/markdown
 ![Arch x86-63 | ARM | AppleSilicon](https://img.shields.io/badge/arch-x86--64%20%7C%20ARM%20%7C%20AppleSilicon-blue)
 
 ![MIT License](https://img.shields.io/badge/license-MIT-green.svg)
-![Version](https://img.shields.io/badge/version-0.2.2-green.svg)
+![Version](https://img.shields.io/badge/version-0.4.1-green.svg)
 ![Development Status](https://img.shields.io/badge/status-stable-green.svg)
 
 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.
 
 [!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://buymeacoffee.com/probello3)
 
+## Table of Contents
+
+- [What's New](#whats-new)
+- [Features](#features)
+- [Technology Stack](#technology-stack)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+  - [From PyPI](#installation-from-pypi-recommended)
+  - [From Source](#installation-from-source)
+  - [Kokoro ONNX Setup](#kokoro-onnx-setup)
+- [Using with AI Agents](#using-with-ai-agents)
+  - [Claude Code Setup](#claude-code-setup)
+  - [Claude Code Output Style](#claude-code-output-style)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [Command Line Options](#command-line-options)
+- [Providers](#providers)
+- [Cache Locations](#cache-locations)
+- [Development](#development)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
+- [Author](#author)
+- [Acknowledgments](#acknowledgments)
+- [Support](#support)
+
 ## What's New
 
+### v0.4.1
+- **Claude Code output style installer** - New `install-claude-style` command to automatically set up TTS audio summaries
+- **Bundled output style** - TTS Summary output style included with the package
+
+### v0.4.0
+- **OpenAI gpt-4o-mini-tts** - New steerable TTS model with `--instructions` option
+- **7 new OpenAI voices** - ash, ballad, coral, sage, verse, marin, cedar (13 total)
+- **ElevenLabs model updated** - Changed from deprecated `eleven_monolingual_v1` to `eleven_multilingual_v2`
+- **Kokoro ONNX 0.5.0** - Updated to latest version
+
+### v0.3.0
+- Major code refactoring with better modularity and code organization
+- New utility modules for shared console, defaults, and HTTP client
+- Test suite with 46 tests for better reliability
+- Documentation synced to match current implementation
+
 ### v0.2.2
 - Updated all HTTP requests and downloaders to ignore SSL certificate errors
 - Improves compatibility with corporate proxies and development environments
@@ -94,7 +136,7 @@ A powerful command-line text-to-speech tool supporting multiple TTS providers (E
 - **Smarter Voice Cache** - Change detection, manual refresh, and voice sample caching
 - **Consistent Error Handling** - Clear error messages with proper exit codes
 - **Multiple Input Methods** - Direct text, stdin piping, and file input (`@filename`)
-- **Volume Control** - Adjust playback volume (0.0 to 5.0) with platform-specific support
+- **Volume Control** - Adjust playback volume (0.0 to 5.0) across all platforms (macOS, Linux, Windows)
 - **Voice Preview** - Test voices with sample text before using
 
 ### Improvements
@@ -110,7 +152,7 @@ A powerful command-line text-to-speech tool supporting multiple TTS providers (E
 - **Configuration File** - Set default preferences in YAML config file (`~/.config/par-tts/config.yaml`)
 - **Flexible Input Methods** - Accept text from command line, stdin pipe, or files (`@filename`)
 - **Voice Name Support** - Use voice names like "Juniper" or "nova" instead of cryptic IDs
-- **Volume Control** - Adjust playback volume (0.0 to 5.0) with platform-specific support
+- **Volume Control** - Adjust playback volume (0.0 to 5.0) across all platforms (macOS, Linux, Windows)
 - **Voice Preview** - Test voices with sample text using `--preview-voice`
 - **Smart Voice Caching** - Change detection, auto-refresh, and voice sample caching
 - **Partial Name Matching** - Type "char" to match "Charlotte" (ElevenLabs)
@@ -151,6 +193,43 @@ curl -LsSf https://astral.sh/uv/install.sh | sh
 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 
+### Windows Audio Requirements
+
+For the best audio playback experience on Windows with volume control, install one of these audio players:
+
+#### ffplay (Recommended)
+```powershell
+# Using Chocolatey
+choco install ffmpeg
+
+# Using Scoop
+scoop install ffmpeg
+
+# Using winget
+winget install ffmpeg
+```
+
+#### VLC Media Player (Alternative)
+Download from [videolan.org](https://www.videolan.org/vlc/) or:
+```powershell
+# Using Chocolatey
+choco install vlc
+
+# Using winget
+winget install VideoLAN.VLC
+```
+
+#### mpg123 (Lightweight Option)
+```powershell
+# Using Chocolatey
+choco install mpg123
+
+# Using Scoop
+scoop install mpg123
+```
+
+**Note**: If no external player is installed, PAR CLI TTS will use Windows PowerShell's built-in MediaPlayer COM object as a fallback. This provides basic playback with volume control (capped at 1.0/100%). For full volume control up to 5.0x, install ffplay, VLC, or mpg123.
+
 ## Installation
 
 ### Installation from PyPI (Recommended)
@@ -246,6 +325,121 @@ export KOKORO_VOICE_PATH=/path/to/voices-v1.0.bin
 
 When these environment variables are set, automatic download is disabled.
 
+## Using with AI Agents
+
+PAR CLI TTS works great with AI agents like [Claude Code](https://claude.ai/code). When using it in an agent, you'll need to grant permission for the agent to run the `par-tts` command.
+
+### Claude Code Setup
+
+The easiest way to allow Claude Code to use `par-tts` is to add the following to your `~/.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(par-tts:*)"
+    ]
+  }
+}
+```
+
+This grants Claude Code permission to run any `par-tts` command without prompting for approval each time.
+
+### Example Agent Usage
+
+Once configured, your AI agent can easily generate speech:
+
+```bash
+# Agent can run TTS commands directly
+par-tts "Task completed successfully!"
+
+# Save audio for notifications
+par-tts "Build finished" --output /tmp/notify.mp3 --no-play
+```
+
+### Claude Code Output Style
+
+This project includes a **TTS Summary** output style for Claude Code that provides audio announcements when tasks are completed. This creates a personalized audio feedback experience where Claude announces what it has accomplished.
+
+#### Features
+
+- Automatic audio summary at the end of every Claude Code response
+- Personalized messages addressing you by name
+- Focus on outcomes and user benefits
+- Natural, conversational language
+
+#### Installation
+
+The easiest way to install the output style is using the built-in CLI command:
+
+```bash
+# Interactive installation (prompts for your name)
+par-tts-install-style
+
+# Non-interactive with name specified
+par-tts-install-style --name "YourName"
+
+# Force overwrite if already installed
+par-tts-install-style --name "YourName" --force
+```
+
+This command will:
+1. Copy the TTS Summary output style to `~/.claude/output-styles/tts-summary.md`
+2. Update `~/.claude/settings.json` with the required `Bash(par-tts:*)` permission
+3. Personalize the output style with your name
+
+#### Prerequisites
+
+**Important**: Before using this output style, ensure:
+
+1. `par-cli-tts` is installed (see [Installation](#installation))
+2. The `install-claude-style` command has been run (automatically grants permissions)
+
+If you prefer manual installation, you can:
+1. Copy `.claude/output-styles/tts-summary.md` to `~/.claude/output-styles/`
+2. Add the following to `~/.claude/settings.json`:
+   ```json
+   {
+     "permissions": {
+       "allow": [
+         "Bash(par-tts:*)"
+       ]
+     }
+   }
+   ```
+
+#### Usage
+
+Activate the output style using the `/output-style` command in Claude Code:
+
+```
+/output-style tts-summary
+```
+
+Once activated, Claude will automatically announce completed tasks with audio feedback.
+
+#### Customization
+
+Edit `~/.claude/output-styles/tts-summary.md` to personalize the experience:
+
+1. **Change your name** - Find the `USER_NAME` variable and update it:
+   ```markdown
+   ## Variables
+   - **USER_NAME**: YourNameHere
+   ```
+
+2. **Update the heading** - Search for "Paul" and replace with your name:
+   ```markdown
+   ## Audio Summary for YourNameHere
+   ```
+
+3. **Customize the TTS command** - Use a different voice or provider:
+   ```markdown
+   par-tts "YourNameHere, task completed." --voice nova --provider openai
+   ```
+
+4. **Adjust message style** - Modify the Communication Guidelines section to change how Claude speaks to you
+
 ## Configuration
 
 ### Configuration File (Recommended)
@@ -404,6 +598,10 @@ par-tts "Stable voice" --stability 0.8 --similarity 0.7
 # Adjust OpenAI speech speed
 par-tts "Fast speech" --provider openai --speed 1.5
 
+# Use OpenAI with voice instructions (gpt-4o-mini-tts only)
+par-tts "Hello there!" --provider openai --instructions "Speak in a cheerful and positive tone"
+par-tts "Good morning" -P openai -i "Speak like a pirate"
+
 # Keep temp files after playback
 par-tts "Keep this" --keep-temp
 
@@ -510,6 +708,7 @@ make clear-cache     # Clear voice cache including samples
 |--------|-------|-------------|---------|
 | `--speed` | `-r` | Speech speed (0.25 to 4.0) | 1.0 |
 | `--format` | `-f` | Audio format (mp3, opus, aac, flac, wav) | mp3 |
+| `--instructions` | `-i` | Voice instructions for gpt-4o-mini-tts (e.g., "Speak cheerfully") | None |
 
 ### Kokoro ONNX Options
 
@@ -543,7 +742,12 @@ make clear-cache     # Clear voice cache including samples
 
 ### ElevenLabs
 
-- **Models**: eleven_monolingual_v1, eleven_multilingual_v1, eleven_multilingual_v2
+- **Models**:
+  - `eleven_multilingual_v2` (default) - Most lifelike, 29 languages
+  - `eleven_v3` - Most expressive, 70+ languages
+  - `eleven_flash_v2.5` - Ultra-low latency (~75ms), 32 languages
+  - `eleven_turbo_v2.5` - Balanced quality/speed, 32 languages
+  - ~~`eleven_monolingual_v1`~~ - Deprecated, will be removed
 - **Voices**: 25+ voices with different accents and styles
 - **Features**: Voice cloning, stability control, similarity boost
 - **Smart Caching**:
@@ -555,15 +759,28 @@ make clear-cache     # Clear voice cache including samples
 
 ### OpenAI
 
-- **Models**: tts-1 (optimized for speed), tts-1-hd (optimized for quality)
-- **Voices**:
+- **Models**:
+  - `gpt-4o-mini-tts` (default) - Steerable TTS with instructions
+  - `tts-1` - Optimized for speed
+  - `tts-1-hd` - Optimized for quality
+- **Voices** (13 total):
   - alloy - Neutral and balanced
+  - ash - Enthusiastic and energetic
+  - ballad - Warm and soulful
+  - coral - Friendly and approachable
   - echo - Smooth and articulate
   - fable - Expressive and animated
-  - onyx - Deep and authoritative
   - nova - Warm and friendly (default)
+  - onyx - Deep and authoritative
+  - sage - Calm and wise
   - shimmer - Soft and gentle
-- **Features**: Speed control (0.25x to 4x), multiple output formats
+  - verse - Clear and melodic
+  - marin - Gentle and soothing
+  - cedar - Rich and resonant
+- **Features**:
+  - Speed control (0.25x to 4x)
+  - Multiple output formats
+  - Voice instructions for gpt-4o-mini-tts (steer emotion, accent, tone)
 - **Output Formats**: mp3, opus, aac, flac, wav, pcm
 - **API Key**: Set `OPENAI_API_KEY` in your .env file
 
@@ -666,6 +883,9 @@ par-cli-tts/
 ├── docs/
 │   ├── ARCHITECTURE.md      # System architecture documentation
 │   └── CLAUDE.md            # Development guidelines
+├── .claude/
+│   └── output-styles/
+│       └── tts-summary.md   # Claude Code TTS output style
 ├── .env.example             # Example environment file
 ├── pyproject.toml           # Project configuration
 ├── Makefile                 # Development commands
@@ -704,6 +924,8 @@ par-cli-tts/
    - Check system volume settings
    - Try adjusting `--volume` flag
    - On Linux, verify audio subsystem (ALSA/PulseAudio) is working
+   - On Windows, install ffplay (`choco install ffmpeg`) for best results
+   - On Windows without external players, the PowerShell fallback will be used
 
 6. **Slow Response Times**
    - Voice previews are cached after first use