elevenlabs-conversion

name	elevenlabs-conversion
description	Convert text into ElevenLabs-flavoured markup using their official prompting standard, grounded in live documentation. Non-destructive: writes to edited/ alongside original/.

ElevenLabs Conversion

Transform plain text into ElevenLabs-optimised markup by applying their official prompting conventions: audio tags, pacing punctuation, emphasis capitalisation, and quote styling. Fetches live ElevenLabs docs at runtime to ensure conversions follow current best practices.

When to use

• You target ElevenLabs TTS and want optimal voice response to pacing, emotion, and delivery cues
• You have a script that needs audio-descriptive tags (laughter, whispers, sighs) or pacing hints
• You want markup grounded in current ElevenLabs guidance, not training data

Inputs to gather

• Source text file (path)
• Optional: working directory for output (defaults to source file's parent)
• Optional: target voice or emotion context (e.g., "narrator", "excited", "somber") to inform tag choices

Procedure

1. Fetch live ElevenLabs documentation:
   • https://elevenlabs.io/docs/best-practices/prompting
   • https://elevenlabs.io/docs/capabilities/text-to-speech Scan for current conventions on audio tags, pacing, capitalisation, and punctuation.
2. Read the source text file and validate encoding.
3. Create <workdir>/original/ and copy the source file unchanged.
4. Apply ElevenLabs conventions to a copy:
   • Audio tags: Insert [laughs], [whispers], [sighs], [breathes] where tone/delivery cues appear in the text.
   • Pacing: Use em-dashes and ellipses (already present or inferred) for natural pauses; do not add extra breaks.
   • Emphasis: Capitalise key words or phrases sparingly (not ALL-CAPS shouting) to signal emphasis.
   • Quote styling: Maintain or standardise quote marks; ElevenLabs responds well to consistent paired quotes.
   • Abbreviations: Spell out sparingly; keep natural speech patterns.
5. Create <workdir>/edited/ and write the converted text there.
6. Output filename: <source-stem>.elevenlabs.txt
7. Produce a decisions log (markdown) noting which tags were added, which pacing cues were inferred, and any voice-sensitivity flags (e.g., "this voice may not respond to [whispers] as expected").

Output / side effects

• <source-stem>.elevenlabs.txt in <workdir>/edited/ — plain text with ElevenLabs markup, ready for API or web interface
• <source-stem>.decisions.md — explains tag choices, pacing decisions, and voice-specific caveats
• 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.

Live grounding: Always fetch ElevenLabs docs before converting. Do not rely solely on training data; ElevenLabs conventions evolve. Flag any conflicts between live docs and your inference.

Voice variability note: ElevenLabs voices respond differently to audio tags and emphasis. Flag in the decisions log which tags may have inconsistent results across voices.