youtube video download and local caching
Automatically downloads full-length YouTube videos using yt-dlp or similar library, storing them locally for subsequent processing. Handles authentication, format selection, and metadata extraction in a single operation, enabling offline processing without repeated network calls. The YoutubeDownloader component manages the download lifecycle and integrates with the transcription pipeline.
Unique: Integrates YouTube download as the first step in a fully automated pipeline rather than requiring manual pre-download, eliminating friction in the shorts generation workflow. Uses yt-dlp for robust format negotiation and metadata extraction.
vs alternatives: Faster end-to-end processing than manual download + separate tool usage because download, transcription, and analysis happen in a single orchestrated pipeline without intermediate file handling.
speech-to-text transcription with timestamp alignment
Converts video audio to text using OpenAI's Whisper model, generating word-level timestamps that map each transcribed segment back to specific video frames. The transcription output includes confidence scores and speaker diarization hints, enabling precise temporal mapping for highlight detection. Handles multiple audio formats and automatically extracts audio from video containers using FFmpeg.
Unique: Integrates Whisper transcription directly into the pipeline with automatic timestamp extraction, eliminating the need for separate transcription tools. Uses FFmpeg for robust audio extraction from any video container format, handling codec variations automatically.
vs alternatives: More accurate than generic speech-to-text APIs (Whisper is trained on 680k hours of multilingual audio) and cheaper than human transcription services, while providing timestamps required for video cropping without additional processing steps.
gpt-4 powered highlight detection and segment ranking
Analyzes full video transcripts using GPT-4 to identify the most engaging, shareable segments based on content relevance, emotional impact, and audience appeal. The system sends the complete transcript to GPT-4 with a structured prompt requesting segment timestamps and engagement scores, then ranks results by predicted virality. This enables semantic understanding of content quality rather than simple keyword matching or silence detection.
Unique: Uses GPT-4's semantic understanding to identify highlights based on content meaning and engagement potential, rather than heuristics like silence detection or keyword frequency. Integrates directly with the transcription output, creating an end-to-end AI-driven curation pipeline.
vs alternatives: Produces more contextually relevant highlights than rule-based systems (silence detection, scene cuts) because it understands narrative flow and emotional beats, though at higher computational cost than heuristic approaches.
face detection and speaker tracking across video frames
Detects human faces in video frames using OpenCV with pre-trained Haar Cascade or DNN-based face detection models, then tracks face position and size across consecutive frames to maintain speaker focus during cropping. The system builds a spatial map of face locations throughout the video, enabling intelligent cropping that keeps speakers centered in the 9:16 vertical frame. Handles multiple faces and tracks the primary speaker based on face size and screen time.
Unique: Combines face detection with temporal tracking to build a continuous spatial map of speaker positions, enabling intelligent cropping that maintains focus rather than static frame selection. Uses OpenCV's optimized detection pipeline for real-time performance on CPU.
vs alternatives: More intelligent than fixed-aspect cropping because it adapts to speaker position dynamically, and faster than ML-based attention models because it uses lightweight Haar Cascade detection rather than deep learning inference on every frame.
intelligent vertical format cropping with speaker-aware framing
Crops video segments from 16:9 (or other aspect ratios) to 9:16 vertical format while keeping detected speakers centered and in-frame. The system uses the face tracking data to calculate optimal crop windows that maximize speaker visibility while minimizing empty space. Applies smooth pan/zoom transitions between crop windows to avoid jarring frame shifts, and handles edge cases where speakers move outside the vertical frame boundary.
Unique: Uses real-time face position data to dynamically adjust crop windows frame-by-frame, rather than applying static crops or simple center-frame extraction. Implements smooth interpolation between crop positions to avoid jarring transitions, creating professional-quality vertical videos.
vs alternatives: Produces better-framed vertical videos than simple center cropping because it tracks speaker position and adapts the crop window dynamically, and faster than manual editing because the entire process is automated based on face detection.
multi-segment video composition and concatenation
Combines multiple cropped video segments into a single output file, handling transitions, audio synchronization, and metadata preservation. The system uses FFmpeg's concat demuxer to join segments without re-encoding (when possible), applies fade transitions between clips, and ensures audio remains synchronized throughout. Supports adding intro/outro sequences, watermarks, and metadata tags for platform-specific optimization.
Unique: Automates the final assembly step using FFmpeg's concat demuxer for lossless joining when codecs match, avoiding re-encoding overhead. Integrates seamlessly with the cropping pipeline to produce publication-ready shorts without manual editing.
vs alternatives: Faster than traditional video editors (no UI overhead, batch-capable) and more efficient than naive re-encoding because it uses FFmpeg's concat demuxer to join segments without transcoding when possible, preserving quality and reducing processing time by 70-80%.
end-to-end pipeline orchestration with error handling
Coordinates the entire workflow from YouTube URL input to final vertical short output, managing state transitions between components, handling failures gracefully, and providing progress tracking. The main.py script implements a sequential pipeline that chains together download → transcription → highlight detection → face tracking → cropping → composition, with checkpointing to resume from failures. Includes logging, error recovery, and optional manual intervention points.
Unique: Implements a fully automated pipeline that chains AI capabilities (Whisper, GPT-4, face detection) with video processing (FFmpeg, OpenCV) in a single coordinated workflow, eliminating manual steps between tools. Includes checkpointing to resume from failures without reprocessing completed steps.
vs alternatives: More efficient than manual tool chaining because intermediate outputs are automatically passed between steps without file I/O overhead, and more reliable than shell scripts because it includes proper error handling and state management.
configurable processing parameters and output optimization
Exposes tunable parameters for each pipeline stage (highlight detection sensitivity, face detection confidence threshold, crop margin, transition duration, output resolution), enabling users to optimize for their specific content type and platform requirements. Configuration is managed through a JSON/YAML file or command-line arguments, with sensible defaults for common use cases (YouTube Shorts, TikTok, Instagram Reels). Supports platform-specific output presets that automatically adjust resolution, bitrate, and aspect ratio.
Unique: Provides platform-specific output presets (YouTube Shorts, TikTok, Instagram) that automatically configure resolution, bitrate, and aspect ratio, rather than requiring manual FFmpeg command construction. Supports both file-based and CLI parameter input for flexibility.
vs alternatives: More flexible than fixed-pipeline tools because users can tune behavior for their content, and more user-friendly than raw FFmpeg because presets eliminate the need to understand codec/bitrate tradeoffs.
+1 more capabilities