| name | podcast-audio-plan |
| description | Generate audio and transcripts for podcast episodes from Fountain screenplays using Produciesta CLI. When asked to "generate podcast audio", "create audio plan", "cast voices", "prepare transcripts", or working with podcast projects that have episodes/*.fountain files, this skill analyzes characters, assigns voices, writes PROJECT.md cast list, generates audio, and prepares transcripts for web deployment. |
Podcast Audio Generation with Produciesta
Generate professional podcast audio from Fountain screenplay files using Claude-assisted voice casting and Produciesta CLI generation.
When to Use This Skill
Use this skill when:
- User asks to generate audio for a podcast project
- Project has episode scripts in Fountain format (
episodes/*.fountain)
- User wants to create or update a cast list in PROJECT.md
- User asks to "cast voices", "assign voices", "plan audio generation"
- User wants to generate audio from screenplays
What This Skill Does
This skill provides a Claude-assisted workflow for podcast audio generation and web publishing:
- Analyze Fountain files to extract character list
- Query available voices from Apple TTS or ElevenLabs
- Match characters to voices based on character traits and voice characteristics
- Write PROJECT.md with proper YAML front matter and cast list
- Generate audio using Produciesta CLI
- Commit audio to Git LFS and verify CDN availability
- Copy transcripts to website episodes directory
- Update website page with CDN links, metadata, and RSS feed
- Validate deployment (subscribe links, playback, transcripts)
- Deploy to production via git push
Prerequisites
Required Tools
- Produciesta CLI at
~/Projects/Produciesta/produciesta-cli/
- Swift 6.2+ (for building Produciesta if needed)
- Xcode 16+ (macOS only)
- Apple TTS (built-in macOS) or ElevenLabs API key
Project Structure
Podcast Source Repository (Produciesta project):
~/podcast-daily-dao/
├── PROJECT.md # Project configuration (Claude creates this)
├── episodes/ # Fountain screenplay files (source)
│ ├── chapter-01.fountain
│ ├── chapter-02.fountain
│ └── ...
├── audio/ # Generated audio files (Git LFS)
│ ├── chapter-01.m4a
│ ├── chapter-02.m4a
│ └── ...
└── .gitattributes # LFS configuration for *.m4a files
Website Repository (intrusive-memory.github.com):
~/Projects/intrusive-memory.github.com/podcasts/daily-dao/
├── index.html # Podcast player page
├── feed.xml # RSS feed
├── podcast-artwork.jpg # Cover art (3000x3000)
├── favicon.ico
├── apple-touch-icon.png
├── episodes/ # Transcripts (copied from source)
│ ├── chapter-01.fountain
│ ├── chapter-02.fountain
│ └── ...
└── audio/ # Placeholder or symlink (audio served from CDN)
Critical Separation:
- Source repo: Where audio is generated and stored (Git LFS)
- Website repo: Where podcast page lives and references CDN URLs
- CDN: Cloudflare R2 serves audio via
https://pub-8e049ed02be340cbb18f921765fd24f3.r2.dev/
Voice Casting Workflow (Claude-Assisted)
IMPORTANT: Produciesta's --autocast feature is currently not working. Instead, use Claude to create the cast list manually.
Step 1: Discover Episodes and Extract Characters
ls episodes/*.fountain
cat episodes/chapter-01.fountain
Claude will:
- Read Fountain files to identify all CHARACTER names
- Analyze dialogue to understand character traits (age, gender, personality)
- Build a comprehensive character list
Step 2: Query Available Voices
For Apple TTS:
say -v '?'
For ElevenLabs:
Claude will:
- Parse available voices and their characteristics
- Note voice IDs, names, languages, and qualities
Step 3: Match Characters to Voices
Claude will:
- Consider character traits from dialogue analysis
- Match each character to the most appropriate voice
- Provide primary and fallback voice options
- Explain the reasoning for each assignment
Step 4: Create or Update PROJECT.md
Claude will:
- Create PROJECT.md with proper YAML front matter
- Write the cast list with voice URIs
- Include episode count and configuration
- Add production notes for documentation
Example PROJECT.md:
---
type: project
title: My Podcast Series
author: Author Name
description: Description of the podcast
episodesDir: episodes
audioDir: audio
filePattern: "*.fountain"
exportFormat: m4a
cast:
- character: NARRATOR
voices:
- apple://com.apple.voice.premium.en-US.Aaron
- character: ALICE
voices:
- apple://com.apple.voice.premium.en-US.Ava
- character: BOB
voices:
- apple://com.apple.voice.premium.en-US.Daniel
---
- NARRATOR: Aaron (mature, authoritative voice)
- ALICE: Ava (young female, clear diction)
- BOB: Daniel (British accent, professional tone)
- 10 episodes in Fountain format
- Generated audio saved to `audio/` directory
- Format: M4A (Apple AAC)
Step 5: Generate Audio with Produciesta
produciesta /path/to/project --format m4a --verbose
What happens:
- ✅ Produciesta reads PROJECT.md cast list
- ✅ Parses Fountain files and resolves character voices
- ✅ Generates audio for all episodes
- ✅ Saves M4A files to
audio/ directory
Voice Providers
Apple Neural TTS (Free)
Advantages:
- No API key required
- Premium voices included with macOS
- Fast, local processing
- No per-character costs
Best for: English podcasts, quick testing, budget projects
Query voices:
say -v '?'
Voice URI format:
apple://com.apple.voice.premium.en-US.Aaron
Popular voices:
- Aaron - Mature male, US accent
- Ava - Young female, US accent, clear
- Daniel - Male, British accent
- Samantha - Female, US accent, warm
- Fred - Male, novelty voice
- Zoe - Female, US accent, professional
ElevenLabs (Paid)
Advantages:
- Extremely natural-sounding voices
- Multilingual support
- Professional quality
- Emotion control
Best for: Professional production, non-English podcasts, high-quality output
Setup:
export ELEVENLABS_API_KEY="your-key-here"
Voice URI format:
elevenlabs://21m00Tcm4TlvDq8ikWAM
Popular voices:
21m00Tcm4TlvDq8ikWAM - Rachel (US female)EXAVITQu4vr4xnSDxMaL - Bella (US female)pNInz6obpgDQGcFmaJgB - Adam (US male)ErXwobaYiN019PkySvjV - Antoni (male, well-rounded)MF3mGyEYCl7XYWbV9V6O - Elli (young female)
Complete End-to-End Publishing Workflow
This is the complete workflow from .fountain files to live podcast on intrusive-memory.productions.
Prerequisites Checklist
Before starting, verify:
Scenario: Publishing Daily Dao Episodes 1-5
Variables for this example:
- Source repo:
~/podcast-daily-dao/
- Website repo:
~/Projects/intrusive-memory.github.com/
- Podcast slug:
daily-dao
- Audio path on CDN:
daily-dao/ (matches slug)
PHASE 1: Audio Generation (Source Repo)
Step 1: Analyze Episodes and Extract Characters
cd ~/podcast-daily-dao
ls episodes/*.fountain
Claude reads sample episodes and identifies:
- NARRATOR - Reads verses and commentary
Step 2: Query Available Voices
say -v '?'
Claude selects:
- NARRATOR → Aaron (mature, contemplative tone)
Step 3: Create PROJECT.md
---
type: project
title: Daily Dao - Tao De Jing Podcast
author: Tom Stovall
description: Daily readings from the Tao Te Ching with commentary
episodesDir: episodes
audioDir: audio
filePattern: "*.fountain"
exportFormat: m4a
cast:
- character: NARRATOR
voices:
- apple://com.apple.voice.premium.en-US.Aaron
---
- NARRATOR: Aaron - Mature, authoritative voice appropriate for philosophical content
- Episodes 1-5 of the Tao Te Ching
- Each episode: ~4-6 minutes
Step 4: Generate Audio Files
produciesta . --format m4a --verbose
Output:
✓ Project directory: /Users/stovak/podcast-daily-dao
✓ Found 5 episodes
✓ Cast list loaded: 1 character
✓ Starting generation...
Episode 1/5: chapter-01.fountain
Parsing... ✓ 15 elements
Generating... ✓ 100%
Exporting... ✓ chapter-01.m4a (3.8 MB, 4m 45s)
[... episodes 2-4 ...]
Episode 5/5: chapter-05.fountain
Parsing... ✓ 14 elements
Generating... ✓ 100%
Exporting... ✓ chapter-05.m4a (3.5 MB, 4m 22s)
✓ Generation complete!
Processed: 5 episodes
Duration: 23m 12s total
Output: ~/podcast-daily-dao/audio/
Step 5: Verify Generated Audio
ls -lh audio/
open audio/chapter-01.m4a
PHASE 2: Git LFS Commit (Source Repo)
Step 6: Configure Git LFS (if not already done)
cat .gitattributes | grep m4a
echo "*.m4a filter=lfs diff=lfs merge=lfs -text" >> .gitattributes
git lfs track "*.m4a"
Step 7: Commit Audio Files to LFS
git add audio/*.m4a
git add .gitattributes
git commit -m "Add audio for chapters 1-5
- Generated with Produciesta using Aaron (Apple TTS)
- Total duration: 23m 12s
- Episodes: chapter-01 through chapter-05
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
git push origin main
Step 8: Verify LFS Upload
git lfs ls-files
git lfs status
Step 9: Verify CDN Availability
curl -I https://pub-8e049ed02be340cbb18f921765fd24f3.r2.dev/daily-dao/chapter-01.m4a
If 404: Wait a few minutes for LFS sync to CDN, or check CDN configuration.
PHASE 3: Website Integration (Website Repo)
Step 10: Copy Transcripts to Website
cd ~/Projects/intrusive-memory.github.com
cp ~/podcast-daily-dao/episodes/*.fountain \
podcasts/daily-dao/episodes/
ls podcasts/daily-dao/episodes/
Step 11: Update Website Metadata
Open podcasts/daily-dao/index.html and verify:
Check page title and description:
<div class="podcast-header">
<h1>Daily Dao</h1>
<p>81 Chapters of the Tao Te Ching</p>
Check CDN URLs in JavaScript:
audioSource.src = '{{ site.audio_cdn }}/daily-dao/chapter-01.m4a';
Check subscribe links:
<a href="podcast://intrusive-memory.productions/podcasts/daily-dao/feed.xml" class="subscribe-link podcast-app">Subscribe in Podcast App</a>
<a href="/podcasts/daily-dao/feed.xml" class="subscribe-link rss">RSS Feed</a>
Step 12: Update RSS Feed
Open podcasts/daily-dao/feed.xml and add episodes:
<item>
<title>Chapter 1 - The fundamental paradox of the Tao</title>
<description>Chapter One introduces us to the fundamental paradox of the Tao...</description>
<pubDate>Wed, 12 Feb 2025 00:00:00 -0500</pubDate>
<enclosure url="https://pub-8e049ed02be340cbb18f921765fd24f3.r2.dev/daily-dao/chapter-01.m4a"
length="3980000"
type="audio/mp4"/>
<guid>https://intrusive-memory.productions/podcasts/daily-dao/chapter-01</guid>
<itunes:duration>285</itunes:duration>
<itunes:episodeType>full</itunes:episodeType>
</item>
Get file size and duration:
stat -f%z ~/podcast-daily-dao/audio/chapter-01.m4a
afinfo ~/podcast-daily-dao/audio/chapter-01.m4a | grep "estimated duration"
Step 13: Update Podcast Metadata
Update _data/podcasts.yml if episode count changed:
- slug: daily-dao
name: Daily Dao - Tao De Jing Podcast
episodes: 5
status: in_progress
published: true
PHASE 4: Validation & Testing
Step 14: Test Locally with Jekyll
cd ~/Projects/intrusive-memory.github.com
bundle exec jekyll serve
Validate checklist:
Step 15: Validate RSS Feed
curl http://localhost:4000/podcasts/daily-dao/feed.xml | xmllint --format -
Check for:
Step 16: Test Transcripts
In browser console:
fetch('/podcasts/daily-dao/episodes/chapter-01.fountain')
.then(r => r.text())
.then(console.log);
Verify:
PHASE 5: Deployment
Step 17: Commit Website Changes
cd ~/Projects/intrusive-memory.github.com
git add podcasts/daily-dao/episodes/*.fountain
git add podcasts/daily-dao/feed.xml
git add podcasts/daily-dao/index.html
git add _data/podcasts.yml
git commit -m "Publish Daily Dao episodes 1-5
- Add transcripts for chapters 1-5
- Update RSS feed with new episodes
- Update episode count in podcasts.yml
- CDN audio URLs verified and working
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
Step 18: Push to Production
git push origin master
Step 19: Verify GitHub Pages Build
gh run list --limit 1
Wait for:
- ✅ GitHub Pages build completes (~1-2 minutes)
- ✅ Changes deploy to production
Step 20: Final Production Validation
Visit live site: https://intrusive-memory.productions/podcasts/daily-dao/
Final checklist:
Workflow Summary
┌─────────────────────────────────────────┐
│ PHASE 1: Audio Generation │
│ - Analyze .fountain files │
│ - Create PROJECT.md with cast │
│ - Generate audio with Produciesta │
│ - Verify playback locally │
└──────────────┬──────────────────────────┘
│
┌──────────────▼──────────────────────────┐
│ PHASE 2: Git LFS Commit │
│ - Configure LFS for .m4a │
│ - Commit audio files │
│ - Push to remote │
│ - Verify CDN availability │
└──────────────┬──────────────────────────┘
│
┌──────────────▼──────────────────────────┐
│ PHASE 3: Website Integration │
│ - Copy transcripts to website │
│ - Update index.html metadata │
│ - Update RSS feed with episodes │
│ - Update _data/podcasts.yml │
└──────────────┬──────────────────────────┘
│
┌──────────────▼──────────────────────────┐
│ PHASE 4: Validation & Testing │
│ - Test locally with Jekyll │
│ - Validate RSS feed │
│ - Check audio playback │
│ - Verify transcripts load │
└──────────────┬──────────────────────────┘
│
┌──────────────▼──────────────────────────┐
│ PHASE 5: Deployment │
│ - Commit website changes │
│ - Push to production │
│ - Verify GitHub Pages build │
│ - Final production validation │
└─────────────────────────────────────────┘
Time Estimate:
- Audio generation: ~2-3 minutes per episode
- LFS commit & CDN verify: 5-10 minutes
- Website updates: 10-15 minutes
- Testing & validation: 10-15 minutes
- Deployment: 5-10 minutes
- Total for 5 episodes: ~45-60 minutes
Character Analysis Guidelines
When analyzing Fountain files to extract characters, Claude should:
1. Identify All Characters
Parse Fountain dialogue blocks:
NARRATOR
This is the narrator speaking.
ALICE
Hello, I'm Alice!
BOB (V.O.)
And I'm Bob, off screen.
Extract: NARRATOR, ALICE, BOB
Note: Character name variations map to same character:
BOB, BOB (V.O.), BOB (O.S.), BOB (CONT'D) → all = BOB
2. Analyze Character Traits
From dialogue and context, determine:
- Age range (child, young adult, middle-aged, elderly)
- Gender (male, female, neutral)
- Personality (authoritative, friendly, serious, playful)
- Role (narrator, protagonist, antagonist, supporting)
- Accent/dialect (if specified or implied)
3. Consider Dialogue Volume
Note how much each character speaks:
- Primary characters (lots of dialogue) → assign premium voices
- Supporting characters (moderate dialogue) → standard voices
- Minor characters (few lines) → can share voices or use default
4. Document Casting Rationale
In PROJECT.md production notes, explain:
- Why each voice was selected
- Character traits that influenced the choice
- Any special considerations
Voice Matching Guidelines
When matching characters to voices:
For Narrators
Ideal characteristics:
- Clear articulation
- Moderate pace
- Authoritative but not harsh
- Easy to listen to for extended periods
Recommended Apple voices:
- Aaron (US male, mature)
- Ava (US female, clear)
- Daniel (UK male, professional)
For Conversational Characters
Ideal characteristics:
- Natural, warm tone
- Expressive (can convey emotion)
- Distinct from other characters
Recommended Apple voices:
- Samantha (US female, friendly)
- Fred (US male, character voice)
- Zoe (US female, professional)
For ElevenLabs
Advantages:
- More emotional range
- Better for character voices
- Multilingual support
When to use:
- Professional productions
- Non-English content
- Need multiple distinct character voices
- Budget allows for API costs
PROJECT.md Structure
Minimal Configuration
---
type: project
title: Podcast Title
episodesDir: episodes
audioDir: audio
filePattern: "*.fountain"
exportFormat: m4a
cast:
- character: CHARACTER_NAME
voices:
- apple://voice.id
---
Complete Configuration
---
type: project
title: Full Podcast Title
author: Author Name
description: Detailed podcast description
episodesDir: episodes
audioDir: audio
filePattern: "*.fountain"
exportFormat: m4a
cast:
- character: NARRATOR
voices:
- apple://com.apple.voice.premium.en-US.Aaron
- apple://com.apple.voice.premium.en-GB.Daniel
- character: CHARACTER_TWO
voices:
- elevenlabs://21m00Tcm4TlvDq8ikWAM
---
[Optional markdown content documenting the project]
Required Fields
type: project - Always requiredtitle - Podcast titleepisodesDir - Relative path to episodes (default: episodes)audioDir - Relative path for output (default: audio)filePattern - Glob pattern for episode files (default: "*.fountain")exportFormat - Audio format: m4a, aiff, wav, caf, mp3cast - Array of character-to-voice mappings
Optional Fields
author - Creator namedescription - Podcast description
Produciesta Generation Commands
Basic Generation
produciesta /path/to/project
produciesta /path/to/project --format m4a
produciesta /path/to/project --verbose
Single Episode
produciesta /path/to/project --episode chapter-01.fountain
produciesta /path/to/project/episodes/chapter-01.fountain
Batch Processing
produciesta /path/to/project --skip-existing
produciesta /path/to/project --resume-from 50
produciesta /path/to/project --regenerate
Preview Mode
produciesta /path/to/project --dry-run
Error Handling
produciesta /path/to/project --fail-fast
produciesta /path/to/project --ignore-generation-errors
Transcript Generation for Web Players
After generating audio, you can deploy .fountain files as transcripts for your podcast website. The web player JavaScript automatically parses and displays them under the audio player.
Transcript Structure
The same .fountain files used for audio generation serve as transcripts:
Example: chapter-01.fountain
---
title: Tao De Jing - Chapter 1
album: Tao De Jing Podcast
artist: Tao De Jing
track: 1
description: Chapter One introduces the fundamental paradox of the Tao.
---
===
Tao De Jing - Chapter 1
[[ slnc 1000 ]]
Chapter One introduces us to the fundamental paradox of the Tao.
[[ slnc 1000 ]]
[[rate 100]]
Speak it aloud, and it slips from your grasp...
[[ rset]]
How Transcripts Are Displayed
The web player JavaScript (in each podcast's index.html):
- Fetches the .fountain file from
episodes/ directory
- Parses with
parseFountain() function:
- Removes YAML frontmatter (
---...---)
- Removes section markers (
===)
- Strips SSML tags (
[[ slnc 1000 ]], [[rate 100]], [[ rset]])
- Splits into lines
- Displays clean text in the transcript section
Result: Only the actual spoken content appears in the transcript.
Preparing Transcripts for Website
Step 1: Copy Fountain Files to Website
cp ~/podcast-project/episodes/*.fountain \
~/Projects/intrusive-memory.github.com/podcasts/daily-dao/episodes/
cp ~/podcast-project/episodes/chapter-01.fountain \
~/Projects/intrusive-memory.github.com/podcasts/daily-dao/episodes/
Step 2: Verify Transcript Section in index.html
Ensure the podcast's index.html includes the transcript section:
CSS (in <style> block):
.transcript-section {
background: rgba(0,0,0,0.4);
border-radius: 12px;
padding: 1.5rem;
margin-bottom: 2rem;
max-height: 300px;
overflow-y: auto;
}
.transcript-content {
font-family: 'Roboto', sans-serif;
color: #e2e8f0;
font-size: 1.1rem;
line-height: 1.8;
}
.transcript-line {
padding: 0.5rem 0;
border-bottom: 1px solid rgba(255,255,255,0.05);
}
HTML (before chapters section):
<div class="transcript-section">
<h3>Transcript</h3>
<div class="transcript-content" id="transcript-content">
<p class="transcript-loading">Loading transcript...</p>
</div>
</div>
JavaScript functions:
function parseFountain(text) {
let content = text.replace(/^---[\s\S]*?---\s*/m, '');
content = content.replace(/^===\s*/m, '');
content = content.replace(/\[\[\s*slnc\s+\d+\s*\]\]/gi, '');
content = content.replace(/\[\[\s*rate\s+\d+\s*\]\]/gi, '');
content = content.replace(/\[\[\s*rset\s*\]\]/gi, '');
const lines = content.split('\n')
.map(line => line.trim())
.filter(line => line.length > 0);
return lines;
}
async function loadTranscript(filename) {
const url = '{{ site.baseurl }}/podcasts/podcast-name/episodes/' + filename;
transcriptContent.innerHTML = '<p class="transcript-loading">Loading transcript...</p>';
try {
const response = await fetch(url);
if (!response.ok) throw new Error('Failed to load');
const text = await response.text();
const lines = parseFountain(text);
transcriptContent.innerHTML = lines.map((line, index) => {
return '<div class="transcript-line" data-line="' + index + '">' + line + '</div>';
}).join('');
} catch (error) {
transcriptContent.innerHTML = '<p class="transcript-loading">Transcript not available</p>';
}
}
Call on chapter change:
function playChapter(chapterNum) {
loadTranscript('chapter-' + padNumber(chapterNum) + '.fountain');
}
Step 3: Deploy and Test
cd ~/Projects/intrusive-memory.github.com
git add podcasts/podcast-name/episodes/*.fountain
git add podcasts/podcast-name/index.html
git commit -m "Add transcripts for podcast episodes"
git push
bundle exec jekyll serve
Transcript File Naming Conventions
Match the naming pattern used by your audio files:
Daily Dao (numbered chapters):
chapter-01.fountain
chapter-02.fountain
...
chapter-81.fountain
Meditations (Julian day + date):
001_january_01.fountain
002_january_02.fountain
...
365_december_31.fountain
Custom naming (YNTSWYD):
Chapter 1.fountain
Chapter 2.fountain
Epilogue.fountain
Critical: The filename must match what the JavaScript loadTranscript() function constructs.
Workflow Integration
When generating audio with this skill:
- Generate audio with Produciesta
- Copy .fountain files to website
episodes/ directory
- Verify transcript section exists in
index.html
- Test locally that transcripts load correctly
- Deploy to production
Complete Workflow Reference
For the full end-to-end workflow including:
- Audio generation
- Git LFS commit and CDN verification
- Transcript deployment
- RSS feed updates
- Validation and testing
- Production deployment
See: "Complete End-to-End Publishing Workflow" section above.
That section provides a step-by-step walkthrough with all commands, validation steps, and troubleshooting guidance.
Troubleshooting Transcripts
Transcript shows "Transcript not available":
- Verify .fountain file exists in
episodes/ directory
- Check filename matches what JavaScript constructs
- Inspect browser console for 404 errors
- Verify file permissions (should be readable)
Transcript shows SSML tags like [[ slnc 1000 ]]:
- Update
parseFountain() function to strip all SSML tags
- See reference implementation in Daily Dao or Meditations
Transcript shows YAML frontmatter:
- Verify regex in
parseFountain() correctly removes frontmatter
- Pattern should be:
/^---[\s\S]*?---\s*/m
Lines are concatenated (not separated):
- Check that
split('\n') is being used
- Verify lines are wrapped in
<div class="transcript-line"> tags
Troubleshooting
Error: "Character not found in cast list"
Cause: Fountain file contains a character not in PROJECT.md cast section.
Solution 1: Add character to PROJECT.md
cast:
- character: MISSING_CHARACTER
voices:
- apple://com.apple.voice.premium.en-US.Aaron
Solution 2: Use default voice
produciesta /path/to/project \
--default-voice "apple://com.apple.voice.premium.en-US.Aaron"
Solution 3: Re-analyze with Claude
Ask Claude to re-read Fountain files and update PROJECT.md cast list.
Error: "Voice provider unavailable"
For ElevenLabs:
echo $ELEVENLABS_API_KEY
export ELEVENLABS_API_KEY="your-key-here"
For Apple TTS:
- Premium voices require download: System Settings → Accessibility → Spoken Content
- Voice ID must be exact (case-sensitive)
Error: "No episodes found"
Check file pattern:
ls episodes/*.fountain
filePattern: "*.fountain"
Audio Quality Issues
Voice too fast/slow:
- Apple TTS: No direct speed control
- ElevenLabs: Has stability/similarity controls
Wrong voice:
- Update voice URI in PROJECT.md
- Regenerate:
produciesta /path/to/project --regenerate
Advanced: Hooks for Automation (macOS Only)
Produciesta supports pre/post-generation hooks for automation:
Create Hooks
mkdir -p /path/to/project/.produciesta-hooks
cat > /path/to/project/.produciesta-hooks/pre-generation.sh << 'EOF'
echo "🎙️ Starting audio generation at $(date)"
EOF
cat > /path/to/project/.produciesta-hooks/post-generation.sh << 'EOF'
echo "✅ Completed audio generation at $(date)"
EOF
chmod +x /path/to/project/.produciesta-hooks/*.sh
Disable Hooks
produciesta /path/to/project --skip-hooks
Creating Execution Plans
When the user asks to "create an audio plan", generate a planning document:
Plan Template
# Audio Generation Plan: [Project Title]
## Project Overview
- **Location**: /path/to/project
- **Episodes**: [N] .fountain files
- **Characters**: [N] unique characters
- **Format**: M4A
- **Provider**: Apple TTS / ElevenLabs
## Step 1: Character Analysis
[Claude analyzes Fountain files]
Characters identified:
- NARRATOR: 150 lines, authoritative narrator voice
- ALICE: 45 lines, young female protagonist
- BOB: 32 lines, supporting male character
## Step 2: Voice Assignment
[Claude matches voices]
Recommended casting:
- NARRATOR → Aaron (mature, clear, authoritative)
- ALICE → Ava (young female, expressive)
- BOB → Daniel (British accent, professional)
## Step 3: PROJECT.md Creation
[Claude creates/updates PROJECT.md with cast list]
## Step 4: Audio Generation
```bash
cd /path/to/project
produciesta . --format m4a --verbose
Step 5: Quality Check
Timeline Estimate
- Character analysis: 5 minutes
- Voice matching: 5 minutes
- PROJECT.md creation: 2 minutes
- Audio generation: ~2 minutes per episode
- Quality check: 10 minutes
- Total: [Estimated based on episode count]
## Best Practices
1. **Always analyze all episodes** before assigning voices (characters may appear later)
2. **Document casting rationale** in PROJECT.md production notes
3. **Test with one episode first** before batch processing
4. **Use premium voices for primary characters** (more dialogue = more important)
5. **Consider voice distinctiveness** to avoid confusion between characters
6. **Commit PROJECT.md to git** for version control and team collaboration
7. **Use dry-run mode** to validate configuration before generating
## Related Tools and Resources
- **Produciesta CLI**: `~/Projects/Produciesta/produciesta-cli/`
- **ProduciestaCore**: Audio generation engine
- **Apple TTS**: Built-in macOS voices
- **ElevenLabs**: Premium voice synthesis API
- **Fountain Format**: https://fountain.io/
- **ElevenLabs Voice Library**: https://elevenlabs.io/voice-library
## Quick Reference: Common Commands
### Audio Generation
```bash
# Generate all episodes
produciesta /path/to/project --format m4a --verbose
# Generate single episode
produciesta /path/to/project --episode chapter-01.fountain
# Dry run (preview without generating)
produciesta /path/to/project --dry-run
# Skip existing files
produciesta /path/to/project --skip-existing
Git LFS Management
git lfs track "*.m4a"
echo "*.m4a filter=lfs diff=lfs merge=lfs -text" >> .gitattributes
git lfs ls-files
git lfs status
git lfs ls-files | grep chapter-01.m4a
CDN Verification
curl -I https://pub-8e049ed02be340cbb18f921765fd24f3.r2.dev/podcast-slug/chapter-01.m4a
Transcript Deployment
cp ~/podcast-source/episodes/*.fountain \
~/Projects/intrusive-memory.github.com/podcasts/podcast-slug/episodes/
ls -la ~/Projects/intrusive-memory.github.com/podcasts/podcast-slug/episodes/
Get Audio Metadata
stat -f%z audio/chapter-01.m4a
afinfo audio/chapter-01.m4a | grep "estimated duration"
ffprobe -v quiet -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 audio/chapter-01.m4a
Jekyll Testing
cd ~/Projects/intrusive-memory.github.com
bundle exec jekyll serve
RSS Feed Validation
curl http://localhost:4000/podcasts/podcast-slug/feed.xml | xmllint --format -
Pre-Flight Validation Checklist
Before starting audio generation:
Source Repository:
Website Repository:
Environment:
Post-Deployment Validation Checklist
After pushing to production:
Production Site:
RSS Feed:
GitHub:
Common Troubleshooting
Issue: Audio generation fails with "Character not found"
Cause: Fountain file has character not in PROJECT.md cast.
Solution:
grep "^[A-Z][A-Z ]*$" episodes/*.fountain | sort -u
Issue: CDN returns 404 for audio files
Cause: LFS files not synced to CDN yet.
Solutions:
- Wait 5-10 minutes for sync
- Verify LFS upload:
git lfs ls-files
- Check file is actually in LFS:
git lfs ls-files | grep filename
- Verify CDN URL path matches podcast slug
Issue: Transcripts show "Transcript not available"
Cause: .fountain files not copied to website or filename mismatch.
Solutions:
- Verify files copied:
ls podcasts/<slug>/episodes/*.fountain
- Check browser console for 404 errors
- Verify filename matches JavaScript
loadTranscript() call
- Check file permissions:
chmod 644 episodes/*.fountain
Issue: RSS feed validation fails
Common errors and fixes:
- Invalid date format: Use RFC-822 format:
Wed, 12 Feb 2025 00:00:00 -0500
- Invalid enclosure URL: Must be full CDN URL with https://
- Missing duration: Add
<itunes:duration>285</itunes:duration> (in seconds)
- Invalid file size: Get actual size with
stat -f%z audio/file.m4a
Issue: Jekyll build fails
Common causes:
- YAML syntax error in frontmatter
- Invalid HTML in index.html
- Missing required files (favicon, artwork)
Debug:
bundle exec jekyll build --verbose
Issue: GitHub Pages not updating
Solutions:
- Check build status:
gh run list --limit 1
- View build logs in Actions tab
- Hard refresh browser: Cmd+Shift+R (macOS) or Ctrl+Shift+R (Windows)
- Clear browser cache
- Wait 2-3 minutes for CDN cache invalidation
Notes
- Do NOT use
--autocast flag - it's currently not working
- Claude-assisted casting provides better control and understanding
- Always verify voice URIs are correct format before generation
- Produciesta handles all audio generation - Claude only creates cast list
- Error logs saved to
GENERATION_ERRORS.md in project root
- Audio files are in Git LFS - not regular git blobs
- CDN serves audio - website only references CDN URLs
- Transcripts are .fountain files - copied from source repo to website
- RSS feeds must be manually updated - no auto-generation yet
