StreamClipper ✂️

AI-assisted first cut — gets you 5 strong draft clips from any stream, fast.

StreamClipper runs an end-to-end pipeline: find → download → transcribe → score → rerank → cut → deliver. No manual scrubbing, no export queues. Just clips in your Telegram.

---

Pipeline

Find video → Download → Whisper transcribe → LLM candidates → Vision rerank → Quality filter → ffmpeg cut → Telegram

Every run writes three inspectable artifacts to output/<video_id>_vision/:

• candidates.json — all LLM-generated clip proposals
• ranking.json — vision model scores
• selection.json — final selected clips with policy applied

---

System Requirements

Requirement	Details
OS	Windows 10 / 11 (current target)
Python	3.10+ (3.11 or 3.12 recommended)
ffmpeg + ffprobe	Both must be on PATH
Internet	YouTube, Groq, and Telegram APIs called at runtime

---

Quick Start

1 — Install Python

Download from python.org. During install, check "Add Python to PATH".

python --version

2 — Install ffmpeg

Option A — winget (Windows):

winget install Gyan.FFmpeg

Option B — manual: Download a build, extract, and add the bin/ folder to your PATH.

Verify:

ffmpeg -version
ffprobe -version

3 — Clone the repo

git clone <your-repo-url>
cd StreamClipper

4 — Create a virtual environment

python -m venv .venv
.venv\Scripts\activate

5 — Install dependencies

pip install --upgrade pip
pip install -r requirements.txt

5.1 — Whisper setup (important)

Whisper is already included in requirements.txt (openai-whisper + torch), but on first run it downloads the selected model automatically.

Default in config.yaml:

whisper_model: "base"

You can switch to:

• tiny (fastest, lowest accuracy)
• base (recommended default)
• small (better accuracy, slower)
• medium / large (best quality, much slower/heavier)

Optional pre-download (so first pipeline run is faster):

python -c "import whisper; whisper.load_model('base')"

6 — Configure your credentials

copy config.example.yaml config.yaml

Open config.yaml and fill in:

youtube_channel_id: "YOUR_CHANNEL_ID"
youtube_api_key:    "YOUR_YT_KEY"
groq_api_key:       "YOUR_GROQ_KEY"
telegram_bot_token: "YOUR_BOT_TOKEN"
telegram_chat_id:   "YOUR_CHAT_ID"

---

API Setup

Telegram

1. Message @BotFather and run /newbot
2. Copy the bot token → telegram_bot_token
3. Send any message to your new bot, then open:

   https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
   

4. Copy the chat.id value → telegram_chat_id

YouTube Data API

1. Create a project in Google Cloud Console
2. Enable YouTube Data API v3
3. Create an API key → youtube_api_key
4. Find your target channel ID → youtube_channel_id

Groq

1. Create an account at console.groq.com
2. Generate an API key → groq_api_key
3. Optionally change models in config:
   • groq_model — candidate generation
   • groq_vision_model — vision reranking

---

Run Commands

One-shot mode (recommended)

python pipeline.py "pragyan chakra sih"

Or use the batch shortcut:

run_streamclipper.bat "pragyan chakra sih"

Utilities

python pipeline.py health   # verify API connectivity
python pipeline.py status   # show last run state
python pipeline.py          # auto polling mode (continuous)

---

Config Reference

Key	What it controls
max_candidates	Upper bound on LLM clip candidates per run
target_final_clips	How many clips to aim for in the final selection
quality_*	Score thresholds — clips below these are dropped
min_*	Minimum acceptance policy (overrides quality gate)
preselection_backfill_*	LLM score backfill limits before selection runs
created_backfill_*	LLM score backfill limits for post-creation clips
telegram_retries	Retry budget for Telegram delivery failures
groq_retries	Retry budget for Groq API failures
youtube_api_retries	Retry budget for YouTube API failures

---

Typical Runtimes

Video length	Estimated runtime
3–10 minutes	~2–8 minutes
30–60 minutes	~8–25 minutes
2–3 hour stream	~20–60+ minutes

Times vary with Groq API latency and vision reranking workload.

---

Fallback Behavior

If StreamClipper can't produce a full output it degrades gracefully:

• Sends any partial clips it successfully cut
• Falls back to a "Top fallback picks" list delivered via Telegram
• On hard Groq rate limits: aborts early and notifies Telegram before exiting

---

Security

⚠️ Never commit real credentials.

Only config.example.yaml belongs in the repo. config.yaml, output/, and temp/ are gitignored.

Before publishing:

1. Revoke and regenerate any keys used locally
2. Confirm config.yaml is not in git history
3. Keep only config.example.yaml in the repo

---

Troubleshooting

ffmpeg not found Install ffmpeg and add the bin/ directory to your PATH environment variable. Restart your terminal after updating PATH.

Stopped due to rate limit The run aborted by design to avoid burning retries on a capped API window. Wait for your Groq quota to reset and retry. Upgrading your Groq plan increases throughput.

Telegram messages not arriving Check telegram_bot_token and telegram_chat_id in config.yaml. Confirm you sent at least one message to the bot from your account before running.

Slow run near vision/backfill stage Lower these config values to reduce API workload:

• max_candidates
• preselection_backfill_limit
• preselection_backfill_time_budget_seconds

Whisper model download or load feels stuck

• First run can take time while downloading model weights.
• Keep whisper_model: "base" for balanced speed/quality.
• For low-RAM machines, use tiny or base.

---

StreamClipper is a product-style starter — clone, key, run. Not a black box, a fast first cut.