How video-use Detects and Handles Vertical Video (9:16) Portrait Sources

video-use detects portrait orientation by checking if a video's height exceeds its width using ffprobe in is_portrait_source(), then applies height-based scaling filters during segment extraction to preserve the 9:16 aspect ratio.

The browser-use/video-use repository automates video rendering for social media platforms like TikTok and Instagram Reels. When processing mixed-aspect-ratio footage, the system must accurately identify vertical video sources to apply appropriate scaling filters. Understanding how video-use detects portrait orientation and renders 9:16 content ensures your clips appear correctly without distortion or cropping.

Portrait Detection via ffprobe in helpers/render.py

The detection logic resides in the is_portrait_source() function within helpers/render.py (lines 34-46). This helper executes ffprobe on the first video stream to extract the width and height values from the metadata. It returns True when the height is greater than the width, identifying the source as portrait orientation.

The is_portrait_source() Implementation

When is_portrait_source() analyzes a video file, it parses the stream metadata to compare dimensions. If height > width, the function signals that the content requires vertical scaling treatment rather than standard landscape scaling. This boolean result drives downstream decisions in the rendering pipeline.

Dynamic Scaling for 9:16 and 16:9 Sources

During segment extraction, the extract_segment() function in helpers/render.py (lines 73-78) uses the portrait detection result to select the appropriate FFmpeg scaling filter. This ensures vertical video maintains its aspect ratio while landscape content fills the frame appropriately.

Height-Based Scaling for Portrait Video

For vertical video sources, the system applies height-based scaling to maintain the 9:16 aspect ratio:

• Final/Preview output: scale=-2:1920 (producing 1080×1920)
• Draft output: scale=-2:1280

The -2 value lets FFmpeg calculate the width automatically while preserving the aspect ratio, ensuring the video fits the vertical canvas without distortion.

Width-Based Scaling for Landscape Video

Conversely, landscape sources use width-based scaling:

• Final/Preview: scale=1920:-2
• Draft: scale=1280:-2

This conditional logic ensures that both vertical video and traditional landscape footage render correctly within the same editing sequence.

Subtitle Optimization for Vertical Canvas

The repository includes a SUB_FORCE_STYLE constant defined in helpers/render.py (lines 41-56). This style is tuned specifically for a 1080×1920 vertical canvas, positioning subtitles safely away from platform UI elements like TikTok's navigation buttons and Instagram Reels controls. When combined with portrait-aware scaling, captions remain legible and unobstructed on vertical video outputs.

Practical Implementation Examples

Detecting portrait orientation in Python:

from pathlib import Path
from helpers.render import is_portrait_source

video_path = Path("my_vertical_clip.mp4")
if is_portrait_source(video_path):
    print("Portrait video detected")
else:
    print("Landscape video")

Implementing custom segment extraction with orientation awareness:

from pathlib import Path
from helpers.render import extract_segment, is_portrait_source

source = Path("vertical.mp4")
portrait = is_portrait_source(source)
scale_filter = "scale=-2:1920" if portrait else "scale=1920:-2"
print(f"Using scale: {scale_filter}")

# Extract a 5-second clip preserving portrait orientation

extract_segment(
    source=source,
    seg_start=10.0,
    duration=5.0,
    grade_filter="",
    out_path=Path("clip.mp4"),
    preview=False,
    draft=False,
)

Command-line rendering handles orientation automatically:

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

Summary

• Portrait detection occurs in is_portrait_source() using ffprobe to check if height exceeds width
• Height-based scaling (scale=-2:1920) preserves 9:16 aspect ratios for vertical video sources
• Width-based scaling (scale=1920:-2) handles traditional landscape content
• Vertical-optimized subtitles via SUB_FORCE_STYLE ensure text appears safely on 1080×1920 canvases
• All orientation logic resides in helpers/render.py, making the pipeline modular and reusable

Frequently Asked Questions

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

The system calls is_portrait_source() in helpers/render.py, which runs ffprobe on the first video stream and compares the width and height values. If the height is greater than the width, the video is classified as portrait (9:16).

What scaling filter does video-use apply to vertical video?

For portrait sources, video-use applies scale=-2:1920 for final renders and scale=-2:1280 for draft quality. The -2 parameter allows FFmpeg to calculate the proportional width automatically while fixing the height to maintain the vertical orientation.

Can video-use handle mixed-orientation sources in the same project?

Yes. The extract_segment() function checks orientation for each source individually during the render pipeline, applying height-based scaling for vertical clips and width-based scaling for landscape clips within the same editing sequence.

Where is the subtitle positioning configured for vertical video?

The subtitle style is defined in the SUB_FORCE_STYLE constant in helpers/render.py (lines 41-56). This configuration is optimized for 1080×1920 vertical canvases to ensure captions appear safely away from platform UI elements on TikTok, Instagram Reels, and YouTube Shorts.

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