YouTube video summarizer with speaker detection, formatted documents, and audio output. Works out of the box with macOS built-in TTS. Optional recommended tools (pandoc, ffmpeg, mlx-audio) enhance quality. Requires internet for YouTube access. No paid APIs or subscriptions. Use when user sends a YouTube URL or asks to summarize/transcribe a YouTube video.
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
🔊 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:
Spawn sub-agent with the full pipeline task immediately
Reply: "🎬 TubeScribe is processing — I'll let you know when it's ready!"
Continue conversation (don't wait!)
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:
bash
python skills/tubescribe/scripts/setup.py
This checks: summarize CLI, pandoc, ffmpeg, Kokoro TTS
Full Workflow (Single Sub-Agent)
Spawn ONE sub-agent that does the entire pipeline:
python
sessions_spawn(
task=f"""
## TubeScribe: Process {youtube_url}
⚠️ CRITICAL: Do NOT install any software.
No pip, brew, curl, venv, or binary downloads.
If a tool is missing, STOP and report what's needed.
Run the COMPLETE pipeline — do not stop until all steps are done.
### Step 1: Extract
```bash
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:
# **<title>**
Video info block — Channel, Date, Duration, URL (clickable). Empty line between each field.
## **Participants** — table with bold headers:
text
Write the summary text to a temp file, then use TubeScribe's built-in audio generation:
bash
# Write summary to temp file (use python3 to write, avoids shell escaping issues)
python3 -c "
text = '''YOUR SUMMARY TEXT HERE'''
with open('<temp_dir>/tubescribe_<video_id>_summary.txt', 'w') as f:
f.write(text)
"
# Generate audio (auto-detects engine, voice, format from config)
python3 skills/tubescribe/scripts/tubescribe.py \
--generate-audio <temp_dir>/tubescribe_<video_id>_summary.txt \
--audio-output ~/Documents/TubeScribe/<safe_title>_summary
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.