--- name: nouclip description: CLI video clipping, hook-first multi-range timelines and skip windows (splice several ranges in any order, cut out bumpers, re-time subtitles without re-transcribing), universal aspect reframing (9:16, 1:1, 4:5), YouTube captions before Whisper transcription, timed transcripts for summarizing a video or YouTube link, kinetic subtitle burning, typography presets, silence trimming, BGM ducking, dependency checks, installation and update workflows using NouClip CLI. --- # NouClip โ€” Agentic Video Clipper & Shorts Engine Skill Operational instructions and procedures for checking prerequisites, installing and updating nouclip, clipping videos, splicing hook-first timelines and skipping bumpers, reframing aspect ratios, reading YouTube captions or transcribing with Whisper, getting timed transcripts to summarize a video, applying typography presets, trimming silence, mixing ducked BGM, and burning kinetic subtitles using the `nouclip` CLI. --- ## ๐Ÿ› ๏ธ Step 0: Verification & Self-Installation (For Agents) Before running clipping commands, verify that required host binaries are present on the system. ### 1. Check if `nouclip` is Installed ```bash nouclip --version ``` If `nouclip` is **not found** (`command not found` or `ENOENT`), install it using one of the following methods: - **Option A (Package Managers โ€” Recommended & Fastest):** Check if `bun`, `npm`, or `pnpm` is available on the machine: ```bash # Using Bun (Fastest) bun add -g nouclip # Using npm npm install -g nouclip # Using pnpm pnpm add -g nouclip ``` - **Option B (One-Line Standalone Script for Linux & macOS):** ```bash curl -fsSL https://raw.githubusercontent.com/nouverse/nouclip/main/install.sh | bash ``` - **Option C (Direct GitHub Releases Binary Download):** ```bash # Linux (x86_64) curl -fsSL https://github.com/nouverse/nouclip/releases/latest/download/nouclip-linux-x64 -o /usr/local/bin/nouclip && chmod +x /usr/local/bin/nouclip # macOS Apple Silicon (arm64) curl -fsSL https://github.com/nouverse/nouclip/releases/latest/download/nouclip-darwin-arm64 -o /usr/local/bin/nouclip && chmod +x /usr/local/bin/nouclip # macOS Intel (x86_64) curl -fsSL https://github.com/nouverse/nouclip/releases/latest/download/nouclip-darwin-x64 -o /usr/local/bin/nouclip && chmod +x /usr/local/bin/nouclip # Windows (PowerShell) Invoke-WebRequest -Uri "https://github.com/nouverse/nouclip/releases/latest/download/nouclip-windows-x64.exe" -OutFile "$env:LOCALAPPDATA\Microsoft\WindowsApps\nouclip.exe" ``` ### Updating `nouclip` There is no self-update command: update the same way it was installed. Find out which from where it lives: ```bash command -v nouclip # ~/.bun/bin โ†’ bun ยท the npm global prefix โ†’ npm ยท /usr/local/bin โ†’ standalone nouclip --version # before and after, to confirm ``` ```bash bun add -g nouclip@latest # installed with Bun npm install -g nouclip@latest # installed with npm pnpm add -g nouclip@latest # installed with pnpm # Standalone binary: re-run the installer โ€” it always fetches the latest release curl -fsSL https://raw.githubusercontent.com/nouverse/nouclip/main/install.sh | bash ``` Update when a flag in this document is rejected as unknown (`error: unknown option`): the installed nouclip is older than these instructions โ€” `--timeline` / `--skip`, the `stitch` command, `--captions`, and YouTube links on `transcript` and `highlight`, are recent. ### 2. Check & Install System Dependencies (`ffmpeg` & `yt-dlp`) Check if installed: ```bash ffmpeg -version yt-dlp --version ``` If missing, install per host OS: - **macOS:** `brew install ffmpeg yt-dlp` - **Ubuntu/Debian:** `sudo apt update && sudo apt install -y ffmpeg && pip install yt-dlp` - **Arch Linux:** `sudo pacman -S ffmpeg yt-dlp` - **Windows:** `winget install Gyan.FFmpeg yt-dlp` --- ## ๐Ÿ” Introspection & Storage Discovery NouClip is agent-friendly. Before re-downloading or re-processing, always inspect the workspace: ```bash # Discover storage paths and existing assets in JSON nouclip info --json # List specific asset collections nouclip list downloads --json nouclip list transcripts --json nouclip list segments --json nouclip list output --json ``` Workspace resolution order: `NOUCLIP_WORKSPACE_DIR` โ†’ a `.nouclip/` directory in the current working directory โ†’ `~/.nouclip/`. Running from a project that has its own `.nouclip/` therefore keeps artifacts local, so always confirm the active paths with `nouclip info --json` before assuming `~/.nouclip/`. Default workspace is `~/.nouclip/`: - `~/.nouclip/downloads/` โ€” Cached raw source/YouTube videos (never re-downloaded if present). - `~/.nouclip/transcripts/` โ€” Whisper JSONs (`*.whisper.json`) and ASS scripts (`*.ass`). - `~/.nouclip/segments/` โ€” Cut raw segments, trimmed videos, and reframed MP4s. - `~/.nouclip/output/` โ€” Final rendered videos with burned subtitles & mixed BGM. --- ## ๐Ÿ’ฌ YouTube Captions First (`--captions`) For a YouTube link, `auto`, `transcript` and `highlight` read the video's own captions **before** sending any audio to Whisper. Captions cost nothing, need no STT endpoint, and cover the whole video without downloading it. Which track is used, in order: 1. **Uploaded captions** in `--lang` โ€” written by a person; timed per line, so word timing is estimated. 2. **YouTube's speech recognition** in `--lang` (the `-orig` track) โ€” timed per word. 3. Otherwise **Whisper**. An automatic *translation* is never used โ€” it is not what was said. The log says which it took: `Using YouTube captions (uploaded | YouTube speech recognition, track โ€ฆ, per-word timing | timing estimated per line)`. An uploaded track in a language other than the spoken one is a translation โ€” fine to read, but the words will not match the speech word for word. - `--captions auto` *(default)*: captions when usable, Whisper otherwise. - `--captions only`: captions or fail โ€” use when no Whisper endpoint is configured. - `--captions off`: always Whisper โ€” use when the captions are known to be poor. **Always pass `--lang` as the language actually spoken** (`en` for an English video). It defaults to `id`, and asking for `id` captions on an English video finds none (or a translation). --- ## ๐Ÿ“ Summarizing a Video or YouTube Link nouclip does not summarize โ€” **you do**, from its timed transcript. No LLM key is needed for this. ```bash # A YouTube link: its captions when it has them โ€” nothing is downloaded nouclip transcript "https://youtu.be/EXAMPLE_ID" --lang en -f txt -o /tmp/talk.txt # Only part of it (times then start at zero) nouclip transcript "https://youtu.be/EXAMPLE_ID" --lang en --range 10:00-25:00 -o /tmp/part.txt # A local file: transcribed with Whisper nouclip transcript ./meeting.mp4 --lang id -o /tmp/meeting.txt ``` The TXT is paragraphs like `[04:33 -> 04:52] โ€ฆ`. Then: - **Read it in parts on a long video** โ€” a two-hour podcast is ~150k characters. Search it for what the person asked about rather than reading it top to bottom when they want one topic. - **Put timestamps on everything**: chapters as `[mm:ss] title`, so the person can jump there โ€” and so a follow-up "clip that part" has its range ready for `nouclip auto --range`. - **Say where the words came from** โ€” uploaded captions, YouTube's recognition, or Whisper โ€” and that names and numbers in a machine transcript can be misheard; quote them as written. - **Only what was said.** A transcript has no picture: do not describe what is on screen, and say so if the question is about visuals. - **Write the summary in the person's language**, whatever the video's is. - For "the best moments" rather than a summary, `nouclip highlight --lang en` scores them from the same words. --- ## โฑ๏ธ Timestamp & Range Syntax NouClip accepts human, timestamp, and second ranges: - **Ranges:** `--range 13:25-14:50` or `--range 01:20..02:15` or `--range 45-75` - **Explicit From/To:** `--from 13:25 --to 14:50` (or `--start 13:25 --end 14:50`) - **Duration:** `--from 13:25 --duration 45s` (or `--start 805 --duration 45`) - **Several ranges, in play order:** `--timeline "1:30-1:35 + 0:00-0:15 + 0:25-0:50"` (separators `+`, `;` or `,`; every range needs an end) - **Windows to cut out:** `--skip "0:06-0:14, 1:10-1:20"` (alias `--exclude`), next to `--range` or `--timeline` - **Formats accepted:** `MM:SS` (`13:25`), `HH:MM:SS` (`01:13:25`), human units (`1h30m`, `13m25s`, `45s`), and raw seconds (`85.5`). --- ## ๐Ÿงฉ Hook-First Timelines & Skip Windows (`--timeline` / `--skip`) A short rarely plays in source order: the punchline goes first, then the setup, and the channel bumper or sponsor read in between is cut. `auto`, `cut` and `stitch` take these flags on top of `--range`: - `--timeline " + + "` โ€” the ranges to keep, **in the order they should play**. `1:30-1:35 + 0:00-0:15` plays the hook from 1:30 first. Alias: `--ranges`. - `--timeline-file tracks.json` โ€” the same as JSON, for manifests you write yourself: `[{ "start": "01:30", "end": "01:35", "tag": "hook" }, { "start": "00:14", "end": "00:50", "tag": "main_body" }]` (`end` or `duration`; times in any accepted form; `tag` is only for the log). - `--skip ", "` โ€” windows to cut out of whatever was selected. `--range 0:00-1:30 --skip 0:06-0:14` keeps 0:00-0:06 and 0:14-1:30. Alone, it applies to the whole file. Alias: `--exclude`. **Find the segments first.** Timestamps come from the transcript, not from guessing: `nouclip transcript --lang en -f txt` gives `[mm:ss -> mm:ss]` paragraphs; pick the hook (the punchline or the strongest claim), the setup, and the payoff from those times, and leave applause or a pause out with `--skip`. What happens, so you can explain it: - The segments are spliced in **one ffmpeg pass** with frame-accurate seeks and a 30 ms fade on either side of every junction (no click). The result is always re-encoded. - A **YouTube link downloads only the window spanning the segments** (earliest start to latest end), not the whole video. A hook from the last minute plus a setup from the first still spans nearly all of it โ€” expect that download, it is cached for the next edit of the same video. - **Subtitles follow the new timeline without a second transcription**: YouTube captions are re-timed onto the spliced clip, words outside the segments are dropped, and a caption never spans a cut. When Whisper runs, it simply hears the spliced clip. - A timeline that resolves to one continuous range behaves exactly like `--range`. `--timeline` cannot be combined with `--range`/`--start`/`--end`/`--duration` โ€” list every range in the timeline. - Output names carry the segments: `_90s-95s+0s-6s+14s-50s_short.mp4`. ```bash # Hook first, then setup, then the payoff โ€” one command, draft for review nouclip auto "https://youtu.be/EXAMPLE_ID" --lang en \ --timeline "1:30-1:35 + 0:00-0:15 + 0:25-0:50" --style hormozi --draft # Keep the first 90 seconds minus the bumper nouclip auto podcast.mp4 --range 0:00-1:30 --skip 0:06-0:14 --draft ``` ### `stitch`: the splice as a primitive When a clip was already transcribed (its `.whisper.json` exists) and only the edit changes, do not transcribe again โ€” stitch and re-time: ```bash nouclip stitch podcast.mp4 \ --timeline "1:30-1:35 + 0:00-0:15" \ --subtitles ~/.nouclip/transcripts/podcast.whisper.json \ -o stitched.mp4 \ --output-subtitles stitched.whisper.json nouclip subtitle stitched.mp4 --sub stitched.whisper.json --style standard -o final.mp4 ``` The `--subtitles` JSON must be timed against the **source** video's clock (the one you are stitching). The re-timed JSON records the `timeline` it came from and tags every word with its segment, so `nouclip subtitle` ends a caption at every cut. --- ## ๐ŸŽจ Typography Presets (`--style`) NouClip includes 5 built-in typography presets: - `--style standard`: Clean, static phrase/sentence-based typography (Arial, 50px, bold outline, balanced 2-line wraps) without per-word karaoke highlighting. **Essential for translated videos, international podcasts, or educational content** where rapid single-word karaoke jumping creates cognitive clash and breaks compound phrases. - `--style hormozi`: High-energy all-caps (Arial Black, 70px), electric neon green highlight (`&H0000FF00`), pop scaling 118%, thick 6px outline. - `--style storyteller`: Clean natural-case (Arial, 54px), soft cyan highlight (`&H0050E3C2`), refined 3px outline. - `--style cinematic`: Elegant all-caps wide-tracking (Trebuchet MS, 58px, spacing +4), golden amber highlight (`&H0000A5FF`). - `--style default`: Classic all-caps (Arial Black, 62px) with yellow highlight (`&H0000FFFF`). Each preset carries its own font size. `--font-size`, `--primary-color` and `--highlight-color` are overrides: pass them only to deviate from the preset, otherwise leave them out so the preset renders as designed. --- ## ๐ŸŒ Agent Translation & Localization Workflow (For AI Agents) When clipping foreign-language videos (e.g. English audio for an Indonesian audience): 1. **Why not raw machine translation?** YouTube auto-translate or raw machine translation is literal, awkward, preserves verbal filler ("Anda tahu", "fakta bahwa"), and chops compound phrases unnaturally (e.g. "pakar rantai" on line 1 and "pasokan" on line 2). 2. **The Agent-as-Translator Pattern**: nouclip does not need an external translation API or LLM key โ€” **you (the AI Agent) are the LLM**. - Step 1: Export timed transcript JSON for the clipped range: ```bash nouclip transcript "" --lang en --format json --range 13:25-14:10 -o /tmp/raw_transcript.json ``` - Step 2: Read `/tmp/raw_transcript.json` with the `read` tool. - Step 3: Localize and translate the dialogue into natural, engaging spoken language (e.g. conversational Indonesian). Keep the sentence timestamps (`start`, `end`) intact and map the words or phrases. - Step 4: Write the translated JSON or compile an ASS script: ```bash nouclip subtitle ./clipped.mp4 --sub /tmp/translated.json --style standard -o ./final.mp4 ``` The `standard` preset will automatically balance line lengths, split clauses at punctuation, and hold each phrase stationary for 2โ€“3 seconds so viewers can easily read and comprehend. ### ๐Ÿ’ก Language Matching vs. Subtitle Style Rule (Agent Guidance) When deciding which `--style` to apply: - **Same Language (Audio matches subtitle language)**: - *Examples:* English audio with English captions, or Indonesian audio with Indonesian captions. - **Use Kinetic presets** (`default`, `hormozi`, `storyteller`, `cinematic`). Active per-word pop animations work effectively because the viewer's eyes and ears process the exact same spoken words synchronously. - **Cross-Language / Translated Subtitles (Audio differs from subtitle language)**: - *Examples:* English audio with Indonesian translated subtitles. - **Recommended default:** `--style standard` (calm, static 2-line wraps held steady for 2โ€“3s). - **If Kinetic subtitles are explicitly requested for translated videos (Acoustic Anchor Protocol)**: - **Never linearly interpolate:** Do not divide total sentence duration evenly across translated words. Grammatical word-order shifts and pauses will cause severe subtitle drift. - **Acoustic Speech Burst Mapping:** Inspect Whisper/ASR word timestamps to find vocal pauses and silence gaps (`>0.3s`). Chunk the translated text into short phrases (3โ€“6 words) matching each vocal cluster. - **Punchline Intonation Locking:** Lock key translated emphasis words (e.g. "BERLAWANAN", "KEBALIKANNYA", "TIDAK ADA LAGI") to the exact millisecond when the speaker raises their pitch or delivers rhetorical punchlines. - **Always enforce `--no-scale`:** Eliminate vertical line-height jitter so text remains rock solid. ### ๐Ÿ›‘ Eliminating Subtitle Jitter (`--no-scale`) - In libass (FFmpeg ASS subtitle engine), pop scaling (`\fscx\fscy`) can cause noticeable vertical line jumping and stutter on bottom/center-aligned multi-word lines as word scales fluctuate during font transforms. - **Solution:** Pass `--no-scale` (available on `nouclip auto` and `nouclip subtitle`). This locks font scaling strictly at 100% and uses pure color-transition highlighting (`#FFFF00` yellow active, `#FFFFFF` white inactive), keeping subtitles rock-solid and stable. --- ## โšก Cache Overwrite & Forced Processing (`--force`) - By default, `nouclip` caches YouTube downloads in `~/.nouclip/downloads/`. - Pass `--force` on `nouclip auto` or `nouclip download` to bypass the cache and force a fresh download and cut. --- ## โœ‚๏ธ Silence & Pause Trimming (`--silence-trim`) - Automatically detects silent pauses between spoken words using Whisper word timestamps (`--silence-gap 0.6` by default). - Excises silent gaps and concatenates video seamlessly with FFmpeg. - Automatically recalculates and frame-shifts subtitle `.ass` timestamps so captions stay 100% aligned with the trimmed video. --- ## ๐ŸŽต Background Music & Sidechain Ducking (`--bgm`) - `--bgm `: Background music track to loop and mix with video audio. - Auto sidechain ducking: BGM volume automatically attenuates when speech is detected and gently rises back up during silence. - `--bgm-volume `: BGM volume factor (default: `0.10`). - `--no-ducking`: Disables sidechain compression for constant volume mixing. --- ## ๐Ÿ“ Aspect Ratios & Framing Modes | Preset | Target Resolution | Description | |---|---|---| | `9:16` *(default)* | 1080x1920 | TikTok, YouTube Shorts, Instagram Reels | | `1:1` | 1080x1080 | Instagram Feed, Square Video | | `4:5` | 1080x1350 | Instagram Portrait Feed | | `16:9` | 1920x1080 | YouTube Horizontal, Widescreen | | `4:3` | 1440x1080 | Classic standard definition | ### Framing Styles (`--mode`) - `--mode blur` *(default, or `--blur`)*: Scales and heavily blurs background video, overlays clean centered foreground. Ideal for podcasts and screen-shares. - `--mode center` *(or `--center`)*: Full-bleed zoom and center crop to fill the entire target canvas. - `--mode pad`: Letterbox / pillarbox with black padding bars. - `--mode stretch`: Scales directly without maintaining source aspect ratio. --- ## โœ๏ธ Staged & Draft Review Workflow (MANDATORY FOR AI AGENTS) > **โš ๏ธ STRICT DIRECTIVE FOR ALL AI AGENTS:** > 1. **ALWAYS use `--draft` (or `--no-burn`) on `nouclip auto` and video clipping.** Never run a blind end-to-end burn in one step. > 2. **ALWAYS inspect and edit the intermediate `.ass` transcript** to fix typos, acronyms, or styling before rendering. > 3. **MANDATORY USER CONFIRMATION:** Always present the draft cuts, summary, and transcript snippet to the user, and **WAIT for explicit user approval before triggering the final render/burn**. AI Whisper STT can mishear proper nouns, brand names, or slang. The staging protocol guarantees zero hallucinated/typo subtitles: ### Step 1: Generate Segment & Subtitle Draft ```bash nouclip auto "https://youtu.be/EXAMPLE_ID" \ --range 13:25-14:10 \ --aspect 9:16 \ --style hormozi \ --blur \ --draft ``` Output will return: - Segment Video: `~/.nouclip/segments/video_framed_9x16_blur.mp4` - Subtitle Script: `~/.nouclip/transcripts/video_13m25s-14m10s.ass` ### Step 2: Review & Edit Subtitle Read and correct any typos in the `.ass` file: ```bash # Agent opens ~/.nouclip/transcripts/.ass and edits words, casing, or styles directly ``` ### Step 3: Present Draft & Await User Confirmation Show the clip proposal and transcript draft to the user in your natural conversational voice/language (the following is an illustrative example): ```text "Draft clip & subtitles are ready (13:25 - 14:10): - Hook / Topic: 'Why we migrated to Hono...' - Style: Hormozi (Neon Green highlight) - Silence Trim: Enabled (>0.6s excised) - BGM: lofi_beat.mp3 (Sidechain ducking active) Ready to proceed with final rendering?" ``` **CRITICAL:** Present the plan in your natural voice, and **STOP to wait for explicit user confirmation**. DO NOT proceed to Step 4 until approved. ### Step 4: Burn Verified Subtitles into Final Video (After Approval) ```bash nouclip subtitle ~/.nouclip/segments/video_framed_9x16_blur.mp4 \ --sub ~/.nouclip/transcripts/video_13m25s-14m10s.ass \ --bgm "lofi_music.mp3" \ -o ~/.nouclip/output/final_short.mp4 ``` --- ## ๐Ÿ› ๏ธ CLI Command Reference ### 1. `info` / `paths` โ€” Storage & Service Introspection ```bash nouclip info [options] --json Output results as clean JSON payload ``` ### 2. `list` / `ls` โ€” Stored Artifacts Discovery ```bash nouclip list [type] [options] [type] Asset category: "downloads", "transcripts", "segments", "output", "all" --json Output asset list as clean JSON payload ``` ### 3. `auto` โ€” End-to-End Automated Pipeline ```bash nouclip auto [options] -r, --range Time range e.g. "13:25-14:50", "01:20..02:15", "45-75" -s, --start, --from Start timestamp e.g. "13:25", "01:13:25", "85s" -e, --end, --to End timestamp e.g. "14:50", "01:15:00" -d, --duration