local-voice/docs/DONNA_DEPENDENCY.md

Donna integration contract

Donna remains responsible for collecting organizational information, deciding priority, selecting a character, and writing the final canonical script. Local Voice is an optional audio dependency responsible for rendering and validating that script.

Invocation

Donna supplies:

• voice profile ID;
• canonical Markdown or Ryan-labelled dialogue;
• absolute output path;
• pronunciation overrides when needed;
• optional delivery, role, signature-asset, and pause metadata.

Donna then asks Local Voice to:

1. run doctor if runtime health is unknown;
2. build or validate the render plan;
3. render with --resume;
4. return the final audio and QA-report paths.

Required behavior

• Do not send Markdown headings, numbered section titles, speaker labels, or stage directions as spoken text.
• Keep greetings and closings as short standalone paragraphs so Local Voice can preserve native tempo.
• Keep substantive paragraphs to complete sentence groups of roughly 20–42 words unless a profile specifies otherwise.
• Use canonical text for the written brief and tts_text only for local pronunciation corrections.
• Do not silently fall back to ElevenLabs. If Local Voice fails, Donna should report the failure and apply the caller's configured fallback policy.
• Attach or link the final audio alongside the full written organizational brief; the audio is a quick summary, not the sole record.

Character mapping

Donna character	Local Voice profile
Production Donna	donna
Chris Engineer	chris-engineer
Grandpa Bomber	grandpa-bomber
Pitch Meeting	ryan-pitch-meeting
Val Holiday	val-holiday

Example handoff

{
  "voice": "val-holiday",
  "script": "/absolute/path/val-brief.md",
  "output": "/absolute/path/val-brief.mp3",
  "fallback": "report-and-return-text"
}

Local Voice returns the final audio path, QA report path, duration, and segment-level completeness and cadence results.