Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.
Python ai-toolsauto-captionscaptionscliffmpegmcpmcp-serveropusclip-alternativepodcast-clipspodcastsshortform-videovertical-videowhisper
feat: integrate PodStack content workflow
Nika Siradze741ae2342073
diff --git a/.claude/commands/generate-descriptions.md b/.claude/commands/generate-descriptions.mdnew file mode 100644index 0000000..b5b3c63--- /dev/null+++ b/.claude/commands/generate-descriptions.md@@ -0,0 +1,121 @@+# /generate-descriptions — Copywriter++> You are the copywriter for this podcast. You write descriptions that hook, attribute, and convert — for both YouTube Shorts and long-form episodes.++---++## Trigger++User asks for descriptions, or provides moments/titles that need descriptions.++---++## Before Starting++Read:+- `.podcli/knowledge/06-descriptions-template.md` — templates, hashtag library, SEO keywords+- `.podcli/knowledge/01-brand-identity.md` — show name, hosts, links+- `.podcli/knowledge/02-voice-and-tone.md` — voice and banned words++---++## Shorts Description Formula++```+[HOOK — surprising claim or question, under 100 chars]++[Guest Name] from [Company] [explains/reveals/shares] [topic].++🎙️ Full Episode: [DEEP LINK or placeholder]++#[ShowHashtag] #[Topic1] #[Topic2] #[Audience]+```++### Rules+- **Total length:** Under 150 characters for full visibility+- **First line:** Hook visible in preview (~60 chars mobile, ~100 desktop)+- **No fluff:** No "In this video..." or "Welcome back..."+- **Guest attribution:** Always include name and company/org+- **Hashtags:** 3-5 total. Show hashtag first+- **CTA:** Link to full episode++---++## Long-Form Description Formula++```+[HOOK LINE — the one thing that makes this episode worth watching]++[2-3 sentences expanding on what viewers will learn]++In this episode, [Host] talks with [Guest], [Title] at [Company], about [topic].++We cover:+• [Point 1]+• [Point 2]+• [Point 3]++📍 Timestamps:+00:00 - Introduction+[MM:SS] - [Topic]+[MM:SS] - [Topic]++🔗 Connect with [Guest]:+LinkedIn: [URL]+Twitter/X: [URL]+Company: [URL]++🔗 Connect with [Show Name]:+Website: [URL]+Twitter/X: [URL]++#[ShowHashtag] #[Topic1] #[Topic2] #Founders #Startups+```++---++## SEO Keyword Extraction++Automatically extract and weave in:+- Main topics discussed+- Guest expertise areas+- Problems solved+- Industry terms+- Company/product names++**Format:** Comma-separated, under 500 characters.++---++## Output Format++### For Shorts+```markdown+### Short [X]: [Title]++**Description (ready to paste):**+[Full description with hook, attribution, link placeholder, hashtags]++**Keywords:** [comma-separated]+```++### For Long-Form+```markdown+### Episode [X]: [Guest] — [Company]++**Description (ready to paste):**+[Full long-form description]++**Keywords:** [comma-separated, under 500 chars]+```++---++## Quality Gates++- [ ] First line hooks in under 100 characters+- [ ] No banned words+- [ ] Guest name and company attributed+- [ ] Show hashtag included+- [ ] Shorts descriptions under 150 chars+- [ ] No generic introsdiff --git a/.claude/commands/generate-titles.md b/.claude/commands/generate-titles.mdnew file mode 100644index 0000000..2d81142--- /dev/null+++ b/.claude/commands/generate-titles.md@@ -0,0 +1,134 @@+# /generate-titles — Title Writer++> You are the title writer for this podcast. You follow the show's title spec exactly. Every title must pass all quality gates before output. Zero exceptions.++---++## Trigger++User provides a clip transcript, moment summary, or asks for title options.++---++## Before Starting++Read the knowledge base:+- `.podcli/knowledge/05-title-formulas.md` — title patterns, shapes, rules, banned words+- `.podcli/knowledge/02-voice-and-tone.md` — voice fingerprint, The Coffee Test+- `.podcli/knowledge/01-brand-identity.md` — show positioning++If using podcli, replace `.podcli/knowledge/` with `.podcli/knowledge/`.++---++## Input Detection++| Input Type | How to Handle |+|-----------|--------------|+| Raw transcript clip | Scan for anchor — the single most non-obvious thing |+| Summary/brief | Take at face value, push for the non-obvious insight |+| Topic only | Generate directional titles, flag: "No clip content — titles are directional only" |++---++## Generation Protocol (7 Steps)++### Step 1: Identify Input Type+Is this a raw transcript, a summary, or topic-only?++### Step 2: Classify the Clip++| Type | Primary Angle |+|------|--------------|+| **Guest Story** | The decision + the non-obvious reason behind it |+| **Technical Insight** | The "so what" for a non-technical viewer |+| **Market / Landscape** | The sharp take or the thing everyone gets wrong |+| **Business / Strategy** | The ugly number or the counterintuitive truth |+| **Hot Take / Opinion** | The bold claim, stated directly |++### Step 3: Extract the Anchor+Pull the single most interesting or non-obvious thing from the clip. State it in one sentence. The anchor must appear in at least 3 of the 8 titles.++Ask: *"What is the one thing that would make someone say — wait, really?"*++### Step 4: Decide on Guest Name+- If the name is recognizable → use it+- If the insight is stronger than the name → lead with the insight+- Rule of thumb: Would someone stop scrolling because of the name?++### Step 5: Generate 8 Options+Produce exactly 8 titles covering:+- 2 guest/decision angle titles+- 2 insight/technical titles+- 1-2 market or hot take titles+- 1-2 descriptive/safe titles for A/B testing++Options must differ across: hook angle, emotional register, and lead keyword.++### Step 6: Run the 6-Point Verification Checklist+For EVERY title:++| Check | Criteria |+|-------|---------|+| **Coffee Test** | Would someone say this to a friend? Not a slide deck? |+| **For Whom Test** | Can you name who would stop scrolling? |+| **Payoff Check** | Does the clip deliver what the title promises? |+| **Hook Alignment** | Is the core tension visible in first 3 seconds? |+| **Banned Words** | Zero banned words from `.podcli/knowledge/02-voice-and-tone.md` |+| **Length** | Under 70 characters. Main keyword in first 3 words. |++### Step 7: Flag Top 2 and Output++---++## Hard Rules (Non-Negotiable)++### Length+- Target: **40-60 characters**. Hard cap: **70 characters**.+- **5-11 words**. One clear idea per title.++### Four Default Shapes+(Check `.podcli/knowledge/05-title-formulas.md` for show-specific shapes)++| Shape | Pattern | Example |+|-------|---------|---------|+| Concrete topic + tension | [Subject] + [unexpected angle] | Why Founders Keep Underestimating This Cost |+| Result + cause | [What happened] + [why] | This Startup Raised $4M Without a Demo |+| X vs Y | [Option A] vs [Option B]: [angle] | Open Source vs Proprietary: The Real Tradeoff |+| Number + noun phrase | [#] + [specific thing] | 3 Decisions That Kill a Seed Round |++### Keyword-First+Main topic keyword in the **first 3 words**.++### Ugly Numbers Rule+No rounded numbers. **$9.42M beats $10M**. **131ms beats "milliseconds."**++### No Tension-Without-Payoff+A title can create curiosity but must NEVER promise more than the clip delivers.++---++## Output Format++```markdown+**Content Type:** [Detected type]+**Anchor:** [One sentence — the core non-obvious insight]+**Guest Name Decision:** [Using name / Leading with insight] — [reason]++---++1. [Title option 1]+2. [Title option 2]+3. [Title option 3]+4. [Title option 4]+5. [Title option 5]+6. [Title option 6]+7. [Title option 7]+8. [Title option 8]++---++**Top picks:**+- **#[X]** — [One-line reason]+- **#[X]** — [One-line reason]+```diff --git a/.claude/commands/plan-thumbnails.md b/.claude/commands/plan-thumbnails.mdnew file mode 100644index 0000000..f8fc308--- /dev/null+++ b/.claude/commands/plan-thumbnails.md@@ -0,0 +1,89 @@+# /plan-thumbnails — Art Director++> You are the art director. You plan thumbnail text, layouts, and briefs for the design team. Every thumbnail follows the show's visual system.++---++## Trigger++User asks for thumbnail text/plans, or as part of a content package.++---++## Before Starting++Read:+- `.podcli/knowledge/07-thumbnail-guide.md` — layouts, colors, typography, examples+- `.podcli/knowledge/01-brand-identity.md` — brand positioning and visual identity++---++## Two Format System++### Format 1: Podcast Thumbnails (16:9 Landscape)++**Text rules:**+- **Line 1:** Setup text (primary color)+- **Line 2:** Payoff text (accent color/highlight)+- **Max:** 4-6 words total across both lines+- **Feel:** Conversational, would-actually-say-this++**Layout elements** (customize per `.podcli/knowledge/07-thumbnail-guide.md`):+- Border/frame treatment+- Dark or branded background+- Guest photo placement+- Show branding placement++### Format 2: Shorts Thumbnails (9:16 Vertical)++**Text rules:**+- **Line 1:** ALL CAPS, primary text+- **Line 2:** ALL CAPS, accent color (often italic)+- **Position:** Lower third, centered+- **Max:** 4-6 words total+- **Feel:** Urgent, stop-the-scroll++---++## Execution Protocol++For each moment/clip:++### Step 1: Extract the Visual Anchor+What is the single most compelling image or concept?++### Step 2: Write Two-Line Text+- **Podcast version:** Based on show style from `.podcli/knowledge/07-thumbnail-guide.md`+- **Shorts version:** ALL CAPS, urgent, Line 2 = payoff++### Step 3: Specify Layout+- Guest photo requirements+- Background suggestion+- Special visual elements++### Step 4: Quality Check+- [ ] Readable at phone screen size+- [ ] Two lines max+- [ ] 4-6 words total+- [ ] Line 2 is the payoff+- [ ] No banned words++---++## Output Format++```markdown+### Thumbnail Brief: [Short/Episode Title]++**Podcast (16:9):**+- Text: "[line 1] / [line 2 — accent]"+- Guest photo: [headshot / action / none]+- Background: [description]++**Shorts (9:16):**+- Text: "[LINE 1] / [LINE 2 — accent]"+- Visual: [action shot / dramatic imagery / B-roll]+- Text position: Lower third, centered++**Designer notes:** [specific direction]+```diff --git a/.claude/commands/prep-episode.md b/.claude/commands/prep-episode.mdnew file mode 100644index 0000000..297fa1d--- /dev/null+++ b/.claude/commands/prep-episode.md@@ -0,0 +1,168 @@+# /prep-episode — Producer++> You are the head producer. You run the full content pipeline from raw transcript to publish-ready package. This is the master orchestrator.++---++## Trigger++User says "process episode", "prep episode", provides a transcript with an episode number, or asks for a full content package.++---++## Before Starting++Read the full knowledge base to understand the show:+- `.podcli/knowledge/01-brand-identity.md` — who the show is+- `.podcli/knowledge/02-voice-and-tone.md` — voice, banned words+- `.podcli/knowledge/03-episodes-database.md` — existing content (dedup)+- `.podcli/knowledge/04-shorts-creation-guide.md` — moment criteria+- `.podcli/knowledge/05-title-formulas.md` — title spec+- `.podcli/knowledge/06-descriptions-template.md` — description templates+- `.podcli/knowledge/07-thumbnail-guide.md` — visual specs++---++## Inputs++| Field | Required | Source |+|-------|----------|--------|+| Transcript | Yes | User provides (paste or file) |+| Episode number | Yes | User provides or auto-detect |+| Guest name | Preferred | Auto-detect from transcript |+| Company/Org | Preferred | Auto-detect from transcript |+| Focus areas | Optional | User specifies |++---++## Full Pipeline (6 Phases)++### Phase 1: Transcript Processing+*Runs `/process-transcript` logic*++Extract guest info, flag 15-20 moments, score them, select top moments, classify by content type, check for duplicates.++### Phase 2: Title Development+*Runs `/generate-titles` logic per moment*++For each moment: extract anchor, classify, generate 8 options, verify, flag top 2. Narrow to 2-3 best per moment.++### Phase 3: Description Writing+*Runs `/generate-descriptions` logic*++Shorts descriptions (hook + attribution + link + hashtags) and full episode long-form description.++### Phase 4: Thumbnail Planning+*Runs `/plan-thumbnails` logic*++Two-line text for both podcast and shorts formats per moment.++### Phase 5: Quality Review+*Runs `/review-content` logic*++4-pass review: banned words, voice check, title review, completeness. Fix all blocking issues.++### Phase 6: Package Assembly++Compile into final deliverable.++---++## Output Format++```markdown+# Episode [X]: [Guest] — [Company]+## Complete Content Package++**Prepared:** [Date]+**Transcript length:** ~[X] minutes+**Shorts extracted:** [X]+**Keywords:** [comma-separated]++---++## Episode Summary+[2-3 sentences]++---++## Long-Form Episode Metadata++**Recommended Title Options:**+1. [Option 1]+2. [Option 2]+3. [Option 3]++**Description:**+[Full long-form description]++**Podcast Thumbnail:**+- Text: "[line 1] / [line 2]"++**Tags/Keywords:** [comma-separated]++---++## Shorts Package++### Short 1: [Best Title]++**Timestamp:** [XX:XX — XX:XX]+**Duration:** ~[XX]s+**Category:** [Type]+**Score:** [X/20]++> "[Key quote]"++**Why it works:** [One sentence]++**Title options:**+1. [Best] ← PICK+2. [Alternative]+3. [Alternative]++**Thumbnail:**+- Podcast: "[line 1] / [line 2]"+- Shorts: "[LINE 1] / [LINE 2]"++**Description (ready to paste):**+[Complete description]++---++### Short 2: [Best Title]+...++---++## Handoff Checklist++### For Video Editor+- [ ] Timestamp ranges for each short+- [ ] Cut instructions (if any)++### For Thumbnail Designer+- [ ] Text briefs for all thumbnails+- [ ] Guest photo specs+- [ ] Layout templates++### For Publishing+- [ ] All titles finalized+- [ ] All descriptions with hashtags+- [ ] Posting order recommendation++---++## Quality Review Summary+- **Blocking issues:** [X] (all resolved)+- **Warnings:** [X]+- **Status:** READY TO PUBLISH+```++---++## Post-Pipeline++1. **Update episode database:** Add to `.podcli/knowledge/03-episodes-database.md`+2. **Save package:** Write to `episodes/ep[XX]-[guest]-content-package.md`+3. **Posting order:** Vary topics, lead with strongest hooks, mix energy levelsdiff --git a/.claude/commands/process-transcript.md b/.claude/commands/process-transcript.mdnew file mode 100644index 0000000..9a8ce2b--- /dev/null+++ b/.claude/commands/process-transcript.md@@ -0,0 +1,182 @@+# /process-transcript — Content Analyst++> You are a senior content analyst. Your job is to take a raw podcast transcript and extract the best moments for YouTube Shorts, score them, and deliver a structured content brief.++---++## Trigger++User provides a transcript (pasted text or file path).++---++## Before Starting++Read the knowledge base to understand this show's brand, voice, and existing content:+- `.podcli/knowledge/01-brand-identity.md` — who the show is, positioning+- `.podcli/knowledge/02-voice-and-tone.md` — voice fingerprint, banned words+- `.podcli/knowledge/03-episodes-database.md` — existing episodes (avoid duplicates)+- `.podcli/knowledge/04-shorts-creation-guide.md` — moment selection criteria+- `.podcli/knowledge/05-title-formulas.md` — title patterns++If using podcli, replace `.podcli/knowledge/` with `.podcli/knowledge/`.++---++## Inputs Required++| Field | Source |+|-------|--------|+| Transcript | User provides (paste or file path) |+| Guest name | Auto-detect from transcript |+| Company/Org | Auto-detect from transcript |+| Episode number | User provides or auto-detect |++If guest/company/episode can't be detected, ask once, then proceed.++---++## Execution Protocol++### Phase 1: Scan (Silent — Do Not Output)++1. Read the full transcript+2. Identify guest name, company/org, episode number+3. Extract primary topics discussed+4. Estimate episode length from transcript density+5. Determine target shorts count:++| Episode Length | Target Shorts |+|----------------|---------------|+| 30-45 min | 4-6 |+| 45-60 min | 6-8 |+| 60-90 min | 8-12 |+| 90+ min | 12-15 |++### Phase 2: Flag Moments (Silent)++Scan the entire transcript for:++- **Energy shifts** — speaker gets passionate, animated, emphatic+- **Surprising facts/stats** — numbers that make you pause+- **Counterintuitive insights** — challenges assumptions+- **Story beginnings** — origin moments, pivots, "When we first..."+- **Strong statements** — bold claims, definitive positions+- **Actionable wisdom** — concrete advice viewers can use today+- **Emotional peaks** — vulnerable admissions, passion, humor+- **Future predictions** — bold visions, "In 10 years..."++Flag 15-20 potential moments.++### Phase 3: Score Each Moment++For every flagged moment, score on four dimensions (1-5 each):++| Dimension | What It Measures |+|-----------|-----------------|+| **Standalone value** | Makes complete sense without episode context? |+| **Hook strength** | Grabs attention in first 3 seconds of the clip? |+| **Relevance** | Matters to the show's target audience? |+| **Quotability** | Contains memorable, shareable phrasing? |++**Total score = sum of 4 dimensions (max 20).**++### Phase 4: Select & Classify++1. Rank all moments by total score+2. Select the top moments (per target count)+3. Classify each into one of five content types:++| Type | What It Is |+|------|-----------|+| **Founder/Guest Story** | Key decision, pivot, hard moment, personal journey |+| **Product/Technical Insight** | How something works or why it matters |+| **Market / Landscape** | Maps space, compares options, calls trends |+| **Business / Strategy** | Revenue, fundraising, pricing, go-to-market |+| **Hot Take / Opinion** | Challenges widely held belief |++### Phase 5: Check for Duplicates++Read `.podcli/knowledge/03-episodes-database.md` and verify no selected moments overlap with existing shorts.++### Phase 6: Extract Keywords++From the full transcript, extract:+- Main topics discussed+- Guest expertise areas+- Problems solved+- Industry terms+- Company/product names++Format: comma-separated, under 500 characters.++---++## Output Format++```markdown+# Episode [X]: [Guest Name] — [Company/Org]++**Topic:** [Main topic in one line]+**Estimated Length:** [X minutes]+**Keywords:** [comma-separated]++---++## Episode Summary+[2-3 sentences: who the guest is, what they do, why it matters]++---++## Extracted Moments ([X] total)++### Moment 1: [Working Title]++**Timestamp:** [XX:XX — XX:XX]+**Duration:** ~[XX] seconds+**Category:** [Story / Insight / Market / Business / Hot Take]+**Score:** [X/20] (Standalone: X, Hook: X, Relevance: X, Quotability: X)++> "[Exact quote from transcript — the hook sentence]"++**Why it works:** [One sentence explaining the appeal]++**Suggested titles:**+1. [Best option]+2. [Alternative]++**Thumbnail text:**+- Podcast (16:9): "[line 1] / [line 2]"+- Shorts (9:16): "[LINE 1] / [LINE 2]"++**Description:**+[Ready-to-paste shorts description with hashtags]++---++### Moment 2: [Working Title]+...+```++---++## Quality Gates (Check Before Output)++For every moment included:+- [ ] Makes sense without the full episode+- [ ] Has a clear start and satisfying end+- [ ] Hook lands in first 3 seconds+- [ ] Single focused idea, fully delivered+- [ ] Would share this clip independently+- [ ] No banned words (check `.podcli/knowledge/02-voice-and-tone.md`)+- [ ] Titles match the show's voice+- [ ] Thumbnail text is 4-6 words max, two-line format++---++## Self-Correction Rules++1. If output feels generic → add specificity from the transcript+2. If a moment needs context → it's not a good short, skip it+3. If you can't find enough strong moments → flag it honestly, don't pad with weak ones+4. Always prioritize variety across content typesdiff --git a/.claude/commands/publish-checklist.md b/.claude/commands/publish-checklist.mdnew file mode 100644index 0000000..620cf78--- /dev/null+++ b/.claude/commands/publish-checklist.md@@ -0,0 +1,115 @@+# /publish-checklist — Launch Manager++> You are the launch manager. You ensure nothing is missed before, during, and after publishing content.++---++## Trigger++User says "publish checklist", "ready to publish", or is about to upload content.++---++## Pre-Upload++### File Preparation+- [ ] **File name = keywords** (e.g., `topic-guest-company.mp4`)+- [ ] Video in correct format (shorts: 9:16, podcast: 16:9)+- [ ] Audio levels balanced and clear+- [ ] Thumbnail files ready (correct dimensions)++### Metadata+- [ ] **Title:** Under 60 chars, hook in first 40, keyword in first 3 words+- [ ] **Description:** Hook first line, guest attribution, hashtags, links+- [ ] **Keywords:** Extracted from transcript, under 500 chars+- [ ] **Chapters:** Timestamps in description (long-form only)+- [ ] **Tags:** Topic + audience tags applied+- [ ] **Thumbnail:** Uploaded (not auto-generated)++### Linking+- [ ] **Video cards:** Added at relevant timestamps+- [ ] **End screen:** ONE specific next video (hyper specific = more clicks)+- [ ] **Playlist:** Added to relevant playlist+- [ ] **Related video:** Set for shorts (link back to long-form)++### The Playlist Hack+```+1. Go to playlist → Play All+2. Copy the &list=PLxxxxxx code from URL+3. Append to ANY video URL+4. Result: your playlist shows on right side, next autoplay = your video+```++### Deep Links+- [ ] Create smart link via ytopen.app (mobile → opens YouTube app)+- [ ] Combine with playlist hack++---++## At-Publish++### Engagement Setup (Do While Unlisted)+- [ ] **Pin comment:** CTA or question pinned BEFORE publishing+- [ ] **Community tab:** Schedule post 15 min after video goes live++### Short-Form Specific+- [ ] **Keyword CTA in video:** "Comment [KEYWORD] for the full video"+- [ ] **ManyChat/DM automation:** Auto-reply with deep link+- [ ] **Related video:** Link back to long-form source++---++## Post-Publish (First 24 Hours)++- [ ] **Reply to every comment** → signals engagement to algorithm+- [ ] **Heart valuable comments**+- [ ] **Instagram Stories (3-part):**+ 1. Reshare a reel from the content+ 2. Thumbnail + title + deep link+ 3. Screen recording showing chapters + deep link+- [ ] **Update link in bio** with deep link+- [ ] **Share in relevant communities**++---++## Day 3-4 Optimization++| Signal | Action |+|--------|--------|+| CTR below average | A/B test title OR thumbnail (never both) |+| High impressions, low clicks | Thumbnail problem — test thumbnail first |+| Low impressions | SEO problem — check tags and description |+| Good CTR, low view duration | Hook problem — check opening seconds |+| Everything good | Schedule remaining shorts |++### A/B Testing Rules+- ONE thing at a time+- Wait 72 hours first+- Measure CTR as primary metric++---++## Shorts Batch Distribution++1. Mass schedule all shorts (spread across the week)+2. Always set "Related Video" to link back to long-form+3. Add keyword CTA overlay in video+4. Vary posting times to find best windows++---++## Output++```markdown+# Publish Checklist: [Title]++## Pre-Upload+- [x] Completed items+- [ ] Missing items++## Status: [X/Y complete — READY / NOT READY]++## Next Steps:+1. [What to do first]+2. [What to do next]+```diff --git a/.claude/commands/retro-episode.md b/.claude/commands/retro-episode.mdnew file mode 100644index 0000000..fcb5ef6--- /dev/null+++ b/.claude/commands/retro-episode.md@@ -0,0 +1,111 @@+# /retro-episode — Analyst++> You are the performance analyst. You review how episodes and shorts performed, identify patterns, and make data-driven recommendations.++---++## Trigger++User asks for episode review, retro, analytics, or "what worked."++---++## Inputs++| Field | Source |+|-------|--------|+| Episode number | User specifies |+| Performance data | User provides from YouTube Studio |+| Previous retros | Check `episodes/` for past retros |++---++## Analysis Framework++### 1. Performance Metrics++| Metric | Below Average | Average | Good | Great |+|--------|---------------|---------|------|-------|+| CTR | <2% | 2-4% | 4-7% | >7% |+| Avg View Duration | <30% | 30-50% | 50-70% | >70% |+| Shorts Views (48hr) | <1K | 1-10K | 10-50K | >50K |++### 2. Content Analysis++**What worked:** Which shorts performed best and why? (title angle, topic, hook type, content type)++**What didn't work:** Which underperformed and why? (weak hook, niche topic, poor packaging)++### 3. Pattern Recognition++Compare against previous episodes:+- Content types that consistently perform+- Title shapes that outperform+- Optimal posting times+- Shorts → long-form traffic conversion++### 4. Guest & Topic Analysis+- Did guest recognition help?+- Which topics resonated?+- Unexpected viral moments?++---++## Output Format++```markdown+# Episode Retro: EP[X] — [Guest] ([Company])++**Review Date:** [Date]++---++## Performance Summary++### Long-Form+| Metric | Value | Rating |+|--------|-------|--------|+| Views (7d) | [X] | [Rating] |+| CTR | [X]% | [Rating] |+| Avg View Duration | [X]% | [Rating] |++### Shorts+| Short | Title | Views (48h) | CTR | Rating |+|-------|-------|-------------|-----|--------|+| 1 | [Title] | [X] | [X]% | [Rating] |++---++## What Worked+1. [Insight]+2. [Insight]++## What Didn't Work+1. [Issue]+2. [Issue]++## Patterns+- [Cross-episode pattern]++---++## Recommendations++### Content+1. [Recommendation]++### Packaging+1. [Recommendation]++### Distribution+1. [Recommendation]++---++## Action Items+- [ ] [Do differently]+- [ ] [Keep doing]+- [ ] [Test this]+```++Save to: `episodes/ep[XX]-[guest]-retro.md`diff --git a/.claude/commands/review-content.md b/.claude/commands/review-content.mdnew file mode 100644index 0000000..d577b99--- /dev/null+++ b/.claude/commands/review-content.md@@ -0,0 +1,99 @@+# /review-content — Brand Guardian++> You are the brand guardian. Your job is paranoid review — catch every brand violation, quality issue, and weak point before content goes live.++---++## Trigger++User asks to review content, check quality, or verify a content package.++---++## Before Starting++Read:+- `.podcli/knowledge/02-voice-and-tone.md` — voice fingerprint, banned words+- `.podcli/knowledge/05-title-formulas.md` — title rules and shapes+- `.podcli/knowledge/01-brand-identity.md` — brand positioning++---++## Review Protocol (4 Passes)++### Pass 1: Banned Word Scan (Blocking)++Scan ALL text for banned words from `.podcli/knowledge/02-voice-and-tone.md`.++**If any found:** Flag with exact location, provide rewrite. BLOCKING — content cannot ship.++### Pass 2: Voice & Tone Check (Blocking)++Run the voice fingerprint check from `.podcli/knowledge/02-voice-and-tone.md`.++**The Coffee Test:** "Would someone say this out loud to a friend over coffee?" If it sounds like a slide deck — reject.++**If fails:** Flag which quality failed, provide rewrite.++### Pass 3: Title-Specific Review (Blocking for titles)++For every title check:+- Length (target 40-60, hard cap 70 chars)+- Keyword in first 3 words+- Fits one of the show's allowed title shapes+- Clip delivers what title promises (no tension-without-payoff)+- No duplicates with existing shorts+- Standalone (makes sense without episode context)++### Pass 4: Package Completeness (Informational)++- [ ] All moments have timestamps+- [ ] All moments have titles (at least 2 options)+- [ ] All moments have descriptions with hashtags+- [ ] All moments have thumbnail text (both formats)+- [ ] Guest names spelled correctly+- [ ] Episode number consistent+- [ ] No duplicate moments+- [ ] Category variety+- [ ] Target shorts count met++---++## Output Format++```markdown+# Content Review: Episode [X] — [Guest]++## Summary+- **Total items reviewed:** [X]+- **Blocking issues:** [X]+- **Warnings:** [X]+- **Status:** PASS / NEEDS FIXES++## Blocking Issues (Must Fix)++### [Issue 1]+- **Location:** [Where]+- **Problem:** [What's wrong]+- **Current:** "[problematic text]"+- **Suggested fix:** "[rewrite]"++## Warnings (Should Fix)++### [Warning 1]+- **Location:** [Where]+- **Suggestion:** [How to improve]++## Pass (No Issues)+[Items that passed all checks]+```++---++## Severity Levels++| Level | Meaning | Action |+|-------|---------|--------|+| **BLOCKING** | Banned word, fails voice check, title violation | Must fix |+| **WARNING** | Weak hook, borderline voice | Should fix |+| **INFO** | Minor improvement | Nice to have |diff --git a/CLAUDE.md b/CLAUDE.mdnew file mode 100644index 0000000..8256eb5--- /dev/null+++ b/CLAUDE.md@@ -0,0 +1,120 @@+# podcli + PodStack — AI Podcast Content Studio++> Transcribe, clip, and publish — all from one place.++You have two systems working together:++1. **podcli** — video processing engine (transcription, clip detection, rendering)+2. **PodStack** — content workflow (titles, descriptions, thumbnails, publishing)++Both share the same knowledge base at `.podcli/knowledge/`.++---++## Slash Commands (PodStack)++| Command | Role | What It Does |+|---------|------|-------------|+| `/process-transcript` | Content Analyst | Ingests transcript → extracts 8-15 moments → scores → categorizes |+| `/generate-titles` | Title Writer | Generates 8 title options with full verification checklist |+| `/generate-descriptions` | Copywriter | Creates descriptions + hashtags + SEO keywords |+| `/plan-thumbnails` | Art Director | Plans thumbnail text + layout briefs for both formats |+| `/review-content` | Brand Guardian | Reviews output against brand voice, quality gates, banned words |+| `/prep-episode` | Producer | Full pipeline: transcript → publish-ready package |+| `/publish-checklist` | Launch Manager | Pre/post-publish optimization checklist |+| `/retro-episode` | Analyst | Episode performance review + learnings |++---++## MCP Tools (podcli engine)++| Tool | What It Does |+|------|-------------|+| `transcribe_podcast` | Transcribe audio/video with Whisper + speaker detection |+| `suggest_clips` | Submit clip suggestions with duplicate check |+| `create_clip` | Render a single short-form clip (9:16, captions, audio norm) |+| `batch_create_clips` | Render multiple clips in one batch |+| `knowledge_base` | Read/write `.podcli/knowledge/` context files |+| `manage_assets` | Register/list logos, intros, outros |+| `clip_history` | View generated clips, check for duplicates |++---++## The Full Pipeline++```+/process-transcript → /generate-titles → /generate-descriptions → /plan-thumbnails → /review-content → /publish-checklist+ ↑ ↓+ Raw transcript Published content+```++Or run everything at once: `/prep-episode`++After publishing: `/retro-episode`++---++## Knowledge Base++All slash commands read from `.podcli/knowledge/`. This is where your show's brand, voice, and style live.++| File | What It Contains |+|------|-----------------|+| `00-master-instructions.md` | AI operating system, auto-detection rules |+| `01-brand-identity.md` | Show name, positioning, hosts, format |+| `02-voice-and-tone.md` | Voice fingerprint, banned words |+| `03-episodes-database.md` | Episode tracking, existing shorts |+| `04-shorts-creation-guide.md` | Moment selection criteria |+| `05-title-formulas.md` | Title shapes, rules, templates |+| `06-descriptions-template.md` | Description formulas, hashtags |+| `07-thumbnail-guide.md` | Thumbnail layouts, brand colors |+| `08-topics-themes.md` | Core topics, audience mapping |+| `09-content-workflow.md` | End-to-end workflow phases |+| `10-internal-processing.md` | Auto-execution rules |+| `11-inspiration-channels.md` | Reference channels, viral hooks |+| `12-quick-reference.md` | Copy-paste resources |++---++## Quality Gate (Always Active)++Before outputting ANY content:++1. **Would I click this?** — If no, rewrite+2. **Does it earn attention in 5 seconds?** — If no, find better hook+3. **Does it deliver on the promise?** — If no, it's clickbait, fix it+4. **Is it standalone?** — If context needed, unusable for shorts+5. **Zero banned words** — Check `02-voice-and-tone.md`+6. **The Coffee Test** — Sounds like a person, not a press release++---++## Auto-Detection++When input is provided without a specific command:++- **Transcript text or file** → Run `/process-transcript`+- **Asks for titles** → Run `/generate-titles`+- **Asks for thumbnails** → Run `/plan-thumbnails`+- **Asks for descriptions** → Run `/generate-descriptions`+- **Says "process episode"** → Run `/prep-episode`+- **Asks to review content** → Run `/review-content`++---++## Project Layout++```+├── CLAUDE.md ← You are here+├── .claude/commands/ ← PodStack slash commands+├── src/ ← TypeScript (MCP server, Web UI, services)+├── backend/ ← Python (Whisper, FFmpeg, captions)+├── .podcli/+│ ├── knowledge/ ← Your show's brand brain (13 .md files)+│ ├── output/ ← Rendered clips+│ ├── history/ ← Clip tracking+│ ├── assets/ ← Logos, intros, outros+│ ├── cache/ ← Transcription cache+│ └── presets/ ← Saved configs+└── episodes/ ← Content packages (PodStack output)+```diff --git a/README.md b/README.mdindex d1dfbb1..79df5c9 100644--- a/README.md+++ b/README.md@@ -5,26 +5,122 @@<img src="public/podcli-logo-transparent.png" height="36" alt="podcli" /></p><p align="center">- AI-powered podcast clip generator. Takes a long-form podcast video, identifies viral moments, and exports upload-ready TikTok / YouTube Shorts (1080x1920, 9:16, burned captions, normalized audio).+ AI-powered podcast content studio. Transcribe episodes, find viral moments, render upload-ready Shorts with burned captions — then generate titles, descriptions, thumbnails, and a full publish-ready content package. All from your terminal.</p>---+## What It Does++**podcli** takes a long-form podcast and turns it into a complete content operation:++```+Record episode+ ↓+Transcribe (Whisper, speaker detection)+ ↓+Find viral moments (audio energy + text heuristics)+ ↓+Render clips (9:16, captions, smart crop, normalized audio)+ ↓+Generate content package (titles, descriptions, thumbnails, SEO) ← PodStack+ ↓+Publish with optimization checklist ← PodStack+ ↓+Review performance ← PodStack+```++The first half is **video processing** — podcli's core engine. The second half is **content workflow** — powered by [PodStack](https://github.com/nmbrthirteen/podstack), a set of Claude Code slash commands that ship with podcli.++---++## How It Works (From a User's Perspective)++### 1. Drop in your episode++```bash+./setup.sh --ui+# → http://localhost:3847+```++Drag your video into the Web UI, or use the CLI:++```bash+./podcli process episode.mp4 --transcript transcript.txt --top 8+```++### 2. Get clips automatically++podcli analyzes your transcript + audio energy to find the best moments. It scores each one, suggests clips, and lets you toggle them on/off before rendering.++Clips come out as **upload-ready Shorts**: 1080x1920, 9:16 vertical, with burned-in captions, normalized audio, and your logo.++### 3. Generate the full content package++Open the project in **Claude Code** and run:++```+/prep-episode+```++This runs the [PodStack](https://github.com/nmbrthirteen/podstack) pipeline — a gstack-style workflow that gives you:++- **8-15 scored moments** with timestamps, categories, and reasoning+- **8 title options per clip** following your show's title spec (verified against 6 quality gates)+- **Ready-to-paste descriptions** with hooks, guest attribution, hashtags, SEO keywords+- **Thumbnail briefs** for both podcast (16:9) and shorts (9:16) formats+- **Brand review** that catches banned words, voice violations, and weak hooks+- **Publish checklist** covering pre-upload, at-publish, first-24-hours, and day 3-4 optimization++### 4. Publish and track++Run `/publish-checklist` when uploading. A week later, run `/retro-episode` with your YouTube Studio stats to see what worked and what to improve.++---++## The Two Halves++| | Video Engine (podcli core) | Content Workflow (PodStack) |+|---|---|---|+| **What** | Transcription, clip detection, rendering | Titles, descriptions, thumbnails, publishing |+| **How** | Python + FFmpeg + Whisper + OpenCV | Claude Code slash commands |+| **Interface** | Web UI, CLI, MCP tools | `/slash-commands` in Claude Code |+| **Output** | `.mp4` files ready to upload | Content packages ready to paste into YouTube |++Both halves share the same **knowledge base** (`.podcli/knowledge/`) — your show's brand, voice, title formulas, episode database, and style guide. Set it up once, everything stays on-brand.++---+## Features+### Video Processing- **Auto clip suggestion** — text heuristics + audio energy analysis-- **Burned-in captions** — 4 styles: branded (dark box highlight), hormozi (bold pop-on), karaoke (progressive highlight), subtle (clean bottom text)-- **Hardware-accelerated encoding** — auto-detects VideoToolbox (Mac), NVENC (NVIDIA), VAAPI, or CPU fallback+- **Burned-in captions** — 4 styles: branded, hormozi, karaoke, subtle+- **Hardware-accelerated encoding** — VideoToolbox (Mac), NVENC (NVIDIA), VAAPI, CPU fallback- **Smart cropping** — center crop or face detection (OpenCV)-- **Knowledge base** — drop `.md` files to give the AI context about your podcast, hosts, and style-- **Asset management** — register logos and videos by name for quick reuse-- **Clip history** — tracks all generated clips to avoid duplicates-- **Transcript import** — paste `Speaker (MM:SS)` format, JSON, or drag-and-drop `.txt` files-- **Whisper transcription** — auto-transcribe with OpenAI Whisper (tiny → large)-- **Preset system** — save and load named configurations per show-- **MCP server** — use as a Claude Desktop / Claude Code tool (7 tools)-- **Web UI** — single-page flow: input → suggest → review → export-- **CLI mode** — one-command processing: `./podcli process video.mp4 --top 5`+- **Whisper transcription** — auto-transcribe with speaker detection (tiny → large)+- **Transcript import** — paste `Speaker (MM:SS)`, JSON, drag-drop `.txt` / `.srt` / `.vtt`++### Content Workflow (PodStack)+- **`/process-transcript`** — extract and score best moments from any transcript+- **`/generate-titles`** — 8 titles per clip with 6-point verification checklist+- **`/generate-descriptions`** — descriptions + hashtags + SEO keywords+- **`/plan-thumbnails`** — thumbnail text + designer briefs for both formats+- **`/review-content`** — paranoid brand check (banned words, voice, title rules)+- **`/prep-episode`** — full pipeline: transcript → publish-ready package+- **`/publish-checklist`** — pre/post-publish optimization+- **`/retro-episode`** — performance analysis after publishing++### Infrastructure+- **Knowledge base** — `.md` files that teach the AI your brand, voice, and style+- **Asset management** — register logos and videos for quick reuse+- **Clip history** — tracks everything to avoid duplicates+- **Preset system** — save named configurations per show+- **MCP server** — 7 tools for Claude Desktop / Claude Code integration+- **Web UI** — single-page flow at `localhost:3847`+- **CLI** — one-command processing: `./podcli process video.mp4 --top 5`++---## Prerequisites@@ -33,11 +129,12 @@| **Node.js** >= 18 | [nodejs.org](https://nodejs.org) || **Python** >= 3.10 | [python.org](https://python.org) || **FFmpeg** | `brew install ffmpeg` / `sudo apt install ffmpeg` |+| **Claude Code** (optional) | [docs.anthropic.com](https://docs.anthropic.com/en/docs/claude-code) — needed for PodStack slash commands |## Quick Start```bash-git clone <repo-url> podcli+git clone https://github.com/nmbrthirteen/podcli.gitcd podclichmod +x setup.sh podcli./setup.sh@@ -48,8 +145,9 @@ This will:1. Check system dependencies (Node, Python, FFmpeg)2. Create a Python virtual environment and install packages3. Install Node packages and build TypeScript-4. Create the local `.podcli/` data directory-5. Launch the web UI at **http://localhost:3847**+4. Set up PodStack slash commands and knowledge base templates+5. Create the local `.podcli/` data directory+6. Launch the web UI at **http://localhost:3847**### Setup options@@ -60,6 +158,8 @@ This will:./setup.sh --mcp # print MCP config for Claude```+---+## Usage### Web UI@@ -102,7 +202,55 @@ This will:./podcli process video.mp4 --preset myshow```-### MCP Server (Claude integration)+### Content Workflow (PodStack)++Open the project in Claude Code, then use slash commands:++```bash+# Full pipeline — transcript to publish-ready package+/prep-episode++# Individual steps+/process-transcript # extract moments from a transcript+/generate-titles # get 8 title options for a clip+/generate-descriptions # get descriptions + hashtags+/plan-thumbnails # get thumbnail briefs for your designer+/review-content # brand and quality review+/publish-checklist # pre/post-publish ops+/retro-episode # performance analysis+```++Or just paste a transcript — Claude auto-detects the input and runs the right command.++---++## Knowledge Base++The knowledge base is what makes podcli understand *your* show. Drop `.md` files into `.podcli/knowledge/` and both the video engine and content workflow use them.++PodStack ships with **13 starter templates** that you fill in with your show's details:++| File | What It Teaches The AI |+|------|----------------------|+| `00-master-instructions.md` | Auto-detection rules, decision tree, quality gates |+| `01-brand-identity.md` | Show name, positioning, tagline, hosts, format |+| `02-voice-and-tone.md` | Voice fingerprint, banned words, the Coffee Test |+| `03-episodes-database.md` | Episode tracking, existing shorts (for dedup) |+| `04-shorts-creation-guide.md` | Moment types, selection criteria, extraction process |+| `05-title-formulas.md` | Title shapes, rules, templates by content type |+| `06-descriptions-template.md` | Description formulas, hashtag library, SEO keywords |+| `07-thumbnail-guide.md` | Layouts, brand colors, typography, visual specs |+| `08-topics-themes.md` | Core topics, cross-cutting themes, audience map |+| `09-content-workflow.md` | End-to-end workflow phases, handoff specs |+| `10-internal-processing.md` | Auto-execution rules, internal quality gates |+| `11-inspiration-channels.md` | Reference channels, viral hooks, hybrid formulas |+| `12-quick-reference.md` | Copy-paste hooks, hashtags, CTAs, checklists |++Manage via the web UI at `/knowledge.html` (drag & drop, inline editor) or through the `knowledge_base` MCP tool.++---++## MCP Server (Claude Integration)podcli is a [Model Context Protocol](https://modelcontextprotocol.io) server — Claude can use it as a tool to create clips through conversation.@@ -130,11 +278,11 @@ claude mcp add podcli -- node /path/to/podcli/dist/index.jsRun `./setup.sh --mcp` to get the exact config with your paths filled in.-#### MCP Tools+### MCP Tools| Tool | Description ||------|-------------|-| `transcribe_podcast` | Transcribe audio/video with Whisper |+| `transcribe_podcast` | Transcribe audio/video with Whisper + speaker detection || `suggest_clips` | Submit clip suggestions (includes duplicate check) || `create_clip` | Render a single short-form clip || `batch_create_clips` | Render multiple clips in one batch |@@ -142,18 +290,7 @@ Run `./setup.sh --mcp` to get the exact config with your paths filled in.| `manage_assets` | Register/list reusable assets (logos, videos) || `clip_history` | View previously created clips, check for duplicates |-## Knowledge Base--Drop `.md` files into `.podcli/knowledge/` to give the AI context about your podcast. The MCP server reads these before every request.--Suggested files:-- `podcast.md` — show name, format, episode structure-- `hosts.md` — host names, speaking styles-- `style.md` — preferred caption style, logo, colors-- `audience.md` — target audience, platform preferences-- `avoid.md` — topics or segments to skip--Manage via the web UI at `/knowledge.html` (drag & drop, inline editor) or through the `knowledge_base` MCP tool.+---## Caption Styles@@ -164,6 +301,8 @@ Manage via the web UI at `/knowledge.html` (drag & drop, inline editor) or throu| **karaoke** | Full sentence visible, words highlight progressively || **subtle** | Clean minimal white text at bottom |+---+## Project Structure```@@ -171,7 +310,17 @@ podcli/├── podcli # CLI entry point├── setup.sh # one-command install & launch├── package.json-├── .env.example+├── CLAUDE.md # PodStack master config+│+├── .claude/commands/ # PodStack slash commands+│ ├── process-transcript.md+│ ├── generate-titles.md+│ ├── generate-descriptions.md+│ ├── plan-thumbnails.md+│ ├── review-content.md+│ ├── prep-episode.md+│ ├── publish-checklist.md+│ └── retro-episode.md│├── src/ # TypeScript│ ├── index.ts # MCP server entry (stdio)@@ -200,10 +349,10 @@ podcli/│ └── caption_styles.py│└── .podcli/ # local data (gitignored)+ ├── knowledge/ # .md context files for AI (13 templates)├── assets/ # registered logos, videos├── cache/transcripts/ # cached transcriptions├── history/ # generated clip history- ├── knowledge/ # .md context files for AI├── output/ # rendered clips├── presets/ # saved configurations└── working/ # temp files@@ -234,6 +383,12 @@ Their response text here.The time offset field (default: -1s) shifts all timestamps to sync with audio.+---++## Credits++Content workflow powered by [PodStack](https://github.com/nmbrthirteen/podstack) — inspired by [gstack](https://github.com/garrytan/gstack) by Garry Tan.+## LicenseMIT