Watch

Watch

Analyze an existing video from timestamped speech and locally inspected visual evidence. Answer the user's question first; preserve structured concept analysis for general summaries. A transcript explains what was said, not everything shown. Watch processes media locally and does not upload video or audio to a media-analysis service.

When to Use

Do not activate for video discovery, new-video creation, financial watchlists, or watching filesystem changes. Other URL sources use yt-dlp support, not a promise that every website or private video is accessible.

Prerequisites

SKILL_DIR is the absolute directory containing this file; scripts sit beside it. Resolve this path from the installed skill, not the current project directory. Python 3.12+ and uv are required. Local media inspection also needs FFmpeg/ffprobe. The documented uv invocation supplies caption/downloader dependencies without changing the user's project.

uv run --no-project --with youtube-transcript-api --with yt-dlp python "$SKILL_DIR/scripts/watch.py" --help
ffmpeg -version
ffprobe -version

Check only dependencies relevant to the selected path. Transcript-only requests do not require FFmpeg. Never install system binaries or large speech models without explicit user authorization. Local processing means the agent's execution machine, not automatically the user's laptop; captions and frames opened by the host assistant remain subject to that host's data policy.

Workflow

1. Select the question and evidence boundary

1. Preserve the user's question verbatim in --question. Without a question, produce a structured summary.
2. Select --engine transcript when speech alone answers the request. Select --engine local when visuals matter. Runtime default is local.
3. Keep media analysis local. Missing captions or speech are evidence gaps, not permission to upload media or select another service.
4. Choose quick, standard, or deep analysis using --depth. This controls presentation, not frame coverage. A deep summary is not an exhaustive visual inspection.

2. Acquire captions without unnecessary media

uv run --no-project --with youtube-transcript-api --with yt-dlp python "$SKILL_DIR/scripts/watch.py" "YOUTUBE_URL" --engine transcript --depth standard --question "Explain the main ideas and actionable takeaways"

YouTube captions use youtube-transcript-api first, then a selected yt-dlp caption track. Other supported URLs use yt-dlp. Read the reported source, manual/automatic kind, actual language, and gaps. Do not claim a requested language was used when a different track was selected, or infer the speaker's language from translated captions.

The report retains source-relative segment timestamps. No captions is missing speech evidence, not evidence of silence. Local files require explicit speech transcription to obtain a transcript; a visual-only result remains useful.

3. Inspect bounded visual evidence

uv run --no-project --with youtube-transcript-api --with yt-dlp python "$SKILL_DIR/scripts/watch.py" "URL_OR_LOCAL_FILE" --engine local --question "Identify the tool shown on screen" --detail balanced --max-frames 40 --resolution 1024

Read every listed frame using Read before claiming what is shown. Combine the images with the timestamped transcript. The report labels each frame with its actual decoded source time and selection reason. Fixed budgets produce sparse coverage on long recordings; do not turn a sampled absence into “never appears.”

• efficient: keyframe selection with uniform fallback.
• balanced: scene-aware selection with uniform fallback.
• transcript detail under the local engine: captions plus explicitly requested cue frames only.
• --no-dedup: preserve near-identical selected images when small text, code, cursor, or UI changes matter. Deduplication is not event detection.

Start with a bounded scan. Identify relevant speech cues (“look here,” “this diagram”) and visual candidates, then inspect a tighter interval or explicit timestamps. A visual event need not be mentioned in speech; do not use captions as the only search index.

uv run --no-project --with youtube-transcript-api --with yt-dlp python "$SKILL_DIR/scripts/watch.py" "URL_OR_LOCAL_FILE" --engine local --start 02:00 --end 02:25 --detail transcript --timestamps 02:13 --max-frames 4 --no-dedup --question "Read the tool name and explain the demonstration"

Focus times and cues are absolute source times; seconds, MM:SS, and HH:MM:SS are accepted. Frames lie inside [start, end). Requested cue time and actual decoded time are distinct. Cue frames reserve space in the total cap; an excessive cue count or out-of-range cue is an error, not a silent omission. The total frame cap is 1–120, resolution is 16–4096px, and downloads are capped at 720p and 256 MiB. Higher resolution cannot recover detail absent from the downloaded source.

For follow-ups, reuse the report's local media only when it is an actual downloaded video. A captions-only run has no media; use the URL again. An audio-only download cannot supply pixels. Keep existing evidence until the follow-up is complete.