# VerticalX (VX) - Complete Technical Specification & Documentation

> VerticalX is an open-source video processing and reframing engine designed to automate the conversion of horizontal 16:9 videos into 9:16 vertical clips optimized for mobile-first platforms (TikTok, Instagram Reels, YouTube Shorts).

## Technical System Architecture

```
                       +-----------------------------------+
                       |    Input Video (16:9 Widescreen)  |
                       +-----------------------------------+
                                         |
                                         v
                       +-----------------------------------+
                       |    PySceneDetect Shot Detector    |
                       +-----------------------------------+
                                         |
                                         v
                       +-----------------------------------+
                       | OpenCV & MobileNet Face/Motion AI |
                       +-----------------------------------+
                                         |
                                         v
                       +-----------------------------------+
                       |  EMA Motion Smoothing Coordinator |
                       +-----------------------------------+
                                         |
                                         v
                       +-----------------------------------+
                       |   FFmpeg GPU Hardware Renderer    |
                       |  (VideoToolbox / NVENC / CPU)     |
                       +-----------------------------------+
                                         |
                                         v
                       +-----------------------------------+
                       |  Output 9:16 Shorts + WebVTT Subs |
                       +-----------------------------------+
```

## Core Modules & Python Architecture

1. `web_ui/app.py`: Flask application serving the web studio UI and managing background reframing tasks.
2. `video_pipeline/tracker.py`: Computes sub-pixel bounding box coordinates for active faces and motion vectors across video frames. Applies Exponential Moving Average (EMA) smoothing to eliminate camera jitter.
3. `video_pipeline/renderer.py`: Constructs hardware-accelerated FFmpeg command arguments for rendering cuts using VideoToolbox, NVENC, or CPU encoders.
4. `video_pipeline/subtitles.py`: Invokes OpenAI Whisper to transcribe audio into WebVTT captions aligned with vertical timestamps.

## Layout Modes Detail

| Layout Mode | Description | Ideal Use Case | FFmpeg Engine |
| :--- | :--- | :--- | :--- |
| `Smart Focus` | Dynamic AI face & motion tracking crop window | Vlogs, solo speakers, keynotes | Dynamic Crop Filter with EMA |
| `Dual Stack` | Vertical split-screen (Top Speaker / Bottom Guest) | 2-person podcast interviews, debates | Dual Stream Filter Complex |
| `Blurred Background` | Original 16:9 video centered over blurred backdrop | Movie trailers, gaming clips | Dual Stream Boxblur + Overlay |
| `Center Crop` | Static 1080x1920 viewport crop | Centered presentations, product demos | Static Crop Filter |
| `Fit (Black Padding)` | Scaled 16:9 frame with black letterboxing | Tutorials with wide text/code | Scale & Pad Filter |
| `Fit & Zoom In` | Scaled frame with adjustable zoom (0%–100%) | Custom framed clips | Scaled Crop & Pad Filter |

## CLI Automation Usage

Execute batch processing via the command line interface:

```bash
python main.py --input /path/to/video.mp4 --layout smart_focus --output /path/to/output_dir/
```

## Security & Privacy Guarantee
VerticalX operates 100% locally. Video streams, audio tracks, and generated transcripts are never transmitted over the internet or sent to third-party cloud services.

## License
MIT License - Open Source & Free for Commercial & Personal Use.