Save a voice profile from a reference audio (5-30s WAV ideal).

Two input modes (EITHER ref_audio_path OR audio_url must be provided, not both): A) Local file: pass ref_audio_path='/path/to/sample.wav'. B) URL clip: pass audio_url='https://youtu.be/...', ts=30, tf=45. yt-dlp downloads the audio and ffmpeg slices [ts, tf] into a 24kHz mono 16-bit PCM WAV, which is then used as the reference.

Workflow:

1. Pick a clean 5-30s speech sample (local file OR URL clip).

2. Write the exact transcript in ref_text.

3. Pick a memorable voice_name (used later as voice_name= in synthesize_speech).

4. Returns a dict with 'status', 'voice_name', 'profile_path', 'ref_audio_path', and (for URL mode) 'source_url', 'ts', 'tf', 'clip_duration_s'.

Common errors:

• both ref_audio_path and audio_url provided: pick one.

• voice_exists: pass overwrite=True or pick a different voice_name.

• bad local path: check the path exists and is readable.

• bad URL: yt-dlp/ffmpeg failure will be reported in the raised RuntimeError.

Generate speech audio with a cloned voice (from voice_name) OR voice design (from instruct), or both.

Three usage modes:

1. Cloned voice: pass voice_name='claudia_asmr', omit instruct.

2. Voice design: pass instruct='whisper, female, low pitch', omit voice_name.

3. Hybrid: pass both voice_name AND instruct to add style to a cloned voice.

Returns dict with: output_path, duration_s, sample_rate, channels, model, voice_name, generation_time_s, and (if any ASMR effect ran) asmr_applied.

ASMR pipeline: highpass(60Hz) -> lowpass -> stereo_pan -> reverb -> binaural -> padding. All ASMR params default to OFF (passthrough). Output is stereo whenever any stereo-capable effect (stereo_pan, reverb, binaural_beat_hz) is active.

Generate speech using voice design keywords only (no cloned voice).

Same ASMR params as synthesize_speech. Use this when you want a one-off voice without persisting a profile. For reusable voices, clone first with clone_voice_from_audio then call synthesize_speech with voice_name.

List all saved voice profiles.

Returns: list of dicts, each with 'name', 'description', 'language', 'source', 'created_at'. Use this to discover available voice_name values before calling synthesize_speech.

Get full metadata of a single saved voice profile: name, description, language, ref_audio_path, ref_text, created_at.

Use this to verify a profile exists and inspect its reference audio path before calling synthesize_speech with that voice_name.

Delete a voice profile and its reference audio file. Cannot be undone.

Use this to free disk space or clean up test voices. The voice will no longer appear in list_voices and synthesize_speech with this voice_name will fail.