youtube-study-note

youtube-study-note Skill

Core philosophy

Treat a video as a time-indexed evidence source, not just a blob of media.

1. Define the goal first: quick skim, full study note, critique, screenshots, or visual summary.
2. Prefer text timeline over raw visual analysis: subtitles > auto subtitles > local audio transcription > visual sampling.
3. Use screenshots only as evidence for important visual moments, not as decoration.
4. Default the HTML report to core-content mode: suppress creator intros, channel promotion, series setup, repeated disclaimers, and other edge context unless the user asks for a complete archive. Lead with the video's actionable core ideas.
5. Translate domain jargon before using it. For technical/finance/trading videos, add plain-language concept cards that explain what each term solves, not just what it is called. When a video is jargon-heavy, generate one built-in imagegen concept illustration per core term and render it inside that term's concept card. Put these concept cards before the overview and route sections so later summaries can use the terms without forcing the reader to guess them first.
6. Separate evidence from interpretation:
   • [FACT]: explicitly stated or shown in the video.
   • [AUTHOR_VIEW]: the creator's claim, opinion, framework, or recommendation.
   • [MODEL_INFERENCE]: inferred by the agent from transcript/frames.
   • [COUNTERPOINT]: adversarial or alternative explanation.
   • [JUDGMENT]: final synthesis with confidence.
7. Generate new explanatory images as original learning aids. Do not reproduce video frames with image generation.
8. Treat the default HTML as a video replacement course pack, not a summary page. The main reading path must teach the core ideas without requiring the learner to open the original video. Original links and screenshots are source evidence only.
9. For trading, finance, medicine, law, or other high-risk domains, add a safety layer: clarify that concepts are learning frameworks, list misuse risks, and require independent validation before action.

Default note packages are written under ~/Documents/video-note unless the user passes --out. Each video gets one self-contained folder named from the video title:

~/Documents/video-note/<video-title-slug>/

Treat that folder as the video learning package. Keep the transcript, JSON artifacts, Markdown report, HTML preview, screenshots, source transcript copies, and logs inside it so the package can be reopened or moved as one unit. For human browsing, also write chapter-level notes under:

~/Documents/video-note/<video-title-slug>/chapters/<chapter-title-slug>/

Each chapter folder should include chapter.md, chapter.json, and any selected frames for that chapter.

Boundaries

Default to private-note safe mode:

• Do not download full YouTube video unless the user says the content is their own, authorized, or they explicitly accept local private-study processing.
• First attempt metadata and subtitles/auto subtitles without downloading media.
• If no subtitles exist, extract audio only for transcription.
• Extract video frames only after a timestamped frame plan exists.
• Prefer short sections around selected timestamps over full-video downloads.
• Do not bypass paywalls, DRM, private access controls, or platform restrictions.
• Do not publish, redistribute, or claim ownership over extracted frames.
• For public sharing, use YouTube timestamp links/embeds instead of screenshots.
• Generated summary images must be original explainer visuals. Prefer a clear 小黑-style viewpoint map over decorative metaphors: pure white 16:9 canvas, thin black hand-drawn linework, one matte-black blob protagonist actively explaining the map, sparse colored handwritten Chinese labels, and no beige paper texture, shadows, gradients, dense cards, or copied video imagery. Use metaphors only when they make the actual video argument easier to understand.

Preflight

Before running tools, check local dependencies:

node "<skill-dir>/scripts/check-deps.mjs"

Required:

• macOS Apple Silicon recommended
• Python 3.10+
• Node.js 20+
• yt-dlp
• ffmpeg / ffprobe

Optional:

• mlx-whisper Python package for local transcription when no subtitles exist
• Built-in imagegen skill/tool for raster learning illustrations.

Recommended workflow

Fast path: one-shot safe mode

Use run for the default private-note workflow. It prepares evidence, generates deterministic first-pass analysis files, renders the report, and writes run-review artifacts under ~/Documents/video-note/<video-title-slug> when --out is omitted. YouTube URLs may use the v= video id only as a temporary bootstrap path before metadata is known; the final package should be rehomed to the title folder.

python3 "<skill-dir>/scripts/video_tool.py" run \
  --input "https://www.youtube.com/watch?v=VIDEO_ID"

If YouTube asks for bot/sign-in confirmation during metadata or subtitle extraction, retry with a local browser cookie source only for private local processing:

python3 "<skill-dir>/scripts/video_tool.py" run \
  --input "https://www.youtube.com/watch?v=VIDEO_ID" \
  --cookies-from-browser chrome

Or use an exported Netscape-format cookies file:

python3 "<skill-dir>/scripts/video_tool.py" run \
  --input "https://www.youtube.com/watch?v=VIDEO_ID" \
  --cookies "/path/to/youtube-cookies.txt"

The helper passes --js-runtimes node to yt-dlp by default because modern YouTube extraction may require a JavaScript runtime. Use --tool-timeout 120 or lower when diagnosing a browser-cookie or network stall.

For an existing transcript file, avoid media access entirely:

python3 "<skill-dir>/scripts/video_tool.py" run \
  --input "https://www.youtube.com/watch?v=VIDEO_ID" \
  --transcript "/path/to/transcript.json" \
  --title "Original video title"

When YouTube has no caption track but a reviewed external transcript is available, pass both --input and --transcript. The note package keeps the YouTube URL/ID for timestamp links while avoiding media download.

The one-shot safe-mode output includes:

• metadata.json
• transcript.json
• transcript.md
• summary.json
• debate.json
• frame_plan.json
• lesson_units.json
• visual_storyboard.json
• assessment.json
• asset_health.json
• replacement_review.json
• image_prompts.json
• generated_images.json
• generated/ after running the image step
• chapters/ with one folder per chapter title
• run_review.json
• notes_for_next_run.md
• report.md
• report.html
• index.html
• frames/
• source_transcripts/
• logs/

Safe mode does not save public-video frames. Use timestamp links in frame_plan.json and report.md unless the user explicitly authorizes local frame extraction.

1. Prepare evidence packet

Use prepare to collect metadata and transcript.

python3 "<skill-dir>/scripts/video_tool.py" prepare \
  --input "https://www.youtube.com/watch?v=VIDEO_ID" \
  --languages "zh.*,en.*" \
  --whisper-model "mlx-community/whisper-large-v3-turbo"

The tool writes:

• metadata.json
• transcript.json
• transcript.md
• agent_packet.json
• logs/prepare.log

2. Agent analysis

Run the deterministic first-pass analyzer, or have the agent read agent_packet.json and transcript.md for deeper model-assisted analysis.

python3 "<skill-dir>/scripts/video_tool.py" analyze \
  --out "~/Documents/video-note/VIDEO_ID"

• summary.json
• debate.json
• frame_plan.json
• image_prompts.json

Follow the schemas in references/schemas.md.

Frame plan rules:

• Choose 3-12 timestamps maximum.
• Prefer frames where visual content adds meaning: diagrams, slides, whiteboard, code, charts, UI operations, formulas, or final summary cards.
• For each timestamp, include reason, topic, evidence_quote, and need_frame.
• If a segment is pure talking head and no visual evidence is needed, set need_frame: false.

3. Extract authorized frames

Only run this when user allows local frame extraction.

python3 "<skill-dir>/scripts/video_tool.py" frames \
  --input "https://www.youtube.com/watch?v=VIDEO_ID" \
  --out "~/Documents/video-note/VIDEO_ID" \
  --frame-plan "~/Documents/video-note/VIDEO_ID/frame_plan.json" \
  --mode authorized

The tool extracts candidates at t-2, t, t+2, then creates frames/index.json for agent review.

4. Frame review

For each candidate group, choose the best frame or discard all. Write:

• frames/selected_frames.json

Keep only frames that improve the core content. Discard frames for intros, self-promotion, creator biography, and transition filler unless they contain an essential concept.

5. Generate original hand-drawn summary images

The analyzer creates image_prompts.json, including overall viewpoint maps and concept-level illustrations for extracted jargon. Use the built-in imagegen skill/tool to generate each prompt as a real bitmap image. Built-in imagegen saves under $CODEX_HOME/generated_images/...; copy or register those final images into the video package before rendering.

After built-in imagegen returns image files, register them:

python3 "<skill-dir>/scripts/video_tool.py" image \
  --out "~/Documents/video-note/VIDEO_ID" \
  --image-prompts "~/Documents/video-note/VIDEO_ID/image_prompts.json" \
  --asset sketch_map_01="~/.codex/generated_images/.../first.png" \
  --asset review_card_01="~/.codex/generated_images/.../second.png" \
  --render

The image step writes:

• generated/sketch_map_01.png
• generated/review_card_01.png
• generated_images.json

These are real raster image files rendered in index.html and report.md, not prompts for the user to copy. Keep these visuals as built-in imagegen drawings rather than SVG approximations. The default style should feel like a 小黑 hand-drawn explainer: pure white background, 16:9 landscape, lots of whitespace, and legible short labels. Concept images must teach one term at a time; viewpoint maps should expose the video's core argument, objections, and practical takeaway. Do not make abstract machinery if it hides the meaning.

6. Render report

python3 "<skill-dir>/scripts/video_tool.py" render \
  --out "~/Documents/video-note/VIDEO_ID"

Output:

• report.md
• report.html
• index.html

Open index.html first for the interactive study view. The HTML is a standalone local page that uses only files from the same video folder. It should include:

• a 5-minute route, plain-language concept course cards, and the core learning path before chapter details
• chapter-level screenshots from frames/selected_frames.json, aligned to the chapter they support
• chapter-level Agent judgment with four fields: useful point, misuse, verification condition, and personal handling
• all-video controversy synthesis before chapter-by-chapter author/skeptic/judge comparison
• source timestamp links for evidence checking, not as the main learning path
• scored review questions with answers and explanations, plus a local scratchpad saved in the browser
• a replacement score from replacement_review.json; below 85 means the package is useful but should not be described as a complete replacement for the video

Adversarial analysis pattern

Always run four passes, even if implemented by one model:

1. Summarizer: explain the author fairly.
2. Skeptic: identify missing evidence, ambiguity, bias, weak causality, survivorship bias, or overclaiming.
3. Counter-Analyst: reconstruct the strongest alternative interpretation.
4. Judge: synthesize what is useful, what is questionable, what needs verification, and how confident the agent is.

Use timestamp evidence for every major claim.

Self-optimization loop

After each successful run, update local experience only with verified observations:

python3 "<skill-dir>/scripts/video_tool.py" remember \
  --out "./video_notes/VIDEO_ID" \
  --source "youtube.com" \
  --note "Auto captions for this channel were noisy; mlx-whisper large-v3-turbo performed better for mixed Chinese/English audio."

Write experience under references/video-patterns/. Do not store private transcript excerpts there unless the user explicitly wants that.

References index

• references/boundaries.md: legal/safety/product boundaries for private notes.
• references/schemas.md: JSON schemas for summary, debate, frame plan, image prompts.
• references/prompts.md: reusable prompts for summarization, critique, frame selection, and image generation.
• references/video-patterns/: local verified experience, updated incrementally.