Video Notes

Video Notes Skill

Convert any YouTube video into a polished, self-contained HTML notes document with:

• Executive summary (~300 words) capturing the core arguments
• AI-generated structured notes with SVG diagrams
• Keyframe gallery — screenshots auto-captured at key moments, each linking back to YouTube
• Fixed sidebar navigation with scroll-spy
• Searchable raw subtitle panel (click any line → jump to that timestamp)

Workflow

Step 1: Extract Subtitles

python3 ~/.claude/skills/video-notes/scripts/extract_subtitles.py  --output /tmp/subs.json

• Default language: en. Pass --lang zh or --lang zh-Hans for Chinese.
• On HTTP 429 errors, retry after a few seconds or try a different language.
• If the video has no auto-generated captions, inform the user and stop.

Output: [{"t": "mm:ss", "s": 123.4, "text": "..."}]

Step 2: Capture Keyframes (requires ffmpeg)

Run the keyframe script. It scores subtitles using heuristics, selects the most important moments (spaced ≥60s apart), downloads only those short video sections, and extracts frames:

python3 ~/.claude/skills/video-notes/scripts/capture_keyframes.py \
   /tmp/subs.json \
  --max-frames 8 \
  --output-json /tmp/keyframes.json

Output: [{"t": "mm:ss", "s": 123.4, "text": "...", "score": 0.5, "image_b64": "..."}]

• If ffmpeg is not installed, skip this step and set {{KEYFRAMES_JSON}} to [] in the template — the gallery section will auto-hide.
• Default --max-frames is 8; reduce for faster generation or increase for longer videos.

Step 3: Read and Understand the Content

Read the subtitle text to understand:

• The video's main topic and overall structure
• Key concepts, arguments, frameworks, and terminology
• Any notable quotes or memorable lines
• Natural section boundaries (topic shifts)

Step 4: Generate HTML Notes

Use assets/note-template.html as the foundation. Fill in each placeholder:

| Placeholder | Content | |---|---| | {{TITLE}} | Page ` tag | | {{SIDEBARNAV}} | .sb-logo block + .nav-a links for each section | | {{SUMMARY}} | Executive summary HTML (see below) | | {{MAINCONTENT}} | Hero block + all note sections | | {{SUBTITLESECNUM}} | Section number for the subtitle panel (e.g. 6) | | {{VIDEOURL}} | Full YouTube URL | | {{VIDEOID}} | YouTube video ID (e.g. dQw4w9WgXcQ) | | {{SUBTITLEJSON}} | Full JSON array from Step 1 | | {{KEYFRAMESJSON}} | Full JSON array from Step 2 (or [] if skipped) | | {{SECTION_IDS}} | JS array: ['hero','summary','s1','s2','keyframes','subtitles']` |

Executive Summary ({{SUMMARY}})

Write ~300 words of HTML paragraphs inside `` tags. Structure:

1. One-sentence core thesis — what is the speaker's central claim?
2. Main argument 1 — first major thread (2–3 sentences)
3. Main argument 2 — second major thread
4. Main argument 3 — third major thread (if applicable)
5. Closing — key prediction, implication, or call to action

Use ` for emphasis. Keep line-height loose (line-height:2`).

Hero Section

Always include a hero section (id="hero") with:

• .hero-badge: speaker name + event/source
• ``: video title (concise, impactful)
• .hero-sub: speaker · role · note type
• .chips: 3–5 topic tags
• .hero-quote: the single most memorable quote

Note Sections

For each major topic area, create `` with:

• .sec-hd header (numbered .sec-n + .sec-title)
• Content using: .card, .g2/.g3 grids, .diag SVG diagrams, .tl timelines, .ql quotes

SVG Diagrams (.diag blocks)

Generate SVGs for comparisons, progressions, and architectures:

Background: rgba(R,G,B,.4) fill + rgba(R,G,B,.3) stroke
Labels: fill="#fff" font-weight="700"; sublabels: fill="#aaa" font-size="9-10"
Arrows: › in , colored to match the row
Connectors: stroke="rgba(255,255,255,.12)" stroke-dasharray="3,3"

Color palette:

• Blue flow: #5b8dee → #9b7cf4 | Green flow: #3ecf8e → #5b8dee
• Old/danger: rgba(244,63,94,.4) | Mid: rgba(240,169,70,.4) | New: rgba(62,207,142,.4)

Sidebar Navigation

  🎬
  {{Short Title}}
  {{Speaker}} · {{Source}}

🏠概览
✦核心总结

🎬关键画面
📄原始字幕

Step 5: Save and Open

open /tmp/-notes.html   # macOS

Tell the user: save path, subtitle entry count, keyframe count, sections covered.

Quality Guidelines

• Summary is mandatory — always write the executive summary; it's the first thing readers see.
• Keyframes add context — when ffmpeg is available, always capture frames; they anchor abstract concepts to real visuals.
• Depth over breadth — 4–7 well-developed sections beat 12 shallow ones.
• Diagrams are mandatory when content has comparisons, progressions, or architectures.
• Language matching — write in the same language as the user's request, regardless of the video's language.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 2992638402-art
• Source: 2992638402-art/video-notes
• License: MIT

Install and usage instructions live in the source repository linked above.