# Knowledge Video Decomposer

> Extract, normalize, segment, and audit first-hand video, audio, subtitle, transcript, or video URL material before any report is written. Use for source gates, ASR, Chrome/page probes, and video_analysis_pack creation.

- Skill: `sitabanubanu/knowledge-video-decomposer` (Agent Skill, multi-file: 26 files)
- Install (CLI): `npx skillmds@latest add sitabanubanu/knowledge-video-decomposer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sitabanubanu/knowledge-video-decomposer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: sitabanubanu (https://skillmd.com/u/sitabanubanu)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/sitabanubanu/knowledge-video-decomposer

---


# Knowledge Video Decomposer

Use this skill to turn source-gated transcript, subtitle, ASR, or approved local
material into a structured knowledge package. In v0.6, platform acquisition is
owned by `acquire-source-material`; this skill's old platform acquisition scripts
are legacy compatibility paths.

Core workflow:
1. Inspect the source and collect metadata.
2. Before processing any video URL or platform page, read references/chrome-routing.md, references/chrome-probe-contract.md, references/source-status.md, and references/platform-prerequisites.md.
3. When starting a new platform workflow, diagnosing an environment failure, or handing the workflow to a new Agent, run scripts/doctor.py and save doctor_report.json / doctor_report.md under logs or 00_source. Doctor is read-only: it checks yt-dlp, ffmpeg/ffprobe, faster-whisper, Node.js, Chrome plugin files, cookies-file presence, Chromium App-Bound signals, Python encoding, and UTF-8 writing, but does not fetch media, launch Chrome, install extensions, or reveal cookie values.
4. Legacy only: use scripts/acquisition_runner.py for old first-pass platform acquisition probing. New URL acquisition should create `00_acquisition/manifest.json` through `acquire-source-material`.
5. Legacy only: use scripts/platform_media_runner.py for old URL-to-material chains. New URL acquisition should be handed off through the acquisition bundle protocol.
6. Use scripts/acquisition_probe.py to record source status, source classes, failed probes, Chrome routing state, and the next allowed route when probe results already exist or when another tool produced the evidence.
7. Platform blocks, HTTP 429, bot/CAPTCHA/login barriers, RequestBlocked errors, or Hearsay URL timeouts on platform URLs must enter the Chrome route decision in references/chrome-routing.md instead of repeating the same extractor.
8. When a yt-dlp bare request or youtube_transcript_api hits a platform block (HTTP 429, bot check, sign-in required, RequestBlocked), first identify the browser that actually owns the authorized login state, then try `--cookies-from-browser edge` or `--cookies-from-browser chrome` as appropriate, or use a user-exported Netscape `cookies.txt`. Never infer the browser from the control-plugin name.
9. If the selected browser profile is locked or cookie decryption fails, do not loop over profiles or silently switch browser families. Follow references/platform-prerequisites.md: request approval before closing the actual browser, or request a user-exported Netscape `cookies.txt`; never read, display, copy, or commit cookie values.
10. If yt-dlp with cookies exposes only storyboards/images or reports `n challenge solving failed`, add a supported JavaScript runtime such as Node.js and, when accepted, `--remote-components ejs:github` before declaring media unavailable.
11. After yt-dlp with cookies, Chrome page inspection, or browser-derived probing obtains subtitles, audio, or a browser-visible transcript, that material must pass through source-status gating (references/source-status.md) before entering full decomposition.
12. Legacy/manual route: when Chrome opens a page and no visible transcript or caption UI is present, the old Chrome deep-probe sequence may still record observations, but new workflows should convert any user-approved transcript, subtitle, page text, or media export into an acquisition bundle before source-gate ingest.
13. Use references/chrome-probe-contract.md and scripts/chrome_media_probe.py for legacy normalization or manual adapter work only. Chrome observations must not bypass the source gate.
14. If Chrome deep-probe succeeds (an actual local media file or subtitle file was exported, or a public downloadable media/subtitle URL was confirmed and fetched), and subsequent ASR or subtitle parsing succeeds, the material qualifies as browser_derived_media - a primary source class that can support source_confirmed. Refer to references/source-status.md for the exact definition and recording requirements.
15. If no primary transcript, no browser-derived media, and no user-provided or legitimately acquired local file exists, stop full decomposition and request primary material. Record that the missing requirement is primary media/transcript, not merely a better prompt.
16. Prefer reliable existing subtitles or transcripts from the platform, yt-dlp (with the explicitly selected Edge/Chrome profile or user-exported cookies as needed), user-provided files, or local parsers - subject to the source-status gate.
17. Use scripts/asr_pipeline.py when a legitimate local audio/video file exists and subtitles/transcripts are unavailable or insufficient. The pipeline runs or resumes faster-whisper ASR, normalizes the transcript, records `primary_audio_asr` provenance, writes ASR quality, alignment, and diarization-compatible reports, and then hands off to segmentation. Missing word timestamps or speaker labels must degrade gracefully and must not turn ASR into a verified verbatim transcript.
18. Use scripts/transcript_normalizer.py to normalize local transcript/subtitle material (`.txt`, `.md`, `.srt`, `.vtt`, `.jsonl`, `.json`) into `01_transcript/raw_transcript.jsonl`, `01_transcript/clean_transcript.jsonl`, and `01_transcript/clean_transcript.md`. The normalizer may open the decomposition gate for source-confirmed transcript material, but it must not write segments, inventory, logic, or video_analysis_pack.
19. Normalize transcript material into timestamped artifacts where timestamps exist, and record transcript provenance, language, confidence, and known limitations.
20. Use scripts/transcript_segmenter.py to segment confirmed/partial transcript material into `02_segments/subtitle_segments.json`, `02_segments/syntax_segments.json`, and `02_segments/argument_segments.json`. Subtitle segments are a readability/timing layer; argument segments are the semantic/rhetorical layer. The segmenter may write `05_gap_check/segmentation_gap_check.md`, but it must not write inventory, source logic, or video_analysis_pack.
21. Use scripts/inventory_extractor.py to extract candidate concepts, examples, claims, and analogies into `03_inventory/`. Inventory entries must preserve evidence spans and remain candidates until source logic review verifies them. The extractor must not write source logic or video_analysis_pack.
22. Use scripts/source_logic_builder.py to reconstruct source-faithful speaker logic into `04_logic/source_logic.md` and `04_logic/logic_graph.json`. This stage may write source-logic gap notes, but it must not add external critique, downstream interpretation, or video_analysis_pack.
23. Use scripts/evidence_auditor.py after source logic exists to audit transcript, segment, inventory, and graph evidence. It writes `05_gap_check/evidence_audit.json`, `05_gap_check/evidence_map.json`, `05_gap_check/claim_source_audit.json`, and `05_gap_check/gap_check.md`; it must not write `video_analysis_pack.md`. Claims require transcript-backed spans, examples require concrete context, and source-logic nodes require transcript-backed evidence.
24. Use scripts/video_analysis_pack_builder.py only after `05_gap_check/evidence_audit.json`, `05_gap_check/evidence_map.json`, and `05_gap_check/claim_source_audit.json` exist and the audit `pack_gate` allows a full or explicitly partial pack. This stage writes `video_analysis_pack.md` and must preserve the full/partial scope label.
25. Preserve evidence links to timestamps or source spans.
26. For Chinese, non-ASCII, Markdown, or JSON artifacts, use scripts/write_artifact.py, apply_patch, or another verified UTF-8 path. Do not write long Chinese artifacts through shell here-strings, inline command strings, PowerShell `>` redirection, or other paths that can silently change encoding or turn characters into question marks.
27. In `source_blocked`, `source_failed`, `secondary_only`, or `degraded_report_only`, do not pre-create the full analysis directory shape (`01_transcript`, `02_segments`, `03_inventory`, `04_logic`, `05_gap_check`) and do not create `video_analysis_pack.md`. Write only `00_source` notes plus a clearly labeled degraded/acquisition report.
28. Validate outputs with scripts/artifact_validator.py before handing them downstream.
29. Output a video_analysis_pack for knowledge-document-composer only after evidence audit and validation pass for an allowed full or explicitly partial source status.

Runner guidance:
- Use scripts/doctor.py before acquisition when the environment is unknown, after a tool-path failure, or before long platform runs. Treat doctor failures as environment/setup issues, not source-content failures.
- Read the doctor `setup_requirements` table before declaring a source blocked or failed. `yt-dlp`, relevant media tools, Chrome plugin readiness, safe UTF-8 writing, and route-specific ASR/cookies/Node prerequisites must be separated from content availability.
- User-exported cookies, extension installation/approval, CAPTCHA/paywall/private/region permission, and local primary-material handoff are manual user steps. Do not automate or fake them.
- `--youtube-cookies auto` means only `work/youtube-cookies/youtube.cookies.txt`; it must not trigger Downloads scanning, browser-cookie extraction, full-disk search, or opening cookie contents.
- Legacy only: use scripts/acquisition_runner.py when reproducing older URL probe behavior. Listed subtitles or media formats are only available routes; they are not `source_confirmed` until a local subtitle/transcript/audio-derived transcript artifact exists.
- Legacy only: use scripts/platform_media_runner.py when reproducing older URL acquisition chains. Downloaded audio must still be followed by scripts/asr_pipeline.py; it is recorded as `pending_primary_media_for_asr`, not as `primary_audio_asr`.
- Legacy/manual adapter only: use scripts/chrome_media_probe.py after Chrome/pageAssets/Playwright inspection has produced layer observations. It writes standard Chrome deep-probe artifacts and suggests the acquisition signal, but it does not launch or control Chrome by itself.
- Use scripts/asr_pipeline.py for local audio/video that has been user-provided or legitimately acquired. It should produce `01_transcript/asr_transcript.jsonl`, canonical `clean_transcript` artifacts, `00_source/asr_pipeline_report.json`, `00_source/asr_pipeline_report.md`, `00_source/asr_alignment_report.json`, and `00_source/asr_diarization.json`.
- Use scripts/transcript_normalizer.py after a transcript/subtitle file exists. It writes transcript artifacts and source-status metadata only; it does not perform semantic decomposition.
- Use scripts/transcript_segmenter.py after `01_transcript/clean_transcript.jsonl` exists and source status is `source_confirmed` or explicitly partial. It writes `02_segments/subtitle_segments.json`, `02_segments/syntax_segments.json`, and `02_segments/argument_segments.json` only and leaves inventory, source logic, and pack creation to later stages.
- Use scripts/inventory_extractor.py after `02_segments/argument_segments.json` exists. It writes `03_inventory` artifacts and inventory gap notes only; source logic and final pack creation remain later stages.
- Use scripts/source_logic_builder.py after `03_inventory` exists. It writes `04_logic` artifacts and source-logic gap notes only; final pack creation remains a later gated stage.
- Use scripts/evidence_auditor.py after `04_logic/logic_graph.json` and `04_logic/source_logic.md` exist. It writes final pre-pack gap artifacts plus `evidence_map.json` and `claim_source_audit.json`, then returns whether the next stage may build a full pack, a partial pack, or must fix evidence findings first.
- Use scripts/video_analysis_pack_builder.py after the evidence auditor returns `enter_video_analysis_pack_builder` or `enter_partial_video_analysis_pack_builder` and all evidence sidecars exist. It writes only `video_analysis_pack.md` and relies on the audit gate rather than reinterpreting source material.
- Use scripts/workflow_runner.py as a low-cost hard-gate runner for acquisition signals and minimal blocked/degraded status outputs.
- Do not treat workflow_runner.py as a full analyzer: it does not fetch media, launch Chrome, create transcripts, segment content, or produce a complete video_analysis_pack.

Read references/platform-prerequisites.md before processing YouTube or platform URLs where yt-dlp, cookies, JavaScript runtime, bot/sign-in checks, DPAPI/App-Bound failures, `n challenge`, missing subtitles, or local ASR routes may arise.
Read references/chrome-routing.md and references/chrome-probe-contract.md before processing video URLs and whenever Chrome route, page-state, platform block, Hearsay URL timeout, 429, bot, CAPTCHA, login, RequestBlocked, visible-transcript, or Chrome deep-probe decisions arise.
Read references/source-status.md before processing video URLs and before deciding whether full, partial, blocked, secondary-only, or degraded outputs are allowed.
Read references/artifact-schema.md before writing intermediate artifacts.
Read references/transcription-fallback.md before running ASR when reliable subtitles or transcripts are unavailable.