R55 — Clipper Agent

Turn YouTube videos into Shorts automatically from your phone

Category: Content Repurposing Runtime: Claude Code AIOS Rating: 7/10

---

What It Does

Two-workflow Telegram bot that turns long-form YouTube videos into optimized short-form clips. Send a YouTube URL from your phone, Vizard AI detects the best moments and generates clips with subtitles and viral scores. Review in Airtable, approve the best ones, then auto-schedule as YouTube Shorts via Blotato.

The entire system runs serverless on Modal — no server to maintain.

Architecture

WORKFLOW 1: GENERATE CLIPS
User sends YouTube URL  →  Vizard AI clips it  →  Airtable review queue
   via Telegram bot          (5-15 min)            + Telegram notification

WORKFLOW 2: SCHEDULE CLIPS
User sends "done reviewing"  →  Approved clips  →  Blotato auto-schedule
   via Telegram bot              from Airtable      → Status = "Ready"

Tech Stack

Platform	Role	Cost
Vizard.ai	Core AI — analyzes video, generates clips with viral scores	Paid (API plan)
Telegram	User interface — send URLs, receive updates from phone	Free
Airtable	Review queue — clips with video, title, viral score	Free tier
Modal	Serverless hosting — webhook endpoints, background processing	Free tier
Blotato	Distribution — schedules approved clips as YouTube Shorts	Paid

Workflows

1. Generate Clips

1. Send YouTube URL to Telegram bot (optionally prefix with clip count: 5 <url>)
2. Vizard API receives URL, processes with language + template settings
3. Bot polls Vizard every 60 seconds for up to 30 minutes
4. Clips saved to Airtable with video, title, transcript, viral score, viral reason
5. Telegram notification with clip count + Airtable link

2. Schedule Approved Clips

1. Review clips in Airtable Gallery view, mark best as "Approved"
2. Send "done reviewing" to Telegram bot
3. Approved clips scheduled as YouTube Shorts via Blotato (next free slot)
4. Airtable status updated to "Ready"
5. Telegram summary: X/Y clips scheduled

Project Structure

R55_clipper_agent/
├── AGENT.md                        (8-step guided setup)
├── .env.example                    (10 environment variables)
├── tools/
│   └── vizard_clipper.py           (603 lines — THE system)
└── docs/
    ├── telegram-bot-setup.md
    ├── vizard-setup.md
    ├── airtable-setup.md
    ├── blotato-setup.md
    └── modal-setup.md

Environment Variables

Required:

Variable	Source	Purpose
VIZARD_API_KEY	Vizard dashboard	Video clipping API
TELEGRAM_BOT_TOKEN	@BotFather on Telegram	Bot authentication
AIRTABLE_PAT	airtable.com/create/tokens	Read/write clips
AIRTABLE_BASE_ID	Airtable URL	Target base
AIRTABLE_TABLE_NAME	User-defined	Target table (default: shortsRobo)
BLOTATO_API_KEY	Blotato → Settings → API	Schedule posts
BLOTATO_YOUTUBE_ACCOUNT_ID	Blotato account settings	Target YouTube channel

Optional:

Variable	Purpose
TELEGRAM_CHAT_ID	Security — restrict bot to your account only
VIZARD_TEMPLATE_ID	Custom subtitle styling
VIZARD_LANG	Subtitle language (default: en)

Airtable Schema — shortsRobo

Field	Type	Source	Purpose
Video	Attachment	Vizard AI	The clipped video file
Title	Single line text	Vizard AI	AI-generated clip title
Caption	Long text	Vizard AI	Transcript / caption
Viral Score	Number	Vizard AI	Virality score 0-100
Viral Reason	Long text	Vizard AI	Why it'll go viral
Source URL	URL	Pipeline	Original YouTube link
Status	Single select	User/Bot	Approved / Rejected / Ready

Security

• API keys stored in Modal Secrets (encrypted, not in code)
• Bot access restricted via TELEGRAM_CHAT_ID — unauthorized messages silently ignored
• Without TELEGRAM_CHAT_ID, anyone can trigger processing and burn Vizard credits

Common Pitfalls

Problem	Cause	Fix
Secret not found on deploy	Secret name mismatch	Must be exactly vizard-clipper-secrets
Columns empty in Airtable	Case-sensitive names	"Viral Score" not "viral score"
Bot responds to strangers	TELEGRAM_CHAT_ID not set	Add it to Modal secret
No approved clips found	Status casing	Must be exactly "Approved" (capital A)
Scheduling fails	No schedule slots	Set up slots in Blotato dashboard

---

Built by Copyweb — architecting how marketing teams operate in an AI-first world.