TubeScribe 🎬

Turn any YouTube video into a polished document + audio summary.

Drop a YouTube link → get a beautiful transcript with speaker labels, key quotes, timestamps that link back to the video, and an audio summary you can listen to on the go.

💸 Free & No Paid APIs

• - No subscriptions or API keys — works out of the box
• Local processing — transcription, speaker detection, and TTS run on your machine
• Network access — fetching from YouTube (captions, metadata, comments) requires internet
• No data uploaded — nothing is sent to external services; all processing stays on your machine
• Safe sub-agent — spawned sub-agent has strict instructions: no software installation, no network calls beyond YouTube

✨ Features

• - 📄 Transcript with summary and key quotes — Export as DOCX, HTML, or Markdown
• 🎯 Smart Speaker Detection — Automatically identifies participants
• 🔊 Audio Summaries — Listen to key points (MP3/WAV)
• 📝 Clickable Timestamps — Every quote links directly to that moment in the video
• 💬 YouTube Comments — Viewer sentiment analysis and best comments
• 📋 Queue Support — Send multiple links, they get processed in order
• 🚀 Non-Blocking Workflow — Conversation continues while video processes in background

🎬 Works With Any Video

• - Interviews & podcasts (multi-speaker detection)
• Lectures & tutorials (single speaker)
• Music videos (lyrics extraction)
• News & documentaries
• Any YouTube content with captions

Quick Start

When user sends a YouTube URL:

1. 1. Spawn sub-agent with the full pipeline task immediately
2. Reply: "🎬 TubeScribe is processing — I'll let you know when it's ready!"
3. Continue conversation (don't wait!)
4. Sub-agent notification will announce completion with title and details

DO NOT BLOCK — spawn and move on instantly.

First-Time Setup

Run setup to check dependencies and configure defaults:

CODEBLOCK0

This checks: summarize CLI, pandoc, ffmpeg, INLINECODE3

Full Workflow (Single Sub-Agent)

Spawn ONE sub-agent that does the entire pipeline:

CODEBLOCK1bash
python3 skills/tubescribe/scripts/tubescribe.py "{youtube_url}"

Note the **Source** and **Output** paths printed by the script. Use those exact paths in subsequent steps.

### Step 2: Read source JSON
Read the Source path from Step 1 output and note:
- metadata.title (for filename)
- metadata.video_id
- metadata.channel, upload_date, duration_string

### Step 3: Create formatted markdown
Write to the Output path from Step 1:

1. `# **<title>**`
---
2. Video info block — Channel, Date, Duration, URL (clickable). Empty line between each field.
---
3. `## **Participants**` — table with bold headers:
   

---
4. `## **Summary**` — 3-5 paragraphs of prose
---
5. `## **Key Quotes**` — 5 best with clickable YouTube timestamps. Format each as:
   

"Another quote." - 25:10

   Use regular dash `-`, NOT em dash `—`. Do NOT use blockquotes `>`. Plain paragraphs only.
---
6. `## **Viewer Sentiment**` (if comments exist)
---
7. `## **Best Comments**` (if comments exist) — Top 5, NO lines between them:
   

- ▲ 123 @AuthorName

Next comment text here.

- ▲ 45 @AnotherAuthor

   Attribution line: dash + italic. Just blank line between comments, NO `---` separators.

---
8. `## **Full Transcript**` — merge segments, speaker labels, clickable timestamps

### Step 4: Create DOCX
Clean the title for filename (remove special chars), then:

### Step 5: Generate audio
Write the summary text to a temp file, then use TubeScribe's built-in audio generation:

This reads `~/.tubescribe/config.json` and uses the configured TTS engine (mlx/kokoro/builtin), voice blend, and speed automatically. Output format (mp3/wav) comes from config.

### Step 6: Cleanup

### Step 7: Open folder

python skills/tubescribe/scripts/tubescribe.py url1 url2 url3