How to Configure Custom Subtitle Styles for Vertical Video Platforms (TikTok, Reels, Shorts)

The video-use library burns subtitles into vertical videos using FFmpeg's subtitles filter with a customizable SUB_FORCE_STYLE constant in helpers/render.py that follows ASS style syntax to ensure text remains visible within platform-specific safe zones.

Configuring custom subtitle styles for vertical video platforms like TikTok, Instagram Reels, and YouTube Shorts requires precise positioning to avoid platform UI elements. The browser-use/video-use repository handles this through FFmpeg's subtitle filter, applying a configurable style string that keeps captions readable on 1080×1920 portrait canvases while respecting the bottom safe zones where platform interfaces appear.

How Subtitle Rendering Works in video-use

The FFmpeg Integration

In helpers/render.py, the build_final_composite function constructs the FFmpeg command that burns subtitles directly into the final video. When the --build-subtitles flag is enabled, the renderer appends a subtitles filter to the processing pipeline.

The Force Style Parameter

The filter invocation follows this pattern:

[current]subtitles='<absolute-path>':force_style='<SUB_FORCE_STYLE>'[outv]

The SUB_FORCE_STYLE variable is injected as the force_style parameter, overriding the default ASS styles in the subtitle file with your custom specifications.

The Default Subtitle Style Configuration

Located at lines 41-56 in helpers/render.py, the SUB_FORCE_STYLE constant defines the default appearance:

# helpers/render.py – Subtitle style (bold-overlay, proven at 1920×1080 and 1080×1920)

# MarginV = 90 places the caption ~30% up from the bottom, keeping it clear of

# TikTok / IG Reels / Shorts UI elements.

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"
)

This configuration uses Helvetica 18pt bold with white text (&H00FFFFFF) and black outlines, optimized for readability on both horizontal and vertical video formats.

Customizing Fonts, Colors, and Positioning

To modify subtitle appearance, edit the SUB_FORCE_STYLE string in helpers/render.py. The syntax follows the libass ASS style specification, where comma-separated key=value pairs define visual properties.

Changing Font Families and Sizes

Replace Helvetica with Arial and increase the font size for better visibility:

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

Adding Background Contrast

For videos with bright or variable backgrounds, add a semi-transparent backing box:

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

The BackColour=&H80000000 value creates a 50% opaque black background (hex format: ABGR).

Platform-Specific Safe Zones (TikTok, Reels, Shorts)

The MarginV parameter is critical for vertical video platforms. On a 1080×1920 frame, TikTok, Instagram Reels, and YouTube Shorts place UI elements (captions, music tags, interaction buttons) in the bottom 25-30% of the screen.

Understanding MarginV

The default MarginV=90 positions the subtitle baseline approximately 30% up from the bottom edge, relative to the ASS PlayResY of 288. This keeps text visible above platform interface elements.

Adjusting for Different Platforms

If targeting platforms with larger UI footprints, increase the margin value:

SUB_FORCE_STYLE = (
    "FontName=Helvetica,FontSize=18,Bold=1,"
    "PrimaryColour=&H00FFFFFF,OutlineColour=&H00000000,BackColour=&H00000000,"
    "BorderStyle=1,Outline=2,Shadow=0,"
    "Alignment=2,MarginV=120"  # Raised higher for larger safe zones

)

Applying Changes to the Render Pipeline

After modifying SUB_FORCE_STYLE, execute the render command with the subtitle flag:

python helpers/render.py path/to/edl.json -o final.mp4 --build-subtitles

According to the SKILL.md documentation, subtitles are composited last in the pipeline (after overlays), ensuring your style settings remain visible above all other video elements.

Summary

• Edit SUB_FORCE_STYLE in helpers/render.py (lines 41-56) to customize subtitle appearance for vertical video platforms.
• Use ASS syntax with comma-separated key=value pairs to define fonts, colors, and positioning.
• Maintain MarginV values between 90-120 to keep text above platform UI elements on TikTok, Reels, and Shorts.
• Render with --build-subtitles to apply your custom styles via FFmpeg's subtitles filter in the build_final_composite function.

Frequently Asked Questions

What file format does video-use use for subtitle styling?

The SUB_FORCE_STYLE constant uses ASS (Advanced SubStation Alpha) style syntax interpreted by FFmpeg's libass filter. This string overrides any styles embedded in the source subtitle file when passed to the force_style parameter.

Why is the default font size only 18pt for 1080p vertical video?

The 18pt size is defined relative to the ASS PlayResY of 288 and scales appropriately when burned into 1080×1920 output. This ensures consistent readability across both horizontal and vertical aspect ratios without requiring resolution-specific configuration.

How do I prevent subtitles from being covered by TikTok's UI elements?

Set MarginV to at least 90 (default) in your SUB_FORCE_STYLE string. This positions the caption baseline approximately 30% up from the bottom of the frame, above the area where TikTok, Instagram Reels, and YouTube Shorts display captions, music tags, and interaction buttons.

Can I use different subtitle styles for different videos without editing the source file?

Currently, video-use applies the global SUB_FORCE_STYLE constant defined in helpers/render.py. To use different styles per project, you must modify this constant before rendering or maintain separate branches of the repository with platform-specific style configurations.

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