What You’ll Learn
Custom Captions
Add subtitles separate from story text
Multi-Language Support
Display captions in different languages
Dual Text System
Story for visuals, captions for display
Translation Ready
Perfect for international audiences
Before You Begin
Make sure you have:- A Pictory API key (get one here)
- Node.js or Python installed on your machine
- Your content text and translated captions prepared
- Language codes for your target language
How Caption System Works
Pictory’s caption system uses a dual-text approach:- Story Text - The main content used by AI to understand context and select appropriate visuals
- Caption Text - The text displayed as subtitles in your final video
- Language Code - Specifies the caption language for proper formatting
- Automatic Sync - Captions are automatically synchronized with video timing
This separation allows you to create videos in one language (for visual selection) while displaying subtitles in another language, making your content accessible to global audiences.
Complete Example
Caption Configuration Parameters
Scene Configuration
| Parameter | Type | Required | Description |
|---|---|---|---|
story | string | Yes | The main text used for AI visual selection and content understanding |
caption | string | Yes | The text that will be displayed as subtitles in the video |
captionLanguage | string | Yes | ISO 639-1 language code for the caption (e.g., “es” for Spanish) |
createSceneOnNewLine | boolean | Yes | Must be false when using captions |
createSceneOnEndOfSentence | boolean | Yes | Must be false when using captions |
Supported Caption Languages
| Language | Code | Language | Code |
|---|---|---|---|
| Chinese | zh | Portuguese | pt |
| Dutch | nl | Russian | ru |
| English | en | Spanish | es |
| French | fr | Hindi | hi |
| German | de | Japanese | ja |
| Italian | it | Korean | ko |
Story vs Caption: Understanding the Difference
When to Use Story Text
When to Use Story Text
Story text is the content the AI uses to:
- Understand the context and meaning of your video
- Select appropriate stock visuals and images
- Determine the overall theme and mood
- Generate relevant background content
When to Use Caption Text
When to Use Caption Text
Caption text is what your viewers will see:
- Displayed as subtitles throughout the video
- Can be a translation of the story text
- Can be simplified or adapted for your audience
- Should match your target audience’s language
Example Use Case
Example Use Case
Scenario: Creating a video for Spanish-speaking students about AI in education.The AI understands the English concept to select educational visuals, but Spanish subtitles appear for your audience.
Common Use Cases
Creating Multilingual Marketing Videos
Educational Content for International Students
Accessibility and Localization
Working with Multiple Scenes
Since automatic scene breaks are disabled when using captions, you need to manually create scenes:Best Practices
Keep Translations Accurate
Keep Translations Accurate
Ensure your caption text accurately reflects the story text:
- Use professional translation services when possible
- Keep the meaning and tone consistent
- Avoid direct word-for-word translations that may sound unnatural
- Test with native speakers before production
Choose the Right Language Code
Choose the Right Language Code
Always use the correct ISO 639-1 language code:
- Double-check the code matches your caption language
- Use region-specific codes when necessary (e.g.,
zh-CNvszh-TW) - Verify the language is supported (see table above)
Match Caption Length to Video Timing
Match Caption Length to Video Timing
Keep captions readable within the scene duration:
- Shorter captions are easier to read
- Break long sentences into multiple scenes
- Aim for 1-2 lines of text per scene
- Test video playback to ensure captions are comfortable to read
Plan Your Scene Structure
Plan Your Scene Structure
Since automatic scene breaks don’t work with captions:
- Plan scene breaks manually before creating the video
- Group related content into logical scenes
- Create separate scene objects for each caption segment
- Consider the visual flow between scenes
Troubleshooting
Error: Cannot use captions with automatic scene breaks
Error: Cannot use captions with automatic scene breaks
Problem: You set
createSceneOnNewLine or createSceneOnEndOfSentence to true with captions.Solution:
Set both parameters to false:Captions appear in wrong language
Captions appear in wrong language
Problem: The caption text displays but formatting is incorrect.Solution:
- Verify you’re using the correct language code (e.g., “es” not “spanish”)
- Check the supported languages table above
- Ensure the caption text is properly encoded (UTF-8)
Visuals don't match my caption content
Visuals don't match my caption content
Problem: The selected visuals don’t seem relevant to your captions.Solution:
Remember that visuals are selected based on
story text, not caption text:- Make sure your
storytext clearly describes the visuals you want - Keep
storytext in a language the AI handles well (English recommended) - The
captionis only for subtitle display, not visual selection
Caption text too long for scene
Caption text too long for scene
Problem: Captions are cut off or hard to read.Solution:
- Break long text into multiple scenes
- Keep each caption to 1-2 lines (approximately 60-100 characters)
- Create separate scene objects for longer content:
Next Steps
Enhance your captioned videos with these features:AI Voice-Over
Add narration in the caption language
Custom Subtitle Styles
Customize caption appearance and formatting
Multi-Level Voice-Over
Use different voices for different scenes
Brand Settings
Apply consistent branding across videos
