@biggora/claude-plugins 1.0.0 → 1.1.0

package/src/skills/text-to-speech/references/espeak-cli.md

@@ -0,0 +1,277 @@
+# espeak-ng CLI Reference
+
+Direct command-line usage of espeak-ng. Useful when you need fine-grained control over
+phonemes, prosody, SSML, or want to avoid the Python pyttsx3 overhead.
+
+---
+
+## Basic Usage
+
+```bash
+# Speak to stdout (pipe to ffmpeg)
+espeak-ng "Hello world"
+
+# Save to WAV file
+espeak-ng -w /tmp/output.wav "Hello world"
+
+# Read from file
+espeak-ng -w /tmp/output.wav -f /tmp/script.txt
+
+# Read from stdin
+echo "Hello world" | espeak-ng -w /tmp/output.wav
+```
+
+---
+
+## Key Flags
+
+| Flag | Description | Example |
+|------|-------------|---------|
+| `-v <voice>` | Voice/language | `-v en-gb`, `-v ru`, `-v de` |
+| `-s <rate>` | Speed in words/min (default 175) | `-s 140` |
+| `-p <pitch>` | Pitch 0–99 (default 50) | `-p 55` |
+| `-a <amplitude>` | Volume 0–200 (default 100) | `-a 120` |
+| `-g <gap>` | Gap between words in 10ms units | `-g 5` |
+| `-w <file>` | Write WAV output to file | `-w out.wav` |
+| `-f <file>` | Read input from text file | `-f script.txt` |
+| `--ipa` | Print IPA phonemes to stdout | `--ipa` |
+| `-q` | Quiet — no audio, just phoneme output | `-q --ipa` |
+| `--pho` | Output phoneme mnemonics | `--pho` |
+| `-m` | Interpret input as SSML markup | `-m` |
+| `-b 1` | Input is UTF-8 (default on Linux) | `-b 1` |
+| `--punct` | Speak punctuation characters | `--punct` |
+| `-z` | No final sentence pause | `-z` |
+
+---
+
+## Voice Selection
+
+```bash
+# List all voices
+espeak-ng --voices
+
+# List voices for a language
+espeak-ng --voices=en
+espeak-ng --voices=ru
+espeak-ng --voices=zh
+
+# Key voice IDs
+# English:  en, en-gb, en-us, en-gb-scotland, en-gb-x-gbclan, en-gb-x-rp
+# Russian:  ru
+# German:   de
+# French:   fr
+# Spanish:  es, es-419 (Latin America)
+# Chinese:  cmn (Mandarin), yue (Cantonese)
+# Japanese: ja
+# Arabic:   ar
+# Hindi:    hi
+# Korean:   ko
+# Italian:  it
+# Dutch:    nl
+# Polish:   pl
+# Ukrainian: uk
+# Turkish:  tr
+# Swedish:  sv
+# Portuguese: pt, pt-br
+```
+
+---
+
+## SSML Support
+
+espeak-ng understands a subset of SSML. Pass `-m` flag to enable:
+
+```bash
+espeak-ng -m -w /tmp/ssml_out.wav '<speak>
+  Hello, <break time="500ms"/> how are you?
+  <prosody rate="slow" pitch="+5st">This part is slower and higher.</prosody>
+  <emphasis level="strong">Important point here.</emphasis>
+  Back to normal speed now.
+</speak>'
+```
+
+### Supported SSML Tags
+
+```xml
+<!-- Pause -->
+<break time="300ms"/>
+<break time="1s"/>
+
+<!-- Prosody control -->
+<prosody rate="slow">...</prosody>        <!-- slow, medium, fast, x-slow, x-fast -->
+<prosody rate="0.8">...</prosody>         <!-- relative rate: 0.5–2.0 -->
+<prosody pitch="+5st">...</prosody>       <!-- semitones: -12st to +12st -->
+<prosody pitch="high">...</prosody>       <!-- x-low, low, medium, high, x-high -->
+<prosody volume="loud">...</prosody>      <!-- silent, x-soft, soft, medium, loud, x-loud -->
+
+<!-- Emphasis -->
+<emphasis level="strong">...</emphasis>  <!-- none, reduced, moderate, strong -->
+
+<!-- Say-as (number/date formatting) -->
+<say-as interpret-as="cardinal">42</say-as>
+<say-as interpret-as="ordinal">3</say-as>
+<say-as interpret-as="characters">CPU</say-as>
+<say-as interpret-as="date" format="ymd">2024-03-15</say-as>
+<say-as interpret-as="time" format="hms24">14:30:00</say-as>
+
+<!-- Phoneme (IPA or x-sampa) -->
+<phoneme alphabet="ipa" ph="həˈloʊ">Hello</phoneme>
+<phoneme alphabet="x-sampa" ph="h@'loU">Hello</phoneme>
+
+<!-- Sub (spoken alias) -->
+<sub alias="Artificial Intelligence">AI</sub>
+
+<!-- Language switch -->
+<voice xml:lang="fr">Bonjour</voice>
+```
+
+---
+
+## Phoneme Control
+
+```bash
+# Get IPA phonemes for text
+espeak-ng -q --ipa "Hello world"
+# → həlˈəʊ wˈɜːld
+
+# Get x-sampa phonemes
+espeak-ng -q --pho "Hello world"
+
+# Speak using IPA directly
+espeak-ng -w /tmp/ipa.wav "<phoneme alphabet='ipa' ph='həˈloʊ'>Hello</phoneme>" -m
+
+# Print phoneme list for a language
+espeak-ng --voices=en --pho
+```
+
+---
+
+## Python Subprocess Integration
+
+```python
+import subprocess
+
+def espeak_tts(text: str, output_wav: str,
+               voice: str = "en-gb-scotland",
+               speed: int = 145,
+               pitch: int = 52,
+               amplitude: int = 110,
+               ssml: bool = False) -> str:
+    """
+    Generate TTS via espeak-ng CLI.
+    Returns path to output WAV file.
+    """
+    cmd = [
+        "espeak-ng",
+        "-v", voice,
+        "-s", str(speed),
+        "-p", str(pitch),
+        "-a", str(amplitude),
+        "-w", output_wav,
+    ]
+    if ssml:
+        cmd.append("-m")
+    cmd.append(text)
+    
+    subprocess.run(cmd, check=True, capture_output=True)
+    return output_wav
+
+
+def espeak_tts_file(input_txt: str, output_wav: str,
+                    voice: str = "en-gb-scotland",
+                    speed: int = 145) -> str:
+    """Generate TTS from a text file."""
+    subprocess.run([
+        "espeak-ng", "-v", voice, "-s", str(speed),
+        "-f", input_txt, "-w", output_wav
+    ], check=True, capture_output=True)
+    return output_wav
+
+
+def get_ipa(text: str, lang: str = "en") -> str:
+    """Return IPA transcription of text."""
+    result = subprocess.run(
+        ["espeak-ng", "-v", lang, "-q", "--ipa", text],
+        capture_output=True, text=True
+    )
+    return result.stdout.strip()
+```
+
+---
+
+## WAV → MP3 Pipeline
+
+```bash
+# Basic
+ffmpeg -i /tmp/espeak.wav -c:a libmp3lame -b:a 192k /tmp/output.mp3 -y -loglevel quiet
+
+# Enhanced speech quality (cleaner high-mids, reduced low rumble)
+ffmpeg -i /tmp/espeak.wav \
+  -af "aresample=44100,equalizer=f=3000:t=o:w=1:g=3,equalizer=f=200:t=o:w=1:g=-2,loudnorm=I=-16:TP=-1.5:LRA=11" \
+  -c:a libmp3lame -b:a 192k /tmp/output.mp3 -y -loglevel quiet
+```
+
+---
+
+## Multi-voice Script (narrator + character)
+
+```python
+import subprocess, os
+
+def multi_voice_tts(lines: list[dict], output_mp3: str) -> str:
+    """
+    lines = [
+      {"text": "Welcome.", "voice": "en-gb-scotland", "speed": 140},
+      {"text": "Thank you.", "voice": "en-us",         "speed": 160},
+    ]
+    """
+    wavs = []
+    for i, line in enumerate(lines):
+        wav = f"/tmp/mv_{i}.wav"
+        subprocess.run([
+            "espeak-ng",
+            "-v", line.get("voice", "en-gb-scotland"),
+            "-s", str(line.get("speed", 145)),
+            "-p", str(line.get("pitch", 50)),
+            "-w", wav,
+            line["text"]
+        ], check=True, capture_output=True)
+        wavs.append(wav)
+    
+    concat = "/tmp/mv_concat.txt"
+    with open(concat, "w") as f:
+        for wav in wavs:
+            f.write(f"file '{wav}'\n")
+    
+    subprocess.run([
+        "ffmpeg", "-f", "concat", "-safe", "0", "-i", concat,
+        "-c:a", "libmp3lame", "-b:a", "192k",
+        output_mp3, "-y", "-loglevel", "quiet"
+    ], check=True)
+    
+    for wav in wavs:
+        os.unlink(wav)
+    
+    return output_mp3
+```
+
+---
+
+## Useful Tuning Combinations
+
+```bash
+# Natural male English (UK)
+espeak-ng -v en-gb-scotland -s 145 -p 42 -a 110 -w out.wav "Text here"
+
+# Natural female English (RP)
+espeak-ng -v en-gb-x-rp -s 150 -p 62 -a 110 -w out.wav "Text here"
+
+# Russian — clear and measured
+espeak-ng -v ru -s 130 -p 50 -a 120 -w out.wav "Текст здесь"
+
+# Fast technical narration (US English)
+espeak-ng -v en-us -s 175 -p 48 -a 105 -w out.wav "Text here"
+
+# Slow, deliberate presentation voice
+espeak-ng -v en-gb-scotland -s 120 -p 50 -g 8 -a 115 -w out.wav "Text here"
+```

package/src/skills/text-to-speech/references/kokoro-onnx.md

@@ -0,0 +1,124 @@
+# Kokoro ONNX — High-Quality Neural TTS
+
+Kokoro is a state-of-the-art offline neural TTS engine. Produces near-human quality audio.
+Available in this environment (`kokoro-onnx` installed) but requires model files.
+
+## Languages Supported
+
+English (US/UK), Chinese, Japanese, Korean, French, Spanish, Hindi, Portuguese, Italian, Brazilian Portuguese
+
+## Installation
+
+```bash
+pip install kokoro-onnx soundfile --break-system-packages
+```
+
+## Model Download (requires internet once)
+
+```python
+from huggingface_hub import hf_hub_download
+
+# Download model files
+model_path = hf_hub_download(repo_id="hexgrad/Kokoro-82M-ONNX", filename="kokoro-v1.0.onnx")
+voices_path = hf_hub_download(repo_id="hexgrad/Kokoro-82M-ONNX", filename="voices-v1.0.bin")
+
+print(f"Model: {model_path}")
+print(f"Voices: {voices_path}")
+```
+
+Or manually download and place in `/tmp/kokoro/`:
+- `kokoro-v1.0.onnx`
+- `voices-v1.0.bin`
+
+## Usage
+
+```python
+from kokoro_onnx import Kokoro
+import soundfile as sf
+import subprocess
+
+def kokoro_tts(text: str, output_mp3: str, voice: str = 'af_heart', speed: float = 1.0,
+               model_path: str = '/tmp/kokoro/kokoro-v1.0.onnx',
+               voices_path: str = '/tmp/kokoro/voices-v1.0.bin'):
+    """
+    Generate high-quality neural TTS with Kokoro.
+    
+    Voices:
+      English (US): af_heart, af_bella, af_nicole, am_adam, am_michael
+      English (UK): bf_emma, bf_isabella, bm_george, bm_lewis
+      Japanese: jf_nezuko, jf_tsumugi, jm_kumo
+      Chinese: zf_xiaobei, zf_xiaoni, zm_yunjian
+      French: ff_siwis
+      Korean: kf_alpha
+      Spanish: es-419-af-dalia, es-419-am-diego
+      Hindi: hf_alpha, hm_omega
+      Italian: if_sara, im_nicola
+      Brazilian PT: pf_dora, pm_alex
+      Portuguese: ptf_edite
+    """
+    kokoro = Kokoro(model_path, voices_path)
+    
+    samples, sample_rate = kokoro.create(text, voice=voice, speed=speed, lang="en-us")
+    
+    wav_path = output_mp3.replace('.mp3', '.wav')
+    sf.write(wav_path, samples, sample_rate)
+    
+    subprocess.run([
+        'ffmpeg', '-i', wav_path,
+        '-c:a', 'libmp3lame', '-b:a', '192k',
+        output_mp3, '-y', '-loglevel', 'quiet'
+    ], check=True)
+    
+    return output_mp3
+
+# Example
+kokoro_tts(
+    "Welcome to our product demo. This neural TTS produces natural speech.",
+    "/tmp/kokoro_output.mp3",
+    voice="af_heart"
+)
+```
+
+## Language Code Mapping
+
+```python
+KOKORO_LANG = {
+    'en-us': 'en-us',
+    'en-gb': 'en-gb',
+    'ja':    'ja',
+    'zh':    'zh',
+    'fr':    'fr-fr',
+    'ko':    'ko',
+    'es':    'es',
+    'hi':    'hi',
+    'it':    'it',
+    'pt':    'pt-br',
+    'pt-pt': 'pt-pt',
+}
+```
+
+## Caching Model Between Sessions
+
+```python
+import os, shutil
+from pathlib import Path
+
+CACHE_DIR = Path('/home/claude/.kokoro_cache')
+CACHE_DIR.mkdir(exist_ok=True)
+
+MODEL_CACHED = CACHE_DIR / 'kokoro-v1.0.onnx'
+VOICES_CACHED = CACHE_DIR / 'voices-v1.0.bin'
+
+def get_or_download_kokoro():
+    if MODEL_CACHED.exists() and VOICES_CACHED.exists():
+        return str(MODEL_CACHED), str(VOICES_CACHED)
+    
+    from huggingface_hub import hf_hub_download
+    model = hf_hub_download("hexgrad/Kokoro-82M-ONNX", "kokoro-v1.0.onnx")
+    voices = hf_hub_download("hexgrad/Kokoro-82M-ONNX", "voices-v1.0.bin")
+    
+    shutil.copy(model, MODEL_CACHED)
+    shutil.copy(voices, VOICES_CACHED)
+    
+    return str(MODEL_CACHED), str(VOICES_CACHED)
+```

package/src/skills/text-to-speech/references/online-engines.md

@@ -0,0 +1,128 @@
+# Online TTS Engines Reference
+
+Use when internet access is available. Superior quality to offline engines.
+
+## Priority Order
+
+1. **OpenAI TTS** — best quality, via Anthropic API artifacts
+2. **edge-tts** (Microsoft Azure) — free, neural quality, 100+ voices
+3. **gTTS** (Google) — free, good quality, 40+ languages
+
+---
+
+## edge-tts (Microsoft Neural TTS — FREE)
+
+Best free online option. 400+ voices, 100+ languages, neural quality.
+
+```bash
+pip install edge-tts --break-system-packages
+```
+
+```python
+import asyncio
+import edge_tts
+
+async def edge_tts_generate(text: str, output_mp3: str, voice: str = "en-US-AriaNeural"):
+    communicate = edge_tts.Communicate(text, voice)
+    await communicate.save(output_mp3)
+    return output_mp3
+
+# Sync wrapper
+def tts(text: str, output_mp3: str, voice: str = "en-US-AriaNeural"):
+    asyncio.run(edge_tts_generate(text, output_mp3, voice))
+
+# List voices
+async def list_voices():
+    voices = await edge_tts.list_voices()
+    for v in voices:
+        print(v['ShortName'], v['Locale'], v['Gender'])
+```
+
+### Recommended Voices
+
+```python
+EDGE_VOICES = {
+    'en-us-f': 'en-US-AriaNeural',      # US English, female, natural
+    'en-us-m': 'en-US-GuyNeural',       # US English, male
+    'en-gb-f': 'en-GB-SoniaNeural',     # UK English, female
+    'ru-f':    'ru-RU-SvetlanaNeural',  # Russian, female
+    'ru-m':    'ru-RU-DmitryNeural',    # Russian, male
+    'de-f':    'de-DE-KatjaNeural',     # German
+    'fr-f':    'fr-FR-DeniseNeural',    # French
+    'es-f':    'es-ES-ElviraNeural',    # Spanish
+    'zh-f':    'zh-CN-XiaoxiaoNeural',  # Chinese
+    'ja-f':    'ja-JP-NanamiNeural',    # Japanese
+    'ar-f':    'ar-EG-SalmaNeural',     # Arabic
+    'hi-f':    'hi-IN-SwaraNeural',     # Hindi
+    'ko-f':    'ko-KR-SunHiNeural',     # Korean
+    'pt-f':    'pt-BR-FranciscaNeural', # Portuguese
+    'it-f':    'it-IT-ElsaNeural',      # Italian
+    'nl-f':    'nl-NL-ColetteNeural',   # Dutch
+    'pl-f':    'pl-PL-AgnieszkaNeural', # Polish
+}
+```
+
+---
+
+## gTTS (Google Text-to-Speech — FREE)
+
+```bash
+pip install gtts --break-system-packages
+```
+
+```python
+from gtts import gTTS
+import subprocess
+
+def gtts_generate(text: str, output_mp3: str, lang: str = 'en', slow: bool = False):
+    tts = gTTS(text=text, lang=lang, slow=slow)
+    tts.save(output_mp3)
+    return output_mp3
+
+# Language codes: 'en', 'ru', 'de', 'fr', 'es', 'zh-CN', 'ja', 'ko', 'ar', 'hi', etc.
+```
+
+---
+
+## OpenAI TTS (via API — best quality)
+
+Use when building Claude-powered artifacts. Call from JavaScript in artifacts:
+
+```javascript
+// In artifact — OpenAI TTS via fetch
+const response = await fetch("https://api.openai.com/v1/audio/speech", {
+  method: "POST",
+  headers: {
+    "Authorization": `Bearer ${OPENAI_KEY}`,
+    "Content-Type": "application/json"
+  },
+  body: JSON.stringify({
+    model: "tts-1-hd",  // or "tts-1" for faster/cheaper
+    input: "Your text here",
+    voice: "alloy",     // alloy, echo, fable, onyx, nova, shimmer
+    response_format: "mp3"
+  })
+});
+const audioBlob = await response.blob();
+const url = URL.createObjectURL(audioBlob);
+// play or download
+```
+
+### OpenAI Voice Options
+- `alloy` — neutral, versatile
+- `echo` — male, calm
+- `fable` — British male, expressive
+- `onyx` — deep male
+- `nova` — female, warm
+- `shimmer` — female, clear
+
+---
+
+## Choosing Between Engines
+
+```
+Need best quality? → OpenAI TTS (if API key available)
+Free + neural quality? → edge-tts (Microsoft Neural)
+Simple + multilingual? → gTTS
+No internet? → Kokoro ONNX (if models available) or pyttsx3
+```

package/src/skills/text-to-speech/references/pyttsx3-espeak.md

@@ -0,0 +1,143 @@
+# pyttsx3 + espeak-ng Reference
+
+Primary TTS engine for this environment. Fully offline, 131+ languages.
+
+## Full API
+
+```python
+import pyttsx3
+
+engine = pyttsx3.init()
+
+# Properties
+engine.setProperty('rate', 145)      # words per minute (100–200, default 200)
+engine.setProperty('volume', 1.0)    # 0.0–1.0
+# Note: 'pitch' property is accepted but has no effect in espeak backend
+
+# List all voices
+voices = engine.getProperty('voices')
+for v in voices:
+    print(v.id, v.name, v.languages)
+
+# Set a specific voice
+engine.setProperty('voice', 'gmw/en-gb-scotland')
+
+# Speak (blocking, uses system audio — not useful in agent)
+# engine.say("Hello"); engine.runAndWait()
+
+# Save to file (USE THIS in agent context)
+engine.save_to_file("Text to speak", '/tmp/output.wav')
+engine.runAndWait()
+```
+
+## Recommended Voice IDs per Language
+
+```python
+VOICE_MAP = {
+    'en':    'gmw/en-gb-scotland',  # clearest English
+    'en-us': 'gmw/en-us',
+    'ru':    'zle/ru',
+    'de':    'gmw/de',
+    'fr':    'roa/fr',
+    'es':    'roa/es',
+    'it':    'roa/it',
+    'pt':    'roa/pt-pt',
+    'nl':    'gmw/nl',
+    'pl':    'zls/pl',
+    'cs':    'zlw/cs',
+    'zh':    'sit/cmn',
+    'ja':    'jpn/ja',
+    'ko':    'ko',
+    'ar':    'sem/ar',
+    'hi':    'inc/hi',
+    'tr':    'trk/tr',
+    'sv':    'gmw/sv',
+    'da':    'gmw/da',
+    'fi':    'urj/fi',
+    'uk':    'zle/uk',
+}
+```
+
+## Quality Optimization
+
+```python
+def high_quality_tts(text: str, out_wav: str, lang: str = 'en', rate: int = 145):
+    import pyttsx3, subprocess
+    
+    engine = pyttsx3.init()
+    engine.setProperty('rate', rate)
+    engine.setProperty('volume', 1.0)
+    
+    voice_id = VOICE_MAP.get(lang, f'gmw/{lang}')
+    voices = engine.getProperty('voices')
+    matched = next((v for v in voices if v.id == voice_id), None)
+    if matched:
+        engine.setProperty('voice', matched.id)
+    
+    engine.save_to_file(text, out_wav)
+    engine.runAndWait()
+    
+    # Enhance with FFmpeg: resample to 44.1kHz + EQ for speech clarity
+    enhanced = out_wav.replace('.wav', '_enhanced.wav')
+    subprocess.run([
+        'ffmpeg', '-i', out_wav,
+        '-af', 'aresample=44100,equalizer=f=3000:t=o:w=1:g=3,equalizer=f=200:t=o:w=1:g=-2,loudnorm=I=-16:TP=-1.5:LRA=11',
+        enhanced, '-y', '-loglevel', 'quiet'
+    ], check=True)
+    
+    return enhanced
+```
+
+## Paragraph-by-Paragraph Generation
+
+For long texts, generate in chunks to avoid engine timeouts:
+
+```python
+def tts_long_text(paragraphs: list[str], output_mp3: str, lang: str = 'en'):
+    import pyttsx3, subprocess, os
+    
+    chunks = []
+    engine = pyttsx3.init()
+    engine.setProperty('rate', 145)
+    
+    for i, para in enumerate(paragraphs):
+        if not para.strip():
+            continue
+        wav = f'/tmp/chunk_{i}.wav'
+        engine.save_to_file(para, wav)
+        engine.runAndWait()
+        chunks.append(wav)
+    
+    # Add 0.3s pause between paragraphs
+    concat_list = '/tmp/tts_concat.txt'
+    with open(concat_list, 'w') as f:
+        for wav in chunks:
+            f.write(f"file '{wav}'\n")
+    
+    subprocess.run([
+        'ffmpeg', '-f', 'concat', '-safe', '0', '-i', concat_list,
+        '-c:a', 'libmp3lame', '-b:a', '192k',
+        output_mp3, '-y', '-loglevel', 'quiet'
+    ], check=True)
+    
+    # Cleanup
+    for wav in chunks:
+        os.unlink(wav)
+    
+    return output_mp3
+```
+
+## Getting Audio Duration
+
+```python
+import subprocess, json
+
+def get_audio_duration(path: str) -> float:
+    """Returns duration in seconds."""
+    result = subprocess.run([
+        'ffprobe', '-v', 'quiet', '-print_format', 'json',
+        '-show_format', path
+    ], capture_output=True, text=True)
+    data = json.loads(result.stdout)
+    return float(data['format']['duration'])
+```