JoeyRedfield/videobook

VideoBook: Turn a Video into an Illustrated eBook

Given a YouTube / Bilibili link by the user, produce a readable technical eBook: output/<video_id>/book.md + book.html (with embedded player card, click-to-enlarge screenshots, Mermaid diagrams), and optionally transcript.corrected.txt (corrected transcript) and publish to GitHub Pages for others to read.

This skill is the orchestration layer and is self-contained: all instructions needed by the agent are in this directory (SKILL.md + references/), and do not rely on the repo's instructions.md / README.md (those are for human readers, kept untouched and not maintained by this skill). The only external dependency is the pipeline's executable code src/*.py: commands and parameters must follow the script's --help output; do not rewrite script logic. Volatile data (e.g., the mispronunciation MAP in src/make_corrected.py) must not be copied into the skill; only state the rule and point to the source file. The one exception is the formatting instruction for step 2: this directory carries an in-tree copy at references/stitcher-prompt.md (the repo version takes precedence).

Prerequisites (must read before first run)

1. Working directory = videobook repo root (check: existence of src/dump_transcript.py and prompts/), all relative paths (output/<video_id>/...) are resolved relative to it. If the repo is not local, first git clone https://github.com/Luke-Evan/videobook.git into the user's code projects directory (do not use a temporary directory or create a separate projects folder), then cd into it.
2. Python >= 3.10 (recommended 3.12). Install dependencies: uv sync (when using uv) or pip install -r requirements.txt. Execute commands using the repo's environment interpreter: uv run python src/xxx.py or .venv/Scripts/python.exe src/xxx.py.
3. One-time login: python src/capture_frames.py --setup-profile opens a dedicated Chrome (data directory .capture-profile/), log in to Bilibili / YouTube via QR code, then close the window; the login state is reused long-term. The membership tier of the logged-in account determines the maximum screenshot resolution.
4. For overseas videos: terminal must use proxy (for subtitle fetching), browser also needs global proxy (otherwise the YouTube iframe in the generated page shows a black block).
5. Commands requiring elevated privileges (outside sandbox) are noted in the last column of the overview table; purely local steps can run inside the sandbox.

Pipeline Overview

Step	What it does	Command	Details	Elevated Privileges
1	Fetch subtitles	python src/dump_transcript.py "<URL>"	references/transcript.md	Bilibili needs
1b	Local ASR fallback when platform has no subtitles	python src/asr_transcript.py <video_id>	references/transcript.md	No (time-consuming)
1.5	Official course notes + 4K slides (run by default, skip only if the course has no homepage)	python src/course_assets.py <video_id> --course-url <course homepage>	references/course-assets.md	Needs for rendering
2	LLM rewrites subtitles into book.md	Follow formatting instructions (references/stitcher-prompt.md; use the repo prompts/stitcher_system.md if it exists)	references/writing.md	No
2b	Corrected transcript (optional)	python src/make_corrected.py <video_id>	references/correction.md	No
3	Capture frames and materialize placeholders into images	python src/capture_frames.py <video_id> "<URL>"	references/capture.md	Yes
4	Render HTML + start local preview	python src/post_process.py "<URL>" output/<id>/book.md then python -m http.server 8080 --directory output/<id>	—	No
5	Inform user of results, ask about large file cleanup	—	See "Delivery" below	—
6	Publish output to pages branch (optional)	python src/publish.py <video_id> then git push origin pages	references/publish.md	No (push needs network)

For errors, quality issues, subtitle fetch failures, ASR interruptions, first check references/troubleshooting.md.

Hard Rules (non-negotiable)

1. If subtitle coverage < 50% (exit code 3), do not proceed to step 2: first fix login state/proxy, or switch to ASR fallback.
2. All screenshot frames must come from the platform player in a logged-in browser; step 3 must never download video/audio files (ffmpeg frame extraction is only the last resort). See references/capture.md for a list of prohibited methods.
3. Cookies are written only to the system temp directory and deleted after use; never commit them to the repo or manually place cookies.txt in the workspace.
4. output/ is unaffected by any git operations; deliverables are published only to the orphan pages branch; main contains only code.
5. Fidelity of correction draft: preserve the original wording and order of the lecturer paragraph by paragraph; only perform ASR mispronunciation replacement + filler word cleanup; no paragraph deletion, no line merging, no heavy rewriting (the validation layer will reject it).
6. Fidelity baseline for writing: Written form ≠ summary; retain analogies, examples, derivation chains; editor additions must be marked with "Editor's note".
7. Copyright of course materials: notes and slides belong to the lecturer (commonly CC BY-NC); the book's opening info block and closing section must retain source links, author attribution, and license name.
8. Slide coverage rule: each page in slides_text.md must appear exactly once in the book; --audit must PASS before submission.
9. Delete large files (audio.m4a, video_source.mp4, etc.) only after asking the user and receiving confirmation.
10. When generating or modifying HTML, ensure text-to-background contrast ratio is no lower than WCAG AA's 4.5:1.
11. Each step is idempotent and re-runnable: before materializing placeholders, the script automatically backs up book.tagged.md; as long as it exists, re-running step 3 can restore screenshots.

Delivery (step 5 must convey all at once)

1. Location of output/<video_id>/book.md;
2. Preview URL http://localhost:8080/book.html; stop the server by pressing Ctrl+C in the terminal;
3. YouTube videos require the browser to access YouTube (proxy); Bilibili videos can be watched directly;
4. Screenshot quality depends on the membership tier of the account logged in .capture-profile/; to get higher quality, log in with a different account and re-run step 3;
5. When official course materials are used, note that the slides in the book are official 4K renders (the book header already notes the source and CC license), demo frames are still video frames; the course/ directory can be deleted entirely without affecting reading;
6. Ask whether to delete large media files generated during the pipeline (Hard Rule 9).

Directory Contents (read on demand, not all at once)

File	When to read
references/transcript.md	Step 1 fetching subtitles; if platform has no subtitles, switch to local ASR
references/writing.md	Step 2 rewriting subtitles into book.md
references/stitcher-prompt.md	Step 2 original formatting instructions (use repo prompts/stitcher_system.md if it exists)
references/course-assets.md	Step 1.5 when course has an official homepage, slide coverage rules, slide upgrades
references/correction.md	Generating corrected transcript and AI line-level correction proposals
references/capture.md	Step 3 frame capture: priority order, explicitly prohibited methods, QA habits
references/publish.md	Step 6 publishing to pages branch
references/troubleshooting.md	Any errors, quality anomalies, subtitle fetch failures, elevated privilege denial

Maintenance Conventions

• This skill is versioned together with the pipeline code in the same repo: if parameters, step order, or hard rules in src/*.py change, this directory must be updated accordingly.
• The repo's instructions.md and README.md are for human readers and are kept untouched; this skill does not maintain them. Do not modify them to make the skill work; when content overlaps with this directory, the agent defers to this directory.
• When syncing references/stitcher-prompt.md, update the commit hash in the source note at the file header.
• For others to install: use skill-installer with --repo Luke-Evan/videobook --path skills/videobook; or after cloning, copy/symlink this directory to ~/.codex/skills/ (Codex only) or ~/.agents/skills/ (cross-agent).
• This directory contains no cookies, login state, output/ artifacts, or any media files, and can be safely distributed publicly.