voice-dna-narrate

name	voice-dna-narrate
description	Generate local zero-shot narration from a locked voice DNA ref - beat mode or picture-timed cues with silence. Identity-safe (no pitch/tempo stacks). Part of Voice DNA Studio by Navid Taheri / Navid AI ToolBox.

Voice DNA Narrate (public skill)

Use when the user has a locked DNA ref and wants spoken VO:

• beats: natural explainer pacing with pauses
• timed: cues aligned to video actions + silence gaps (editor adds music)

Identity rules

1. Always pass the locked audio_prompt_path / --ref.
2. Use frozen exaggeration / cfg_weight / temperature from the lock.
3. No pitch, tempo, or proximity character FX.
4. Emphasis = optional later volume rides only.
5. Resume from chunk files after interrupt; do not wipe chunks mid-job.
6. Separate chunks_<job>/ per job/speaker - never mix.

Beat mode

Script: short spoken lines; blank lines = thought boundaries.

cd "$VOICE_DNA_ROOT"
source .venv/Scripts/activate

python -m voice_dna_studio narrate \
  --mode beats \
  --script path/to/script.txt \
  --ref workspace/voices/<slug>/<Name-N>/ref/ref_<Name-N>.wav \
  --chunks workspace/chunks/<job> \
  --out-wav workspace/out/<job>.wav \
  --out-mp3 workspace/out/<job>.mp3 \
  --exaggeration 0.36 --cfg-weight 0.62 --temperature 0.58

Timed / picture-lock mode

Script lines: START_SEC | short cue

python -m voice_dna_studio narrate \
  --mode timed \
  --script path/to/timed.txt \
  --ref workspace/voices/<slug>/<Name-N>/ref/ref_<Name-N>.wav \
  --chunks workspace/chunks/<job>_timed \
  --video-dur 848.221 \
  --out-wav workspace/out/<job>_timed.wav \
  --out-mp3 workspace/out/<job>_timed.mp3 \
  --cue-map workspace/out/<job>_CUE_MAP.csv \
  --exaggeration 0.36 --cfg-weight 0.62 --temperature 0.58

Rules:

• Place speech at action starts; silence while work happens
• If overrun, push next cue - never time-stretch speech
• Deliver audio duration ≈ video duration + cue map

Long runs

• background=true + notify when driving from an agent
• Free GPU VRAM before model load
• Resume is automatic via contiguous beat_XXX / u_XXX files

Delivery checklist

• ffprobe duration
• absolute output paths
• params + ref name labeled
• cue map if timed
• confirm no pitch/tempo processing was applied

Anti-patterns

• Back-to-back VO on a long silent tutorial when picture timing was requested
• Deleting chunks after natural stitch but before a peaks/remix pass (if used)
• Starting a second full model load beside a live generate on 8 GB GPUs