Video Notes

Video Notes

Turn a YouTube URL or local video file into two Markdown files: a key-points note and a full timestamped transcript.

Usage: /video-notes [--out-dir ] [--lang ]

Pipeline: a stdlib-only Python CLI fetches the transcript (YouTube subtitles first, Whisper API fallback) and emits transcript.json. You then read that JSON and author the two Markdown files yourself — the summary, key points, and chapters are your work, not a separate API call.

Step 1: Parse the arguments

From the user input extract:

• source — the YouTube URL or local file path (required)
• --out-dir — destination folder for the two Markdown files. If omitted,

default to ./video-notes/ in the current working directory.

• --lang — transcription language hint passed to Whisper (default en). Has

no effect when subtitles are used; only matters for the Whisper fallback.

Step 2: Check dependencies

Run which yt-dlp ffmpeg ffprobe curl. If any is missing, tell the user the install command (brew install yt-dlp ffmpeg, or your platform's equivalent) and stop. Do NOT check OPENAI_API_KEY yet — it is only needed if the video has no subtitles.

Step 3: Run the transcript pipeline

SKILL_DIR=
OUT=$(mktemp -d)
python3 "$SKILL_DIR/scripts/cli.py" "" --lang  --out "$OUT"

Notes:

• The scripts are stdlib-only — any Python 3.9+ works. If you prefer an isolated

interpreter, create a venv once (python3 -m venv .venv) and use its python; no pip install is needed.

• On success the command prints the path to $OUT/transcript.json.
• The CLI surfaces clean errors (exit code ≠ 0):
• "Not a recognized YouTube URL or existing local file" → bad source argument.
• "OPENAIAPIKEY is not set" → the video had no subtitles and Whisper is

needed; tell the user to export OPENAI_API_KEY and re-run.

• A yt-dlp failure on a private/members-only video → report it and note that

--cookies-from-browser may be needed.

Step 4: Read the transcript

Read $OUT/transcript.json. Schema:

{
  "meta": {"type","title","source","channel","duration","video_id"},
  "transcript_source": "subtitles" | "whisper",
  "segments": [{"start": 8.16, "text": "…"}]
}

start is in seconds.

Step 5: Author the two output files

Write both files into the --out-dir (default ./video-notes/). Build the slug YYYY-MM-DD- — lower-case, kebab-case, ASCII-safe. For YouTube sources prefer the video's ORIGINAL upload date (yt-dlp upload_date); otherwise use today's date.

-notes.md

Frontmatter:

---
title: 
source: 
channel: 
duration: 
date: 
tags: [video-notes]
---

Body:

• ## TL;DR — a 3-5 sentence summary you write from the transcript.
• ## Key Points — key points grouped by theme (bullet list).
• ## Chapters — chapters as - [MM:SS] topic. Derive chapter boundaries by

reading the transcript and grouping segments by topic shift; use the start of the first segment in each group, formatted MM:SS (or H:MM:SS past an hour). For YouTube sources, make each timestamp a link: [MM:SS](&t=s).

Write the note in the same language as the video (or whatever language the user asks for). For consistent formatting you may reuse the shipped helpers in scripts/transcript.py: fmt_timestamp(seconds) returns "MM:SS"/"H:MM:SS" and youtube_link(url, seconds) builds the &t=Ns link (returns None for local sources). Either call them or format by hand to the same convention.

-transcript.md

Frontmatter (title, source, type: transcript), then every segment on its own line as [MM:SS] text.

Step 6: Report

Print the two absolute output paths and the one-line TL;DR so the user can jump straight to the files.

Extending: route notes into your own knowledge base

--out-dir is the seam for personal workflows. Point it at, say, an Obsidian vault's inbox and add your own frontmatter convention (extra entities:, source_url, compiled: false, etc.) in Step 5. The pipeline stays generic; the destination and the note schema are yours to customize.

Source & license

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

• Author: iamvista
• Source: iamvista/video-notes
• License: MIT

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