VerticalX is an intelligent, open-source video reframing platform designed to eliminate the manual labor of pan-and-scan editing. Whether you are producing TikToks, YouTube Shorts, or Instagram Reels, VerticalX converts horizontal videos — including podcast episodes, webinars, interview shows, gaming streams, and vlogs — into high-engaging vertical content.
Powered by computer vision focal tracking, hardware-accelerated FFmpeg streams, PySceneDetect camera split analysis, and OpenAI Whisper speech-to-text, VerticalX delivers studio-quality vertical outputs directly from your browser or terminal.
Automatically keeps key subjects centered in the 9:16 frame. Choose tracking algorithms optimized for:
- Humans: Haar-Cascade face detection & MobileNet-SSD person tracking (dominant speaker focus).
- Animals: MobileNet-SSD detection for pets and wildlife.
- Vehicles: Vehicle bounding box tracking.
- Action Motion: Dense Optical Flow magnitude tracking (tracks high-motion vectors).
- Saliency Details: Sobel edge gradient spatial analysis.
- Smart Focus: AI tracks the active speaker or subject dynamically across the frame.
- Blurred Background: Fits the full widescreen video centered over a rich, Gaussian-blurred background.
- Center Crop: Classic centered 9:16 vertical crop.
- Fit Frame: Letterboxed presentation centered on a clean black canvas.
- Dual Stack (Split Screen): Vertically stacks top and bottom views for multi-speaker podcasts or dual-camera cuts.
Convert entire horizontal videos into vertical 9:16 portrait videos without cutting them into clips. Perfect for full podcast episodes, webinars, and long-form content.
Slice long-form videos into multiple vertical short clips designed for social platforms. Set custom timestamps or let AI automatically detect camera scene transitions for you.
Integrates OpenAI Whisper speech-to-text engine to automatically generate frame-accurate WebVTT subtitle overlays to maximize viewer retention.
- Hardware Acceleration: Auto-probes Apple Silicon VideoToolbox (
h264_videotoolbox) and NVIDIA GPU (h264_nvenc) for up to 10x faster renders. - Clean Single-File Output: Saves exclusively the final MP4 video file under namespaced project directories with zero clutter.
VerticalX includes a sleek, local Web Studio interface running in your browser:
- Drag-and-Drop Video Upload: Instant playback and source video preview.
- Dual Reframing Mode Tabs: Seamlessly toggle between FULL VIDEO and TIMELINE CUTS reframing workflows.
- Interactive Controls: Select layout styles, focus target categories, and zoom percentages interactively.
- One-Click MP4 Downloads: Preview rendered vertical videos in the gallery and download exports instantly.
| Layer | Technologies & Libraries |
|---|---|
| Frontend UI | HTML5, Vanilla JavaScript, CSS3 (Dark Obsidian Design System) |
| Backend Web Server | Python 3, Flask, Werkzeug WSGI |
| Computer Vision & Tracking | OpenCV (cv2), Haar Cascades, MobileNet-SSD, Dense Optical Flow |
| Scene Detection | PySceneDetect (Content Detector) |
| Speech-to-Text Subtitles | openai-whisper, PyTorch |
| Video Processing Engine | Native FFmpeg, Apple h264_videotoolbox, NVIDIA h264_nvenc, libx264 |
VerticalX compiles reframing workflows natively to system binaries for maximum performance. Ensure FFmpeg is installed:
brew install ffmpegsudo apt update && sudo apt install ffmpegchoco install ffmpeg-
Clone the Repository:
git clone https://github.com/vinaykolupula/VerticalX.git cd VerticalX -
Install Python Dependencies:
pip install -r requirements.txt
-
(Optional) Enable AI Speech-to-Text Subtitles:
pip install openai-whisper torch
-
Launch the Web Studio Dashboard:
python web_ui/app.py
Open http://localhost:5001 in your browser!
Batch process vertical cut jobs directly from the terminal using JSON configuration files:
python reframe.py run -i source_video.mp4 -c cuts_sample.json -o ./output [OPTIONS]| Option | Flag | Description | Default |
|---|---|---|---|
| Input File | -i, --input |
Path to the widescreen source video file. | Required |
| Config JSON | -c, --config |
Path to JSON cuts configuration file. | Required |
| Output Directory | -o, --outdir |
Directory where rendered vertical videos are saved. | ./output |
| Encoder | -e, --encoder |
Video encoder (libx264, h264_videotoolbox, h264_nvenc). |
libx264 |
| Jobs / Threads | -j, --jobs |
Maximum parallel rendering worker tasks. | 4 |
| Auto-Subtitles | --transcribe |
Enables OpenAI Whisper speech-to-text subtitle generation. | False |
Scan visual camera changes to automatically output a boilerplate JSON timeline configuration:
python reframe.py detect-scenes -i source_video.mp4 -t 30.0 -o cuts_detected.json| Layout Mode | Visual Style | Edge Cropping | Ideal Use Case |
|---|---|---|---|
smart_focus |
AI tracks target subjects dynamically. | Dynamic | Speakers, Vlogs, Action Shots |
blur_frame |
Full 16:9 video centered over blurred backdrop. | 0% (Full Video Visible) | Widescreen Gameplay, Presentations |
crop |
Centered vertical 9:16 viewport crop. | 44% (Left/Right Edges) | Centered Solo Speakers |
fit |
Full 16:9 video centered on black background. | 0% (Full Video Visible) | Documentaries, Trailers |
fit_zoom |
Full 16:9 video enlarged by custom zoom %. | Custom Zoom Margin | Cinematic Zoom Framing |
split |
Crops left & right halves into top & bottom split screen. | Dual Stack Split | Podcasts, 2-Person Interviews |
| Reframing Mode | Destination Directory | Export Filename | File Contents |
|---|---|---|---|
| FULL VIDEO | ./output/full-video/<project_name>/ |
<project_name>.mp4 |
Exclusively 1 MP4 video file |
| TIMELINE CUTS | ./output/cuts/<project_name>/cut-X/ |
<project_name>_cut-X.mp4 |
Exclusively 1 MP4 video file per cut |
For an in-depth breakdown of stream-processing graph pipelines, computer vision focal tracking math, FFmpeg filter complex equations, and concurrency locks, refer to architecture.md.
Contributions are welcome! Please feel free to submit a Pull Request or open an Issue for bug reports or feature requests.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for more details.
⭐ Star VerticalX on GitHub if you find it useful!