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 (get one here)
- Node.js or Python installed on your machine
- Text content ready for video conversion
How Dynamic Captions Work
ThemaxSubtitleLines 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 alongsidemaxSubtitleLines, caption lines are synchronized with the spoken audio:
- Audio Generation: The story text is converted to speech using the selected AI voice.
- Line Timing: The audio service provides timing data that determines when each caption line appears.
- Caption Sync: Each caption line is displayed on screen at the exact moment it is spoken in the voiceover.
- Line Control: The
maxSubtitleLinesvalue limits how many lines of text are visible simultaneously.
Without AI Voiceover
ThemaxSubtitleLines 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
| Parameter | Type | Required | Description |
|---|---|---|---|
scenes[].maxSubtitleLines | number | No | Maximum number of caption lines displayed simultaneously. When omitted, all lines are shown on the scene at once. |
maxSubtitleLines Values
| Value | Description |
|---|---|
| Not set | All caption lines are displayed on the scene at once (no progressive display) |
1 | Displays one caption line at a time. Ideal for short-form content |
2 | Standard caption display. Suitable for most content types |
3 | Displays more text simultaneously. Recommended for educational or detailed content |
4 | Maximum text density. Best for information-heavy content |
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:Two Lines (maxSubtitleLines: 2)
The most common configuration, providing a balance between readability and content density:Three Lines (maxSubtitleLines: 3)
Appropriate for longer sentences or content that benefits from additional on-screen context:Mixed Line Counts
DifferentmaxSubtitleLines values can be assigned to individual scenes within the same video:
Aspect Ratio Considerations
The optimalmaxSubtitleLines value depends on the video aspect ratio:
| Aspect Ratio | Orientation | Recommendation |
|---|---|---|
16:9 | Landscape | 2-3 lines |
1:1 | Square | 2 lines |
4:5 | Vertical | 1-2 lines |
9:16 | Portrait | 1-2 lines |
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:| Provider | Example Voices | Caption Sync Method |
|---|---|---|
| ElevenLabs | Rachel, Adam | Native timing alignment |
| AWS Polly | Aria, Matthew | Via transcription service |
| Google TTS | Eugene, Lisa | Via transcription service |
Best Practices
Match Line Count to Platform
Match Line Count to Platform
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
Enable Voice-Over for Best Results
Enable Voice-Over for Best Results
While dynamic captions function without voiceover, enabling AI voiceover synchronizes caption lines with the spoken audio, providing the best viewer experience:
Consider Reading Speed
Consider Reading Speed
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
Coordinate with Font Size
Coordinate with Font Size
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
Default Behavior Without maxSubtitleLines
Default Behavior Without maxSubtitleLines
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
Captions Not Syncing With Audio
Captions Not Syncing With Audio
Cause: Caption lines appear on screen but are not synchronized with the voiceover.Resolution:
- Verify that voice-over is enabled in the request
- Confirm that
maxSubtitleLinesis set at the scene level - Ensure that smart layouts are not in use, as they manage text display independently
maxSubtitleLines Not Allowed With Smart Layouts
maxSubtitleLines Not Allowed With Smart Layouts
Cause: The API returns an error because
maxSubtitleLines cannot be combined with smart layouts.Resolution:- Remove
maxSubtitleLinesfrom the scene configuration, or - Remove
smartLayoutNameorsmartLayoutIdif dynamic captions are required
maxSubtitleLines Not Allowed With Caption
maxSubtitleLines Not Allowed With Caption
Cause: The API returns an error because
maxSubtitleLines and caption cannot be used together.Resolution:- Remove either the
maxSubtitleLinesorcaptionparameter - Use the
storyparameter withmaxSubtitleLinesfor dynamic captions
caption parameter uses its own text handling and is incompatible with dynamic captions.More Lines Displayed Than Expected
More Lines Displayed Than Expected
Cause: Subtitles appear with more lines than the configured
maxSubtitleLines value.Resolution:- Verify the parameter is spelled correctly:
maxSubtitleLines - Confirm the parameter is set at the scene level, not the video level
- Ensure that smart layouts are not active on the scene
- 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
