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

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. 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.

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, 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.

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.

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:

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:

# 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. 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 (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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}