Metadata-Version: 2.4
Name: xil-pipeline
Version: 0.1.0
Summary: Show-agnostic audio production pipeline: markdown script to podcast-ready MP3 via ElevenLabs
Project-URL: Repository, https://github.com/xilcmd/xil-pipeline
Project-URL: Issues, https://github.com/xilcmd/xil-pipeline/issues
Author-email: John Brissette <xilcmd@gmail.com>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: audio,elevenlabs,podcast,production-pipeline,text-to-speech,tts
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.12
Requires-Dist: audioop-lts>=0.2.1; python_version >= '3.13'
Requires-Dist: elevenlabs<3,>=2.38
Requires-Dist: httpx>=0.27
Requires-Dist: mutagen>=1.47
Requires-Dist: pydantic<3,>=2.0
Requires-Dist: pydub<1,>=0.25
Provides-Extra: all
Requires-Dist: google-genai<2,>=1.60; extra == 'all'
Requires-Dist: gtts<3,>=2.5; extra == 'all'
Requires-Dist: ollama<1,>=0.6; extra == 'all'
Requires-Dist: pyttsx3<3,>=2.99; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-cov<8,>=7.0; extra == 'dev'
Requires-Dist: pytest<10,>=9.0; extra == 'dev'
Requires-Dist: ruff>=0.15; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-autorefs>=1.4; extra == 'docs'
Requires-Dist: mkdocs-awesome-pages-plugin>=2.10; extra == 'docs'
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
Requires-Dist: pymdown-extensions>=10.16; extra == 'docs'
Provides-Extra: google
Requires-Dist: google-genai<2,>=1.60; extra == 'google'
Provides-Extra: ollama
Requires-Dist: ollama<1,>=0.6; extra == 'ollama'
Provides-Extra: tts-alt
Requires-Dist: gtts<3,>=2.5; extra == 'tts-alt'
Requires-Dist: pyttsx3<3,>=2.99; extra == 'tts-alt'
Description-Content-Type: text/markdown

# 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

```bash
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

```bash
# Scaffold a new project workspace
xil-init my-show --show "My Podcast"
cd my-show

# Scan the sample script (pre-flight check)
xil-scan scripts/sample_S01E01.md

# Parse into structured JSON
xil-parse scripts/sample_S01E01.md --episode S01E01

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

# Generate voice and SFX stems (requires ELEVENLABS_API_KEY)
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 THE 413)
- **`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"`.

## Environment

- Python 3.12+
- ElevenLabs API key via `ELEVENLABS_API_KEY` environment variable
- `ffmpeg` required for audio processing (pydub dependency)

## Development

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

## License

AGPL-3.0 — see [LICENSE](LICENSE) for details.
