How to Configure Subtitle force_style for TikTok, Instagram, and YouTube to Avoid UI Occlusion

Configure dynamic subtitle margins in video-use by replacing the static SUB_FORCE_STYLE constant with a platform-aware function that sets MarginV=90 for vertical videos (TikTok, Instagram Reels, YouTube Shorts) and MarginV=20 for horizontal content (YouTube Desktop).

The browser-use/video-use repository automates video editing with FFmpeg, including hard-burning subtitles via the subtitles filter. By default, all subtitles use a fixed force_style string that positions text at the bottom of the frame. However, vertical video platforms overlay UI elements—captions, usernames, music badges, and action buttons—that occupy the bottom 25-30% of the screen, risking text occlusion. Implementing platform-specific margin configurations ensures your subtitles remain readable across all distribution channels.

Understanding the Subtitle Rendering Pipeline

In video-use, subtitle burning occurs in helpers/render.py using FFmpeg's subtitles filter applied as the final processing step. This ensures text renders on top of all video overlays and effects.

The default style is defined as a constant at line 41:

# helpers/render.py

SUB_FORCE_STYLE = (
    "FontName=Helvetica,FontSize=18,Bold=1,"
    "PrimaryColour=&H00FFFFFF,OutlineColour=&H00000000,BackColour=&H00000000,"
    "BorderStyle=1,Outline=2,Shadow=0,"
    "Alignment=2,MarginV=90"
)

The MarginV parameter controls vertical spacing from the frame edge. For libass (the subtitle renderer used by FFmpeg), the canvas scales to a reference height of 288 pixels, meaning a MarginV of 90 pixels shifts the text baseline approximately 30% up from the bottom edge.

Platform-Specific Subtitle Positioning

Different platforms require distinct safe zones to prevent UI occlusion. Vertical formats need significant bottom margins, while horizontal formats can utilize tighter spacing.

Why MarginV=90 Matters for Vertical Video

TikTok, Instagram Reels, and YouTube Shorts display persistent UI chrome at the bottom of the 1080×1920 frame. The default MarginV=90 value in helpers/render.py was deliberately chosen to clear these interface elements, moving subtitles into the visible safe zone rather than the bottom 25-30% where platform badges and action buttons reside.

Horizontal Video Configuration

For YouTube Desktop and standard landscape feeds, UI elements typically appear at the extreme edges or as overlays that don't penetrate the lower third of the frame. A reduced margin of MarginV=20 provides tighter visual hierarchy and conventional subtitle positioning without risking occlusion.

Implementing Dynamic Platform Detection

To automate platform-specific styling, implement a helper function that checks video orientation and adjusts margins accordingly. The repository already provides is_portrait_source() (lines 34-38) to detect vertical source material.

Add this function to helpers/render.py after the is_portrait_source() definition:

def subtitle_style_for_platform(portrait: bool, platform: str) -> str:
    """
    Return a libass force_style string adjusted for the target platform.
    platform: "tiktok", "instagram", "youtube_shorts", "youtube_desktop"
    """
    base = "FontName=Helvetica,FontSize=18,Bold=1,"
    base += "PrimaryColour=&H00FFFFFF,OutlineColour=&H00000000,BackColour=&H00000000,"
    base += "BorderStyle=1,Outline=2,Shadow=0,Alignment=2"

    # Vertical video platforms require larger bottom margins

    if portrait:
        if platform in {"tiktok", "instagram", "youtube_shorts"}:
            margin = 90          # Safe-zone for UI at bottom

        else:
            margin = 20          # Fallback for rare vertical desktop UI

    else:
        # Horizontal video – UI rarely hides subtitles

        margin = 20

    return f"{base},MarginV={margin}"

Next, modify the argument parser around line 630 to accept a platform flag:

# helpers/render.py – around line 630

parser.add_argument(
    "--platform",
    choices=["tiktok", "instagram", "youtube_shorts", "youtube_desktop"],
    default="youtube_desktop",
    help="Target platform for subtitle placement"
)

Finally, update the FFmpeg filter construction at line 542 to use the dynamic style:

# Before constructing the subtitles filter

platform = args.platform
force_style = subtitle_style_for_platform(is_portrait_source(source), platform)

# Updated filter string (replacing the static SUB_FORCE_STYLE reference)

f"{current}subtitles='{subs_abs}':force_style='{force_style}'[outv]"

Command-Line Usage Examples

With these modifications, you can target specific platforms via command-line arguments:

TikTok (Vertical - Safe Zone):

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

Instagram Reels (Vertical - Safe Zone):

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

YouTube Shorts (Vertical - Safe Zone):

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

YouTube Desktop (Horizontal - Tight Margin):

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

Summary

• Static defaults risk occlusion: The original SUB_FORCE_STYLE in helpers/render.py uses MarginV=90, which is optimized for vertical platforms but excessive for horizontal content.
• Platform detection is key: Use the existing is_portrait_source() function to determine video orientation before applying subtitle styles.
• Vertical videos need 90px margins: TikTok, Instagram Reels, and YouTube Shorts require MarginV=90 to clear bottom UI elements like captions, usernames, and music badges.
• Horizontal videos use 20px margins: YouTube Desktop and landscape formats only need MarginV=20 for conventional subtitle placement.
• Implementation requires three changes: Add the subtitle_style_for_platform() function, expose the --platform argument, and update the FFmpeg filter string at line 542.

Frequently Asked Questions

How does libass interpret the MarginV value in FFmpeg's subtitles filter?

Libass scales the subtitle rendering canvas to a reference height of 288 pixels. A MarginV value of 90 represents roughly 30% of this canvas height, moving the text baseline significantly upward from the bottom edge. This scaling ensures consistent relative positioning regardless of the actual video resolution (1080×1920 or 1920×1080).

Can I customize the MarginV values for specific branding requirements?

Yes. Modify the subtitle_style_for_platform() function in helpers/render.py to return any MarginV integer. For example, if you need subtitles higher on TikTok to accommodate a custom end card, change margin = 90 to margin = 120. Just ensure the value clears the platform's UI safe zones, which typically occupy the bottom 25-30% of vertical frames.

Why must subtitles be burned after overlays according to the source code?

SKILL.md documents a hard rule that subtitles must be applied last in the filter chain. This ensures text renders on top of all visual elements—b-roll, graphics, and transitions—maintaining readability. Burning subtitles earlier in the pipeline would allow subsequent overlays to obscure the text.

Where is the default subtitle style documented in the repository?

The default SUB_FORCE_STYLE configuration is defined in helpers/render.py at lines 41-49, with platform-specific commentary explaining the 90-pixel margin choice. Additional context about subtitle customization appears in README.md under the "Burns subtitles" section, which notes that the default style uses "2-word UPPERCASE chunks" but remains fully customizable.

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