par-cli-tts 0.4.0__tar.gz → 0.4.2__tar.gz

par_cli_tts-0.4.2/.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.4.0 → par_cli_tts-0.4.2}/.gitignore

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

{par_cli_tts-0.4.0 → par_cli_tts-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: par-cli-tts
-Version: 0.4.0
+Version: 0.4.2
 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
@@ -68,15 +68,45 @@ 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.4.0-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)
@@ -106,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
@@ -122,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)
@@ -163,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)
@@ -258,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)
@@ -281,6 +463,10 @@ provider: kokoro-onnx
 # Default voice
 voice: Rachel
 
+# API keys (optional - can also be set via environment variables)
+# elevenlabs_api_key: your-elevenlabs-api-key-here
+# openai_api_key: your-openai-api-key-here
+
 # Output settings
 output_dir: ~/Documents/audio
 keep_temp: false
@@ -701,6 +887,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
@@ -739,6 +928,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

{par_cli_tts-0.4.0 → par_cli_tts-0.4.2}/README.md

@@ -5,15 +5,45 @@
 ![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.4.0-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)
@@ -43,7 +73,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
@@ -59,7 +89,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)
@@ -100,6 +130,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)
@@ -195,6 +262,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)
@@ -218,6 +400,10 @@ provider: kokoro-onnx
 # Default voice
 voice: Rachel
 
+# API keys (optional - can also be set via environment variables)
+# elevenlabs_api_key: your-elevenlabs-api-key-here
+# openai_api_key: your-openai-api-key-here
+
 # Output settings
 output_dir: ~/Documents/audio
 keep_temp: false
@@ -638,6 +824,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
@@ -676,6 +865,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

{par_cli_tts-0.4.0 → par_cli_tts-0.4.2}/pyproject.toml

@@ -63,6 +63,7 @@ Wiki = "https://github.com/paulrobello/par-cli-tts/wiki"
 [project.scripts]
 par-tts = "src.tts_cli:app"
 par-tts-kokoro = "src.kokoro_cli:app"
+par-tts-install-style = "src.install_claude_style:app"
 
 [build-system]
 requires = [
@@ -99,11 +100,13 @@ packages = [
 include = [
     "py.typed",
     "**/*.py",
+    ".claude/**/*",
 ]
 
 [tool.hatch.build.targets.sdist]
 include = [
     "src",
+    ".claude",
     "LICENSE",
     "README.md",
     "pyproject.toml",

{par_cli_tts-0.4.0 → par_cli_tts-0.4.2}/src/__init__.py

@@ -1,3 +1,3 @@
 """PAR CLI TTS - Command line text-to-speech tool."""
 
-__version__ = "0.4.0"
+__version__ = "0.4.2"

{par_cli_tts-0.4.0 → par_cli_tts-0.4.2}/src/config_file.py

@@ -18,6 +18,10 @@ class ConfigFile(BaseModel):
     voice: str | None = Field(None, description="Default voice")
     model: str | None = Field(None, description="Default model")
 
+    # API keys (optional - can also be set via environment variables)
+    elevenlabs_api_key: str | None = Field(None, description="ElevenLabs API key")
+    openai_api_key: str | None = Field(None, description="OpenAI API key")
+
     # Output settings
     output_dir: str | None = Field(None, description="Default output directory")
     output_format: str | None = Field(None, description="Default output format")
@@ -102,6 +106,10 @@ class ConfigManager:
             "# Default model",
             "# model: eleven_monolingual_v1",
             "",
+            "# API keys (optional - can also be set via environment variables)",
+            "# elevenlabs_api_key: your-elevenlabs-api-key-here",
+            "# openai_api_key: your-openai-api-key-here",
+            "",
             "# Output settings",
             "# output_dir: ~/Documents/audio",
             "# output_format: mp3",

par_cli_tts-0.4.2/src/install_claude_style.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python
+"""
+Install the TTS Summary output style for Claude Code.
+
+This is a separate CLI entry point to avoid conflicts with the main
+par-tts command's argument parsing.
+"""
+
+import json
+import re
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.prompt import Prompt
+
+from src.console import console
+
+app = typer.Typer(
+    help="Install TTS Summary output style for Claude Code",
+    no_args_is_help=True,
+)
+
+
+@app.command()
+def install(
+    user_name: Annotated[
+        str | None,
+        typer.Option(
+            "-n",
+            "--name",
+            help="Your name for personalized audio summaries",
+        ),
+    ] = None,
+    force: Annotated[
+        bool,
+        typer.Option(
+            "-f",
+            "--force",
+            help="Overwrite existing output style if it exists",
+        ),
+    ] = False,
+) -> None:
+    """
+    Install the TTS Summary output style for Claude Code.
+
+    This command installs the TTS Summary output style to your Claude Code
+    configuration and grants permission for Claude to run par-tts commands.
+    After installation, activate it in Claude Code with: /output-style tts-summary
+    """
+    # Define paths using cross-platform home directory
+    claude_dir = Path.home() / ".claude"
+    output_styles_dir = claude_dir / "output-styles"
+    settings_file = claude_dir / "settings.json"
+    output_style_file = output_styles_dir / "tts-summary.md"
+
+    # Get the bundled output style from the package
+    # Try multiple locations for cross-platform compatibility
+    possible_paths = [
+        # Installed package location (relative to this file)
+        Path(__file__).parent.parent / ".claude" / "output-styles" / "tts-summary.md",
+        # Current working directory (for development)
+        Path.cwd() / ".claude" / "output-styles" / "tts-summary.md",
+    ]
+
+    bundled_style = None
+    for path in possible_paths:
+        if path.exists():
+            bundled_style = path
+            break
+
+    if not bundled_style:
+        console.print("[red]Error: Could not find bundled output style file.[/red]")
+        console.print("[dim]Searched locations:[/dim]")
+        for path in possible_paths:
+            console.print(f"  [dim]- {path}[/dim]")
+        raise typer.Exit(1)
+
+    # Prompt for user name if not provided
+    if not user_name:
+        user_name = Prompt.ask(
+            "[cyan]Enter your name for personalized audio summaries[/cyan]",
+            default="User",
+        )
+
+    # Create directories if they don't exist
+    try:
+        output_styles_dir.mkdir(parents=True, exist_ok=True)
+        console.print(f"[dim]Ensured directory exists: {output_styles_dir}[/dim]")
+    except PermissionError:
+        console.print(f"[red]Error: Permission denied creating directory: {output_styles_dir}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Error creating directory: {e}[/red]")
+        raise typer.Exit(1)
+
+    # Check if output style already exists
+    if output_style_file.exists() and not force:
+        console.print("[yellow]Output style already exists at:[/yellow]", output_style_file)
+        console.print("[dim]Use --force to overwrite[/dim]")
+    else:
+        # Copy and customize the output style
+        console.print("[cyan]Installing TTS Summary output style...[/cyan]")
+
+        try:
+            content = bundled_style.read_text(encoding="utf-8")
+
+            # Customize the user name in the content
+            content = re.sub(
+                r"\*\*USER_NAME\*\*:\s*\w+",
+                f"**USER_NAME**: {user_name}",
+                content,
+            )
+            content = re.sub(
+                r"## Audio Summary for \w+",
+                f"## Audio Summary for {user_name}",
+                content,
+            )
+            content = re.sub(
+                r"Address \w+ directly",
+                f"Address {user_name} directly",
+                content,
+            )
+            content = re.sub(
+                r"Paul,",
+                f"{user_name},",
+                content,
+            )
+            content = re.sub(
+                r'"Paul,',
+                f'"{user_name},',
+                content,
+            )
+            content = re.sub(
+                r"\[Bash tool call: par-tts \"[^\"]*Paul",
+                f'[Bash tool call: par-tts "{user_name}',
+                content,
+            )
+
+            output_style_file.write_text(content, encoding="utf-8")
+            console.print(f"[green]✓ Installed output style to: {output_style_file}[/green]")
+        except PermissionError:
+            console.print(f"[red]Error: Permission denied writing to: {output_style_file}[/red]")
+            raise typer.Exit(1)
+        except Exception as e:
+            console.print(f"[red]Failed to copy output style: {e}[/red]")
+            raise typer.Exit(1)
+
+    # Update settings.json with permission
+    console.print("[cyan]Updating Claude Code permissions...[/cyan]")
+
+    settings: dict[str, Any] = {}
+    if settings_file.exists():
+        try:
+            file_content = settings_file.read_text(encoding="utf-8")
+            if file_content.strip():
+                settings = json.loads(file_content)
+                console.print("[dim]Loaded existing settings.json[/dim]")
+            else:
+                console.print("[dim]settings.json is empty, creating new configuration[/dim]")
+                settings = {}
+        except json.JSONDecodeError as e:
+            console.print(f"[yellow]Warning: Could not parse existing settings.json: {e}[/yellow]")
+            console.print("[yellow]Creating backup and new configuration[/yellow]")
+            # Create backup
+            backup_file = settings_file.with_suffix(".json.backup")
+            try:
+                settings_file.rename(backup_file)
+                console.print(f"[dim]Backup created: {backup_file}[/dim]")
+            except Exception:
+                pass
+            settings = {}
+        except PermissionError:
+            console.print(f"[red]Error: Permission denied reading: {settings_file}[/red]")
+            raise typer.Exit(1)
+
+    # Ensure permissions structure exists (handle missing or null values)
+    if "permissions" not in settings or settings["permissions"] is None:
+        settings["permissions"] = {}
+    if "allow" not in settings["permissions"] or settings["permissions"]["allow"] is None:
+        settings["permissions"]["allow"] = []
+
+    # Ensure allow is a list (handle edge cases)
+    if not isinstance(settings["permissions"]["allow"], list):
+        console.print("[yellow]Warning: permissions.allow is not a list, resetting[/yellow]")
+        settings["permissions"]["allow"] = []
+
+    # Add par-tts permission if not already present (avoid duplicates)
+    par_tts_permission = "Bash(par-tts:*)"
+    if par_tts_permission not in settings["permissions"]["allow"]:
+        settings["permissions"]["allow"].append(par_tts_permission)
+        console.print(f"[green]✓ Added permission: {par_tts_permission}[/green]")
+    else:
+        console.print(f"[dim]Permission already exists: {par_tts_permission}[/dim]")
+
+    # Write updated settings
+    try:
+        settings_file.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+        console.print(f"[green]✓ Updated settings: {settings_file}[/green]")
+    except PermissionError:
+        console.print(f"[red]Error: Permission denied writing to: {settings_file}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Failed to update settings.json: {e}[/red]")
+        raise typer.Exit(1)
+
+    # Success message
+    console.print()
+    console.print("[bold green]Installation complete![/bold green]")
+    console.print()
+    console.print("[cyan]To activate the output style in Claude Code, run:[/cyan]")
+    console.print("  [bold]/output-style tts-summary[/bold]")
+    console.print()
+    console.print(f"[dim]Your name is set to: {user_name}[/dim]")
+    console.print(f"[dim]To change your name, edit: {output_style_file}[/dim]")
+
+
+if __name__ == "__main__":
+    app()

{par_cli_tts-0.4.0 → par_cli_tts-0.4.2}/src/providers/elevenlabs.py

@@ -7,12 +7,14 @@ from typing import Any
 
 with warnings.catch_warnings():
     warnings.filterwarnings("ignore", message="Core Pydantic V1 functionality", category=UserWarning)
-    from elevenlabs import VoiceSettings, play, save
+    from elevenlabs import VoiceSettings
     from elevenlabs.client import ElevenLabs
+    from elevenlabs.play import save
 
 from src.defaults import DEFAULT_ELEVENLABS_VOICE
 from src.http_client import create_http_client
 from src.providers.base import TTSProvider, Voice
+from src.utils import play_audio_bytes
 from src.voice_cache import VoiceCache, resolve_voice_identifier
 
 
@@ -152,20 +154,14 @@ class ElevenLabsProvider(TTSProvider):
 
     def play_audio(self, audio_data: bytes | Iterator[bytes], volume: float = 1.0) -> None:
         """
-        Play audio data.
+        Play audio data with volume control.
 
         Args:
             audio_data: Audio data to play.
             volume: Volume level (0.0 = silent, 1.0 = normal, 2.0 = double volume).
-                   Note: ElevenLabs play() doesn't support volume, will use system default.
         """
-        # For play, we need to convert iterator to bytes
-        if isinstance(audio_data, bytes):
-            play(audio_data)
-        else:
-            # Convert iterator to bytes for playback
-            audio_bytes = b"".join(audio_data)
-            play(audio_bytes)
+        # Convert iterator to bytes if needed
+        if not isinstance(audio_data, bytes):
+            audio_data = b"".join(audio_data)
 
-        # Note: ElevenLabs play() function doesn't support volume control
-        # Consider using system players with volume support if needed
+        play_audio_bytes(audio_data, volume=volume, suffix=".mp3")

{par_cli_tts-0.4.0 → par_cli_tts-0.4.2}/src/tts_cli.py

@@ -28,48 +28,60 @@ from src.providers import PROVIDERS, TTSProvider
 app = typer.Typer(help="Text-to-speech command line tool with multiple provider support")
 
 
-def get_api_key(provider: str) -> str | None:
+def get_api_key(provider: str, config_file: Any = None) -> str | None:
     """
-    Get API key for the specified provider from environment.
+    Get API key for the specified provider from config file or environment.
 
     Args:
         provider: Provider name (elevenlabs, openai, kokoro-onnx).
+        config_file: Optional config file with API keys.
 
     Returns:
         API key string or None for providers that don't need one.
 
     Raises:
-        SystemExit: If API key is not found in environment.
+        SystemExit: If API key is not found anywhere.
     """
     # kokoro-onnx doesn't need an API key
     if provider == "kokoro-onnx":
         return None
 
-    env_var_map = {
-        "elevenlabs": "ELEVENLABS_API_KEY",
-        "openai": "OPENAI_API_KEY",
+    # Map provider to config file field and environment variable
+    key_map = {
+        "elevenlabs": ("elevenlabs_api_key", "ELEVENLABS_API_KEY"),
+        "openai": ("openai_api_key", "OPENAI_API_KEY"),
     }
 
-    env_var = env_var_map.get(provider)
-    if not env_var:
+    if provider not in key_map:
         handle_error(f"Unknown provider '{provider}'", ErrorType.INVALID_PROVIDER)
         return None  # For type checker, never reached
 
+    config_field, env_var = key_map[provider]
+
+    # Check config file first
+    if config_file:
+        api_key = getattr(config_file, config_field, None)
+        if api_key:
+            return api_key
+
+    # Fall back to environment variable
     api_key = os.getenv(env_var)
-    if not api_key and provider != "kokoro-onnx":
+    if not api_key:
         handle_error(
-            f"{env_var} not found. Please set {env_var} in your .env file or environment", ErrorType.MISSING_API_KEY
+            f"{env_var} not found. Please set {env_var} in your config file or environment",
+            ErrorType.MISSING_API_KEY,
         )
 
     return api_key
 
 
-def create_provider(provider_name: str, **kwargs: Any) -> TTSProvider:
+def create_provider(provider_name: str, config_file: Any = None, **kwargs: Any) -> TTSProvider:
     """
     Create a TTS provider instance.
 
     Args:
         provider_name: Name of the provider.
+        config_file: Optional config file with API keys.
         **kwargs: Additional provider configuration.
 
     Returns:
@@ -83,7 +95,7 @@ def create_provider(provider_name: str, **kwargs: Any) -> TTSProvider:
             f"Unknown provider '{provider_name}'. Available: {', '.join(PROVIDERS.keys())}", ErrorType.INVALID_PROVIDER
         )
 
-    api_key = get_api_key(provider_name)
+    api_key = get_api_key(provider_name, config_file)
     validate_api_key(api_key, provider_name)
     provider_class = PROVIDERS[provider_name]
 
@@ -477,7 +489,10 @@ def handle_speech_generation(
 
             if play_audio:
                 console.print("[cyan]Playing audio...[/cyan]")
-                tts_provider.play_audio(audio_data, volume=volume)
+                # Read from saved file since iterator was consumed
+                with open(output_path, "rb") as f:
+                    audio_bytes = f.read()
+                tts_provider.play_audio(audio_bytes, volume=volume)
         else:
             if play_audio:
                 console.print("[cyan]Playing audio...[/cyan]")
@@ -496,7 +511,10 @@ def handle_speech_generation(
                 tts_provider.save_audio(audio_data, tmp_path)
 
                 try:
-                    tts_provider.play_audio(audio_data, volume=volume)
+                    # Read from saved file since iterator was consumed
+                    with open(tmp_path, "rb") as f:
+                        audio_bytes = f.read()
+                    tts_provider.play_audio(audio_bytes, volume=volume)
 
                     if keep_temp or temp_dir:
                         console.print(f"[green]Audio saved to: {tmp_path}[/green]")
@@ -543,14 +561,14 @@ def main(
         str | None, typer.Argument(help="Text to convert to speech. Use '-' for stdin, '@filename' to read from file")
     ] = None,
     provider: Annotated[
-        str,
+        str | None,
         typer.Option(
             "-P",
             "--provider",
             help="TTS provider to use (elevenlabs, openai, kokoro-onnx)",
             envvar="TTS_PROVIDER",
         ),
-    ] = DEFAULT_PROVIDER,
+    ] = None,
     voice: Annotated[
         str | None,
         typer.Option(
@@ -754,7 +772,7 @@ def main(
 
     # Apply config file defaults (CLI args override these)
     if config_file:
-        provider = provider or config_file.provider or DEFAULT_PROVIDER
+        provider = provider or config_file.provider
         voice = voice or config_file.voice
         model = model or config_file.model
         output = output or (Path(config_file.output_dir) / "output.mp3" if config_file.output_dir else None)
@@ -771,6 +789,10 @@ def main(
         )
         debug = debug or config_file.debug or False
 
+    # Apply default provider if still not set
+    if not provider:
+        provider = DEFAULT_PROVIDER
+
     # Store debug mode globally for error handler
     sys._debug_mode = debug  # type: ignore
 
@@ -794,7 +816,7 @@ def main(
         return
 
     # Create provider
-    tts_provider = create_provider(provider)
+    tts_provider = create_provider(provider, config_file)
 
     # Handle cache management operations (ElevenLabs only)
     if refresh_cache or clear_cache_samples:

{par_cli_tts-0.4.0 → par_cli_tts-0.4.2}/src/utils.py

@@ -1,6 +1,7 @@
 """Utility functions for PAR CLI TTS."""
 
 import hashlib
+import shutil
 import subprocess
 import sys
 import tempfile
@@ -138,8 +139,7 @@ def play_audio_with_player(file_path: Path, volume: float = 1.0) -> None:
         # afplay supports volume flag (-v)
         subprocess.run(["afplay", "-v", str(volume), str(file_path)], check=True)
     elif sys.platform == "win32":  # Windows
-        # Windows doesn't have native volume control for start command
-        subprocess.run(["start", "", str(file_path)], shell=True, check=True)
+        _play_audio_windows(file_path, volume)
     else:  # Linux and others
         # Try common audio players with volume support
         players_with_volume = [
@@ -160,6 +160,154 @@ def play_audio_with_player(file_path: Path, volume: float = 1.0) -> None:
         raise RuntimeError("No audio player found. Install aplay, paplay, ffplay, or mpg123.")
 
 
+def _find_windows_audio_player() -> str | None:
+    """Find an available audio player on Windows.
+
+    Checks for ffplay, VLC, and mpg123 in that order.
+
+    Returns:
+        Name of the found player, or None if no player is available.
+    """
+    # Prefer ffplay (comes with ffmpeg, most reliable)
+    if shutil.which("ffplay"):
+        return "ffplay"
+
+    # VLC media player
+    vlc_paths = [
+        r"C:\Program Files\VideoLAN\VLC\vlc.exe",
+        r"C:\Program Files (x86)\VideoLAN\VLC\vlc.exe",
+    ]
+    for vlc_path in vlc_paths:
+        if Path(vlc_path).exists():
+            return "vlc"
+
+    # mpg123 for Windows
+    if shutil.which("mpg123"):
+        return "mpg123"
+
+    return None
+
+
+def _play_with_powershell(file_path: Path, volume: float, timeout: int = 60) -> None:
+    """Play audio using PowerShell MediaPlayer COM object.
+
+    This is a fallback for Windows when no external player is available.
+    Uses the Windows built-in MediaPlayer COM object for reliable playback.
+
+    Args:
+        file_path: Path to the audio file to play.
+        volume: Volume level (0.0 = silent, 1.0 = normal, 2.0 = double).
+            Note: MediaPlayer volume range is 0.0 to 1.0, values above 1.0
+            are capped at 1.0.
+        timeout: Maximum playback time in seconds.
+
+    Raises:
+        RuntimeError: If PowerShell execution fails.
+    """
+    # MediaPlayer volume is 0.0 to 1.0, cap values above 1.0
+    media_volume = min(volume, 1.0)
+
+    # PowerShell script using MediaPlayer COM object
+    ps_script = f"""
+$file = "{file_path}"
+$volume = {media_volume}
+
+$player = New-Object -ComObject MediaPlayer.MediaPlayer
+$player.Open($file)
+$player.Volume = $volume
+
+# Wait for media to be ready
+while ($player.ReadyState -lt 3) {{
+    Start-Sleep -Milliseconds 100
+}}
+
+# Get duration and wait for playback
+$duration = $player.Duration
+if ($duration -gt 0) {{
+    $player.Play()
+    Start-Sleep -Seconds $duration
+}} else {{
+    # If duration not available, wait up to {timeout} seconds
+    $player.Play()
+    Start-Sleep -Seconds {timeout}
+}}
+
+$player.Close()
+[System.Runtime.InteropServices.Marshal]::ReleaseComObject($player) | Out-Null
+"""
+
+    try:
+        subprocess.run(
+            ["powershell", "-NoProfile", "-NonInteractive", "-Command", ps_script],
+            check=True,
+            timeout=timeout + 10,  # Extra buffer for startup/shutdown
+        )
+    except subprocess.TimeoutExpired as e:
+        raise RuntimeError(f"Audio playback timed out after {timeout} seconds") from e
+    except subprocess.CalledProcessError as e:
+        raise RuntimeError(f"PowerShell audio playback failed: {e}") from e
+
+
+def _play_audio_windows(file_path: Path, volume: float = 1.0) -> None:
+    """Play audio on Windows with volume control.
+
+    Tries external players first (ffplay, VLC, mpg123), then falls back
+    to PowerShell MediaPlayer COM object.
+
+    Args:
+        file_path: Path to the audio file to play.
+        volume: Volume level (0.0 = silent, 1.0 = normal, 2.0 = double).
+
+    Raises:
+        RuntimeError: If no audio playback method succeeds.
+    """
+    player = _find_windows_audio_player()
+
+    if player == "ffplay":
+        # ffplay uses 0-100 volume scale
+        subprocess.run(
+            [
+                "ffplay",
+                "-volume",
+                str(int(volume * 100)),
+                "-nodisp",
+                "-autoexit",
+                "-hide_banner",
+                "-loglevel",
+                "error",
+                str(file_path),
+            ],
+            check=True,
+        )
+    elif player == "vlc":
+        # VLC volume scale: 0-256 where 256 is 100%
+        # Higher values possible but 512 is 200%
+        vlc_path = r"C:\Program Files\VideoLAN\VLC\vlc.exe"
+        if not Path(vlc_path).exists():
+            vlc_path = r"C:\Program Files (x86)\VideoLAN\VLC\vlc.exe"
+        subprocess.run(
+            [
+                vlc_path,
+                "--intf",
+                "dummy",
+                "--play-and-exit",
+                "--volume",
+                str(int(volume * 256)),
+                str(file_path),
+            ],
+            check=True,
+        )
+    elif player == "mpg123":
+        # mpg123 uses scale factor (32768 = normal)
+        subprocess.run(
+            ["mpg123", "-f", str(int(volume * 32768)), str(file_path)],
+            check=True,
+        )
+    else:
+        # Fallback to PowerShell MediaPlayer
+        _play_with_powershell(file_path, volume)
+
+
 def play_audio_bytes(audio_data: bytes, volume: float = 1.0, suffix: str = ".mp3") -> None:
     """Play audio data from bytes using system player.