Subtitle Safe Zones for Mobile Video Platforms: How video-use Calculates Margins

Mobile video platforms reserve a bottom safe zone for subtitles calculated as a percentage of frame height, typically 5–8%, ensuring text avoids collision with UI elements like progress bars and controls.

The browser-use/video-use repository implements a robust system for handling subtitle safe zones for mobile video platforms such as TikTok, Instagram Reels, and YouTube Shorts. These platforms require specific margin calculations to prevent subtitles from overlapping with native interface elements. The library derives these margins from a normalized visible frame model, applying a configurable ratio to ensure consistent positioning across any resolution.

Understanding Mobile Video Safe Zones

Mobile-first platforms reserve specific areas of the screen for native interface elements. According to the source code documentation in skills/manim-video/references/production-quality.md, the library assumes a visible frame of approximately 14.2 units wide by 8.0 units tall for standard 16:9 content. This model represents the effective canvas area where subtitles can safely appear without risk of being obscured by platform overlays.

The Bottom Safe Zone Requirement

The critical area for subtitle placement is the bottom margin, which creates a safe zone above progress bars, caption toggles, and navigation buttons. Unlike fixed pixel measurements, the library calculates this margin as a fraction of the total frame height, ensuring proportional spacing across 720p, 1080p, and 4K resolutions.

How Margin Calculation Works in video-use

The margin calculation follows a specific formula implemented in the rendering pipeline:

margin_bottom = FRAME_HEIGHT × MARGIN_RATIO

Where FRAME_HEIGHT uses the normalized height of 8.0 units (from the 14.2 × 8.0 visible frame), and MARGIN_RATIO is a configurable constant.

Default Margin Ratios

As implemented in helpers/render.py, the default MARGIN_RATIO ranges from 0.05 to 0.08 (5% to 8% of the frame height). This yields a bottom safe zone of approximately 0.4 to 0.64 units, which translates to roughly 40 to 64 pixels at 1080p resolution. This range accommodates the safe zone requirements of major mobile platforms while maintaining readability.

Automatic Resolution Scaling

Because the calculation uses a ratio rather than absolute pixels, the safe zone automatically scales with video resolution. The same MARGIN_RATIO applies equally to left and right margins, ensuring subtitles remain fully visible within the safe rectangle even when content is letterboxed or pillarboxed on different devices.

Implementation in the Codebase

The actual margin application occurs in helpers/render.py, where the library constructs FFmpeg subtitle filters using the calculated margin value.

# helpers/render.py – building the subtitle filter

SUB_FORCE_STYLE = "Fontname=Menlo,Fontsize=36,PrimaryColour=&HFFFFFF&,MarginV={margin_bottom}"
...
if has_subs:
    # `margin_bottom` is derived from the visible frame height

    subs_abs = str(subtitles_path.resolve()).replace(":", r"\:").replace("'", r"\'")
    cmd = (
        f"{current}subtitles='{subs_abs}':force_style='"
        f"{SUB_FORCE_STYLE.format(margin_bottom=int(FRAME_HEIGHT * MARGIN_RATIO))}'[outv]"
    )

In this implementation, MarginV (the vertical margin parameter in FFmpeg's force_style option) receives the calculated pixel value, positioning subtitles exactly within the safe zone. The SKILL.md file (around line 180) further documents these subtitle dimensions, emphasizing the importance of placement (margin from bottom) for production-quality output.

Customizing Margins for Different Platforms

While the default ratios work for most platforms, specific applications may require tighter or looser margins. For example, TikTok's interface might allow for a smaller safe zone than YouTube Shorts.

To customize the margin, modify the MARGIN_RATIO constant before rendering:

# Example: tighter margin for TikTok (3% of height)

MARGIN_RATIO = 0.03

When the render step executes, FFmpeg applies this custom MarginV value, ensuring subtitles sit precisely where the target platform's UI elements end.

Summary

• Subtitle safe zones for mobile video platforms prevent text collision with native UI elements like progress bars and controls.
• The video-use library calculates margins using FRAME_HEIGHT × MARGIN_RATIO, defaulting to 5–8% of the visible frame height.
• Default settings create a bottom safe zone of approximately 40–64 pixels at 1080p, scaling automatically to any resolution.
• Implementation occurs in helpers/render.py via FFmpeg's force_style parameter, specifically the MarginV setting.
• Developers can customize safe zones per platform by adjusting the MARGIN_RATIO constant.

Frequently Asked Questions

What is the standard subtitle safe zone size for mobile video?

The standard safe zone for mobile subtitles typically ranges from 5% to 8% of the total frame height. In the video-use repository, this translates to approximately 0.4 to 0.64 units on the normalized 8.0-unit tall frame, or roughly 40 to 64 pixels at 1080p resolution. This ensures subtitles remain visible above platform UI elements like progress bars and navigation controls.

How does video-use calculate subtitle margins for different resolutions?

The library calculates margins as a ratio of the visible frame height rather than using fixed pixel values. The formula margin_bottom = FRAME_HEIGHT × MARGIN_RATIO ensures that whether the output is 720p, 1080p, or 4K, the subtitle safe zone scales proportionally. This approach maintains consistent positioning across different aspect ratios and device sizes.

Can I customize the safe zone margins for specific platforms like TikTok or Instagram?

Yes, you can customize margins by adjusting the MARGIN_RATIO constant before rendering. For platforms requiring tighter spacing, such as TikTok, you might set MARGIN_RATIO = 0.03 (3% of frame height). The helpers/render.py file applies this value to FFmpeg's MarginV parameter, allowing platform-specific subtitle placement without modifying the core rendering logic.

Where are subtitle safe zones documented in the video-use repository?

The safe zone concept is documented in skills/manim-video/references/production-quality.md (lines 64–66), which defines the visible frame dimensions of 14.2 × 8.0 units. Additional implementation details appear in SKILL.md around line 180, focusing on subtitle placement and margins, while the actual calculation logic resides in helpers/render.py.

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