{"id":"28b1edda-2616-4d54-87ef-722f51a25e77","slug":"talkicut","kind":"skill","name":"talkicut","summary":"Give a silent screen recording a voice: agent skill that turns screen recordings into vertical clips with TTS narration and burned captions (ffmpeg, no API keys)","owner":"laopro","repoUrl":"https://github.com/laopro/talkicut","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-10-22T23:12:16.000Z","addedAt":"2026-11-01T02:04:25.770Z","logoUrl":"https://avatars.githubusercontent.com/u/189813298?u=10ce5a8ad3f25b988f88f498b3b0502fef00f995&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["design-media"],"tags":["ai-agents","captions","ffmpeg","python","reels","screen-recording","shorts","tiktok"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-11-01T02:18:35.897Z","sample":false,"url":"https://conduits.dev/tools/talkicut","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# talkicut\n\n**Give a silent screen recording a voice, then cut it into vertical clips. Or describe a video and let it build one.**\n\nA screen recording with no audio track is the modern silent film: no transcript, nothing for an AI clipper to select. talkicut reads the recording, helps you choose the beats, writes nothing for you, speaks the narration you wrote, and burns word-synced captions into a 9:16 clip.\n\nNo footage? Give it a topic. `storyboard` scaffolds the beats, `make` pulls real footage (YouTube) and images (web search) for each beat, draws animated charts from the data you give it, adds NCS music, and renders one narrated, crossfaded video with a spoken hook and word-by-word captions.\n\nPlain Python + ffmpeg. No API keys, no accounts, no cloud. Works on Windows, macOS and Linux, under any agent that can run a shell, with any model - including models that cannot see images.\n\n```\n recording.mp4 ──▶ probe/sheet/ocr ──▶ plan.json ──▶ render ──▶ clips/\n   (silent)          (read the UI)      (beats +        (TTS +      1080x1920\n                                         narration)      captions)   .mp4 + .srt + .jpg\n```\n\n## Install\n\nClone it straight into the folder your agent reads as skills:\n\n```bash\n# OpenCode\ngit clone https://github.com/laopro/talkicut.git ~/.config/opencode/skills/talkicut\n\n# Claude Code / Claude Desktop\ngit clone https://github.com/laopro/talkicut.git ~/.claude/skills/talkicut\n\n# Codex / Cursor / anything that reads .agents/skills\ngit clone https://github.com/laopro/talkicut.git .agents/skills/talkicut\n```\n\nOr copy the folder anywhere and point your agent's skill directory at it:\n\n```bash\n./install.sh                 # macOS / Linux, defaults to ~/.config/opencode/skills\n.\\install.ps1                # Windows (PowerShell)\n./install.sh ~/.claude/skills\n```\n\nRequirements: Python 3.9+ and `ffmpeg`/`ffprobe` with `libass`, `boxblur` and `loudnorm`. Optional: [`edge-tts`](https://github.com/rany2/edge-tts) for the good voices (`doctor --fix` installs it); without it, the OS voice is used offline.\n\n> macOS note: Homebrew's `ffmpeg` 9 build ships without `libass`, so captions are skipped (with a warning). Use a full build - a static one from evermeet.cx, or any tap that bundles libass - if you want burned captions. Everything else renders fine with the Homebrew build.\n\n## Use it\n\nJust hand your agent the recording:\n\n> \"acá tenés la grabación de mi app (no tiene audio), sacale 3 clips verticales para reels con subtítulos\"\n\nThe agent follows `SKILL.md`. By hand it is five commands:\n\n```bash\npython scripts/talkicut.py doctor                  # what this machine has\npython scripts/talkicut.py probe demo.mp4          # duration, audio, scene cuts\npython scripts/talkicut.py sheet demo.mp4          # timestamped contact sheets\npython scripts/talkicut.py plan demo.mp4 --beats 4 # scaffold plan.json (--full to cover the whole video)\npython scripts/talkicut.py render plan.json        # -> ./clips\npython scripts/talkicut.py verify clips            # catch the silent failures\n```\n\nWith no recording at all:\n\n```bash\npython scripts/talkicut.py storyboard \"un reel sobre las IA actuales\" --beats 4 --seconds 28 --out reel.plan.json\n# fill: title (spoken hook), script, and one of video / query / chart per beat\npython scripts/talkicut.py make reel.plan.json --out reel.mp4   # fetch + render + crossfade + music\n```\n\nThe agent researches the topic with its own web tools, writes the narration and one visual per beat (footage search, image search or a chart with sourced numbers). The pipeline does not invent facts.\n\n`selftest` renders a synthetic video end to end, so you can tell \"my plan is wrong\" apart from \"this machine is broken\".\n\n## What you get\n\n- 1080x1920 (or 1:1, 4:5, 16:9), full screen visible over a blurred fill - no UI is cropped away\n- `--aspect auto` keeps a horizontal recording horizontal, scaled straight with no blur\n- burned captions in three presets (`clean`, `tiktok`, `bold`), word-synced when edge-tts is available\n- a spoken hook on a colour box, then captions where the word being said lights up\n- audio normalized to -16 LUFS, with a silent AAC track when there is no voice\n- `manifest.json`, plus optional `.srt` and `.jpg` per clip\n- `--stitch` joins the clips in plan order into one file: a full-video edit with the same encode\n- prompt-only reels: real footage, full-bleed pans and Ken Burns over web images, animated counter / bar / line / table charts, crossfades inside and between beats, beats that last exactly as long as the narration, and `credits.txt` with every source\n- background music: `--music track.mp3`, a YouTube/NCS URL, or `fetch --music \"NCS progressive house\"` (yt-dlp) loops under the voice at 8%, faded in and out\n- `+faststart` so platforms start processing the upload immediately\n\n## Commands\n\n| Command | What it does |\n|---|---|\n| `doctor` | checks ffmpeg, filters, fonts and TTS backends, with install commands for your OS |\n| `probe` | duration, resolution, audio, scene cuts, as text or `--json` |\n| `plan` | scaffolds `plan.json` with beats snapped to real cuts, and a character budget per beat |\n| `storyboard` | scaffolds a plan from a prompt, for videos with no source footage |\n| `fetch` | per beat: footage (`video`, yt-dlp) and images (`query`, web search; `--from wiki` for free licences only), plus an NCS track; `--sheet` writes a contact sheet to review them |\n| `make` | `fetch` + `render --stitch` + copy to `--out`: one call from plan to finished video |\n| `sheet` | contact sheets with timestamps, for vision models |\n| `ocr` | timestamped UI transcript, for models without vision |\n| `render` | plan -> finished clips |\n| `verify` | every clip in a folder: streams, duration, size, mean volume |\n| `selftest` | synthetic end-to-end run, no user files touched |\n\n`render` flags: `--audio tts|source|mix`, `--tts auto|edge|system|none`, `--voice`, `--lang`, `--aspect auto|9:16|4:5|1:1|16:9`, `--fit auto|blur|cover|pad`, `--style clean|tiktok|bold`, `--music file|url`, `--music-volume 0.08`, `--stitch [name]`, `--srt`, `--thumbnail`, `--dry-run`, `--brief`, `--only`, `--force`, `--jobs`, `--json`.\n\n## Why it works like this\n\n- **Blurred fill, not crop.** Screen content is landscape; cropping to 9:16 destroys the UI. `--fit cover` exists for footage that can lose its edges, `--fit pad` for flat backgrounds.\n- **Manual beats, mechanical render.** No virality model pretends to know your story. The agent reads the screen, you write the words, the pipeline does the rest.\n- **Rate fitting, not time-stretching.** When the narration is too long, the voice is re-synthesized faster; `atempo` makes TTS sound drunk.\n- **Capability detection.** The script asks ffmpeg which filters exist and asks the OS which voices exist, then degrades visibly instead of dying.\n\n## Documentation\n\n- `SKILL.md` - the agent workflow, decisions and failure table\n- `references/editing.md` - full-video editing, horizontal output, stitching, pacing\n- `references/auto-video.md` - prompt-only videos: research, image queries, licensing, text-only beats\n- `references/plan-schema.md` - every plan field and default\n- `references/narration.md` - pacing math, hooks, per-language notes\n- `references/platforms.md` - install matrix, voices per OS, known breakage\n- `references/ffmpeg-notes.md` - filter chains and the bugs behind them\n- `assets/plan.example.json` - copy-paste starting point for a recording\n- `assets/topic.plan.example.json` - topic-only plan: angle, spoken hook, footage, charts, closing question\n\n## Limits\n\n- It does not choose highlights for you: no ASR and no virality model. Beat selection and narration are the judgment part.\n- A full edit is built from the beats you define; it does not detect silences or dead time automatically.\n- Web images and YouTube footage are not licence-checked (`credits.txt` lists every source page; use `--from wiki` when that matters). A wrong pick is always possible: look at `media/sheet.jpg` before publishing.\n- Captions are word-synced only with edge-tts; OS voices get proportional timing (good to ~0.3 s over a 30 s clip).\n- Face-tracking crops are out of scope - screen content should stay uncropped anyway.\n\n## License\n\nMIT. See `LICENSE`.\n"}