feat(workflow): Video Sourcing + Retouch — download viral clips, extract key frames, retouch, review via Telegram, then upload

[petermuidev]

Feature Description

New production workflow that downloads viral short-form videos, identifies key frames, retouches/re-edits them, and uploads fresh content — with a Telegram review gate before any upload goes to main.

Motivation

The current MoneyPrinterV2 workflows all generate content from scratch (script → TTS → images → video). But the fastest path to fresh, engaging content is often:

1. Find a viral video that's already proven (via SourceDiscovery pipeline)
2. Extract the best moments/frames
3. Retouch — add new text overlays, different music, re-caption, re-format
4. Review — send draft to Telegram for human approval
5. Upload — only after approval

This is especially powerful for:

• TikTok sliders — extract key frames from a viral video and rebuild as an image slider with fresh text
• YouTube Shorts — download a clip, add new voiceover/TTS, re-caption
• Content repurposing — same viral concept across different formats/platforms

Proposed Solution

New class: src/classes/VideoSourcing.py

VideoSourcing(fp_profile_path)
  ├── download_video(source_url) → local MP4 path
  ├── extract_key_frames(video_path, count=6) → List[FrameInfo]
  ├── analyze_frames(frames) → AI analysis of best moments
  ├── retouch_video(video_path, instructions) → retouched MP4 path
  ├── generate_slider_from_frames(frames, concept) → slider pack
  └── run(source_item) → DraftContent

DraftContent schema

{
  "source_item_id": "src-tiktok-abc123",
  "original_url": "https://...",
  "original_platform": "tiktok",
  "draft_type": "video_retouch|slider_from_frames|clip_with_new_voiceover",
  "draft_path": "/path/to/output.mp4 or /path/to/slider_pack/",
  "key_frames": [{ "timestamp": 3.2, "image_path": "...", "score": 0.9 }],
  "script": "AI-generated script based on key frame analysis",
  "title": "...",
  "caption": "...",
  "telegram_review_sent": true,
  "approved": false
}

New script: scripts/run_video_sourcing.py

CLI entry point:

• --source-id — pick a SourceItem from .mp/sources/ JSON
• --source-url — directly provide a video URL to download
• --draft-type — video_retouch, slider_from_frames, clip_with_new_voiceover
• --concept-id — optional concept template to overlay on the retouched content
• --send-telegram — send draft to Telegram for review (ALWAYS ON by default)
• --upload-on-approve — auto-upload after Telegram approval
• --list-sources — list available SourceItems from recent discovery runs

Pipeline flow

SourceDiscovery → .mp/sources/sources_YYYY-MM-DD.json
                         ↓
VideoSourcing picks a source item
                         ↓
1. yt-dlp downloads video to .mp/temp/
2. ffmpeg extracts key frames at sampled timestamps
3. Vision model (via OmniRoute) analyzes each frame → scores + descriptions
4. LLM generates retouch instructions based on frame analysis + content_lane
5. ffmpeg/moviepy applies retouch (text overlay, music swap, re-caption, etc.)
6. Draft MP4 or slider pack saved to .mp/output/
7. Telegram bot sends draft + preview for human review
8. Only after human "approve" → upload to YouTube/TikTok

Telegram review gate (CRITICAL)

Before PR to main or any upload, the draft MUST be sent to Telegram for review. This matches the existing pattern in run_poc_video.py and run_tiktok_slider.py (both have --send-telegram flags).

The review message should include:

• Thumbnail preview (first key frame)
• Original source URL and platform
• Draft type (retouch / slider / voiceover)
• AI-generated title + caption
• Draft video or slider pack as attachment
• Approve/Reject buttons (Telegram inline keyboard)

Storage: .mp/sources/ and .mp/drafts/

• .mp/sources/ — SourceItem JSONs from discovery runs
• .mp/drafts/ — DraftContent JSONs + output files awaiting review
• .mp/uploaded/ — approved and uploaded content logs

Key dependencies

• yt-dlp — download videos from TikTok, YouTube, Instagram, etc.
• ffmpeg — frame extraction, video retouching, overlay composition
• moviepy — higher-level video editing (text overlays, music swap)
• Vision model via OmniRoute — analyze extracted frames
• Telegram Bot API — review gate with inline keyboard for approve/reject
• SourceDiscovery pipeline (companion issue) — feeds source items

Alternatives Considered

• Manual download + manual edit → rejected (whole point is automation)
• Full AI video generation from scratch → already exists in YouTube class; this is the complementary "sourced" approach
• Download-only (no retouch) → rejected; plain re-upload risks copyright issues; retouch makes it original

Risks & Mitigations

• Copyright — retouching changes enough to make content original; Telegram review gate catches anything questionable
• Platform scraping instability — yt-dlp is community-maintained and frequently updated; fallback to manual URL input
• Quality control — vision model frame analysis + Telegram human review = double gate