What You’ll Learn
Custom Music
Add your own music tracks from URLs
AI Music Selection
Let AI choose appropriate background music
Volume Control
Adjust music volume for perfect balance
Music Trimming
Use specific portions of music tracks
Before You Begin
Make sure you have:- A Pictory API key (get one here)
- Node.js or Python installed on your machine
- Music file accessible via public URL (for custom music)
- Basic understanding of video creation with Pictory API
How Background Music Works
When you add background music to a video:- Music Selection - You provide a custom music URL or enable AI auto-selection
- Audio Processing - The music file is accessed and processed
- Volume Adjustment - Music volume is set according to your specifications
- Clip Extraction - Specific portions of the music are extracted (if clips defined)
- Audio Mixing - Music is mixed with voice-over and video audio
- Duration Matching - Music loops or fades to match video length
- Video Rendering - Final video is rendered with all audio layers combined
Background music automatically loops if the music track is shorter than your video duration. The music fades out gracefully at the end of the video for a professional finish.
Complete Example
Background Music Configuration Parameters
Music Settings
| Parameter | Type | Required | Description |
|---|---|---|---|
backgroundMusic.enabled | boolean | Yes | Set to true to enable background music in the video |
backgroundMusic.musicUrl | string | No | Public URL to your custom music file. Cannot be used with autoMusic. |
backgroundMusic.autoMusic | boolean | No | Set to true to let AI select appropriate background music. Cannot be used with musicUrl. |
backgroundMusic.volume | number | No | Music volume level from 0 (muted) to 1 (full volume). Default: 0.5 |
backgroundMusic.clips | array | No | Array of music clip objects defining which portions of the music to use. Maximum 10 clips. |
Music Clips Configuration
| Parameter | Type | Required | Description |
|---|---|---|---|
clips[].start | number | Yes | Start time in seconds where the music clip begins |
clips[].end | number | Yes | End time in seconds where the music clip ends. Must be greater than start. |
Supported Audio Formats
| Format | Extension | Description | Best Used For |
|---|---|---|---|
| MP3 | .mp3 | Most common audio format (recommended) | General use, best compatibility |
| WAV | .wav | Uncompressed audio, high quality | High-quality music, professional audio |
| AAC | .aac | Advanced audio codec | Modern devices, streaming |
| M4A | .m4a | Apple audio format | Music purchased from iTunes |
| FLAC | .flac | Lossless compression | Audiophile quality, large files |
| OGG | .ogg | Open-source format | Web streaming, game audio |
Volume Level Reference
Choose the right volume based on your video’s audio composition:| Volume Value | Percentage | Effect | Best Used For |
|---|---|---|---|
| 0 | 0% | Muted | No background music |
| 0.1-0.2 | 10-20% | Very subtle | Videos with heavy narration, podcasts |
| 0.3-0.4 | 30-40% | Soft background | Videos with voice-over, professional presentations |
| 0.5 | 50% | Balanced | General use, balanced audio mix |
| 0.6-0.7 | 60-70% | Noticeable music | Videos without voice-over, music videos |
| 0.8-0.9 | 80-90% | Prominent music | Emphasis on music, minimal narration |
| 1.0 | 100% | Full volume | Pure background music, no other audio |
Voice-Over Recommendations:
- With AI voice-over: Use 0.2-0.4 to ensure narration is clearly heard
- Without voice-over: Use 0.5-0.8 for more prominent background music
- With original video audio: Use 0.2-0.3 to avoid overwhelming existing audio
Using AI-Selected Music
Let the AI automatically choose appropriate background music for your video:- AI analyzes your video content and theme
- Selects music that matches the video’s mood and pacing
- Chooses from a library of royalty-free music tracks
- No need to provide your own music URL
Using Music Clips
Extract and use specific portions of a music track:Single Clip Example
Multiple Clips Example
Full Track (No Clips)
Common Use Cases
Educational Videos with Narration
Marketing Videos with Energetic Music
Social Media Content (No Voice-Over)
Professional Presentations
Best Practices
Balance Music with Voice-Over
Balance Music with Voice-Over
Ensure music complements rather than competes with narration:
- With Voice-Over: Use volume 0.2-0.4 for background music
- Clear Narration: Keep music soft enough that every word is heard
- Voice Emphasis: Music should enhance, not distract from the message
- Test Levels: Preview videos to ensure proper audio balance
- Consistent Volume: Maintain consistent music volume throughout
Choose Appropriate Music for Content
Choose Appropriate Music for Content
Match music style to your video’s purpose and audience:
- Educational Content: Use calm, neutral background music
- Marketing Videos: Choose upbeat, energetic tracks
- Professional Presentations: Use subtle, corporate-style music
- Social Media: Opt for trending or popular music styles
- Emotional Content: Match music mood to video emotion (inspiring, somber, etc.)
- Brand Alignment: Ensure music fits your brand identity
Use Royalty-Free Music
Use Royalty-Free Music
Avoid copyright issues by using properly licensed music:
- Royalty-Free Libraries: Use sites like AudioJungle, Epidemic Sound, Artlist
- Creative Commons: Verify licenses allow commercial use
- Stock Music: Invest in quality stock music libraries
- Original Music: Commission custom tracks for unique branding
- AI Music: Use AI-generated music that’s copyright-safe
- Attribution: Follow license requirements for attribution when needed
Optimize Music File Accessibility
Optimize Music File Accessibility
Ensure your music files can be accessed by the API:
- Public URLs: Upload to cloud storage (AWS S3, Google Drive, Dropbox)
- Direct Links: Use direct download links, not streaming or preview URLs
- Stable URLs: Ensure links won’t expire during processing
- Test Access: Verify URLs work in incognito browser
- File Size: Keep files under 50MB for faster processing
- Format: Use MP3 format for best compatibility
Strategic Clip Usage
Strategic Clip Usage
Use music clips to enhance your video effectively:
- Skip Intros: Start clips after long musical intros
- Use Choruses: Extract upbeat, engaging portions of songs
- Avoid Vocals: Consider instrumental tracks or sections for clarity
- Loop Planning: Choose clips that loop naturally if needed
- Length Matching: Use clips that align with your video duration
- Multiple Clips: Vary music across different video sections (max 10)
Troubleshooting
Error: Cannot access music file
Error: Cannot access music file
Problem: The API cannot download or process your music file.Solution:
- Verify the URL is publicly accessible (test in incognito browser)
- Ensure it’s a direct download link, not a streaming or preview link
- For Google Drive: Right-click → Share → “Anyone with the link” → Copy link
- For Dropbox: Share → Create link → change “dl=0” to “dl=1” at end of URL
- Check file hasn’t been deleted or moved
- Verify file format is supported (MP3, WAV, AAC, M4A)
- Ensure file size is reasonable (under 50MB recommended)
Music is too loud or too quiet
Music is too loud or too quiet
Problem: Background music volume doesn’t balance well with other audio.Solution:
- Adjust the
volumeparameter (range: 0-1) - With voice-over: Try 0.2-0.4 for subtle background
- Without voice-over: Try 0.5-0.8 for more prominent music
- Test different values to find the right balance
- Consider the original music file’s volume level
- Use audio editing software to normalize music before uploading
Error: Cannot use musicUrl and autoMusic together
Error: Cannot use musicUrl and autoMusic together
Problem: Request fails because both
musicUrl and autoMusic are specified.Solution:- Choose one method: custom music OR AI-selected music
- Remove
musicUrlif usingautoMusic: true - Remove
autoMusicif usingmusicUrl - Example with AI music:
{ enabled: true, autoMusic: true, volume: 0.4 } - Example with custom music:
{ enabled: true, musicUrl: "...", volume: 0.4 }
Music doesn't loop properly
Music doesn't loop properly
Problem: Music ends abruptly or doesn’t loop smoothly.Solution:
- The API automatically loops music shorter than the video
- Choose music that loops naturally (same start and end)
- Use music editing software to create seamless loops
- Consider using full-length tracks that match video duration
- Use multiple clips to control exactly which portions play
- Music automatically fades out at video end for smooth finish
Clip times don't work as expected
Clip times don't work as expected
Problem: Music clips don’t extract the expected portions of the track.Solution:
- Verify
starttime is less thanendtime - Check that times are in seconds, not minutes
- Ensure clip times don’t exceed the music file duration
- Test clip times using an audio player first
- Maximum 10 clips per video
- Clips play in the order they’re defined in the array
No music in final video
No music in final video
Problem: Created video but background music is missing.Solution:
- Verify
enabled: trueinbackgroundMusicconfiguration - Check
volumeis not set to 0 (muted) - Ensure either
musicUrlorautoMusic: trueis specified - Verify job completed successfully without errors
- Check API response for any warnings about music processing
- Test with AI music first to isolate custom URL issues
- Verify music file URL is accessible and in supported format
Music Looping and Fading
Automatic Looping
When your music track is shorter than the video:- Music automatically loops from the beginning
- Seamless looping for music designed to loop
- Use loop-friendly tracks for best results
Automatic Fade-Out
At the end of the video:- Music fades out gracefully over the last 2-3 seconds
- Prevents abrupt audio cutoff
- Creates professional-sounding finish
Using Clips to Control Looping
Next Steps
Enhance your videos with these complementary features:AI Voice-Over
Add narration to videos with background music
Brand Settings
Apply consistent branding with background music
Intro/Outro Videos
Add intro and outro sequences with music
Custom Subtitle Styling
Style subtitles to complement your music videos
API Reference
For complete technical details, see:- Render Storyboard Video - Full API specification including backgroundMusic
- Get Job Status - Monitor job status and get video URLs
