How alexfazio/viral-clips-crew works
Project type and purpose
• Type: An open‑source command‑line video‑processing tool (not a full‑blown web or microservices system).
• Purpose: Ingest long‑form video, transcribe and analyze it with LLMs (OpenAI & Google Gemini), extract “viral” highlights, generate subtitles, and output ready‑to‑publish clips.
File structure
Top‑level entries and their roles:
• app.py (orchestrator): entry point that ties all steps together
• Modules handling each stage:
• ytdl.py: video ingestion/download
• local_transcribe.py & crew.py: transcription and AI‑driven analysis
• clipper.py: segment extraction
• subtitler.py: subtitle generation
• extracts.py: utility for collating AI outputs
• utils.py: shared helper functions
• resources/: prompts, lists, static data
• input_files/: drop‑zone for source clips
• crew_output/: stores intermediate API responses
• subtitler_output/: final output directory
• Config & metadata: pyproject.toml, .env, .github/workflows/pylint.yml
Key architecture insights from README
• Uses Python 3.7+, Poetry for dependency management
• External dependencies: CrewAI library, OpenAI API, Google Gemini API
• Linear pipeline: ingestion → transcription → analysis → clipping → subtitling
Main components & how to represent them
A. Video Ingestion
– Component: ytdl.py
– Input: raw video (from input_files/)
– Output: local video file
B. Transcription Service
– Components: local_transcribe.py (optional local engine), crew.py (CrewAI wrapper)
– External: OpenAI LLM / Google Gemini APIs
– Output: transcript (text) + timestamps
C. AI Analysis & Highlight Extraction
– Component: crew.py & extracts.py
– Processes transcript to identify “viral” moments
– Uses prompts (faster_subs_prompt.txt) and variant lists
– Output: candidate clip metadata
D. Clip Generation
– Component: clipper.py
– Input: source video + timestamps
– Output: trimmed video segments
E. Subtitle Generation
– Component: subtitler.py
– Input: clip + transcript segment
– Output: subtitle file (e.g., SRT)
F. Output Storage
– Directory: subtitler_output/
– Also log intermediate JSON in crew_output/
Relationships & data flow
1. User drops video → app.py kicks off pipeline
2. ytdl.py fetches/validates source
3. Transcript stage calls external LLM APIs → text + timestamps
4. AI analysis module processes transcript → selects high‑impact moments
5. clipper.py extracts segments based on timestamps
6. subtitler.py annotates clips with subtitles
7. Final assets pushed to subtitler_output/
Architectural patterns & design principles
• Pipeline/chain of responsibility: each module performs one step, passes results downstream
• Separation of concerns: ingestion, transcription, analysis, clipping, subtitling are decoupled
• External service abstraction: crew.py wraps API calls, isolating AI‑specific logic
• Config‑as‑code: resources and prompts live in resources/ for easy tweakability
• Utility functions in utils.py to avoid duplication