xil-pipeline 0.1.8

Show-agnostic audio production pipeline: markdown script to podcast-ready MP3 via ElevenLabs

xil-pipeline

Show-agnostic audio production pipeline that turns a markdown script into a podcast-ready MP3 via the ElevenLabs API.

A project.json file sets the show name; every script derives file paths from it via a shared slug. The pipeline parses scripts, generates TTS voices and SFX, assembles a rough master, exports isolated WAV layers for DAW mixing, and produces a final master MP3. Supporting utilities handle voice discovery, SFX generation, stem migration on script revisions, stale cleanup, and Studio import/export. All API-calling scripts support --dry-run to preview costs before spending quota.

Installation

pip install xil-pipeline            # core dependencies
pip install xil-pipeline[all]       # all optional backends (Google GenAI, gTTS, Ollama)
pip install xil-pipeline[dev]       # development and testing

Quick Start

See samples/Tech_Deep_Dive_S01E04.md for an example of the markdown script format the pipeline expects. It demonstrates dialogue, acting directions, SFX/ambience/music cues, beats, sections, and scenes. samples/S01E04_techdeepdive_2026-04-02.mp3 is the rendered output — a two-host tech podcast segment generated entirely from that script.

# Scaffold a new project workspace (creates a copy of the sample script)
xil-init my-show --show "My Podcast"
cd my-show

# Scan the sample script (pre-flight check)
# Always run scan before parse when onboarding a new episode — it will catch
# unrecognized speakers before they silently disappear from the parsed output.
xil-scan scripts/sample_S01E01.md --speakers configs/my-show/speakers.json

# Parse into structured JSON
xil-parse scripts/sample_S01E01.md --episode S01E01 --speakers configs/my-show/speakers.json

# Preview TTS character cost (no API calls)
xil-produce --episode S01E01 --dry-run

# Generate voice and SFX stems (requires ELEVENLABS_API_KEY — see Environment below)
xil-produce --episode S01E01

# Export DAW layers for mixing in Audacity
xil-daw --episode S01E01

# Produce final master MP3
xil-master --episode S01E01

Pipeline Stages

Command	Script	Description
xil-init	xil_init	Scaffold a new project workspace
xil-scan	XILP000	Pre-flight script scanner
xil-parse	XILP001	Markdown script parser
xil-produce	XILP002	Voice + SFX generation (ElevenLabs API)
xil-assemble	XILP003	Two-pass audio assembly
xil-studio	XILP004	ElevenLabs Studio project onboarding
xil-daw	XILP005	DAW layer export (4 WAVs for Audacity)
xil-cues	XILP006	Sound cues sheet ingester
xil-migrate	XILP007	Stem migrator for script revisions
xil-cleanup	XILP008	Stale stem cleanup
xil-regen	XILP009	Reverse script generator
xil-import	XILP010	ElevenLabs Studio export importer
xil-master	XILP011	Final master MP3 export

Utilities

Command	Script	Description
xil-voices	XILU001	Voice discovery and audition
xil-sfx	XILU002	Standalone SFX generation
xil-csv-join	XILU003	CSV + SFX/cast annotation
xil-sample	XILU004	Voice sample generator
xil-sfx-lib	XILU005	SFX library discovery
xil-splice	XILU006	Parsed JSON splice utility

Configuration

• project.json -- show name (derives all file paths via slug)
• speakers.json -- speaker names the parser recognizes (optional, built-in defaults for sample)
• cast_<slug>_<TAG>.json -- voice assignments, speaker settings
• sfx_<slug>_<TAG>.json -- sound effect mappings and API parameters

All scripts accept --show to override the show name. Resolution order: --show flag > project.json > default "sample".

Episode tag formats

The <TAG> portion of all file and directory names supports any string. Use --episode for standard episodic content or --tag for non-episodic formats:

Content type	Tag format	Examples	Notes
Podcast episode	S01E04	S02E11, S03E01	Default — derived from script header
Audiobook chapter	V01C03	V01C01–V01C20	Volume + Chapter; use --tag V01C03 with xil-parse
Drama short	S01D01	S01D03	Season + Drama number; or just use S01E01
Standalone one-shot	E01	E01–E99	No season prefix; standard --episode E01 works
Bonus / special	BONUS01	TRAILER, BONUS02	Any string via --tag; use uppercase by convention

Episodic tags (S01E04, E01) are derived automatically from the script header. All other formats require --tag on xil-parse:

xil-parse scripts/gatsby_V01C03.md --tag V01C03
xil-produce --episode V01C03 --dry-run
xil-daw --episode V01C03

Stems are stored under stems/<slug>/<TAG>/, so multiple shows and tag formats coexist safely in one workspace.

See the SFX Reuse Guide for workflows that minimize ElevenLabs API credit usage by referencing existing assets in the SFX/ library.

Environment

• Python 3.12+
• ffmpeg required for audio processing (pydub dependency)

ElevenLabs API Key

Several pipeline commands call the ElevenLabs API and require an API key:

Commands	Requires key
xil-produce, xil-sfx, xil-studio, xil-sample, xil-cues --generate	Yes
All other commands (xil-scan, xil-parse, xil-daw, xil-master, etc.)	No

Obtain a key: https://elevenlabs.io → Profile → API Keys

Set for the current shell session:

export ELEVENLABS_API_KEY=your_key_here

Persist it (add to ~/.bashrc or ~/.zshrc):

echo 'export ELEVENLABS_API_KEY=your_key_here' >> ~/.bashrc
source ~/.bashrc

Verify it is set:

echo $ELEVENLABS_API_KEY

Always use --dry-run first to preview character cost before making API calls.

Man Pages

Man pages for all 19 commands are included in the package and installed automatically with pip install.

Enable man pages after pip install --user

Pages land in ~/.local/share/man/man1/. Add this line to ~/.bashrc (or ~/.profile on Debian):

export MANPATH="$HOME/.local/share/man:$(manpath 2>/dev/null)"

Then reload your shell and use man normally:

source ~/.bashrc
man xil-parse
man xil-produce
man xil           # overview of all commands

For apropos / whatis support, update the man database once:

mandb --user-db ~/.local/share/man

System-wide installs (sudo pip install)

Pages land in /usr/local/share/man/man1/ which is indexed by default. Run sudo mandb to refresh if pages don't appear immediately.

Development

git clone <repo-url>
cd xil-pipeline
pip install -e ".[all,dev]"
pytest tests/ -v

License

AGPL-3.0 — see LICENSE for details.