Claude Skill

tubescribe

YouTube video summarizer with speaker detection, formatted documents, and audio output.

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download alekseiul-sprut-agent-kit-skills_tubescribe-bb8e6a1.zip · 42 KB

Install

skills CLI npx skills add https://github.com/AlekseiUL/sprut-agent-kit/tree/main/skills/tubescribe
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alekseiul-sprut-agent-kit@llmmart
Git git clone https://github.com/AlekseiUL/sprut-agent-kit.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole alekseiul/sprut-agent-kit collection as a plugin from our marketplace. Git is the plain clone.

README

TubeScribe 🎬

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

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

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

Free & No Paid APIs

  • No subscriptions — no API keys, no paid services
  • No usage limits — process as many videos as you want
  • Local processing — transcription, speaker detection, TTS all run on your machine
  • Network access — YouTube fetching (video metadata, captions, comments) requires internet

Quick Start

Just send a YouTube URL to your agent. TubeScribe handles everything automatically.

Non-Blocking Processing

TubeScribe runs in the background:

  1. You send a YouTube link
  2. Agent replies: "🎬 TubeScribe is processing [title]..."
  3. You can keep chatting — conversation isn't blocked
  4. When done, you get notified with the results

No waiting, no freezing — just seamless async processing.

First-Time Setup

python skills/tubescribe/scripts/setup.py

What setup.py does: Checks if recommended tools are present (summarize, pandoc, ffmpeg, TTS engine) and offers to install any missing ones. It only downloads from official sources (Homebrew, PyPI, GitHub releases). You can skip any install — the skill works without them using macOS built-in TTS and HTML fallback.

What setup.py does NOT do: It does not upload data, contact unknown hosts, or modify system files outside ~/.claudeclaw/tools/ and ~/.tubescribe/.

Output Example

~/Documents/TubeScribe/
├── Interview With Expert.docx    # Formatted document
└── Interview With Expert.mp3     # Audio summary

Document Structure

  1. Title + video info (channel, date, duration)
  2. Participants — who's speaking
  3. Summary — key points in 3-5 paragraphs
  4. Key Quotes — 5 best moments with clickable timestamps
  5. Viewer Sentiment — what commenters are saying
  6. Best Comments — top 5 comments by likes
  7. Full Transcript — merged paragraphs with speaker labels

Batch & Queue

Multiple videos at once

tubescribe url1 url2 url3

Queue management

tubescribe --queue-add "URL"      # Add while processing
tubescribe --queue-status         # Check queue
tubescribe --queue-next           # Process next
tubescribe --queue-clear          # Clear queue

Configuration

Config file: ~/.tubescribe/config.json

Setting Default Options
document.format docx docx, html, md
audio.format mp3 mp3, wav
audio.tts_engine mlx mlx, kokoro, builtin
mlx_audio.voice_blend {af_heart: 0.6, af_sky: 0.4} any voice mix
output.folder ~/Documents/TubeScribe any path

Requirements

  • Required: summarize CLI (brew install steipete/tap/summarize)
  • Optional:
    • pandoc — DOCX output (brew install pandoc)
    • ffmpeg — MP3 audio (brew install ffmpeg)
    • yt-dlp — YouTube comments (brew install yt-dlp)
    • mlx-audio — Fastest TTS on Apple Silicon (auto-installed via setup)
    • Kokoro TTS — PyTorch fallback for non-Apple-Silicon (auto-installed via setup)

yt-dlp Installation

TubeScribe checks these locations for yt-dlp (in order):

  1. System PATH (which yt-dlp)
  2. Homebrew: /opt/homebrew/bin/yt-dlp or /usr/local/bin/yt-dlp
  3. pip/pipx: ~/.local/bin/yt-dlp
  4. TubeScribe tools: ~/.claudeclaw/tools/yt-dlp/yt-dlp

If not found, setup will offer to download a standalone binary to the tools directory.

Error Handling

Clear messages for common issues:

Issue Message
Private video ❌ Video is private — can't access
No captions ❌ No captions available for this video
Invalid URL ❌ Not a valid YouTube URL
Age-restricted ❌ Age-restricted video — can't access without login

Privacy & Network

What uses the network:

  • summarize CLI / yt-dlp — fetches video captions, metadata, and comments from YouTube
  • setup.py — one-time download of tools (pandoc, ffmpeg, yt-dlp, TTS models) from official sources

What runs locally (no network):

  • Speaker detection and transcript analysis (Claude sub-agent, same as your main agent)
  • TTS audio generation (MLX-Audio Kokoro, Apple say, or Kokoro PyTorch — all on-device)
  • Document generation (pandoc)
  • Audio conversion (ffmpeg)

No data is uploaded anywhere. Video content is fetched from YouTube, processed on your machine, and saved locally. Nothing is sent back.

Config paths (~/.tubescribe/config.json) point to local TTS installations on your machine (e.g., ~/.claudeclaw/tools/mlx-audio). These are not remote services.

Security

Code Injection (Fixed in v1.1.0)

Earlier development versions had a vulnerability where video text could be injected into dynamically executed Python code. This was fixed by properly escaping all text with json.dumps().

HTML Output (Fixed in v1.1.2+)

  • XSS prevention: all text escaped before inline formatting
  • Single-quote escaping added in v1.1.3
  • Link double-encoding fixed in v1.1.3

Archive Extraction (Fixed in v1.1.3)

Zip-slip path traversal prevention when installing pandoc/yt-dlp via setup script.

Shell Commands

The skill uses subprocess to call external CLI tools (summarize, yt-dlp, pandoc, ffmpeg). YouTube URLs are validated and normalized before processing, and filenames are sanitized. However, as with any tool that processes external content, review the code if you have concerns.

External Dependencies

The setup script downloads tools from official sources:

  • pandoc — from Homebrew or official releases
  • yt-dlp — from GitHub releases (yt-dlp/yt-dlp)
  • mlx-audio — pip install from PyPI (Apple Silicon only, uses MLX framework)
  • Kokoro TTS — pip install from PyPI (PyTorch, cross-platform fallback)

All sources are well-known and widely used. Review scripts/setup.py if you have concerns about supply chain security.

License

MIT


Made by Jackie 🦊 & Matus 🇸🇰

Skill manifest

metadata: { "claudeclaw": { "emoji": "🎬", "requires": { "bins": ["summarize"] } } }

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. 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:

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:

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:

  1. # **<title>**

  1. Video info block — Channel, Date, Duration, URL (clickable). Empty line between each field.

  1. ## **Participants** — table with bold headers:
    | **Name** | **Role** | **Description** |
    |----------|----------|-----------------|
    

  1. ## **Summary** — 3-5 paragraphs of prose

  1. ## **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.

  1. ## **Viewer Sentiment** (if comments exist)

  1. ## **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.

  1. ## **Full Transcript** — merge segments, speaker labels, clickable timestamps

Step 4: Create DOCX

Clean the title for filename (remove special chars), then:

pandoc <output_path> -o ~/Documents/TubeScribe/<safe_title>.docx

Step 5: Generate audio

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

# 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.

Step 6: Cleanup

python3 skills/tubescribe/scripts/tubescribe.py --cleanup <video_id>

Step 7: Open folder

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:**
> 🎬 TubeScribe is processing - 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": "mlx"
  },
  "mlx_audio": {
    "path": "~/.claudeclaw/tools/mlx-audio",
    "model": "mlx-community/Kokoro-82M-bf16",
    "voice": "af_heart",
    "lang_code": "a",
    "speed": 1.05
  },
  "kokoro": {
    "path": "~/.claudeclaw/tools/kokoro",
    "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 mlx mlx, kokoro, builtin TTS engine (mlx = fastest on Apple Silicon)

MLX-Audio Options (preferred on Apple Silicon)

Option Default Description
mlx_audio.path ~/.claudeclaw/tools/mlx-audio mlx-audio venv location
mlx_audio.model mlx-community/Kokoro-82M-bf16 MLX model to use
mlx_audio.voice af_heart Voice preset (used if no voice_blend)
mlx_audio.voice_blend {af_heart: 0.6, af_sky: 0.4} Custom voice mix (weighted blend)
mlx_audio.lang_code a Language code (a=US English)
mlx_audio.speed 1.05 Playback speed (1.0 = normal, 1.05 = 5% faster)

Kokoro PyTorch Options (fallback)

Option Default Description
kokoro.path ~/.claudeclaw/tools/kokoro Kokoro repo location
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
  • mlx-audio — Fastest TTS on Apple Silicon: pip install mlx-audio (uses MLX backend for Kokoro)
  • Kokoro TTS — PyTorch fallback: 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 ~/.claudeclaw/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

python skills/tubescribe/scripts/tubescribe.py --queue-status

If Already Processing

# 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

# 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)

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

Processes all URLs sequentially with a summary at the end.

Error Handling

The script detects and reports these errors with clear messages:

Error Message
Invalid URL ❌ Not a valid YouTube URL
Private video ❌ Video is private — can't access
Video removed ❌ Video not found or removed
No captions ❌ No captions available for this video
Age-restricted ❌ Age-restricted video — can't access without login
Region-blocked ❌ Video blocked in your region
Live stream ❌ Live streams not supported — wait until it ends
Network error ❌ Network error — check your connection
Timeout ❌ Request timed out — try again later

When an error occurs, report it to the user and don't proceed with that video.

Tips

  • For long videos (>30 min), increase sub-agent timeout to 900s
  • Speaker detection works best with clear interview/podcast formats
  • Single-speaker videos (tutorials, lectures) skip speaker labels automatically
  • Timestamps link directly to YouTube at that moment
  • Use batch mode for multiple videos: tubescribe url1 url2 url3
Files (sprut-agent-kit)
  • .clawhub
    • origin.json 142 B
      Loading…
  • scripts
    • config.py 8.4 KB
      Loading…
    • html_writer.py 12.6 KB
      Loading…
    • setup.py 28.2 KB
      Loading…
    • tubescribe.py 49.1 KB
      Loading…
  • CHANGELOG.md 16.4 KB
    Loading…
  • README.md 6.6 KB
    # TubeScribe 🎬
    
    **Turn any YouTube video into a polished document + audio summary.**
    
    Drop a YouTube link → get a beautiful transcript with speaker labels, key quotes, clickable timestamps, and an audio summary you can listen to on the go.
    
    ## 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
    
    ## Free & No Paid APIs
    
    - **No subscriptions** — no API keys, no paid services
    - **No usage limits** — process as many videos as you want
    - **Local processing** — transcription, speaker detection, TTS all run on your machine
    - **Network access** — YouTube fetching (video metadata, captions, comments) requires internet
    
    ## Quick Start
    
    Just send a YouTube URL to your agent. TubeScribe handles everything automatically.
    
    ### Non-Blocking Processing
    
    TubeScribe runs in the background:
    1. You send a YouTube link
    2. Agent replies: "🎬 TubeScribe is processing **[title]**..."
    3. **You can keep chatting** — conversation isn't blocked
    4. When done, you get notified with the results
    
    No waiting, no freezing — just seamless async processing.
    
    ### First-Time Setup
    
    ```bash
    python skills/tubescribe/scripts/setup.py
    ```
    
    **What setup.py does:** Checks if recommended tools are present (`summarize`, `pandoc`, `ffmpeg`, TTS engine) and offers to install any missing ones. It only downloads from official sources (Homebrew, PyPI, GitHub releases). You can skip any install — the skill works without them using macOS built-in TTS and HTML fallback.
    
    **What setup.py does NOT do:** It does not upload data, contact unknown hosts, or modify system files outside `~/.claudeclaw/tools/` and `~/.tubescribe/`.
    
    ## Output Example
    
    ```
    ~/Documents/TubeScribe/
    ├── Interview With Expert.docx    # Formatted document
    └── Interview With Expert.mp3     # Audio summary
    ```
    
    ### Document Structure
    
    1. **Title** + video info (channel, date, duration)
    2. **Participants** — who's speaking
    3. **Summary** — key points in 3-5 paragraphs
    4. **Key Quotes** — 5 best moments with clickable timestamps
    5. **Viewer Sentiment** — what commenters are saying
    6. **Best Comments** — top 5 comments by likes
    7. **Full Transcript** — merged paragraphs with speaker labels
    
    ## Batch & Queue
    
    ### Multiple videos at once
    ```bash
    tubescribe url1 url2 url3
    ```
    
    ### Queue management
    ```bash
    tubescribe --queue-add "URL"      # Add while processing
    tubescribe --queue-status         # Check queue
    tubescribe --queue-next           # Process next
    tubescribe --queue-clear          # Clear queue
    ```
    
    ## Configuration
    
    Config file: `~/.tubescribe/config.json`
    
    | Setting | Default | Options |
    |---------|---------|---------|
    | `document.format` | `docx` | `docx`, `html`, `md` |
    | `audio.format` | `mp3` | `mp3`, `wav` |
    | `audio.tts_engine` | `mlx` | `mlx`, `kokoro`, `builtin` |
    | `mlx_audio.voice_blend` | `{af_heart: 0.6, af_sky: 0.4}` | any voice mix |
    | `output.folder` | `~/Documents/TubeScribe` | any path |
    
    ## Requirements
    
    - **Required:** `summarize` CLI (`brew install steipete/tap/summarize`)
    - **Optional:**
      - `pandoc` — DOCX output (`brew install pandoc`)
      - `ffmpeg` — MP3 audio (`brew install ffmpeg`)
      - `yt-dlp` — YouTube comments (`brew install yt-dlp`)
      - mlx-audio — Fastest TTS on Apple Silicon (auto-installed via setup)
      - Kokoro TTS — PyTorch fallback for non-Apple-Silicon (auto-installed via setup)
    
    ### yt-dlp Installation
    
    TubeScribe checks these locations for yt-dlp (in order):
    
    1. System PATH (`which yt-dlp`)
    2. Homebrew: `/opt/homebrew/bin/yt-dlp` or `/usr/local/bin/yt-dlp`
    3. pip/pipx: `~/.local/bin/yt-dlp`
    4. TubeScribe tools: `~/.claudeclaw/tools/yt-dlp/yt-dlp`
    
    If not found, setup will offer to download a standalone binary to the tools directory.
    
    ## Error Handling
    
    Clear messages for common issues:
    
    | Issue | Message |
    |-------|---------|
    | Private video | ❌ Video is private — can't access |
    | No captions | ❌ No captions available for this video |
    | Invalid URL | ❌ Not a valid YouTube URL |
    | Age-restricted | ❌ Age-restricted video — can't access without login |
    
    ## Privacy & Network
    
    **What uses the network:**
    - `summarize` CLI / `yt-dlp` — fetches video captions, metadata, and comments from YouTube
    - `setup.py` — one-time download of tools (pandoc, ffmpeg, yt-dlp, TTS models) from official sources
    
    **What runs locally (no network):**
    - Speaker detection and transcript analysis (Claude sub-agent, same as your main agent)
    - TTS audio generation (MLX-Audio Kokoro, Apple `say`, or Kokoro PyTorch — all on-device)
    - Document generation (pandoc)
    - Audio conversion (ffmpeg)
    
    **No data is uploaded anywhere.** Video content is fetched *from* YouTube, processed on your machine, and saved locally. Nothing is sent back.
    
    **Config paths (`~/.tubescribe/config.json`)** point to local TTS installations on your machine (e.g., `~/.claudeclaw/tools/mlx-audio`). These are not remote services.
    
    ## Security
    
    ### Code Injection (Fixed in v1.1.0)
    Earlier development versions had a vulnerability where video text could be injected into dynamically executed Python code. This was fixed by properly escaping all text with `json.dumps()`.
    
    ### HTML Output (Fixed in v1.1.2+)
    - XSS prevention: all text escaped before inline formatting
    - Single-quote escaping added in v1.1.3
    - Link double-encoding fixed in v1.1.3
    
    ### Archive Extraction (Fixed in v1.1.3)
    Zip-slip path traversal prevention when installing pandoc/yt-dlp via setup script.
    
    ### Shell Commands
    The skill uses subprocess to call external CLI tools (`summarize`, `yt-dlp`, `pandoc`, `ffmpeg`). YouTube URLs are validated and normalized before processing, and filenames are sanitized. However, as with any tool that processes external content, review the code if you have concerns.
    
    ### External Dependencies
    The setup script downloads tools from official sources:
    - **pandoc** — from Homebrew or official releases
    - **yt-dlp** — from GitHub releases (yt-dlp/yt-dlp)
    - **mlx-audio** — pip install from PyPI (Apple Silicon only, uses MLX framework)
    - **Kokoro TTS** — pip install from PyPI (PyTorch, cross-platform fallback)
    
    All sources are well-known and widely used. Review `scripts/setup.py` if you have concerns about supply chain security.
    
    ## License
    
    MIT
    
    ---
    
    Made by Jackie 🦊 & Matus 🇸🇰
    
  • SKILL.md 12.5 KB
    ---
    name: tubescribe
    description: "YouTube video summarizer with speaker detection, formatted documents, and audio output."
    triggers:
      - youtube url
      - summarize video
      - transcribe video
      - саммари видео
      - транскрипт youtube
      - разбери видео
    ---
    metadata:
      {
        "claudeclaw":
          {
            "emoji": "🎬",
            "requires": { "bins": ["summarize"] }
          }
      }
    ---
    
    # 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. 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}
    
    ⚠️ 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:
    
    1. `# **<title>**`
    ---
    2. Video info block — Channel, Date, Duration, URL (clickable). Empty line between each field.
    ---
    3. `## **Participants**` — table with bold headers:
       ```
       | **Name** | **Role** | **Description** |
       |----------|----------|-----------------|
       ```
    ---
    4. `## **Summary**` — 3-5 paragraphs of prose
    ---
    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 <output_path> -o ~/Documents/TubeScribe/<safe_title>.docx
    ```
    
    ### Step 5: Generate audio
    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.
    
    ### Step 6: Cleanup
    ```bash
    python3 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:**
    > 🎬 TubeScribe is processing - 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": "mlx"
      },
      "mlx_audio": {
        "path": "~/.claudeclaw/tools/mlx-audio",
        "model": "mlx-community/Kokoro-82M-bf16",
        "voice": "af_heart",
        "lang_code": "a",
        "speed": 1.05
      },
      "kokoro": {
        "path": "~/.claudeclaw/tools/kokoro",
        "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` | `mlx` | `mlx`, `kokoro`, `builtin` | TTS engine (mlx = fastest on Apple Silicon) |
    
    ### MLX-Audio Options (preferred on Apple Silicon)
    | Option | Default | Description |
    |--------|---------|-------------|
    | `mlx_audio.path` | `~/.claudeclaw/tools/mlx-audio` | mlx-audio venv location |
    | `mlx_audio.model` | `mlx-community/Kokoro-82M-bf16` | MLX model to use |
    | `mlx_audio.voice` | `af_heart` | Voice preset (used if no voice_blend) |
    | `mlx_audio.voice_blend` | `{af_heart: 0.6, af_sky: 0.4}` | Custom voice mix (weighted blend) |
    | `mlx_audio.lang_code` | `a` | Language code (a=US English) |
    | `mlx_audio.speed` | `1.05` | Playback speed (1.0 = normal, 1.05 = 5% faster) |
    
    ### Kokoro PyTorch Options (fallback)
    | Option | Default | Description |
    |--------|---------|-------------|
    | `kokoro.path` | `~/.claudeclaw/tools/kokoro` | Kokoro repo location |
    | `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`
    - mlx-audio — Fastest TTS on Apple Silicon: `pip install mlx-audio` (uses MLX backend for Kokoro)
    - Kokoro TTS — PyTorch fallback: 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 | `~/.claudeclaw/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
    python skills/tubescribe/scripts/tubescribe.py url1 url2 url3
    ```
    Processes all URLs sequentially with a summary at the end.
    
    ## Error Handling
    
    The script detects and reports these errors with clear messages:
    
    | Error | Message |
    |-------|---------|
    | Invalid URL | ❌ Not a valid YouTube URL |
    | Private video | ❌ Video is private — can't access |
    | Video removed | ❌ Video not found or removed |
    | No captions | ❌ No captions available for this video |
    | Age-restricted | ❌ Age-restricted video — can't access without login |
    | Region-blocked | ❌ Video blocked in your region |
    | Live stream | ❌ Live streams not supported — wait until it ends |
    | Network error | ❌ Network error — check your connection |
    | Timeout | ❌ Request timed out — try again later |
    
    When an error occurs, report it to the user and don't proceed with that video.
    
    ## Tips
    
    - For long videos (>30 min), increase sub-agent timeout to 900s
    - Speaker detection works best with clear interview/podcast formats
    - Single-speaker videos (tutorials, lectures) skip speaker labels automatically
    - Timestamps link directly to YouTube at that moment
    - Use batch mode for multiple videos: `tubescribe url1 url2 url3`
    
  • _meta.json 129 B
    Loading…

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.