What You’ll Learn
Inline Styles
Define custom styles directly in API requests
Full Control
Customize fonts, colors, positions, and effects
No Presets Needed
Style without saving configurations
Animation Options
Add entry and exit animations
Before You Begin
Make sure you have:- A Pictory API key (get one here)
- Node.js or Python installed on your machine
- Basic understanding of colors (RGBA format)
- Familiarity with subtitle positioning
How Custom Subtitle Styling Works
When you define subtitle styles inline:- Style Definition - You specify all subtitle properties in your request
- Property Application - Font, colors, position, and effects are configured
- Animation Setup - Entry and exit animations are applied (optional)
- No Saving Required - Style exists only for this video (not saved to account)
- Video Rendering - Subtitles render with your exact specifications
Inline subtitle styles give you complete control without creating saved presets. This is perfect for one-time custom styling or testing different subtitle configurations.
Complete Example
Subtitle Style Parameters
Font Properties
| Property | Type | Description | Example |
|---|---|---|---|
fontFamily | string | Font name | ”Poppins”, “Arial”, “Roboto” |
fontUrl | string | Custom font URL (optional) | “https://example.com/font.woff2” |
fontSize | number | Font size in pixels | 48, 36, 60 |
Color Properties
All colors use RGBA format:rgba(R, G, B, A) where R/G/B are 0-255 and A is 0-1
| Property | Description | Example |
|---|---|---|
color | Main text color | rgba(255, 255, 255, 1) (white) |
backgroundColor | Background behind text | rgba(0, 0, 0, 0.7) (semi-transparent black) |
keywordColor | Color for highlighted keywords | rgba(255, 215, 0, 1) (gold) |
shadowColor | Text shadow color | rgba(0, 0, 0, 0.8) (dark gray) |
Position and Layout
| Property | Type | Options/Description |
|---|---|---|
position | string | top-left, top-center, top-right, center-left, center-center, center-right, bottom-left, bottom-center, bottom-right |
alignment | string | left, center, right |
paragraphWidth | string | Percentage of screen width (e.g., “80%”, “100%“) |
shadowWidth | string | Shadow size as percentage (e.g., “2%”, “5%“) |
Text Styling
| Property | Type | Options |
|---|---|---|
decorations | array | ["bold"], ["underline"], ["italics"], ["linethrough"] (can combine multiple) |
case | string | uppercase, lowercase, capitalize, smallcapitalize |
Animation Options
You can add up to 2 animations per subtitle style (one entry, one exit).Available Animations
| Animation Name | Type | Description |
|---|---|---|
none | Entry/Exit | No animation |
fade | Entry/Exit | Gradual fade in or out |
drift | Entry/Exit | Drift motion with fade |
wipe | Entry/Exit | Wipe across screen |
text reveal | Entry | Text reveals character by character |
elastic | Entry | Elastic bounce effect |
typewriter | Entry | Typewriter effect |
blur | Entry/Exit | Blur transition |
bulletin | Entry | Bulletin board style |
Animation Configuration
| Property | Options | Description |
|---|---|---|
name | string | Animation name from table above |
type | string | entry (appearing) or exit (disappearing) |
speed | string | slow, medium, fast, custom |
direction | string | up, down, left, right (for directional animations) |
RGBA Color Format
| Component | Range | Description |
|---|---|---|
| R (Red) | 0-255 | Red intensity |
| G (Green) | 0-255 | Green intensity |
| B (Blue) | 0-255 | Blue intensity |
| A (Alpha) | 0-1 | Transparency (0 = transparent, 1 = opaque) |
Common Colors
| Color | RGBA Value |
|---|---|
| White | rgba(255, 255, 255, 1) |
| Black | rgba(0, 0, 0, 1) |
| Semi-transparent black | rgba(0, 0, 0, 0.7) |
| Gold | rgba(255, 215, 0, 1) |
| Red | rgba(255, 0, 0, 1) |
| Blue | rgba(0, 120, 255, 1) |
| Green | rgba(34, 197, 94, 1) |
Common Use Cases
Professional Business Subtitles
Social Media Style
Educational Content
Animated Dynamic Subtitles
Best Practices
Choose Readable Font Combinations
Choose Readable Font Combinations
Select fonts and sizes for optimal readability:
- Font Size: 36-56 pixels for most videos (1920x1080)
- Font Families: Use web-safe fonts like Poppins, Roboto, Arial, Montserrat
- Font Weight: Bold is generally more readable on video
- Custom Fonts: Test custom fonts thoroughly before production
- Consistency: Use same font family across all scenes for cohesion
Use High-Contrast Colors
Use High-Contrast Colors
Ensure subtitles are easily visible:
- Light Text on Dark: White text on semi-transparent black (most common)
- Dark Text on Light: Black text on white background (high brightness videos)
- Shadow for Depth: Add shadows to text without backgrounds
- Keyword Colors: Use contrasting colors for keyword highlights
- Test Backgrounds: Verify readability on various scene backgrounds
Position Strategically
Position Strategically
Place subtitles where they’re visible but not intrusive:
- Bottom-Center: Standard position, doesn’t cover main content
- Avoid Top: Unless content is primarily at bottom
- Width: 70-90% paragraph width prevents text from reaching edges
- Alignment: Center alignment works best for most content
- Scene-Specific: Consider different positions for different scene types
Apply Animations Sparingly
Apply Animations Sparingly
Use animations to enhance, not distract:
- Entry Animation: Fade or drift work well for most content
- Exit Animation: Faster exit (fade) than entry feels natural
- Speed: Medium or fast speeds prevent slow pacing
- Avoid Overuse: Too many animations can be distracting
- Match Content: Playful animations for casual, simple for professional
Test Before Production
Test Before Production
Always preview your custom styles:
- Create Test Video: Use short sample text first
- Multiple Scenes: Test with different background colors
- Device Testing: View on mobile and desktop
- Readability Check: Ensure text is clear at different video sizes
- Adjust Iteratively: Refine style based on test results
Troubleshooting
Subtitles are hard to read
Subtitles are hard to read
Problem: Text is not clearly visible in the video.Solution:
- Increase background opacity (higher alpha value in backgroundColor)
- Use higher contrast between text color and background
- Add or increase shadow (shadowColor and shadowWidth)
- Increase font size (try 48-56 pixels)
- Use bold decoration for thicker, more visible text
Colors don't look as expected
Colors don't look as expected
Problem: Subtitle colors appear different than intended.Solution:
- Verify RGBA format is correct (rgba(R, G, B, A))
- Check RGB values are 0-255, alpha is 0-1
- Ensure proper comma separation in RGBA values
- Test colors with online RGBA picker before using
- Remember alpha channel affects transparency
- Check for typos in color values
Font doesn't appear or looks wrong
Font doesn't appear or looks wrong
Problem: Specified font isn’t being used.Solution:
- Use standard web fonts (Poppins, Roboto, Arial, Montserrat)
- Check font name spelling exactly
- If using custom font URL, verify URL is accessible
- Ensure fontUrl points directly to font file (.woff2, .woff, .ttf)
- Test with standard font first, then add custom
Animations not working
Animations not working
Problem: Entry or exit animations don’t appear.Solution:
- Verify animation name is from available options
- Check type is either “entry” or “exit”
- Ensure speed is “slow”, “medium”, “fast”, or “custom”
- Maximum 2 animations allowed (one entry, one exit)
- Check animations array syntax is correct
- Try simple “fade” animation first to test
Subtitles positioned incorrectly
Subtitles positioned incorrectly
Problem: Subtitles appear in wrong location on screen.Solution:
- Verify position value matches available options
- Position names are case-sensitive and hyphenated
- Check for typos: “bottom-center” not “bottom center”
- Ensure paragraphWidth doesn’t push text off-screen
- Test with “bottom-center” first as baseline
- Review final video to verify placement
Next Steps
Explore more subtitle and branding options:Subtitle Styles
Use saved subtitle style presets
Highlight Keywords
Automatically emphasize important words
Brand Settings
Apply complete brand presets to videos
Custom Captions
Add multilingual captions to videos
API Reference
For complete technical details, see:- Render Storyboard Video - Full API specification
- Get Job Status - Monitor job status and progress
