maxSubtitleLines parameter allows you to create cleaner, more readable captions by limiting how much text appears simultaneously.
What You’ll Learn
Line Control
Limit subtitle lines for cleaner presentation
Readability
Improve viewer experience with controlled text
Scene-Level Config
Apply different settings per scene
Style Integration
Works with subtitle styles and formatting
Before You Begin
Make sure you have:- A Pictory API key (get one here)
- Node.js or Python installed on your machine
- Text content ready for video conversion
- Understanding of subtitle display preferences
How maxSubtitleLines Works
When you setmaxSubtitleLines for a scene:
- Text Analysis - Your story content is analyzed and segmented into sentences
- Line Calculation - The system calculates how text fits based on font size, style, and aspect ratio
- Scene Distribution - Text is distributed across scenes respecting the maximum lines
- Subtitle Rendering - Each scene displays no more than the specified number of lines
The
maxSubtitleLines parameter intelligently groups text based on your subtitle style settings and video aspect ratio to ensure optimal readability across all display sizes.Complete Example
Understanding the Parameters
Scene-Level Configuration
| Parameter | Type | Required | Description |
|---|---|---|---|
scenes[].maxSubtitleLines | number | No | Maximum number of subtitle lines to display at once |
Line Count Recommendations
| Value | Display | Best Used For |
|---|---|---|
1 | Single line | Social media shorts, TikTok, Instagram Reels |
2 | Two lines | Standard videos, YouTube, most content types |
3 | Three lines | Longer sentences, detailed explanations |
4+ | Multiple lines | Dense information, educational content |
Line Count by Use Case
Single Line (maxSubtitleLines: 1)
Best for short-form social media content where quick, punchy text is preferred:Two Lines (maxSubtitleLines: 2)
The most common setting, balancing readability with content density:Three Lines (maxSubtitleLines: 3)
Good for longer sentences or when more context is needed:Aspect Ratio Considerations
ThemaxSubtitleLines calculation takes your video’s aspect ratio into account:
| Aspect Ratio | Orientation | Line Capacity | Recommendation |
|---|---|---|---|
16:9 | Landscape | More horizontal space | 2-3 lines work well |
9:16 | Portrait | More vertical space | 1-2 lines recommended |
1:1 | Square | Balanced | 2 lines optimal |
Portrait videos (9:16) have less horizontal space, so longer sentences may wrap more. Consider using fewer
maxSubtitleLines for portrait content to maintain readability.Best Practices
Match Lines to Platform
Match Lines to Platform
Choose line count based on where your video will be published:
- TikTok/Reels: 1 line for quick reading
- YouTube: 2 lines for standard viewing
- Educational platforms: 2-3 lines for detailed content
- Presentations: 2 lines for professional look
Consider Reading Speed
Consider Reading Speed
Factor in how fast viewers can read:
- Fewer lines = faster comprehension
- More lines = more context but slower processing
- Match line count to content complexity
- Test with real viewers if possible
Coordinate with Font Size
Coordinate with Font Size
Line count and font size work together:
- Larger fonts need fewer lines
- Smaller fonts can accommodate more lines
- Ensure text remains readable at all sizes
- Test on different screen sizes
Use with Scene Breaking
Use with Scene Breaking
Combine with scene creation options:
createSceneOnEndOfSentence: truecreates natural breaksmaxSubtitleLinescontrols text within each break- Together they create well-paced, readable subtitles
- Avoid very long scenes with high line counts
Test Different Values
Test Different Values
Experiment to find optimal settings:
- Create test videos with different line counts
- Compare readability across variations
- Consider your specific content type
- Adjust based on actual viewing experience
Troubleshooting
Error: maxSubtitleLines not allowed with smart layouts
Error: maxSubtitleLines not allowed with smart layouts
Problem: API returns error when using maxSubtitleLines with smart layouts.Solution:
- Remove
maxSubtitleLinesfrom scene configuration - Smart layouts manage text display automatically
- Choose one approach: smart layouts OR manual line control
- Remove
smartLayoutNameorsmartLayoutIdif you need line control
Error: maxSubtitleLines not allowed with caption
Error: maxSubtitleLines not allowed with caption
Problem: API returns error when using both maxSubtitleLines and caption.Solution:
- Remove either
maxSubtitleLinesorcaptionparameter - The
captionfeature has its own text handling - Use
storywithmaxSubtitleLinesfor controlled subtitle display - Captions are meant for separate display text, not story content
Text still shows more lines than expected
Text still shows more lines than expected
Problem: Subtitles appear with more lines than the maxSubtitleLines setting.Solution:
- Verify the parameter is spelled correctly:
maxSubtitleLines - Ensure it’s at the scene level, not video level
- Check that you’re not using smart layouts
- Very long words may cause unexpected wrapping
- Adjust font size if needed for better fitting
Inconsistent line counts across scenes
Inconsistent line counts across scenes
Problem: Some scenes show different numbers of lines.Solution:
- This is normal behavior based on text length
maxSubtitleLinessets a maximum, not exact count- Shorter text may naturally use fewer lines
- The system optimizes for readability within the limit
- This maintains natural text flow
Next Steps
Enhance your subtitle configuration with these features:Custom Subtitle Style
Create custom inline subtitle formatting
Saved Subtitle Styles
Apply saved subtitle style presets
Smart Layouts
Use pre-designed layouts with automatic text handling
Highlight Keywords
Emphasize important words in subtitles
