🎬 NouClip — Agentic Video Clipper & Shorts Engine

An agentic-first CLI tool for video cutting, aspect ratio reframing, Whisper transcription, animated kinetic subtitles, smart audio ducking, and auto silence trimming.

Designed for automated workflows, AI agent harnesses, and power users who need deterministic, scriptable video operations with persistent artifact caching.

---

⚡ Core Philosophy & Features

• 🤖 Agentic-First & Context-Rich: Built-in introspection commands (nouclip info, nouclip list --json) that allow AI agents and scripts to discover paths, inspect storage, and reuse existing artifacts.

• 📦 Zero-Waste Artifact Management: Downloaded raw videos, audio WAVs, word-level Whisper transcripts (.json), and styled ASS subtitle files are preserved in dedicated folders rather than deleted silently.

• ⏱️ Human & Agent Timestamps: Supports flexible range syntaxes like --range 13:25-14:50, 01:13:25, 85s, and 13m25s.

• 📐 Universal Aspect Reframing: Converts videos to any aspect ratio (9:16, 1:1, 4:5, 16:9, or custom W:H) with multiple framing modes (blur, center, pad, stretch).

• 🎨 Typography Presets (--style): Instant subtitle styling presets:

  • hormozi: Bold all-caps (Arial Black, 70px), neon green active-word highlight (&H0000FF00), pop zoom scaling (118%), thick outline.
  • storyteller: Clean natural-case (Arial, 54px), soft cyan active-word highlight (&H0050E3C2), thin outline.
  • cinematic: Wide tracking (Trebuchet MS, 58px), golden amber highlight (&H0000A5FF).
  • default: Classic all-caps (Arial Black, 62px) with yellow highlight.

  Each preset ships its own font size; --font-size, --primary-color and --highlight-color override it only when passed.

• ✂️ Silence & Pause Trimming (--silence-trim): Reads Whisper word timestamps to automatically cut silent pauses (>0.6s), concatenating speech seamlessly and auto-shifting subtitle timestamps.

• 🎵 Smart BGM & Sidechain Ducking (--bgm): Auto-loops background music and dynamically ducks/lowers BGM volume when speech is active (sidechaincompress + amix).

• ✍️ Draft & Staged Workflow (--draft / --no-burn): Cuts and prepares transcript/ASS files for human or agent review before burning subtitles into the final video.

• 🎙️ GPU STT Integration: Directly integrates with local GPU endpoints like Voice Compute or any OpenAI-compatible Whisper API.

---

📁 Workspace & Artifact Structure

NouClip organizes all assets in a structured workspace (defaults to ~/.nouclip or ./.nouclip):

~/.nouclip/
├── downloads/        # Cached source/YouTube videos (never re-downloaded twice)
├── transcripts/      # Whisper JSON transcripts (*.whisper.json) and ASS scripts (*.ass)
├── segments/         # Raw cut segments, trimmed audio/video, and reframed files
└── output/           # Final rendered videos with burned subtitles & mixed BGM

Run nouclip info anytime to inspect current paths, file counts, and storage usage.

---

📥 Installation

💡 Don't know how to setup? You can let your AI agent install and configure everything autonomously! Jump to Let Your AI Agent Setup & Use the CLI.

Method 1: Package Managers (Bun / npm / pnpm) — Recommended

The easiest and fastest way to install and update NouClip globally across all platforms:

# Using Bun (Recommended & Fastest)
bun add -g nouclip

# Using npm
npm install -g nouclip

# Using pnpm
pnpm add -g nouclip

# Or run instantly without installing:
bunx nouclip --help
# or
npx nouclip --help

---

Method 2: Standalone Binaries (Pre-compiled)

If you do not have Bun or Node.js installed, download the pre-compiled standalone binary (zero runtime dependencies required) for your operating system from the GitHub Releases page:

Platform	Architecture	Binary
🐧 Linux	x86_64	nouclip-linux-x64
🍎 macOS	Apple Silicon (M1/M2/M3/M4)	nouclip-darwin-arm64
🍏 macOS	Intel (x86_64)	nouclip-darwin-x64
🪟 Windows	x86_64	nouclip-windows-x64.exe

---

Method 3: One-Line Install Script (Linux / macOS)

Downloads the latest release binary for your architecture and places it into /usr/local/bin:

curl -fsSL https://raw.githubusercontent.com/nouverse/nouclip/main/install.sh | bash

---

Method 4: From Source (Development)

git clone https://github.com/nouverse/nouclip.git
cd nouclip
bun install

# Run via Bun
bun run src/cli.ts --help

# Or build standalone executable
bun run build
./dist/nouclip --help

---

📋 Prerequisites

1. FFmpeg & yt-dlp installed on system PATH:
   • macOS: brew install ffmpeg yt-dlp
   • Ubuntu/Debian: sudo apt install ffmpeg && pip install yt-dlp
   • Windows: winget install Gyan.FFmpeg yt-dlp
2. (Optional) Voice Compute or an OpenAI Whisper API endpoint for generating word-level subtitle timings.

---

⚙️ Configuration & Environment Variables

NouClip resolves each variable by precedence, first match wins:

1. Shell environment variables (always win)
2. ~/.nouclip/.env (Global user config)
3. ./.env (Current working directory — fills in what the global file left unset)

Example .env

# Storage & Workspace Paths (Optional)
NOUCLIP_WORKSPACE_DIR=~/.nouclip
NOUCLIP_DOWNLOAD_DIR=~/.nouclip/downloads
NOUCLIP_TRANSCRIPT_DIR=~/.nouclip/transcripts
NOUCLIP_OUTPUT_DIR=~/.nouclip/output

# STT Whisper / Audio Endpoint (Local voice-compute or Cloud OpenAI/Groq)
NOUCLIP_OPENAI_AUDIO_URL=http://localhost:8880
NOUCLIP_OPENAI_AUDIO_API_KEY=
NOUCLIP_OPENAI_AUDIO_MODEL=large-v3

# LLM Endpoint (Optional — for automated highlight suggestion)
NOUCLIP_OPENAI_LLM_URL=https://api.openai.com/v1
NOUCLIP_OPENAI_LLM_API_KEY=
NOUCLIP_OPENAI_LLM_MODEL=gpt-4o-mini

---

🚀 Usage Guide & Workflows

1. Inspecting Storage & Cached Assets (Introspection)

# Display storage paths, file counts, and service status
nouclip info

# JSON output for AI agents
nouclip info --json

# List cached downloaded videos
nouclip list downloads

# List generated transcripts
nouclip list transcripts

# List final rendered outputs
nouclip list output

---

2. End-to-End Automated Pipeline (nouclip auto)

Downloads (or reuses cache), cuts segment, reframes to vertical, transcribes with Whisper, and burns kinetic subtitles:

# Standard automated short (9:16 blurred background with kinetic subtitles)
nouclip auto "https://youtu.be/EXAMPLE_ID" --range 13:25-14:10

# Power Creator Setup: Hormozi Typography + Silence Trimming + Background Music
nouclip auto podcast.mp4 \
  --range 01:20-02:00 \
  --style hormozi \
  --silence-trim \
  --bgm "lofi_track.mp3" \
  --bgm-volume 0.10 \
  -o out/viral_short.mp4

# Clean Framing Only (0 subtitles — for video editors & post-production)
nouclip auto "https://youtu.be/EXAMPLE_ID" --range 13:25-14:10 --no-subtitles -o clean_short.mp4

# From local file with square 1:1 aspect ratio
nouclip auto interview.mp4 --range 01:20-02:00 --aspect 1:1 --mode pad -o out/feed.mp4

---

3. Review & Staged Workflow (Draft Mode)

If you want to review and correct subtitle typos before rendering the final video:

# Step 1: Generate segment + transcript without burning
nouclip auto "https://youtu.be/EXAMPLE_ID" --range 13:25-14:10 --style hormozi --draft

# Output:
# 📹 Video Segment  : ~/.nouclip/segments/video_framed_9x16_blur.mp4
# 📝 Subtitle Script: ~/.nouclip/transcripts/video_13m25s-14m10s.ass

# Step 2: Open and edit the .ass file in any text editor

# Step 3: Burn the verified subtitles & mix BGM
nouclip subtitle ~/.nouclip/segments/video_framed_9x16_blur.mp4 \
  --sub ~/.nouclip/transcripts/video_13m25s-14m10s.ass \
  --bgm "lofi_track.mp3" \
  -o ~/.nouclip/output/final_short.mp4

---

4. Modular Commands

Cut Video Segment

nouclip cut input.mp4 --range 13:25-14:10

Reframe Aspect Ratio & Mode

# 9:16 Vertical with blurred background fill
nouclip crop input.mp4 --aspect 9:16 --mode blur

# 1:1 Square with center crop fill
nouclip crop input.mp4 --aspect 1:1 --mode center

Extract Audio & Whisper Transcribe

nouclip extract input.mp4 --lang id --format json

Burn Subtitles & Mix Audio

nouclip subtitle input.mp4 --sub captions.ass --bgm music.mp3 --bgm-volume 0.10 -o final.mp4

---

🤖 Let Your AI Agent Use the CLI

NouClip is designed from the ground up to be agentic-first. AI coding assistants and autonomous agents (such as Nouride, Claude Code, Cursor, Cline, OpenClaw, etc.) can inspect storage, reuse cached artifacts, and execute multi-step clipping pipelines deterministically using structured JSON outputs and the bundled skill.

---

💡 Don't know how to setup? Let your AI agent do it for you!

You don't need to manually configure FFmpeg, yt-dlp, or install binaries yourself. Simply give your AI agent the bundled skill file from skills/nouclip/SKILL.md and ask:

"Please setup and verify NouClip on my machine."

The skill includes self-contained instructions for your agent to automatically check for nouclip, ffmpeg, and yt-dlp, run OS-specific installations, and verify health without manual intervention.

---

📦 Bundled Agent Skill

A comprehensive, production-ready skill file is maintained directly inside the repository at skills/nouclip/SKILL.md.

🛠️ Installing the Skill into Your AI Agent

1. For Nouride / OpenClaw Daemons

Copy the skill folder into your agent's shared or personal skills directory:

# Copy to Nouride shared skills
cp -r skills/nouclip ~/.nouride/agents/shared/skills/
# Or copy to a specific agent's workspace
cp -r skills/nouclip ~/.nouride/agents/<agent-id>/skills/

2. For Cursor / Claude Code / Cline / Windsurf

Copy the skill instructions into your project's rules or prompt directory:

# Cursor Rules
mkdir -p .cursor/rules && cp skills/nouclip/SKILL.md .cursor/rules/nouclip.md

# Claude Code / Cline Instructions
mkdir -p .claude && cp skills/nouclip/SKILL.md .claude/nouclip-skill.md

💡 Why Agents Love NouClip:

• Introspection: nouclip info --json gives the agent total visibility into disk usage, configured endpoints, and workspace directories.
• Discovery: nouclip list <downloads|transcripts|segments|output> --json returns structured arrays of existing assets so agents never re-download or re-transcribe unnecessarily.
• Safety & Drafts: The --draft / --no-burn flag allows agents to review, correct typos, or adjust ASS subtitle scripts before committing to a full video render.

---

🧪 Testing & CI

NouClip comes with an extensive unit and E2E test suite running across macOS, Linux, and Windows:

# Run all tests
bun test

# Typecheck & Lint
bun run typecheck
bun run lint

---

📄 License

MIT © Nouverse Technologies & Gading Nasution