PaunClip

PaunClip is a local-first AI clipping workspace for turning long videos, podcasts, interviews, tutorials, and channel batches into short-form clips. It combines YouTube ingest, transcript-first analysis, highlight selection, caption rendering, hook generation, smart reframing, and local output management in one developer-friendly app.

PaunClip can run in three ways:

• Web development app with npm run dev
• Desktop app through the Electron .exe
• CLI/headless mode with the paunclip command

Current status: PaunClip is under active development. Source installs are supported, and Windows desktop release artifacts are built from GitHub Releases.

What PaunClip Is For

PaunClip is designed for creators and operators who want to:

• Import a YouTube URL or local video.
• Analyze the transcript to find short-form moments.
• Review highlights before spending time rendering.
• Render vertical clips with captions and optional hook audio.
• Process multiple channel videos through Campaign mode.
• Keep everything local: database, storage, output, cookies, and API keys stay on the machine.

Features

• Workflow: guided single-video clipping flow.
• Projects: browse previous sessions and continue unfinished work.
• Campaigns: fetch channel videos, pick candidates, choose clip counts per video, and batch-create sessions.
• AI API settings: bring your own provider for highlight finding, transcription, hooks, and titles.
• OpenAI-compatible providers: works with provider-specific base URLs when the endpoint supports the required task.
• Caption presets: ASS/libass-based caption styles such as Karaoke, Deep Diver, Pod P, Popline, Seamless Bounce, Beasty, Youshaei, Mozi, Glitch Infinite, and Baby Earthquake.
• Hook audio: optional intro hook with frozen first frame before the source clip begins.
• Smart reframe: fast crop modes plus Smart Face mode for keeping speakers visible.
• Transcript-first YouTube flow: use subtitles/transcripts when available before downloading full video.
• Section rendering: render selected YouTube moments from timestamped sections when possible.
• CLI/headless mode: run doctor checks, create clips, manage campaigns, and render from a colorful terminal interface or clean JSON automation mode.
• Desktop packaging: Electron runtime with bundled media tools support.

Requirements

Required for source installs

• Node.js 22+
• npm
• Git

Runtime tools

PaunClip uses:

• FFmpeg for cutting, rendering, caption burn-in, thumbnails, and hook audio.
• FFprobe for media validation and duration probing.
• yt-dlp for YouTube metadata, subtitles, audio, video, and section downloads.
• SQLite + Prisma for local project/session/job storage.

For source installs, npm run desktop:tools downloads the pinned yt-dlp binary into vendor/bin. The CLI installer wires YTDLP_PATH to that bundled binary, and PaunClip resolves bundled yt-dlp before any system yt-dlp on PATH. FFmpeg/FFprobe are resolved from package dependencies or configured paths.

Install From Source

Clone the repository first:

git clone https://github.com/paundrapf/PaunClip.git
cd PaunClip

Windows

Open PowerShell in the repository root:

.\install.ps1

The installer will:

• validate Node.js 22+ and npm,
• run npm ci,
• download media tools,
• create %LOCALAPPDATA%\PaunClip\bin\paunclip.cmd,
• point the CLI shim at the bundled vendor/bin/win32/<arch>/yt-dlp.exe,
• add that folder to the current user's PATH,
• run npm run cli:smoke.

After install, open a new PowerShell window and test:

paunclip --help
paunclip doctor

Useful installer options:

.\install.ps1 --skip-install
.\install.ps1 --skip-smoke
.\install.ps1 --force
.\install.ps1 --dry-run

Uninstall the CLI shim and PATH entry:

.\uninstall.ps1

Linux

Run from the repository root:

chmod +x ./install.sh ./uninstall.sh
./install.sh

The installer will:

• validate Node.js 22+ and npm,
• run npm ci,
• download media tools,
• create ~/.local/bin/paunclip,
• point the CLI wrapper at the bundled vendor/bin/linux/<arch>/yt-dlp,
• add ~/.local/bin to ~/.profile when needed,
• run npm run cli:smoke.

Refresh your shell:

source ~/.profile

Then test:

paunclip --help
paunclip doctor

Useful installer options:

./install.sh --skip-install
./install.sh --skip-smoke
./install.sh --force
./install.sh --dry-run

Uninstall the CLI wrapper and PATH block:

./uninstall.sh

Run Modes

1. Web development

npm run dev

Open:

http://localhost:3000

Use this mode while developing UI, backend, pipeline logic, and settings.

2. Desktop app

Download the latest Windows desktop build from GitHub Releases when available, or build/package it locally:

npm run desktop:pack

Windows artifacts are created under:

dist/desktop

The desktop app stores user data under the OS user data directory, not inside the install folder.

Release builds are created by the desktop release workflow for tags such as v0.1.0.

3. CLI/headless

After install:

paunclip doctor
paunclip create clips "https://youtube.com/watch?v=..." --clips 3
paunclip create campaign "Creator Batch" "https://youtube.com/@channel" --fetch 10

Without installing to PATH:

node ./bin/paunclip.cjs --help

CLI Command Reference

Global options:

--profile <path>   Use a specific PaunClip profile directory
--json             Machine-readable output
--no-color         Disable ANSI colors in human output
--quiet            Reduce human output
--verbose          More diagnostics
--yes              Accept safe defaults
--help             Show help
--version          Show version

General:

paunclip --help
paunclip --version
paunclip setup
paunclip setup ai
paunclip setup ai task highlight-finder
paunclip setup ai task caption-maker
paunclip setup ai task hook-maker
paunclip setup ai task youtube-title-maker
paunclip setup ai quick --provider groq
paunclip setup ai validate
paunclip setup cookies
paunclip setup output
paunclip setup check
paunclip doctor

Human CLI output includes an ASCII PaunClip banner, colored status badges, and scan-friendly tables. Automation stays strict: --json disables colors, banners, and progress noise on stdout. You can also set NO_COLOR=1 or pass --no-color for plain output, and FORCE_COLOR=1 to force color in terminals that do not report TTY support.

Single-video clips:

paunclip create clips <youtube-url|video-path>
paunclip create clips <source> --clips 3
paunclip create clips <source> --prompt "find business lessons"
paunclip create clips <source> --prompt-file prompt.txt
paunclip create clips <source> --language id
paunclip create clips <source> --caption-style karaoke
paunclip create clips <source> --clip-length auto
paunclip create clips <source> --content-preset podcast
paunclip create clips <source> --reframe smart_face
paunclip create clips <source> --hook
paunclip create clips <source> --no-hook
paunclip create clips <source> --auto-render
paunclip create clips <source> --queue
paunclip create clips <source> --processing-start 00:10
paunclip create clips <source> --processing-end 10:00
paunclip create clips <source> --srt transcript.srt

Render:

paunclip render <sessionId>
paunclip render <sessionId> --all
paunclip render <sessionId> --select 1,3
paunclip render <sessionId> --queue

Campaigns:

paunclip create campaign <name> <youtube-channel-or-playlist>
paunclip create campaign <name> <source> --fetch 20
paunclip create campaign <name> <source> --type videos
paunclip create campaign <name> <source> --type shorts
paunclip create campaign <name> <source> --type all
paunclip campaign list
paunclip campaign show <campaignId>
paunclip campaign fetch <campaignId> --limit 20
paunclip campaign videos <campaignId>
paunclip campaign start <campaignId> --videos 1,2,3 --clips 3
paunclip campaign start <campaignId> --videos all --clips 3 --queue
paunclip campaign start <campaignId> --videos yt:<videoId> --clips 3
paunclip campaign start <campaignId> --per-video 1=5,2=3
paunclip campaign watch <campaignId>

Sessions:

paunclip sessions list
paunclip session show <sessionId>
paunclip session logs <sessionId>
paunclip session retry <sessionId>
paunclip session cancel <sessionId>

Jobs:

paunclip jobs list
paunclip job watch <jobId>
paunclip job cancel <jobId>

Configuration:

paunclip setup
paunclip setup ai
paunclip setup ai task highlight-finder
paunclip setup ai task caption-maker
paunclip setup ai task hook-maker
paunclip setup ai task youtube-title-maker
paunclip setup ai quick --provider groq
paunclip setup ai quick --provider groq --api-key-env GROQ_API_KEY --yes
paunclip setup ai task caption-maker --provider groq --api-key-env GROQ_API_KEY --model whisper-large-v3-turbo --yes
paunclip setup ai task hook-maker --provider groq --api-key-env GROQ_API_KEY --model canopylabs/orpheus-v1-english --voice hannah --yes
paunclip setup ai validate
paunclip setup ai validate hook-maker
paunclip setup cookies --path cookies.txt --yes
paunclip setup cookies validate-live <youtube-url>
paunclip setup output --path ./output --yes
paunclip setup check --json
paunclip doctor --youtube-url <youtube-url>
paunclip config init
paunclip config show
paunclip config doctor
paunclip config ai init [file]
paunclip config ai edit
paunclip config ai apply [file] --validate
paunclip config ai validate [file]
paunclip config ai show
paunclip config ai export <file>
paunclip config provider list
paunclip config provider validate <task>
paunclip config cookies detect <file>
paunclip config cookies validate <file>
paunclip config cookies set <file>
paunclip config cookies import <file>
paunclip config cookies status
paunclip config cookies clear
paunclip config output set <path>
paunclip config output path
paunclip config output open
paunclip config logs open
paunclip config presets list

Provider task names:

highlight-finder
caption-maker
hook-maker
youtube-title-maker

Recommended provider setup is the guided wizard:

paunclip setup

For only AI setup:

paunclip setup ai

paunclip setup ai is task-based. Normal users can configure one thing at a time:

• Highlight Finder: chat model for choosing moments.
• Caption Maker: transcription model for accurate captions.
• Hook Maker: TTS model plus voice.
• YouTube Title Maker: chat model for titles.

Custom OpenAI-compatible providers are filtered by capability. For example, chat-only endpoints such as OpenCode can be used for Highlight Finder and YouTube Title Maker, but should not be selected for Caption Maker or Hook Maker.

For VPS/automation, keep the key in an environment variable:

export GROQ_API_KEY="your-groq-api-key"
paunclip setup ai quick --provider groq --api-key-env GROQ_API_KEY --yes

Advanced JSON config is still supported:

paunclip config ai init
paunclip config ai edit
paunclip config ai apply --validate

On Windows, paunclip config ai edit opens Notepad by default. On Linux, it uses $VISUAL, $EDITOR, or nano. paunclip.ai.local.json is gitignored because it may contain local API keys. A safe template without secrets lives in paunclip.ai.example.json.

paunclip config provider set ... still exists for old scripts, but new users should start with paunclip setup.

Cookie setup supports common browser-extension exports:

paunclip setup cookies
paunclip config cookies detect cookies.txt
paunclip setup cookies validate-live "https://youtube.com/watch?v=..."

If the file is already Netscape cookies.txt, PaunClip stores a reference to that path. If the file is JSON or a raw Cookie: header, PaunClip converts it to a private Netscape file because yt-dlp expects that format.

The normal cookie check only verifies that the file is readable and contains YouTube login-shaped cookies. The live check verifies the thing that matters for rendering: metadata, subtitles, and video media stream access for a real URL. This is especially important on VPS/datacenter machines, where YouTube can allow subtitles but block video download with a bot challenge.

Basic Workflow

1. Install PaunClip and run:

   paunclip setup

2. Confirm everything is ready:

   paunclip setup check
   paunclip doctor --youtube-url "https://youtube.com/watch?v=..."

3. Add cookies later if YouTube requires them:

   paunclip setup cookies

4. Create a single-video session:

   paunclip create clips "https://youtube.com/watch?v=..." --clips 3

5. Review highlights in the app or render from CLI:

   paunclip render <sessionId> --all

6. For channel batches:

   paunclip create campaign "My Batch" "https://youtube.com/@channel" --fetch 20
   paunclip campaign videos <campaignId>
   paunclip campaign start <campaignId> --videos 1,2,3 --clips 3

Local Data and Profiles

PaunClip is local-first. It stores data in a profile directory:

• settings
• provider config
• cookies
• SQLite database
• source media
• rendered clips
• logs

Use a separate profile for testing:

paunclip --profile ./tmp-profile doctor

Do not commit profile folders, .env, cookies, API keys, storage, or rendered clips.

Troubleshooting

paunclip is not recognized

Open a new terminal after running the installer.

On Windows, confirm this folder is in user PATH:

%LOCALAPPDATA%\PaunClip\bin

On Linux, confirm:

echo "$PATH" | grep "$HOME/.local/bin"

Node.js version error

Install Node.js 22+ and open a new terminal.

YouTube download or metadata fails

• Run paunclip doctor.
• Run paunclip doctor --youtube-url "<url>" to live-test metadata, subtitles, and media download.
• Check yt-dlp status.
• Import cookies if YouTube blocks access.
• Run paunclip setup cookies validate-live "<url>" after refreshing cookies.
• Try fetching fewer videos in Campaign mode.
• If analysis succeeds but render fails, YouTube likely allowed subtitles but blocked video media download on that machine. Refresh cookies, render on the local desktop app/laptop, or upload a local MP4 fallback.

AI provider fails

• Run the guided AI setup again:

  paunclip setup ai
  paunclip setup check

• Make sure the provider supports the task:

  • chat for Highlight Finder,
  • transcription for Caption Maker,
  • TTS/voice for Hook Maker.

• For OpenAI-compatible custom providers, use the base URL, not the full chat completion endpoint.

Captions are delayed

Use a transcription provider that returns timestamps. SRT fallback is a last resort and can be less precise.

Output folder confusion

Check:

paunclip setup output
paunclip config output path

Desktop and CLI profiles may use different storage/output paths.

Development

Install dependencies:

npm ci

Run checks:

npm run typecheck
npm run lint
npm test
npm run build
npm run cli:smoke

Run web app:

npm run dev

Run CLI without installing:

node ./bin/paunclip.cjs --help

Package desktop:

npm run desktop:pack
npm run desktop:smoke

desktop:smoke expects a freshly packaged Windows build under dist/desktop.

Branch and Release Workflow

Recommended workflow:

1. Build changes on a feature branch.
2. Open a pull request into main.
3. Let CI run typecheck, lint, tests, build, and CLI smoke.
4. Merge when CI and manual smoke checks are stable.
5. Create a v*.*.* tag to publish Windows desktop artifacts through GitHub Releases.
6. Add auto-update metadata once release artifacts are stable.

Security Notes

• PaunClip is local-first, but API keys and cookies are sensitive.
• Do not commit .env, cookies, storage, logs, rendered clips, or profile directories.
• Prefer paunclip setup, environment variables, or the Settings UI for secrets.
• Keep cookies private and rotate them if they are exposed.
• Report security issues privately. See SECURITY.md.

License

MIT. See LICENSE.