Tutorial & FAQ

Complete guide to installing, using, and troubleshooting Qlipper AI

Getting Started

What is Qlipper AI?

Qlipper AI is a local, AI-powered video clipping tool that runs entirely on your computer. No cloud uploads, no monthly subscriptions. Download YouTube videos, analyze them with AI, and create viral clips automatically.

  • 100% Local: All processing happens on your machine
  • Unlimited: No per-video or per-minute charges
  • Private: Your videos never leave your computer
  • AI-Powered: Automatically finds viral moments using Gemini AI

System Requirements

Minimum

  • • macOS 10.15+ or Windows 10+
  • • 8GB RAM
  • • 500MB free storage
  • • Internet (for AI analysis)

Recommended

  • • 16GB+ RAM
  • • Apple Silicon or modern CPU
  • • SSD with 50GB+ free
  • • Stable internet connection

Installation

Method 1: One-Click Launch (Recommended)

macOS

Double-click Qlipper-AI.command or run:

cd /path/to/QLIPPER/app
./run-mac.sh

Windows

Double-click run-windows.bat

Method 2: Manual Installation

Step 1: Install Node.js

Download and install from nodejs.org (LTS version)

macOS users can also use: brew install node

Step 2: Install Dependencies

cd /path/to/QLIPPER/app

# Install backend dependencies
cd backend
npm install

# Install frontend dependencies
cd ../frontend
npm install

# Build frontend
npm run build

Step 3: Start Server

cd ../backend
npm start

Then open http://localhost:3001 in your browser

What Gets Installed Automatically

Component Location Purpose
yt-dlp backend/bin/ YouTube downloader
ffmpeg backend/bin/ Video processing
Puppeteer Chrome Auto-downloaded Text overlay rendering
Node modules backend/node_modules/ Backend dependencies

First-Time Setup

1. Get an API Key

You need at least one AI API key. Gemini is recommended (free tier available):

  1. Go to ai.google.dev
  2. Click "Get API Key"
  3. Create a new key
  4. Copy the key

2. Configure Settings

  1. Open Qlipper AI in your browser (http://localhost:3001)
  2. Click the Settings icon (⚙️) in the top right
  3. Paste your API key in the "Gemini API Key" field
  4. Click outside the modal to save

3. Test the Pipeline

  1. Copy a YouTube URL
  2. Paste it in the search bar
  3. Click the sparkles button (✨)
  4. Configure settings and click "Get AI Clips"
  5. Wait for processing to complete

User Guide

Quick Start: Unified Pipeline

The fastest way to create clips from a YouTube video:

  1. Paste a YouTube URL in the main search bar
  2. Click the sparkles button (✨) or press Enter
  3. Wait for download and transcription
  4. Select AI model and configure clip settings
  5. Click "Get AI Clips"
  6. Review and download your clips

Tool A: YouTube Download

Download YouTube videos to your Asset Library:

  • Toggle "Save to Asset Library" ON
  • Paste YouTube URL
  • Click Download
  • Video will be saved and auto-transcribed

Tool B: AI Analysis

Analyze videos with AI to find viral moments:

  • Select video source (YouTube URL or Asset Library)
  • Choose AI model (Gemini, GPT-4o, Claude, etc.)
  • Click "Analyze"
  • Analysis results are saved automatically

Tool C: Clipper

Create clips from analysis results:

  • Select video source (YouTube URL or Asset Library)
  • Optionally select a saved analysis
  • Paste or edit clip JSON
  • Configure style settings
  • Click "Process Clips"

What's New? (Version Changelog)

What Features Are Included in the Latest Version?

Qlipper AI is constantly improving. Check the latest features and improvements:

v1.6.5 (Latest)

Feb 8, 2026

Smart Quality Picker + Accurate Subtitles

  • • Smart Quality Picker: Probes YouTube for available resolutions before download (no more blind 4K selection on 720p videos)
  • • Auto-select Best Quality: Gold-accented UI shows exactly what's available
  • • Whisper Word-Level Transcription: Precise subtitle timing using base model with word_timestamps=True
  • • Isolated to Subtitles Only: Lazy loading with no performance hit on lower-end Windows devices
  • • Caption Quality Indicator: Shows "YouTube Captions" vs "AI Enhanced" with manual "Enhance Accuracy" button
  • • Smart Caching: Backend prefers Whisper word-level data over VTT when available

v1.6.4

Feb 8, 2026

Critical Bug Fixes + UX Improvements

  • • Input/ColorPicker z-index layering fixes (100% click reliability)
  • • FFmpeg filter escaping improvements (prevents crashes with special chars)
  • • Subtitle system mutual exclusion (ASS preferred)
  • • Subtitle spacing fixes (preview matches export)

v1.6.3

Feb 7, 2026

ASS Subtitle Engine (10-100x faster)

  • • Native ASS subtitle burning (no more PNG overlays)
  • • Word-by-word karaoke with glow/scale/color
  • • Zero stream ID collisions

For the full version history, visit GitHub or check the CHANGELOG.md file

Troubleshooting

403 Forbidden Error

▼

Symptoms: YouTube downloads fail with "403 Forbidden" or "HTTP Error 403"

Cause: YouTube is blocking the download request. This is usually temporary.

Solutions:

  1. Update yt-dlp: Go to Settings → YouTube Downloader → Click "Update yt-dlp"
  2. Wait 5-10 minutes and try again
  3. Try a different video to test if it's video-specific
  4. Restart the application

Note: Qlipper AI v1.5.1+ includes automatic retry with multiple strategies. If one method fails, it will automatically try another.

DRM Protected / JavaScript Runtime Error

▼

Symptoms: Error message says "This video is DRM protected" or mentions "nsig" or "signature extraction"

Cause: This is usually NOT actual DRM. It means yt-dlp needs a JavaScript runtime (Node.js or Deno) to solve YouTube's protection challenges.

Solutions:

  1. Update yt-dlp: Settings → YouTube Downloader → "Update yt-dlp"
  2. Ensure Node.js is installed: Run node --version in terminal
  3. Restart the application after updating
  4. Try a different video to test if yt-dlp works

Note: Qlipper AI v1.5.1+ automatically configures yt-dlp to use Node.js, which should resolve this issue for most users.

Node.js Not Found

▼

Symptoms: Error message says "Node.js not found" or "node: command not found"

Solutions:

macOS:

# Install via Homebrew
brew install node

# Or download from nodejs.org
# Then restart terminal

Windows:

  1. Download from nodejs.org
  2. Run the installer
  3. Restart Command Prompt

Frontend Not Built

▼

Symptoms: Error says "Frontend not built. Run: cd frontend && npm run build"

Solutions:

cd /path/to/QLIPPER/app/frontend
npm install
npm run build

Note: This should happen automatically on first launch. If it doesn't, run the commands above manually.

Gemini Model Error: "Must provide a model name"

▼

Symptoms: AI analysis fails with "Must provide a model name" error

Cause: The Gemini model variant setting is empty or invalid.

Solutions:

  1. Go to Settings
  2. Check "Gemini Model Variant" field
  3. If empty, set it to: gemini-1.5-flash-latest
  4. Or clear the field to use default
  5. Click outside to save
  6. Try analysis again

Note: Qlipper AI v1.5.1+ automatically handles empty model names.

Port 3001 Already in Use

▼

Symptoms: Server fails to start with "EADDRINUSE" or "port already in use"

Solutions:

macOS/Linux:

# Find process using port 3001
lsof -i :3001

# Kill the process (replace PID with actual process ID)
kill -9 <PID>

Windows:

# Find process using port 3001
netstat -ano | findstr :3001

# Kill the process (replace PID with actual process ID)
taskkill /PID <PID> /F

Or simply close any other Qlipper AI instances that might be running.

FFmpeg Download Failed / Runtime Error

▼

Symptoms: Error message says "Downloaded ffmpeg but it failed to run" or "FFmpeg test failed"

Cause: FFmpeg was downloaded but cannot execute. This is commonly due to antivirus blocking, corrupted download, missing dependencies, or permission issues.

Solutions:

Quick Fix (Recommended):

Install FFmpeg through your system package manager. This avoids download issues and is the easiest solution.

macOS:

  1. Open Terminal
  2. Install Homebrew (if not installed): ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  3. Install FFmpeg: brew install ffmpeg
  4. Verify installation: ffmpeg -version
  5. Restart Qlipper AI

Windows:

Use Windows Package Manager (winget):

  1. Open Command Prompt (Win + R, type "cmd", press Enter)
  2. Run: winget install ffmpeg
  3. If prompted, press "Y" to agree to the license
  4. Wait for installation to complete
  5. Verify installation: ffmpeg -version
  6. Close Command Prompt and restart Qlipper AI

Alternative for Windows (Chocolatey):

If winget is not available, use Chocolatey:

  1. Open Command Prompt as Administrator (right-click → "Run as administrator")
  2. Run: choco install ffmpeg
  3. Restart your computer
  4. Restart Qlipper AI

Troubleshooting Steps:

  1. Check if antivirus is blocking: Temporarily disable antivirus/Windows Defender and restart Qlipper AI
  2. Clear cache: Delete the backend/bin folder and restart Qlipper AI
  3. Check permissions: Make sure your user account has write permissions to the installation directory
  4. Restart your computer: This often resolves permission and system issues

Note: After installing FFmpeg via package manager, you can safely delete the backend/bin/ folder. Qlipper AI will use the system-installed FFmpeg instead.

Preflight Failed: yt-dlp Blocked or Can't Download

▼

Symptoms: Terminal shows ✗ yt-dlp exists but failed to run, followed by ECONNRESET then ECONNABORTED during re-download attempt.

Cause: Two compounding issues: (1) Windows Defender/antivirus silently blocks yt-dlp.exe from running, and (2) the auto-repair download from GitHub fails due to firewall or regional ISP block.

Solutions (pick just one):

Option 1 — Add Windows Defender Exclusion (Recommended)

  1. Open Windows Security → Virus & threat protection → Manage settings
  2. Scroll to Exclusions → Add or remove exclusions
  3. Add the entire Qlipper folder (e.g. D:\YT SHORT\Qlipper-AI-v1.6.15\)
  4. Restart Qlipper AI — preflight will re-test the binary

Option 2 — Manual yt-dlp Download (Works without internet via GitHub)

  1. On another device or with VPN, go to: github.com/yt-dlp/yt-dlp/releases/latest
  2. Download yt-dlp.exe
  3. Place it at: [your Qlipper folder]\backend\bin\yt-dlp.exe (replace existing)
  4. Restart Qlipper AI

Option 3 — Use a VPN, then restart

Enable a VPN to allow the auto-repair download from GitHub to succeed. After startup completes, the VPN can be turned off for normal use.

Note: You only need ONE option to work. Try Option 1 first.

Other Common Issues

Permission Denied (macOS)

chmod +x run-mac.sh
chmod +x Qlipper-AI.command

npm install Fails

# Clear npm cache
npm cache clean --force

# Delete node_modules and retry
rm -rf node_modules
npm install

yt-dlp Not Working

The preflight check should auto-download yt-dlp. If it fails:

macOS: brew install yt-dlp

Windows: Download from GitHub releases

FFmpeg Not Found

macOS: brew install ffmpeg

Windows: Download from ffmpeg.org and add to PATH

Need more help? Check out the full documentation in the documentation/ folder

← Back to Home