tubescribe

# 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. ### 💸 100% Free & Local - **No subscription** — runs entirely on your machine - **No API keys required** — works out of the box - **No data leaves your computer** — your content stays private - **No usage limits** — summarize as many videos as you want ### ✨ Features - **🎯 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 - **📄 Transcript with summary and key quotes** — Export as DOCX, HTML, or Markdown - **📋 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. 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: ```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} Run the COMPLETE pipeline — do not stop until all steps are done. ### Step 1: Extract ```bash python3 /Users/matusvojtek/.openclaw/workspace/skills/tubescribe/scripts/tubescribe.py "{youtube_url}" ``` Note the video_id from the output (e.g., "Source: /tmp/tubescribe_ABC123_source.json" → video_id is ABC123). ### Step 2: Read source JSON Read `/tmp/tubescribe_<video_id>_source.json` and note: - metadata.title (for filename) - metadata.video_id - metadata.channel, upload_date, duration_string ### Step 3: Create formatted markdown Write to `/tmp/tubescribe_<video_id>_output.md`: 1. `# **<title>**` --- 2. Video info block (Channel, Date, Duration, clickable URL) --- 3. `## **Participants**` — table with bold headers: ``` | **Name** | **Role** | **Description** | |----------|----------|-----------------| ``` --- 4. `## **Summary**` — 3-5 paragraphs --- 5. `## **Key Quotes**` — 5 best with clickable YouTube timestamps. Format each as: ``` "Quote text here." - [12:34](https://www.youtube.com/watch?v=ID&t=754s) "Another quote." - [25:10](https://www.youtube.com/watch?v=ID&t=1510s) ``` 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: ``` Comment text here. *- ▲ 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: ```bash pandoc /tmp/tubescribe_<video_id>_output.md -o ~/Documents/TubeScribe/<safe_title>.docx ``` ### Step 5: Generate audio ```bash cd ~/.openclaw/tools/kokoro && source .venv/bin/activate ``` Then Python: read Summary from markdown, generate with Kokoro (voice=0.6*af_heart+0.4*af_sky), save as MP3 to ~/Documents/TubeScribe/<safe_title>_summary.mp3 ### Step 6: Cleanup ```bash python3 /Users/matusvojtek/.openclaw/workspace/skills/tubescribe/scripts/tubescribe.py --cleanup <video_id> ``` ### Step 7: Open folder ```bash open ~/Documents/TubeScribe/ ``` ### Report Tell what was created: DOCX name, MP3 name + duration, video stats. """, label="tubescribe", runTimeoutSeconds=900, cleanup="delete" ) ``` **After spawning, reply immediately:** > 🎬 Processing "[video title if known, or just the URL]" — I'll let you know when it's ready! Then continue the conversation. The sub-agent notification announces completion. ## Configuration Config file: `~/.tubescribe/config.json` ```json { "output": { "folder": "~/Documents/TubeScribe", "open_folder_after": true, "open_document_after": false, "open_audio_after": false }, "document": { "format": "docx", "engine": "pandoc" }, "audio": { "enabled": true, "format": "mp3", "tts_engine": "builtin" }, "kokoro": { "venv_path": "~/.tubescribe/kokoro-env", "voice_blend": { "af_heart": 0.6, "af_sky": 0.4 }, "speed": 1.05 }, "processing": { "subagent_timeout": 600, "cleanup_temp_files": true } } ``` ### Output Options | Option | Default | Description | |--------|---------|-------------| | `output.folder` | `~/Documents/TubeScribe` | Where to save files | | `output.open_folder_after` | `true` | Open output folder when done | | `output.open_document_after` | `false` | Auto-open generated document | | `output.open_audio_after` | `false` | Auto-open generated audio summary | ### Document Options | Option | Default | Values | Description | |--------|---------|--------|-------------| | `document.format` | `docx` | `docx`, `html`, `md` | Output format | | `document.engine` | `pandoc` | `pandoc` | Converter for DOCX (falls back to HTML) | ### Audio Options | Option | Default | Values | Description | |--------|---------|--------|-------------| | `audio.enabled` | `true` | `true`, `false` | Generate audio summary | | `audio.format` | `mp3` | `mp3`, `wav` | Audio format (mp3 needs ffmpeg) | | `audio.tts_engine` | `builtin` | `builtin`, `kokoro` | TTS engine (builtin = macOS say) | ### Kokoro TTS Options (optional) | Option | Default | Description | |--------|---------|-------------| | `kokoro.venv_path` | `~/.tubescribe/kokoro-env` | Python venv with Kokoro installed | | `kokoro.voice_blend` | `{af_heart: 0.6, af_sky: 0.4}` | Custom voice mix | | `kokoro.speed` | `1.05` | Playback speed (1.0 = normal, 1.05 = 5% faster) | ### Processing Options | Option | Default | Description | |--------|---------|-------------| | `processing.subagent_timeout` | `600` | Seconds for sub-agent (increase for long videos) | | `processing.cleanup_temp_files` | `true` | Remove /tmp files after completion | ### Comment Options | Option | Default | Description | |--------|---------|-------------| | `comments.max_count` | `50` | Number of comments to fetch | | `comments.timeout` | `90` | Timeout for comment fetching (seconds) | ### Queue Options | Option | Default | Description | |--------|---------|-------------| | `queue.stale_minutes` | `30` | Consider a processing job stale after this many minutes | ## Output Structure ``` ~/Documents/TubeScribe/ ├── {Video Title}.html # Formatted document (or .docx / .md) └── {Video Title}_summary.mp3 # Audio summary (or .wav) ``` After generation, opens the folder (not individual files) so you can access everything. ## Dependencies **Required:** - `summarize` CLI — `brew install steipete/tap/summarize` - Python 3.8+ **Optional (better quality):** - `pandoc` — DOCX output: `brew install pandoc` - `ffmpeg` — MP3 audio: `brew install ffmpeg` - `yt-dlp` — YouTube comments: `brew install yt-dlp` - Kokoro TTS — High-quality voices: see https://github.com/hexgrad/kokoro ### yt-dlp Search Paths TubeScribe checks these locations (in order): | Priority | Path | Source | |----------|------|--------| | 1 | `which yt-dlp` | System PATH | | 2 | `/opt/homebrew/bin/yt-dlp` | Homebrew (Apple Silicon) | | 3 | `/usr/local/bin/yt-dlp` | Homebrew (Intel) / Linux | | 4 | `~/.local/bin/yt-dlp` | pip install --user | | 5 | `~/.local/pipx/venvs/yt-dlp/bin/yt-dlp` | pipx | | 6 | `~/.openclaw/tools/yt-dlp/yt-dlp` | TubeScribe auto-install | If not found, setup downloads a standalone binary to the tools directory. The tools directory version doesn't conflict with system installations. ## Queue Handling When user sends multiple YouTube URLs while one is processing: ### Check Before Starting ```bash python skills/tubescribe/scripts/tubescribe.py --queue-status ``` ### If Already Processing ```bash # Add to queue instead of starting parallel processing python skills/tubescribe/scripts/tubescribe.py --queue-add "NEW_URL" # → Replies: "📋 Added to queue (position 2)" ``` ### After Completion ```bash # Check if more in queue python skills/tubescribe/scripts/tubescribe.py --queue-next # → Automatically pops and processes next URL ``` ### Queue Commands | Command | Description | |---------|-------------| | `--queue-status` | Show what's processing + queued items | | `--queue-add URL` | Add URL to queue | | `--queue-next` | Process next item from queue | | `--queue-clear` | Clear entire queue | ### Batch Processing (multiple URLs at once) ```bash