# How video-use Handles Portrait Source Detection and Scaling: A Technical Deep Dive

> Explore how video-use detects and scales portrait videos using ffprobe and ffmpeg. Learn about the technical pipeline for optimized video rendering.

- Repository: [Browser Use/video-use](https://github.com/browser-use/video-use)
- Tags: deep-dive
- Published: 2026-07-09

---

**video-use detects portrait videos by checking if height exceeds width using ffprobe, then applies height-based scaling filters (`scale=-2:1280` or `scale=-2:1920`) for vertical videos and width-based scaling for landscape videos during the ffmpeg rendering pipeline.**

The **video-use** repository provides automated video processing utilities that handle orientation-aware transcoding. Understanding how the library manages **portrait source detection and scaling** is crucial for developers working with mixed-orientation video content. The implementation relies on ffprobe for dimension analysis and dynamically constructs ffmpeg filter chains based on orientation flags.

## Detecting Portrait Orientation with ffprobe

The orientation detection logic centers on dimension comparison using ffprobe metadata.

### The is_portrait_source() Function

In [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py), the **`is_portrait_source()`** function (lines 34-46) executes ffprobe to retrieve video dimensions and returns `True` when the video's height exceeds its width:

```python

# Conceptual implementation based on helpers/render.py#L34-L46

def is_portrait_source(video_path):
    # Uses ffprobe to get width and height

    height > width  # Returns True for portrait orientation

```

This boolean flag drives all subsequent scaling decisions in the rendering pipeline.

## Scaling Logic for Portrait vs Landscape Videos

Once orientation is determined, the **`extract_segment()`** function (lines 73-78 in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py)) selects appropriate scaling filters based on the portrait flag and rendering mode.

### Draft Preview Scaling (1280px)

For **draft previews**, video-use applies dimension-specific scaling to balance quality and processing speed:

- **Portrait videos**: Use `scale=-2:1280` (height 1280px, width auto-calculated)
- **Landscape videos**: Use `scale=1280:-2` (width 1280px, height auto-calculated)

The `-2` value ensures ffmpeg calculates the missing dimension while maintaining the original aspect ratio and keeping the value divisible by 2 for codec compatibility.

### Final Render Scaling (1920px)

For **final renders** and high-quality outputs, the pipeline switches to 1920px maximum dimensions:

- **Portrait videos**: Use `scale=-2:1920` (height 1920px)
- **Landscape videos**: Use `scale=1920:-2` (width 1920px)

This approach ensures that vertical videos maintain their portrait orientation while fitting within standard 1080p workflows.

## Implementation in the Rendering Pipeline

The scaling logic integrates directly into ffmpeg's video filter chain. After `extract_segment()` determines the appropriate `scale` string, it concatenates this value with other filters (such as HDR tonemapping or color grading) to form the final `-vf` argument.

The complete pipeline follows this sequence:

1. **Detection**: `is_portrait_source()` queries ffprobe for dimensions
2. **Decision**: `extract_segment()` selects height-based or width-based scaling
3. **Execution**: The scale filter joins the ffmpeg command's video filter chain

## Code Examples and Usage

### Basic Rendering Commands

The script automatically detects portrait sources without manual intervention:

```bash

# Standard render – automatically detects and scales portrait sources

python helpers/render.py edl.json -o final.mp4

# Draft preview – applies 1280px scaling limits

python helpers/render.py edl.json -o preview.mp4 --draft

```

### Debug Portrait Detection

Verify orientation detection for specific files:

```bash
python -c "
from pathlib import Path
from helpers.render import is_portrait_source
print(is_portrait_source(Path('path/to/video.mp4')))
"

```

### Generated ffmpeg Commands

When video-use processes a **portrait source**, the generated ffmpeg command includes height-based scaling:

```bash

# Portrait video output

ffmpeg -i input.mp4 -vf "scale=-2:1920,format=yuv420p" output.mp4

```

For **landscape sources**, the command switches to width-based scaling:

```bash

# Landscape video output

ffmpeg -i input.mp4 -vf "scale=1920:-2,format=yuv420p" output.mp4

```

## Summary

- **video-use** determines orientation by comparing height and width using ffprobe in `is_portrait_source()` (lines 34-46 of [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py)).
- **Portrait videos** (height > width) receive height-based scaling filters (`scale=-2:1280` for drafts, `scale=-2:1920` for final renders).
- **Landscape videos** receive width-based scaling filters (`scale=1280:-2` or `scale=1920:-2`).
- The **`extract_segment()`** function (lines 73-78) applies these filters dynamically based on the draft flag and orientation.
- The chosen scale parameter integrates into ffmpeg's `-vf` video filter chain alongside other processing filters.

## Frequently Asked Questions

### How does video-use determine if a video is portrait or landscape?

The **`is_portrait_source()`** function in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) executes ffprobe to retrieve the video's width and height metadata. It returns `True` when the height value exceeds the width, indicating a portrait (vertical) orientation rather than landscape.

### What is the difference between draft and final render scaling?

Draft previews use **1280px** as the maximum dimension (`scale=-2:1280` for portrait, `scale=1280:-2` for landscape), while final renders use **1920px** (`scale=-2:1920` or `scale=1920:-2`). This allows draft processing to complete faster with lower resolution outputs while maintaining the correct aspect ratio.

### Why does the scaling filter use -2 instead of -1?

The `-2` value in ffmpeg's scale filter ensures that the automatically calculated dimension is divisible by 2, which is required for most video codecs (including H.264). Using `-1` could result in odd-numbered dimensions that cause encoding errors or compatibility issues.

### Can I override the automatic portrait detection?

The current implementation in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) automatically detects orientation using `is_portrait_source()` within the `extract_segment()` function. To force a specific orientation, you would need to modify the source code to bypass the ffprobe check or manually set the `portrait` flag before the scaling logic executes at lines 73-78.