Skip to main content
This guide shows you how to control the number of subtitle lines displayed on screen at any given time. The 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
npm install axios

How maxSubtitleLines Works

When you set maxSubtitleLines for a scene:
  1. Text Analysis - Your story content is analyzed and segmented into sentences
  2. Line Calculation - The system calculates how text fits based on font size, style, and aspect ratio
  3. Scene Distribution - Text is distributed across scenes respecting the maximum lines
  4. 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

import axios from "axios";

const API_BASE_URL = "https://api.pictory.ai/pictoryapis";
const API_KEY = "YOUR_API_KEY";

const SAMPLE_TEXT =
  "AI is poised to significantly impact educators and course creators on social media. " +
  "By automating tasks like content generation, visual design, and video editing, " +
  "AI will save time and enhance consistency.";

async function createVideoWithMaxSubtitleLines() {
  try {
    console.log("Creating video with controlled subtitle lines...");

    const response = await axios.post(
      `${API_BASE_URL}/v2/video/storyboard/render`,
      {
        videoName: "text_to_video_max_lines",

        // Voice-over configuration
        voiceOver: {
          enabled: true,
          aiVoices: [
            {
              speaker: "Brian",
              speed: 100,
              amplificationLevel: 0,
            },
          ],
        },

        // Scene configuration with maxSubtitleLines
        scenes: [
          {
            story: SAMPLE_TEXT,
            createSceneOnNewLine: true,
            createSceneOnEndOfSentence: true,
            maxSubtitleLines: 2,              // Display max 2 lines at a time
          },
        ],
      },
      {
        headers: {
          "Content-Type": "application/json",
          Authorization: API_KEY,
        },
      }
    );

    const jobId = response.data.data.jobId;
    console.log("✓ Video creation started!");
    console.log("Job ID:", jobId);

    // Monitor progress
    console.log("\nMonitoring video creation...");
    let jobCompleted = false;
    let jobResult = null;

    while (!jobCompleted) {
      const statusResponse = await axios.get(
        `${API_BASE_URL}/v1/jobs/${jobId}`,
        {
          headers: { Authorization: API_KEY },
        }
      );

      const status = statusResponse.data.data.status;
      console.log("Status:", status);

      if (status === "completed") {
        jobCompleted = true;
        jobResult = statusResponse.data;
        console.log("\n✓ Video with controlled subtitles is ready!");
        console.log("Video URL:", jobResult.data.videoURL);
      } else if (status === "failed") {
        throw new Error("Video creation failed: " + JSON.stringify(statusResponse.data));
      }

      await new Promise(resolve => setTimeout(resolve, 5000));
    }

    return jobResult;
  } catch (error) {
    console.error("Error:", error.response?.data || error.message);
    throw error;
  }
}

createVideoWithMaxSubtitleLines();

Understanding the Parameters

Scene-Level Configuration

ParameterTypeRequiredDescription
scenes[].maxSubtitleLinesnumberNoMaximum number of subtitle lines to display at once

Line Count Recommendations

ValueDisplayBest Used For
1Single lineSocial media shorts, TikTok, Instagram Reels
2Two linesStandard videos, YouTube, most content types
3Three linesLonger sentences, detailed explanations
4+Multiple linesDense information, educational content
RestrictionsThe maxSubtitleLines parameter has the following limitations:Supported Workflows:
  • Text-to-Video (using story parameter)
  • Article-to-Video (using blogUrl parameter)
Not Supported With:
  • When using smartLayoutName or smartLayoutId (smart layouts manage text display automatically)
  • When using the caption parameter (captions have their own text handling)
  • Audio-to-Video workflows (audioUrl)
  • Video-to-Video workflows (videoUrl)
  • PowerPoint-to-Video workflows (pptUrl)

Line Count by Use Case

Single Line (maxSubtitleLines: 1)

Best for short-form social media content where quick, punchy text is preferred:
{
  scenes: [{
    story: "Your content here...",
    maxSubtitleLines: 1,
    createSceneOnEndOfSentence: true
  }]
}
Result: Clean, single-line captions that are easy to read quickly.

Two Lines (maxSubtitleLines: 2)

The most common setting, balancing readability with content density:
{
  scenes: [{
    story: "Your content here...",
    maxSubtitleLines: 2,
    createSceneOnEndOfSentence: true
  }]
}
Result: Standard two-line subtitles suitable for most video content.

Three Lines (maxSubtitleLines: 3)

Good for longer sentences or when more context is needed:
{
  scenes: [{
    story: "Your detailed content with longer sentences...",
    maxSubtitleLines: 3,
    createSceneOnEndOfSentence: true
  }]
}
Result: More text visible, good for educational or documentary content.

Aspect Ratio Considerations

The maxSubtitleLines calculation takes your video’s aspect ratio into account:
Aspect RatioOrientationLine CapacityRecommendation
16:9LandscapeMore horizontal space2-3 lines work well
9:16PortraitMore vertical space1-2 lines recommended
1:1SquareBalanced2 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

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
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
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
Combine with scene creation options:
  • createSceneOnEndOfSentence: true creates natural breaks
  • maxSubtitleLines controls text within each break
  • Together they create well-paced, readable subtitles
  • Avoid very long scenes with high line counts
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

Problem: API returns error when using maxSubtitleLines with smart layouts.Solution:
  • Remove maxSubtitleLines from scene configuration
  • Smart layouts manage text display automatically
  • Choose one approach: smart layouts OR manual line control
  • Remove smartLayoutName or smartLayoutId if you need line control
Problem: API returns error when using both maxSubtitleLines and caption.Solution:
  • Remove either maxSubtitleLines or caption parameter
  • The caption feature has its own text handling
  • Use story with maxSubtitleLines for controlled subtitle display
  • Captions are meant for separate display text, not story content
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
Problem: Some scenes show different numbers of lines.Solution:
  • This is normal behavior based on text length
  • maxSubtitleLines sets 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:

API Reference

For complete technical details, see: