HHOOKYDOCS
← Back to Home GitHubGet Hooky
GETTING STARTED

Quickstart Guide

Hooky is an autonomous, terminal-first AI video clipper and local Web Studio. It ingests long YouTube videos or local MP4 files, extracts high-retention hooks with Google Gemini 2.0, generates word-level animated subtitles with Whisper, and renders 9:16 vertical videos using FFmpeg—all on your own machine.

Automated setup

You do not need to install Python virtual environments, pip packages, or FFmpeg manually. The main.sh and main.ps1 scripts detect missing prerequisites and install them automatically.

1. Installation

Clone the repository and launch the all-in-one runner for your operating system:

macOS / Linux
git clone https://github.com/pranav256/Hooky.git
cd Hooky
./main.sh
Windows (PowerShell)
git clone https://github.com/pranav256/Hooky.git
cd Hooky
Set-ExecutionPolicy -Scope Process Bypass
.\main.ps1

2. What happens on the first run?

  1. FFmpeg Check: Auto-installs FFmpeg & FFprobe using Homebrew (macOS), apt/dnf/pacman (Linux), or winget (Windows).
  2. Package Manager: Installs uv (the ultra-fast Python package installer) if not present.
  3. Virtual Environment: Creates .venv and installs exact locked dependencies in ~5 seconds.
  4. Configuration: Auto-generates your local .env file from .env.example.
  5. Web Studio Launch: Boots the Web Studio at http://127.0.0.1:8000 and pops open your default web browser!
ARCHITECTURE

The Autonomous Pipeline

Understanding how Hooky transforms a 2-hour long horizontal podcast into multiple viral 9:16 Shorts with zero human intervention.

01

Discovery / Radar

Scans channels.txt or accepts raw URLs in links.txt.

→
02

Gemini 2.0 AI

Semantic narrative analysis, tension curves & virality scoring (1-99).

→
03

Whisper Sync

Word-level microsecond alignment fusing source captions + int8 Whisper.

→
04

9:16 Framing

Active speaker auto-tracking, dynamic blur canvas, or centered crop.

→
05

Caption Burn

Hormozi kinetic pop subtitles rendered via vector ASS stream.

→
06

Atomic Export

Crash-proof FFmpeg render with render_state.json resumption.

Why local-first processing matters

Data privacy and security

Cloud clipping SaaS platforms require uploading gigabytes of your raw video footage to third-party cloud buckets. Hooky keeps 100% of your video files on your local drive. Only the text transcript is sent to Google Gemini for hook selection.

Zero minute caps and zero fees

Cloud tools charge $19–$99/month and throttle you with 60–120 minute monthly limits. Hooky is MIT-licensed, completely free, and has zero limits. Process 100 hours of video every day at zero software cost.

USER INTERFACE

Web Studio Manual

The built-in Web Studio gives you a visual cockpit to preview hook recommendations, trim timestamps, test framing modes, and manage settings.

Launching the Studio

Run the launcher without arguments or specify the web command:

./main.sh web
Hooky Web Studio Interface
Interactive Hook Workbench — Dual-Mode 9:16 Canvas Simulator & Dialogue Inspectorhttp://127.0.0.1:8000

Core Web Studio Features

  • Dual-Mode Visual Stage: Seamlessly toggle between the live YouTube video player and the 9:16 Canvas Simulator with animated avatars.
  • Intelligent Framing Selector:
    • Auto-Track (Speaker): Detects speaker position and applies smooth horizontal panning to keep faces centered.
    • Fit (Gaussian Blur): Fits the full 16:9 video in the center while generating a dynamic blurred background.
    • Center Crop (9:16): Directly crops the middle 1080×1920 region.
  • Kinetic Subtitle Preview: Real-time word highlight playback matching the Hormozi, Clean, and Yellow subtitle engines.
  • ±0.5s Timestamp Nudge Controls: Granular precision to fine-tune hook entry and exit cut points down to the millisecond.
  • Settings Manager: View and edit your .env file with automatic credential masking (••••••••) for Instagram passwords and API keys.
  • Output Gallery: Instant in-browser playback for all rendered MP4 clips with one-click file download.
Hooky Settings Editor
Environment Configuration (.env)
Hooky Channel Radar Monitor
Channel Radar (channels.txt)
Local security and token authentication

Web Studio binds strictly to loopback (127.0.0.1), generates a cryptographically secure one-time session token on each launch, and enforces strict Host/Origin validation to protect against malicious web scripts or DNS rebinding.

TERMINAL REFERENCE

CLI Command Reference

Every feature in Hooky can be scripted headlessly or scheduled via cron / Task Scheduler.

./main.sh webPORTAL

Launches the FastAPI Web Studio server, generates session credentials, and opens your default browser at http://127.0.0.1:8000.

./main.sh makeAUTOMATION

Autonomous batch clipping engine. Reads handles from channels.txt and links from links.txt, extracts top viral moments, downloads source media, burns subtitles, and outputs finished 9:16 clips to output/.

./main.sh doctorDIAGNOSTICS

Performs a comprehensive environment audit: verifies FFmpeg/FFprobe binaries, checks CUDA/hardware acceleration, validates Python packages, and makes a lightweight test ping with your Gemini API key.

./main.sh channelsRADAR

Inspects all YouTube channels listed in channels.txt, fetches view velocity, filters videos exceeding view thresholds, and populates the clipping queue.

./main.sh parts [URL or file.mp4]SERIES

Splits long interviews or stories into a serialized "Part 1, Part 2, Part 3..." series, using sentence and scene boundaries to avoid cutting speakers mid-sentence.

./main.sh queuePUBLISHER

Inspects the local Instagram publishing queue, checks pending clips, schedules upload windows, and runs the safe-pacing jitter scheduler.

CONFIGURATION

Config & Environment

Customize Hooky's AI models, FFmpeg quality profiles, subtitle typography, and Instagram safe posting windows.

.env Configuration Keys

VariableDefaultDescription
GEMINI_API_KEY—Google Gemini API key (free from Google AI Studio).
GEMINI_MODELgemini-3.8-flashPrimary Gemini model for transcript reasoning and viral scoring.
GEMINI_MODEL_FALLBACKSgemini-3.1-flash-liteAutomatic fallback chain if rate limits or quota caps are hit.
QUALITYhighesthighest (CRF 15, medium preset) or high (CRF 20, fast encode).
WHISPER_MODELtinyWhisper model size: tiny, base, or small.
WHISPER_COMPUTEint8Quantization mode. int8 runs smoothly on modest CPUs with ~4GB RAM.
SUB_STYLEhormoziSubtitle preset: hormozi, clean, or yellow.
SUB_FONTArialFont family for burned ASS subtitles.
PARTS_BACKGROUNDblurBackground for 9:16 portrait fit: blur (Gaussian) or plain.
IG_USERNAME / IG_PASSWORD—Optional Instagram credentials for autonomous Reels publishing.
QUEUE_MIN_GAP_MINUTES60Minimum randomized cooldown interval between social uploads.

channels.txt Radar Syntax

Add YouTube channel handles to monitor and auto-clip top performers:

# Syntax: @handle | limit=N min_views=N
@hubermanlab | limit=3 min_views=250000
https://www.youtube.com/@TheDiaryOfACEO | limit=2 min_views=500000
@lexfridman | limit=1

links.txt Direct Ingestion Syntax

Target specific YouTube URLs or local video files with inline overrides:

# Syntax: URL_OR_PATH | clips=N | min=S max=S | style=STYLE
https://www.youtube.com/watch?v=dQw4w9WgXcQ | clips=auto | style=hormozi
D:/Videos/Podcast_Episode_42.mp4 | clips=5 | min=20 max=55 | style=yellow
ANIMATION & CAPTIONS

Subtitles & Styling

Hooky features a specialized Advanced SubStation Alpha (ASS) engine that generates broadcast-grade, word-by-word animated karaoke subtitles.

PRESET

Hormozi Kinetic Pop

High-energy uppercase typography, bold font weights, and an acid-green active word highlight pop.

YOU DON'T NEED MORE CONTENT.
YOU NEED BETTER MOMENTS.
PRESET

Editorial Clean

Understated elegance with a translucent dark backing pill, mixed-case lettering, and white accent highlights.

Every story has a punchline. Find it.
PRESET

Cyberpunk Yellow

Neon yellow highlight with black drop shadows and monospace framing for tech, gaming, and developer clips.

[00:14] HIGHEST_RETENTION_HOOK
SUPPORT

FAQ & Troubleshooting

Answers to common questions regarding hardware, quotas, and troubleshooting.

Do I need an NVIDIA GPU to run Hooky?

No. Hooky was specifically engineered with lightweight defaults (Whisper int8 quantization and multi-threaded FFmpeg CPU encoding). It runs comfortably on standard 4GB RAM laptops with dual-core processors. If an NVIDIA GPU with CUDA is present, Hooky automatically detects it for faster rendering.

How much does the Google Gemini API cost?

$0 for standard usage. Google AI Studio provides a generous free tier for Gemini models (like gemini-3.8-flash and gemini-3.1-flash-lite). Hooky only sends transcript text (roughly two small API calls per video), so you can process dozens of videos daily without exceeding free limits.

How does Hooky prevent Instagram bans?

Hooky incorporates human-like jitter intervals (60–120 minutes between posts), configurable posting hour windows (e.g. 5 PM to midnight), and atomic upload locks. It marks posts with an uncertain outcome state rather than immediately retrying, preventing accidental double-posts.

What should I do if FFmpeg is missing?

Run ./main.sh doctor (or .\main.ps1 doctor). The launcher will detect that FFmpeg is missing and offer to install it automatically via your system package manager.