{
  "markdown": "# watch-cli\n\n![CI](https://github.com/sonpiaz/watch-cli/actions/workflows/ci.yml/badge.svg)\n\n**Watch any social video → get an architecture diagram, working component, runnable notebook, or step-by-step cheat sheet — automatically.**\n\nEyes and ears for your AI agent. watch-cli composes `yt-dlp` + `ffmpeg` + a Whisper-class ASR into a single command that hands an agent the raw materials to \"watch\" any video: VIDEO + FRAMES + TRANSCRIPT, ready for an LLM to read frames as images and transcript as text.\n\n```bash\nwatch https://twitter.com/anyone/status/12345\n```\n\nWorks on YouTube, X, LinkedIn, TikTok, Reddit, Vimeo, and Facebook. Login-walled posts (LinkedIn, private X, FB) work with `WATCH_BROWSER=auto`, which reads cookies from a browser you are signed in to.\n\n## What you can build\n\nHand the `watch` output to your agent with one of five prompts in [`prompts/`](prompts/):\n\n| Drop in a video of… | Get back |\n|---|---|\n| A coding walkthrough | [Working project files](prompts/implement-from-video.md) |\n| A system architecture talk | [Interactive architecture diagram](prompts/extract-architecture.md) |\n| A UI / motion demo | [Working React component](prompts/clone-ux.md) |\n| A paper or research talk | [Runnable notebook](prompts/paper-to-code.md) |\n| A long tutorial | [Step-by-step cheat sheet](prompts/tutorial-walkthrough.md) |\n\nThe prompt library is what turns *\"video → frames + transcript\"* into *\"video → working artifact\"*. The full [Prompt library](#prompt-library) section below has copy-paste templates.\n\n---\n\n## Why this exists\n\nLarge language models can't watch video natively — they read text and\nlook at still images. You can hand a video to a multimodal API and get\nback a chat-style summary, but for an agent workflow that's the wrong\nartifact: the agent wants the raw frames and the full transcript so it\ncan reason for itself, not someone else's pre-digested recap.\n\nA video is just frames + audio, and each piece already has a fast,\nnear-free primitive:\n\n- `yt-dlp` downloads from any social platform\n- `ffmpeg` extracts evenly-spaced frames\n- An ASR model transcribes the audio\n- A multimodal LLM hears tone, music, SFX, language, mood\n\nCompose them and your agent has the materials to watch any social video.\n\n---\n\n## What it looks like\n\n```text\n$ watch https://www.linkedin.com/posts/some-talk_activity-12345\n\nVIDEO: /tmp/dl-video/abc123.mp4\nDURATION: 218\nFRAMES:\n  /tmp/frames_abc123/frame_01.jpg\n  /tmp/frames_abc123/frame_02.jpg\n  …\nTRANSCRIPT:\n  Today I want to talk about how decomposition unlocks 10× cost reduction in\n  multimodal pipelines …\n```\n\nYour agent reads the JPGs and the transcript. That's the whole watch.\n\n---\n\n## Why pay-per-use, not subscription\n\nMost subscription summary tools start around **$15/month** and deliver a\npolished, human-readable summary. If you're feeding an AI agent, that's the\nwrong artifact — agents need raw frames and the full transcript to reason\nfor themselves, not someone else's pre-digested recap.\n\nA typical research session is 1–3 videos, not 100. Through Kyma — the default\nbackend — a 1-hour video costs **~$0.05** (transcribe is the only paid step;\nframe extraction is local ffmpeg).\n\n| This month you watch | You pay |\n|---|---|\n| 0 videos | $0 |\n| 1 one-hour video | ~$0.05 |\n| 100 one-hour videos | ~$5 |\n\nNo monthly minimum, no seat license, no lock-in. The free credit at Kyma\nsignup is enough to run the full pipeline end-to-end before you spend a cent.\n\n---\n\n## Install\n\n```bash\n# macOS — Homebrew (recommended)\nbrew tap sonpiaz/tap\nbrew install watch-cli\n\n# Any OS — curl\ncurl -fsSL https://github.com/sonpiaz/watch-cli/releases/latest/download/install.sh | bash\n```\n\n> The curl one-liner auto-falls back to `git clone` of `main` if no\n> published release tarball is reachable.\n\n### Claude Code (skill marketplace)\n\nIf you use Claude Code, install watch-cli as a skill:\n\n```\n/plugin marketplace add sonpiaz/watch-cli\n/plugin install watch-cli@watch-cli\n```\n\nThe agent then picks up `watch <url>` as a first-class command.\n\nPin a specific version:\n\n```bash\ncurl -fsSL https://github.com/sonpiaz/watch-cli/releases/download/v0.3.4/install.sh \\\n  | WATCH_CLI_VERSION=0.3.4 bash\n```\n\nOr from a clone:\n\n```bash\ngit clone https://github.com/sonpiaz/watch-cli ~/.watch-cli\ncd ~/.watch-cli && ./install.sh\n```\n\nThe installer checks for `yt-dlp`, `ffmpeg`, `jq`, `curl`, `python3` and\nsymlinks the commands into `~/.local/bin`. On macOS:\n\n```bash\nbrew install yt-dlp ffmpeg jq\n```\n\nOn Debian/Ubuntu:\n\n```bash\nsudo apt install yt-dlp ffmpeg jq python3 curl\n```\n\n### Optional install flags\n\n```bash\n./install.sh --with-skill   # also drop SKILL.md into ~/.claude/skills/watch-cli/\n./install.sh --with-mcp     # print the npm install hint for the MCP stdio server\n```\n\n- `--with-skill` copies the portable `SKILL.md` into `~/.claude/skills/watch-cli/`\n  so Claude Code picks up watch-cli as a skill on next start. The same file\n  works in OpenClaw and hermes-agent — see [`SKILL.md`](SKILL.md).\n- `--with-mcp` prints the manual install line for [`@sonpiaz/watch-cli-mcp`](mcp-server/),\n  the MCP stdio server that exposes watch-cli to Claude Desktop, Cursor, Cline,\n  Continue.dev, Windsurf, Zed, and any other MCP-capable client. The flag will\n  auto-install once the package is published to npm.\n\n---\n\n## Setup\n\n```bash\nexport KYMA_API_KEY=kyma-xxxxxxxx\n```\n\nGet a Kyma key at [kymaapi.com](https://kymaapi.com/?src=skill:watch) — 60 seconds, no card.\n\nPrefer bring-your-own-keys? Comment in `GROQ_API_KEY` and `GOOGLE_AI_KEY`\nin `.env.example` and watch-cli falls back to direct provider calls.\n\n---\n\n## Why Kyma\n\nwatch-cli uses Kyma as its AI backend. A few things you get for free:\n\n![models](https://img.shields.io/endpoint?url=https://api.kymaapi.com/api/badge/models.json)\n![creators](https://img.shields.io/endpoint?url=https://api.kymaapi.com/api/badge/creators.json)\n![free credit](https://img.shields.io/endpoint?url=https://api.kymaapi.com/api/badge/free-credit.json)\n\n- **One key, every model in this CLI.** watch-cli calls Kyma using\n  capability aliases (`transcribe`, `audio-understand`). When Kyma swaps\n  in a better model behind the alias, your scripts keep working unchanged.\n- **Per-call cost in the response.** Every transcribe gives you a real\n  number, not an end-of-month dashboard surprise.\n- **Auto-fallback across providers.** If the underlying audio provider is\n  throttling or down, Kyma routes through another. Your script never sees\n  the outage.\n- **Free credit at signup.** About 9 hours of audio at the default rate.\n  Enough to know if you like it before you spend a cent.\n\nThe badges above pull live from `api.kymaapi.com/api/stats`, so the model\ncount and free-credit number stay current without a watch-cli release.\n\n---\n\n## Commands\n\n```text\nwatch <url> [frame-count] [--cookies <file>] [--no-cache]\n  Orchestrator. Downloads, extracts frames, transcribes — one block out.\n  Archives the result; watching the same URL again reuses it.\n\nwatch-archive ls | find <query> | get <id|url> | where\n  Query everything you've watched. `find` returns the timestamp of the\n  matching line, so you get a seek position, not a video to re-watch.\n\ndl-video <url> [out-dir] [--cookies <file>]\n  Just download the video. Returns the local mp4 path.\n\nextract-frames <video> [count] [out-dir]\n  Pull N evenly-spaced JPG frames. Default 8.\n\ntranscribe <audio-or-video> [language] [--segments-out <path>]\n  Speech-to-text. Auto-extracts audio from video first.\n  --segments-out also writes timestamped segments to a JSON sidecar.\n\naudio-q <audio-or-video> \"<question>\"\n  Audio scene Q&A — tone, music, SFX, language, emotion.\n  Beyond pure transcription.\n\nmodels [--all]\n  List audio models available on Kyma (live, no hardcoded list).\n  --all to see every Kyma SKU (text + image + video + audio).\n```\n\n### Watch once, keep it\n\nEvery successful run is archived to `~/.watch-cli/archive`, so the same\nvideo is never transcribed twice. A second `watch` on the same URL skips\nboth the download and the ASR call and prints byte-identical output.\n\n```bash\nwatch https://youtu.be/xyz          # first run: downloads, transcribes\nwatch https://youtu.be/xyz          # cache hit, no API spend\nwatch-archive find \"context graph\"  # → id, [04:32], the line, across everything\n```\n\nRecords are plain JSON, SRT and JPG on disk. `grep` and `jq` read them\nperfectly well without this tool, and `transcript.srt` drops straight into\nany video player. Full layout in [`docs/archive.md`](docs/archive.md).\n\n### How `transcribe` and `audio-q` stay current\n\nThe scripts call Kyma using the `transcribe` and `audio-understand` aliases,\nnot raw model IDs. When Kyma swaps the underlying model (Whisper v4,\nVoxtral, a faster ASR), watch-cli keeps working without an update — the\nalias points to whichever model is current. Run `watch-cli models` any time\nto see what's behind the alias today.\n\n---\n\n## Login-walled videos\n\nMost YouTube / TikTok / Reddit / Vimeo / public X work without setup.\nLinkedIn, private X posts, and Facebook need a session.\n\nwatch-cli fetches every URL anonymously and never reads a browser\nsession on its own. For a login-walled URL, opt in per run:\n\n```bash\nWATCH_BROWSER=auto watch <url>      # any signed-in browser: Chrome → Firefox → Safari → Edge → Brave → Chromium\nWATCH_BROWSER=firefox watch <url>   # one browser\n```\n\nCookies are read from the local browser profile by yt-dlp, sent only to\nthat platform, and never stored or uploaded.\n\nFor servers / CI without browsers, pass a manual cookies file:\n\n```bash\nwatch <url> --cookies ~/cookies.txt\n```\n\nFull setup walkthrough: [docs/cookies.md](docs/cookies.md).\n\n---\n\n## Use with Claude Code (or any agent)\n\n```text\nYou have access to a `watch` command that takes a URL and returns\na video, 8 frames, and the transcript. Read the frames as images and\nthe transcript as text — that's enough to \"watch\" any social video.\n```\n\nThe output block is structured so an agent can parse it without help:\n`VIDEO:` line, `FRAMES:` block (one path per line), `TRANSCRIPT:` block.\n\n---\n\n## Prompt library\n\nBeyond the generic prompt above, five copy-paste prompts in\n[`prompts/`](prompts/) turn `watch` output into a specific artifact:\n\n| Goal | File |\n|---|---|\n| Coding walkthrough → working project | [`implement-from-video.md`](prompts/implement-from-video.md) |\n| System talk → interactive architecture diagram | [`extract-architecture.md`](prompts/extract-architecture.md) |\n| UI / motion demo → working React component | [`clone-ux.md`](prompts/clone-ux.md) |\n| Paper / research talk → runnable notebook | [`paper-to-code.md`](prompts/paper-to-code.md) |\n| Long tutorial → step-by-step cheat sheet | [`tutorial-walkthrough.md`](prompts/tutorial-walkthrough.md) |\n\nPaste the chosen prompt above the `watch` output, hand the whole thing\nto your agent.\n\n### Use as a Claude Code skill\n\nDrop [`skills/watch-cli/`](skills/watch-cli/) into your\n`~/.claude/skills/` folder and the agent will pick up `/watch <url>`\nas a first-class command, including the prompt library above.\n\n```bash\nmkdir -p ~/.claude/skills\ncp -r skills/watch-cli ~/.claude/skills/\n```\n\n---\n\n## How it works\n\n```text\nURL ──▶ yt-dlp ──▶ video.mp4 ──┬──▶ ffmpeg ──▶ frames/*.jpg\n                                │\n                                └──▶ ffmpeg ──▶ audio.mp3 ──┬──▶ Kyma /v1/audio/transcriptions\n                                                            │     (Whisper Large v3 Turbo, 228× realtime)\n                                                            │\n                                                            └──▶ Kyma /v1/audio/understand\n                                                                  (Gemini 3 Flash audio — tone/music/SFX)\n```\n\nEach step is a primitive. None of them needs a vision LLM.\n\n---\n\n## Show what you build\n\nBuilt something cool from a video? Drop it in\n[Discussions](https://github.com/sonpiaz/watch-cli/discussions) under\n**Show and tell**. Post the source URL, the prompt you used, and your\nartifact. Curated highlights make it back into the README.\n\n---\n\n## Limitations and cost\n\nWatch-cli is fast and cheap because it composes primitives instead of\ncalling a video LLM. The tradeoffs are honest.\n\n### Cost per video\n\nTranscription is the only paid step. Frame extraction is local ffmpeg,\nfree.\n\n| Video length | Transcribe cost |\n|---|---|\n| 5 minutes (tweet, short demo) | ~$0.005 |\n| 1 hour (LinkedIn talk, podcast) | ~$0.05 |\n| 2 hours (conference talk) | ~$0.11 |\n\nFree credit at Kyma signup covers about 9 hours of transcribe. A BYOK\npath is available — see `.env.example`.\n\n### What works well\n\n- Talking-head content: tutorials, conference talks, lectures, walkthroughs\n- Architecture and system diagrams shown for at least 3 seconds\n- Code that stays on screen long enough to read\n- ~95 languages (anything Whisper v3 turbo supports)\n\n### What works poorly\n\n- Music videos, action movies, fast-cut content. Eight evenly-spaced\n  frames miss key moments. Bump count: `watch <url> 24`.\n- Editor sessions that scroll fast through code. Same fix.\n- Audio with heavy background music and overlapping speakers. Transcript\n  quality drops. Use `audio-q` for a scene description instead.\n- Videos longer than ~2 hours. The transcribe provider has a 25MB audio\n  cap. Watch-cli auto-downsamples but a 3-hour talk may still exceed.\n  Workaround: split via `ffmpeg -ss` before piping.\n\n### What does not work yet\n\n- Region-locked videos (some YouTube, TikTok). yt-dlp returns an error;\n  watch-cli surfaces it.\n- Live streams. Download finishes only after the stream ends.\n- Silent screencasts. Transcribe returns empty. Increase frame count and\n  use `audio-q` for any sound design instead.\n\n### Frame count guidance\n\n| Video type | Recommended `frame-count` |\n|---|---|\n| Short tweet / clip (<2 min) | 4 to 8 (default) |\n| Standard tutorial / talk (5–20 min) | 8 to 16 |\n| Long talk / lecture (20–60 min) | 16 to 24 |\n| Conference talk / multi-hour (>1 hr) | 24 to 32 |\n| Fast-cut or dense UI demo | Double the recommendation for that length |\n\n---\n\n## License\n\nMIT. © 2026 Son Piaz.\n",
  "bytes": 14066,
  "sha": "5b1b22c588c75c1144696272817fcddc573ba19735e43cfdbf3c715d5da315f5",
  "repo_slug": "sonpiaz/watch-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sonpiaz_watch_cli_7f9769ad/readme"
}