Skip to main content
Dynamic captions are progressive on-screen subtitles controlled by the maxSubtitleLines parameter. This parameter determines how many lines of caption text appear on screen at any given time. When AI voiceover is enabled, each caption line is synchronized with the spoken audio, appearing precisely as it is narrated.

What You Will Learn

Enable Dynamic Captions

Configure caption lines that appear progressively on screen

Control Line Count

Use maxSubtitleLines to set the number of visible caption lines

Multi-Language Support

Compatible with ElevenLabs, AWS Polly, and Google voices

Prerequisites

Ensure you have the following before proceeding:
  • A Pictory API key
  • Node.js or Python installed on your machine
  • Text content ready for video conversion

How Dynamic Captions Work

The maxSubtitleLines parameter enables dynamic captions at the scene level. When included in a scene configuration, Pictory generates caption lines that appear progressively on screen, limited to the specified number of lines.

With AI Voiceover

When AI voiceover is enabled alongside maxSubtitleLines, caption lines are synchronized with the spoken audio:
  1. Audio Generation: The story text is converted to speech using the selected AI voice.
  2. Line Timing: The audio service provides timing data that determines when each caption line appears.
  3. Caption Sync: Each caption line is displayed on screen at the exact moment it is spoken in the voiceover.
  4. Line Control: The maxSubtitleLines value limits how many lines of text are visible simultaneously.

Without AI Voiceover

The maxSubtitleLines parameter can also be used without voiceover. In this mode, caption lines are distributed uniformly across the scene duration, with each line displayed for an equal amount of time.
When maxSubtitleLines is not provided, all caption lines for the scene are displayed on screen at once. To enable progressive caption display, set maxSubtitleLines to the desired number of visible lines. For the best results, pair maxSubtitleLines with AI voiceover to synchronize caption lines with the spoken audio.

Complete Example

Understanding the Parameters

Scene-Level Configuration

maxSubtitleLines Values

When maxSubtitleLines is not included in the request, all caption text for the scene is shown at once. Setting this parameter activates progressive caption display. Enabling AI voiceover synchronizes caption lines with the spoken audio.

Line Count by Use Case

Single Line (maxSubtitleLines: 1)

Suited for short-form social media content where concise, fast-paced text is preferred:
Result: Clean, single-line captions optimized for quick readability. Ideal for TikTok, Instagram Reels, and YouTube Shorts.

Two Lines (maxSubtitleLines: 2)

The most common configuration, providing a balance between readability and content density:
Result: Standard two-line captions suitable for most video formats. Recommended for YouTube, LinkedIn, and marketing videos.

Three Lines (maxSubtitleLines: 3)

Appropriate for longer sentences or content that benefits from additional on-screen context:
Result: Increased text visibility per frame. Ideal for educational, documentary, or training content.

Mixed Line Counts

Different maxSubtitleLines values can be assigned to individual scenes within the same video:

Aspect Ratio Considerations

The optimal maxSubtitleLines value depends on the video aspect ratio:
Vertical and portrait formats (4:5 and 9:16) have limited horizontal space, causing longer sentences to wrap more frequently. Use fewer lines for vertical content to maintain readability.

Supported Voice Providers

Dynamic captions with voiceover synchronization are supported across all voice providers:
CompatibilityDynamic captions via maxSubtitleLines function with or without AI voiceover. When AI voiceover is enabled, caption lines are synchronized with the spoken audio, appearing on screen as each line is narrated.Supported Workflows:
  • Text-to-Video (using story parameter)
  • Article-to-Video (using blogUrl parameter)
  • Image slideshows with text overlays
Not Supported With:
  • smartLayoutName or smartLayoutId (smart layouts manage text display independently)
  • The caption parameter (uses separate text handling)
  • Audio-to-Video workflows (audioUrl)
  • Video-to-Video workflows (videoUrl)
  • PowerPoint-to-Video workflows (pptUrl)

Best Practices

Select the line count based on the target publishing platform:
  • TikTok/Reels: 1 line for rapid readability
  • YouTube: 2 lines for standard viewing
  • Educational platforms: 2-3 lines for detailed content
  • Presentations: 2 lines for a professional appearance
While dynamic captions function without voiceover, enabling AI voiceover synchronizes caption lines with the spoken audio, providing the best viewer experience:
Account for viewer reading speed when selecting a line count:
  • Fewer lines result in faster comprehension
  • More lines provide additional context but require more processing time
  • Match line count to content complexity
Line count and font size are interdependent:
  • Larger fonts require fewer lines to avoid overcrowding
  • Smaller fonts can accommodate additional lines
  • Verify that text remains legible at all sizes
  • Test across different screen dimensions
When maxSubtitleLines is not provided, all caption text for the scene is displayed at once. To enable progressive caption display, explicitly set this parameter to the desired line count.

Troubleshooting

Cause: Caption lines appear on screen but are not synchronized with the voiceover.Resolution:
  1. Verify that voice-over is enabled in the request
  2. Confirm that maxSubtitleLines is set at the scene level
  3. Ensure that smart layouts are not in use, as they manage text display independently
Cause: The API returns an error because maxSubtitleLines cannot be combined with smart layouts.Resolution:
  1. Remove maxSubtitleLines from the scene configuration, or
  2. Remove smartLayoutName or smartLayoutId if dynamic captions are required
Smart layouts and dynamic captions are mutually exclusive. Select one approach per scene.
Cause: The API returns an error because maxSubtitleLines and caption cannot be used together.Resolution:
  1. Remove either the maxSubtitleLines or caption parameter
  2. Use the story parameter with maxSubtitleLines for dynamic captions
The caption parameter uses its own text handling and is incompatible with dynamic captions.
Cause: Subtitles appear with more lines than the configured maxSubtitleLines value.Resolution:
  1. Verify the parameter is spelled correctly: maxSubtitleLines
  2. Confirm the parameter is set at the scene level, not the video level
  3. Ensure that smart layouts are not active on the scene
  4. Reduce font size if long words are causing unexpected line wrapping

Next Steps

Enhance your dynamic captions with these related features:

Custom Subtitle Style

Customize font, color, and background of your captions

Saved Subtitle Styles

Apply saved subtitle style presets

Highlight Keywords

Emphasize important words in captions

Smart Layouts

Use pre-designed layouts with automatic text handling

API Reference

For complete technical details, refer to the following resources:

Render Storyboard Video

Configure dynamic captions and voice-over settings

Get Job Status

Monitor video creation progress

Get Text Styles

Retrieve available subtitle styles

Get Smart Layouts

Retrieve all available smart layout templates