manual-prosody-addition

Manual Prosody Addition

Translate freeform user notes about pacing, emphasis, character delivery, and emotion into engine-specific markup. Claude locates targets in the source and applies appropriate tags (SSML by default, or ElevenLabs if configured), while documenting every interpretation.

When to use

• You have a script and freeform prose notes on how it should sound (e.g., "this character is angry here", "pause before the punchline")
• You want markup that respects your script intent without writing XML/tags yourself
• You need the engine-specific flavour (SSML vs. ElevenLabs) to be applied automatically based on your preference

Inputs to gather

• Source text file (path)
• Prosody notes as freeform text (e.g., "paragraph 2: make soft and contemplative", "the word 'explosion' at line 15 should be emphatic")
• Optional: working directory for output (defaults to source file's parent)
• Engine preference will be loaded from config.json if it exists; if missing, ask the user (SSML is the default)

Procedure

1. Read ${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/text-to-speech-toolkit/config.json if it exists. Extract default_engine. If missing, assume SSML; optionally ask the user.
2. Read the source text file and validate encoding.
3. Parse the user's prosody notes and identify targets:
   • Location cues: "paragraph 2", "line 15", "the word 'explosion'", section names
   • Delivery cues: "soft", "emphatic", "angry", "contemplative", "whispered", "excited"
   • Structure cues: "new section", "pause", "long silence" Locate each target in the source text precisely (report line numbers or excerpt context).
4. Map delivery cues to engine-specific markup:
   • SSML: "soft" → <prosody volume="-20dB">, "emphatic" → <emphasis level="strong">, "whispered" → <prosody pitch="-50%">, "excited" → <prosody rate="120%" pitch="+20%">, pauses → <break time="..."/>
   • ElevenLabs: "soft" → [whispers] or reduce capitalisation, "emphatic" → Capitalise key words, "whispered" → [whispers], "excited" → Capitalise, add [excited] audio tag, pauses → em-dash or ellipsis
5. Create <workdir>/original/ and copy the source file unchanged.
6. Create <workdir>/edited/ and write the marked-up output. Output filename: <source-stem>.ssml.xml (SSML) or <source-stem>.elevenlabs.txt (ElevenLabs).
7. Produce a decisions log (markdown) showing:
   • Each user note and its target location
   • The markup generated
   • Any ambiguities or alternative interpretations considered

Output / side effects

• <source-stem>.ssml.xml or <source-stem>.elevenlabs.txt in <workdir>/edited/ — marked-up script ready for TTS, engine flavour determined by config
• <source-stem>.decisions.md — interpretation log showing how each prosody note was mapped to markup
• Original source file preserved in <workdir>/original/

Safety / constraints

Non-destructive editing (brand rule): Never overwrite the user's source file. Always create original/ and edited/ subdirectories in the working directory. Default <workdir> to the source file's parent directory; allow the user to override.

Config-priming: Before applying any markup, read config.json and use default_engine to prime the engine flavour. If the file is missing or default_engine is unset, behave engine-agnostic (ask or default to SSML).

Ambiguous targets: If a user note is vague (e.g., "make it better"), ask for clarification. Do not guess. If a location target is ambiguous (multiple matches), list candidates and ask the user to disambiguate.

Preserve tone: Respect the user's intent. If a note says "soft", don't add emphasis elsewhere. Document any artistic choices you make.