# How video-use Differentiates and Processes Portrait versus Landscape Source Videos

> video-use expertly handles portrait vs landscape video processing. Discover how we auto-detect orientation with ffprobe and apply FFmpeg filters to preserve aspect ratios for optimal rendering.

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

---

**video-use automatically detects video orientation using ffprobe and applies conditional FFmpeg scale filters to preserve aspect ratios, ensuring portrait videos maintain vertical dimensions while landscape videos maintain horizontal dimensions during rendering.**

The open-source `video-use` repository handles mixed-orientation footage by inspecting each source video's dimensions before processing. This differentiation ensures that vertical content intended for TikTok, Instagram Reels, or YouTube Shorts retains its native aspect ratio, while horizontal footage maintains its intended layout. The orientation logic is implemented in the Python-based rendering pipeline, specifically within the segment extraction phase.

## Orientation Detection with ffprobe

The `video-use` tool determines video orientation through the `is_portrait_source()` helper function located in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py). This function executes `ffprobe` to analyze the source file's metadata and returns `True` when the video height exceeds its width.

According to the source code at lines 134-136, the detection logic compares the height and width dimensions obtained from the video probe. This boolean flag is then passed through the rendering pipeline to determine which scaling parameters to apply.

```python
from pathlib import Path
from helpers.render import is_portrait_source

video = Path("example_portrait.mp4")
print(is_portrait_source(video))   # → True when height > width

```

## Conditional Scaling Logic in extract_segment()

Within the `extract_segment()` function in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py), the orientation flag determines which **scale** filter FFmpeg receives. The `-2` placeholder in these filter values instructs FFmpeg to automatically calculate the corresponding dimension while preserving the original aspect ratio, preventing distortion or unwanted cropping.

### Draft Build Scaling (1280px Resolution)

For fast, low-resolution preview renders (draft builds), the scaling logic fixes the dominant dimension to 1280 pixels:

- **Portrait sources** receive `scale=-2:1280` (fixed height of 1280px, width calculated automatically)
- **Landscape sources** receive `scale=1280:-2` (fixed width of 1280px, height calculated automatically)

This logic is implemented at lines 173-176 in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py).

### Final and Preview Build Scaling (1080p Resolution)

For final output or draft-preview builds targeting 1080p resolution, the scaling adjusts to 1920 pixels on the dominant axis:

- **Portrait sources** receive `scale=-2:1920` (fixed height of 1920px)
- **Landscape sources** receive `scale=1920:-2` (fixed width of 1920px)

These parameters are defined at lines 177-178 in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py).

## Rendering Pipeline Integration

The orientation check is performed **once per source** during the initial processing phase. The resulting `scale` filter is then concatenated with optional **HDR tone-mapping** and **grading** filters to construct the final video filter graph (`vf`). 

This approach ensures that every extracted segment inherits the correct orientation-aware scaling without requiring manual intervention. The pipeline automatically handles mixed-orientation edit decision lists (EDLs), applying the appropriate scaling parameters to each segment based on its detected source orientation.

## Practical Implementation Examples

### Detect Orientation Programmatically

Use the `is_portrait_source` function to check orientation before processing:

```python
from pathlib import Path
from helpers.render import is_portrait_source

video = Path("vertical_clip.mp4")
if is_portrait_source(video):
    print("Processing as portrait orientation")
else:
    print("Processing as landscape orientation")

```

### Render Mixed-Orientation EDLs

Process an edit decision list containing both portrait and landscape sources using the automatic detection:

```bash

# Final quality render (1080p)

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

# Fast draft render (1280px)

python helpers/render.py my_edl.json -o draft.mp4 --draft

```

### Pipeline Integration with Grading

The scaling filters work in conjunction with grading presets defined in [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py). The orientation-aware scaling is applied before the grading filters in the FFmpeg filter chain, ensuring that color correction and tone mapping operate on correctly dimensioned frames.

## Summary

- **Orientation Detection**: The `is_portrait_source()` function in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) (lines 134-136) uses `ffprobe` to identify when height exceeds width.
- **Adaptive Scaling**: The `extract_segment()` function applies different FFmpeg scale filters based on orientation, using `-2` to preserve aspect ratios automatically.
- **Resolution Tiers**: Draft builds use 1280px scaling (lines 173-176), while final builds use 1920px scaling (lines 177-178).
- **Pipeline Efficiency**: Orientation is checked once per source and integrated into the filter graph alongside HDR and grading filters.
- **Platform Compatibility**: This differentiation ensures portrait videos render correctly for vertical platforms while maintaining landscape integrity for horizontal formats.

## Frequently Asked Questions

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

The repository uses the `is_portrait_source()` helper function in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) to execute `ffprobe` on the video file. It returns `True` when the video's height is greater than its width, indicating portrait orientation. This boolean flag is then passed to the scaling logic to determine appropriate FFmpeg parameters.

### What FFmpeg scale filter does video-use apply to portrait videos?

For portrait videos, `video-use` applies `scale=-2:1280` for draft builds or `scale=-2:1920` for final builds. The `-2` value tells FFmpeg to automatically calculate the width while preserving the aspect ratio, while the fixed height value (1280 or 1920) ensures the vertical dimension dominates the output.

### Why does video-use use -2 in the FFmpeg scale parameters?

The `-2` placeholder in FFmpeg's scale filter instructs the encoder to calculate the corresponding dimension automatically while preserving the original aspect ratio. For example, `scale=-2:1280` fixes the height to 1280 pixels and calculates the width proportionally. This prevents distortion that would occur from fixed-width scaling on portrait content.

### Does video-use require manual rotation for portrait sources?

No, manual rotation is not required. The `video-use` pipeline automatically handles orientation through the `is_portrait_source()` detection and applies the appropriate scaling filters during the `extract_segment()` phase. This ensures portrait videos are processed with vertical dimensions intact without additional preprocessing steps.