Read this in Portuguese (pt-BR).
Clipador turns a raw YouTube video (or a local file) into a queue of short (9:16, Reels/Shorts/TikTok format) and long (16:9) clips, already cut, subtitled, with a thumbnail and metadata, ready for a human to review and post.
Nothing publishes automatically: the pipeline is 100% assisted generation, every clip always goes through an editorial checkpoint before going live.
- What the project does
- How it works (architecture)
- Repository structure
- Prerequisites
- Installation and first run
- Environment variables
- Useful commands per part of the project
- Additional documentation
- License
You give it a YouTube link (or a local video file) and a content category, and Clipador delivers, for each clip:
- Automatic selection of the best excerpts from the source video, chosen by an LLM from the full transcript (not generic silence/scene cutting: the model reads the content and picks what has viral potential, with a rerank pass and a prosody check).
- Vertical reframing (9:16) with face detection and active-speaker detection, so the clip comes out framed like an actual Reel/Short, not a horizontal video with black bars.
- Karaoke-style burned-in subtitles, word by word, with ready-made visual presets
(
impacto,anton,neon,classico) and an option to highlight keywords with their own color. - AI-composed thumbnail: person cutout, background treatment/generation via Gemini ("Nano Banana"), with a local fallback (Pillow) when the AI key isn't configured, so the pipeline never gets stuck for lack of it.
- Title, description and hashtags generated by an LLM, ready to paste into the post.
- Optional watermark, applied by explicit decision on each run (never a silent default).
- Review queue: every run produces a manifest (
manifest.json) and aready-to-post.txtper clip; re-running against the same video generates new clips, without repeating excerpts already used.
The desktop app (app/) is the main way to use Clipador: download the installer
from Releases, install with one
click, no Python or terminal required, updates itself. The same engine (engine/) can
also be used directly through the Python CLI, useful for development or scripting.
YouTube / local file
│
▼
┌───────────────────┐ transcription, excerpt selection, cutting, reframing,
│ engine (Python) │ subtitles, thumbnail, title/description/hashtags
└─────────▲─────────┘ runs as a CLI, no server of its own
│ spawns the engine as a subprocess (never reimplements its logic)
┌─────────┴─────────┐
│ app (Electron) │ desktop UI: New Clip, Rebrand, Settings, KB editor
└────────────────────┘ ships with Python + the engine + ffmpeg bundled in
engine/is the only part that knows how to transcribe, cut, reframe, subtitle, and generate thumbnails/metadata. It runs standalone from the command line, and is treated as a black box byapp/: none of its logic is reimplemented in TypeScript.app/is the Electron desktop app: the distributable product. Its installer bundles a portable Python runtime with the engine's dependencies already installed plus ffmpeg, so a non-technical person can install and use it with no Python, no terminal, and no manual setup. Auto-updates itself via GitHub Releases.
pster-cliping/
├── engine/ # Python pipeline (transcription → cut → subtitles → thumbnail → metadata)
│ ├── src/clipador/ # pipeline code, see engine/CLAUDE.md for the full layout
│ ├── kb/ # knowledge base per content category
│ └── README.md # how to install and run the engine, full CLI guide
├── app/ # Electron desktop app, the distributable product
│ ├── scripts/ # build-python-runtime.ps1, fetch-ffmpeg.ps1 (embedded runtime)
│ └── README.md
├── .github/workflows/ # release.yml: builds and publishes the installer on a version tag
├── .docs/decisions/ # technical decision records with the evidence behind them
└── LICENSE # PolyForm Noncommercial 1.0.0
Each code folder has its own README.md (install and usage) and CLAUDE.md (stack,
internal layout, and binding technical decisions for that part). This root README is
the entry point; for deep detail on any part, go straight to its README/CLAUDE.md.
| Tool | What for | Required for |
|---|---|---|
| Nothing | just install and run the app | the desktop app (.exe from Releases) |
| Python >= 3.11 | runs the engine | running the CLI directly, or app/ in dev mode |
| ffmpeg on PATH, built with libass | cutting, reframing, subtitle burn-in | engine (CLI/dev only; bundled in the desktop app) |
| Node.js 24 and npm | building/running the Electron app from source | app/ in dev mode, or building the installer yourself |
| CUDA GPU | optional, only if you opt into local transcription (whisperx/faster-whisper) |
nothing by default: the default configuration runs 100% on CPU/cloud |
Download the latest installer from
Releases, run it (one click, no
admin needed), and open Clipador from the Desktop/Start Menu shortcut. Fill in your AI
API keys in the Settings screen and you're ready to generate clips. Details on the
bundled runtime and auto-update in app/README.md.
For development or scripting, without the desktop app:
git clone https://github.com/J-Pster/pster-cliping.git
cd pster-cliping/engine
pip install -e ".[video,cloud-transcribe,thumbnail-ai]"
cp .env.example .env
# fill in ELEVENLABS_API_KEY and CLAUDE_CODE_OAUTH_TOKEN (or ANTHROPIC_API_KEY) in .env
python -m clipador.cli "https://www.youtube.com/watch?v=XXXXXXXXXXX" \
--category politico_pessoa \
--watermark offClips land in engine/output/<video_id>_<title>/, together with the thumbnail, burned-in
subtitles, metadata, and a ready-to-post.txt per clip. Full install guide (optional
extras, GPU, fonts) and usage guide (every flag) in engine/README.md.
No credential is hardcoded in code: everything comes from .env. engine/.env.example
documents every variable line by line; summary of the most important ones:
| Variable | Required | Description |
|---|---|---|
ELEVENLABS_API_KEY |
yes, by default | transcription via ElevenLabs Scribe v2 (default backend; without the key the pipeline fails loudly on purpose, see .docs/decisions/2026-09-02-transcricao-elevenlabs-scribe.md) |
CLAUDE_CODE_OAUTH_TOKEN |
yes (oauth mode, default) |
token generated with claude setup-token, consumes the Claude Pro/Max subscription quota |
ANTHROPIC_API_KEY |
yes (if CLIPADOR_LLM_AUTH_MODE=api_key) |
pay-per-use billing directly on the Anthropic API |
GEMINI_API_KEY |
optional | AI thumbnail (without it, falls back to a local Pillow treatment) and text LLM if CLIPADOR_TEXT_LLM_PROVIDER=gemini |
CLIPADOR_TEXT_LLM_PROVIDER |
optional (claude default) |
claude or gemini, the LLM used for the text stages |
CLIPADOR_LLM_AUTH_MODE |
optional (oauth default) |
oauth or api_key, only matters with CLIPADOR_TEXT_LLM_PROVIDER=claude |
HUGGINGFACE_TOKEN |
optional | real diarization on the local whisperx --diarize backend |
ASSEMBLYAI_API_KEY |
optional | only for --transcriber assemblyai |
BUFFER_API_KEY + BUFFER_CHANNEL_<GROUP>_<PLATFORM> |
optional | automatic publishing of approved clips via Buffer (clipador-publish) |
# engine (Python) — from the engine/ folder
python -m pytest tests/ -q # offline suite, no real network/ffmpeg
python -m clipador.cli --help # full, always-current flag list
python scripts/run_test_video.py # end to end with the test video
# app (Electron) — from the app/ folder
npm run dev # app + hot reload
npm run build # typecheck + production build
npm run dist # build the Windows installer locally (needs runtime:all first)engine/README.md— full install and CLI usage guide (every flag, optional extras, subtitle presets).engine/CLAUDE.md— stack, internal layout, and binding technical decisions for the engine.app/README.md— desktop app dev setup, bundled runtime, packaging, and auto-update..docs/decisions/— decision records with the evidence behind non-obvious choices (e.g. why transcription uses ElevenLabs Scribe v2 instead of a local model).
This project is under the PolyForm Noncommercial License 1.0.0: personal and noncommercial use is free; commercial use requires direct authorization from the author (Joao Pster).