VideoCascadeLogo
VideoCascade

Audio Overlays

Add background music, sound effects, and voiceovers to your videos

Audio elements allow you to add audio tracks on top of your video's original audio. Perfect for background music, sound effects, voiceovers, ambient sounds, and creating rich audio landscapes for your videos.

Audio Element Structure

interface AudioElement {
  type: 'audio';
  url: string;
  timing: TimingConfig;
  effects?: AudioEffects;
  loop?: boolean;
}

Required Properties

PropertyTypeDescription
type'audio'Must be "audio"
urlstringURL to the audio file (must be publicly accessible)
timingTimingConfigWhen to play the audio

Optional Properties

PropertyTypeDefaultDescription
effectsAudioEffectsundefinedAudio effects like volume and fades
loopbooleanfalseWhether to loop the audio track

Audio Mixing: Audio elements are mixed with your base video's audio. All audio tracks play simultaneously and are combined in the final output.

Supported Formats

Audio overlays support the following formats:

  • MP3 - MPEG Layer 3 (recommended for music)
  • WAV - Waveform Audio File Format (best quality, larger files)
  • AAC - Advanced Audio Coding
  • M4A - MPEG-4 Audio
  • OGG - Ogg Vorbis

Format Recommendation: Use MP3 for best compatibility and reasonable file sizes. Use WAV for highest quality when file size isn't a concern.

Timing Configuration

Control when the audio plays in your video.

interface TimingConfig {
  startTime?: number; // Start time in seconds
  endTime?: number; // End time in seconds
  entireVideo?: boolean; // Play for entire video
}

Entire Video

Play audio for the entire video duration:

{
  "timing": {
    "entireVideo": true
  }
}

Time Range

Play audio for a specific time range:

{
  "timing": {
    "startTime": 10,
    "endTime": 45
  }
}

This plays audio from 10 seconds to 45 seconds (35 seconds total).

From Start

Play from the beginning for a specific duration:

{
  "timing": {
    "startTime": 0,
    "endTime": 30
  }
}

Audio Effects

Add volume control and fade transitions to your audio.

interface AudioEffects {
  volume?: number; // 0 (silent) to 1 (full volume)
  fadeIn?: FadeConfig; // Fade in transition
  fadeOut?: FadeConfig; // Fade out transition
}

interface FadeConfig {
  duration: number; // Duration in seconds
  easing?: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
}

Volume Control

Control the loudness of the audio track:

{
  "effects": {
    "volume": 0.5
  }
}

Volume values:

  • 0 = Silent (muted)
  • 0.3 = Quiet background music
  • 0.5 = Medium volume
  • 0.8 = Loud but not overpowering
  • 1 = Full volume (default)

Volume Mixing Tip: When adding music to videos with dialogue, use volume 0.2-0.4 to keep the music in the background without overpowering speech.

Fade In

Smoothly fade in the audio when it starts:

{
  "effects": {
    "fadeIn": {
      "duration": 2,
      "easing": "ease-in"
    }
  }
}

This gradually increases volume from 0 to the target volume over 2 seconds.

Fade Out

Smoothly fade out the audio when it ends:

{
  "effects": {
    "fadeOut": {
      "duration": 3,
      "easing": "ease-out"
    }
  }
}

This gradually decreases volume to 0 over the last 3 seconds.

Combined Effects

Use multiple effects together:

{
  "effects": {
    "volume": 0.4,
    "fadeIn": {
      "duration": 2,
      "easing": "ease-in"
    },
    "fadeOut": {
      "duration": 3,
      "easing": "ease-out"
    }
  }
}

Easing Functions

EasingBehaviorBest For
linearConstant rate of changeMechanical, consistent fades
ease-inStarts slow, ends fastNatural fade-in
ease-outStarts fast, ends slowNatural fade-out
ease-in-outSlow start and end, fast middleSmooth transitions

Loop Property

The loop property controls whether the audio repeats:

Loop Disabled (Default)

Audio plays once:

{
  "type": "audio",
  "url": "https://example.com/sound-effect.mp3",
  "loop": false
}

Use cases:

  • One-time sound effects
  • Voiceovers
  • Short audio clips
  • Timed audio inserts

Loop Enabled

Audio continuously loops while the timing duration is active:

{
  "type": "audio",
  "url": "https://example.com/background-music.mp3",
  "loop": true
}

Use cases:

  • Background music
  • Ambient sounds
  • Continuous soundscapes
  • Short loops extended over long videos

Timing vs Loop: If your timing duration is longer than the audio duration and loop is false, the audio will stop early. Set loop: true to repeat the audio throughout the timing duration.

Complete Examples

Background Music

Add background music to your entire video:

curl -X POST https://api.videocascade.com/v1/videos \
  -H "Authorization: Bearer vca_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "fileUrl": "https://example.com/video.mp4",
    "elements": [
      {
        "type": "audio",
        "url": "https://example.com/background-music.mp3",
        "timing": { "entireVideo": true },
        "effects": {
          "volume": 0.3,
          "fadeIn": { "duration": 2 },
          "fadeOut": { "duration": 3 }
        },
        "loop": true
      }
    ]
  }'
const response = await fetch('https://api.videocascade.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vca_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fileUrl: 'https://example.com/video.mp4',
    elements: [
      {
        type: 'audio',
        url: 'https://example.com/background-music.mp3',
        timing: { entireVideo: true },
        effects: {
          volume: 0.3,
          fadeIn: { duration: 2 },
          fadeOut: { duration: 3 },
        },
        loop: true,
      },
    ],
  }),
});

const data = await response.json();
console.log('Video ID:', data.videoId);
import requests

response = requests.post(
    'https://api.videocascade.com/v1/videos',
    headers={
        'Authorization': 'Bearer vca_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'fileUrl': 'https://example.com/video.mp4',
        'elements': [
            {
                'type': 'audio',
                'url': 'https://example.com/background-music.mp3',
                'timing': {'entireVideo': True},
                'effects': {
                    'volume': 0.3,
                    'fadeIn': {'duration': 2},
                    'fadeOut': {'duration': 3},
                },
                'loop': True,
            },
        ],
    }
)

data = response.json()
print(f"Video ID: {data['videoId']}")
interface AudioElement {
  type: 'audio';
  url: string;
  timing: { entireVideo: boolean };
  effects: {
    volume: number;
    fadeIn: { duration: number };
    fadeOut: { duration: number };
  };
  loop: boolean;
}

const backgroundMusic: AudioElement = {
type: 'audio',
url: 'https://example.com/background-music.mp3',
timing: { entireVideo: true },
effects: {
volume: 0.3,
fadeIn: { duration: 2 },
fadeOut: { duration: 3 },
},
loop: true,
};

const response = await fetch('https://api.videocascade.com/v1/videos', {
method: 'POST',
headers: {
'Authorization': 'Bearer vca_your_api_key',
'Content-Type': 'application/json',
},
body: JSON.stringify({
fileUrl: 'https://example.com/video.mp4',
elements: [backgroundMusic],
}),
});

Sound Effect

Add a sound effect at a specific moment:

{
  "fileUrl": "https://example.com/video.mp4",
  "elements": [
    {
      "type": "audio",
      "url": "https://example.com/whoosh.mp3",
      "timing": {
        "startTime": 15,
        "endTime": 16
      },
      "effects": {
        "volume": 0.7
      }
    }
  ]
}

Voiceover

Add a voiceover to specific sections:

{
  "fileUrl": "https://example.com/video.mp4",
  "elements": [
    {
      "type": "audio",
      "url": "https://example.com/voiceover-intro.mp3",
      "timing": {
        "startTime": 0,
        "endTime": 10
      },
      "effects": {
        "volume": 0.9,
        "fadeIn": { "duration": 0.5 },
        "fadeOut": { "duration": 0.5 }
      }
    },
    {
      "type": "audio",
      "url": "https://example.com/voiceover-outro.mp3",
      "timing": {
        "startTime": 50,
        "endTime": 60
      },
      "effects": {
        "volume": 0.9,
        "fadeIn": { "duration": 0.5 },
        "fadeOut": { "duration": 0.5 }
      }
    }
  ]
}

Multiple Audio Tracks

Layer multiple audio tracks:

{
  "fileUrl": "https://example.com/video.mp4",
  "elements": [
    {
      "type": "audio",
      "url": "https://example.com/background-music.mp3",
      "timing": { "entireVideo": true },
      "effects": {
        "volume": 0.25,
        "fadeIn": { "duration": 2 },
        "fadeOut": { "duration": 3 }
      },
      "loop": true
    },
    {
      "type": "audio",
      "url": "https://example.com/ambient-nature.mp3",
      "timing": { "entireVideo": true },
      "effects": {
        "volume": 0.15
      },
      "loop": true
    },
    {
      "type": "audio",
      "url": "https://example.com/notification-sound.mp3",
      "timing": {
        "startTime": 30,
        "endTime": 31
      },
      "effects": {
        "volume": 0.6
      }
    }
  ]
}

Common Use Cases

Tutorial Background Music

Add subtle background music to tutorials:

{
  "type": "audio",
  "url": "https://cdn.example.com/calm-background.mp3",
  "timing": { "entireVideo": true },
  "effects": {
    "volume": 0.2,
    "fadeIn": { "duration": 3, "easing": "ease-in" },
    "fadeOut": { "duration": 4, "easing": "ease-out" }
  },
  "loop": true
}

Tutorial Tip: Keep background music volume low (0.15-0.25) so it doesn't compete with narration.

Transition Sound Effects

Add whoosh sounds for transitions:

{
  "type": "audio",
  "url": "https://cdn.example.com/whoosh.mp3",
  "timing": {
    "startTime": 10,
    "endTime": 10.5
  },
  "effects": {
    "volume": 0.5
  }
}

Intro Music

Add energetic music for the intro:

{
  "type": "audio",
  "url": "https://cdn.example.com/upbeat-intro.mp3",
  "timing": {
    "startTime": 0,
    "endTime": 8
  },
  "effects": {
    "volume": 0.6,
    "fadeOut": { "duration": 1.5, "easing": "ease-out" }
  }
}

Ambient Soundscape

Create an ambient audio environment:

{
  "elements": [
    {
      "type": "audio",
      "url": "https://cdn.example.com/rain-sounds.mp3",
      "timing": { "entireVideo": true },
      "effects": {
        "volume": 0.2
      },
      "loop": true
    },
    {
      "type": "audio",
      "url": "https://cdn.example.com/thunder.mp3",
      "timing": {
        "startTime": 15,
        "endTime": 18
      },
      "effects": {
        "volume": 0.4
      }
    }
  ]
}

Product Demo Music

Upbeat music for product demonstrations:

{
  "type": "audio",
  "url": "https://cdn.example.com/corporate-upbeat.mp3",
  "timing": { "entireVideo": true },
  "effects": {
    "volume": 0.35,
    "fadeIn": { "duration": 2 },
    "fadeOut": { "duration": 2 }
  },
  "loop": true
}

Podcast Background

Subtle background for podcasts:

{
  "type": "audio",
  "url": "https://cdn.example.com/podcast-ambient.mp3",
  "timing": { "entireVideo": true },
  "effects": {
    "volume": 0.1
  },
  "loop": true
}

Gaming Montage

Energetic music for gaming montages:

{
  "type": "audio",
  "url": "https://cdn.example.com/epic-gaming-music.mp3",
  "timing": { "entireVideo": true },
  "effects": {
    "volume": 0.5,
    "fadeIn": { "duration": 1, "easing": "ease-in" },
    "fadeOut": { "duration": 2, "easing": "ease-out" }
  },
  "loop": true
}

Sequential Sound Effects

Add multiple sound effects at different times:

{
  "elements": [
    {
      "type": "audio",
      "url": "https://cdn.example.com/pop.mp3",
      "timing": { "startTime": 5, "endTime": 5.3 },
      "effects": { "volume": 0.6 }
    },
    {
      "type": "audio",
      "url": "https://cdn.example.com/ding.mp3",
      "timing": { "startTime": 12, "endTime": 12.5 },
      "effects": { "volume": 0.7 }
    },
    {
      "type": "audio",
      "url": "https://cdn.example.com/swoosh.mp3",
      "timing": { "startTime": 20, "endTime": 20.8 },
      "effects": { "volume": 0.5 }
    }
  ]
}

Narration with Background Music

Combine narration and music with ducking effect:

{
  "elements": [
    {
      "type": "audio",
      "url": "https://cdn.example.com/background-music.mp3",
      "timing": { "entireVideo": true },
      "effects": {
        "volume": 0.15,
        "fadeIn": { "duration": 2 },
        "fadeOut": { "duration": 3 }
      },
      "loop": true
    },
    {
      "type": "audio",
      "url": "https://cdn.example.com/narration.mp3",
      "timing": {
        "startTime": 5,
        "endTime": 35
      },
      "effects": {
        "volume": 0.95,
        "fadeIn": { "duration": 0.5 },
        "fadeOut": { "duration": 0.5 }
      }
    }
  ]
}

Advanced Examples

Dynamic Music Intensity

Layer multiple tracks for building intensity:

{
  "elements": [
    {
      "type": "audio",
      "url": "https://cdn.example.com/bass-layer.mp3",
      "timing": { "entireVideo": true },
      "effects": { "volume": 0.3 },
      "loop": true
    },
    {
      "type": "audio",
      "url": "https://cdn.example.com/melody-layer.mp3",
      "timing": { "startTime": 10, "endTime": 60 },
      "effects": {
        "volume": 0.4,
        "fadeIn": { "duration": 2 }
      },
      "loop": true
    },
    {
      "type": "audio",
      "url": "https://cdn.example.com/drums-layer.mp3",
      "timing": { "startTime": 20, "endTime": 60 },
      "effects": {
        "volume": 0.35,
        "fadeIn": { "duration": 1.5 }
      },
      "loop": true
    }
  ]
}

Cinematic Audio Design

Create a rich cinematic soundscape:

{
  "elements": [
    {
      "type": "audio",
      "url": "https://cdn.example.com/orchestral-score.mp3",
      "timing": { "entireVideo": true },
      "effects": {
        "volume": 0.4,
        "fadeIn": { "duration": 3, "easing": "ease-in" },
        "fadeOut": { "duration": 5, "easing": "ease-out" }
      },
      "loop": true
    },
    {
      "type": "audio",
      "url": "https://cdn.example.com/wind-ambience.mp3",
      "timing": { "entireVideo": true },
      "effects": { "volume": 0.15 },
      "loop": true
    },
    {
      "type": "audio",
      "url": "https://cdn.example.com/dramatic-hit.mp3",
      "timing": { "startTime": 30, "endTime": 32 },
      "effects": { "volume": 0.7 }
    }
  ]
}

Scene-Based Audio

Different audio for different scenes:

{
  "elements": [
    {
      "type": "audio",
      "url": "https://cdn.example.com/scene1-music.mp3",
      "timing": { "startTime": 0, "endTime": 20 },
      "effects": {
        "volume": 0.4,
        "fadeIn": { "duration": 2 },
        "fadeOut": { "duration": 2 }
      }
    },
    {
      "type": "audio",
      "url": "https://cdn.example.com/scene2-music.mp3",
      "timing": { "startTime": 20, "endTime": 40 },
      "effects": {
        "volume": 0.4,
        "fadeIn": { "duration": 2 },
        "fadeOut": { "duration": 2 }
      }
    },
    {
      "type": "audio",
      "url": "https://cdn.example.com/scene3-music.mp3",
      "timing": { "startTime": 40, "endTime": 60 },
      "effects": {
        "volume": 0.4,
        "fadeIn": { "duration": 2 },
        "fadeOut": { "duration": 2 }
      }
    }
  ]
}

Best Practices

Volume Levels

Volume Guidelines for different audio types:

  • Background music with dialogue: 0.15-0.3
  • Background music without dialogue: 0.4-0.6
  • Sound effects: 0.5-0.8
  • Voiceovers/narration: 0.85-1.0
  • Ambient sounds: 0.1-0.25

Fade Transitions

Always use fades for professional-sounding audio:

{
  "effects": {
    "fadeIn": { "duration": 2, "easing": "ease-in" },
    "fadeOut": { "duration": 3, "easing": "ease-out" }
  }
}

Fade duration guidelines:

  • Quick transitions: 0.5-1 second
  • Standard fades: 2-3 seconds
  • Cinematic fades: 4-6 seconds
  • Subtle background: 1-2 seconds

Audio Mixing Strategy

Layer audio effectively:

  1. Base layer: Original video audio (dialogue, etc.)
  2. Background music: Volume 0.2-0.3
  3. Ambient sounds: Volume 0.1-0.2
  4. Sound effects: Volume 0.5-0.7
  5. Voiceover: Volume 0.9-1.0 (highest priority)

Example mix:

{
  "elements": [
    {
      "type": "audio",
      "url": "https://cdn.example.com/music.mp3",
      "effects": { "volume": 0.25 },
      "loop": true
    },
    {
      "type": "audio",
      "url": "https://cdn.example.com/ambient.mp3",
      "effects": { "volume": 0.15 },
      "loop": true
    },
    {
      "type": "audio",
      "url": "https://cdn.example.com/voiceover.mp3",
      "effects": { "volume": 0.95 }
    }
  ]
}

File Optimization

Optimize audio files:

  • Use MP3 at 128-192 kbps for music
  • Use MP3 at 96-128 kbps for speech
  • Use WAV for highest quality (larger files)
  • Normalize audio levels before uploading
  • Remove silence from beginning/end

Loop Considerations

When to loop:

  • Background music longer than video
  • Ambient soundscapes
  • Short music beds
  • Continuous effects

When not to loop:

  • Voiceovers
  • One-time sound effects
  • Music that matches video duration
  • Narrative audio

Timing Synchronization

Sync audio with visual content:

{
  "elements": [
    {
      "type": "audio",
      "url": "https://cdn.example.com/impact-sound.mp3",
      "timing": { "startTime": 15.2, "endTime": 15.8 }
    }
  ]
}

Use precise timing (to tenths of seconds) for sound effects.

Performance Tips

Keep file sizes reasonable:

  • Compress audio files appropriately
  • Use lower bitrates for background elements
  • Limit the number of simultaneous audio tracks
  • Pre-normalize audio levels

Quality Guidelines

Audio quality checklist:

  • ✅ Consistent volume levels across tracks
  • ✅ Appropriate fade in/out transitions
  • ✅ No audio clipping or distortion
  • ✅ Clear dialogue/narration
  • ✅ Balanced mix (no single element dominates)

Troubleshooting

Audio Not Playing

Check these issues:

  1. URL is publicly accessible (test in browser)
  2. Audio format is supported (MP3, WAV, etc.)
  3. Timing is within video duration
  4. Volume is not 0
  5. Audio file is not corrupted

Audio Too Quiet or Loud

Solutions:

{
  "effects": {
    "volume": 0.4
  }
}

Adjust volume level. Remember: values are 0-1.

Audio Pops or Clicks

Causes:

  • Missing fade transitions
  • Abrupt starts/stops
  • Volume too high

Solutions:

{
  "effects": {
    "fadeIn": { "duration": 0.5 },
    "fadeOut": { "duration": 0.5 }
  }
}

Audio Doesn't Loop

Check:

{
  "loop": true
}

Also verify timing duration is longer than audio duration.

Audio Clips or Distorts

Solutions:

  • Reduce volume: "volume": 0.6 instead of 1.0
  • Normalize audio file before uploading
  • Check source audio isn't already clipping
  • Reduce number of simultaneous audio tracks

Multiple Audio Tracks Too Loud

When mixing multiple tracks, reduce individual volumes:

{
  "elements": [
    {
      "type": "audio",
      "url": "https://cdn.example.com/track1.mp3",
      "effects": { "volume": 0.3 }
    },
    {
      "type": "audio",
      "url": "https://cdn.example.com/track2.mp3",
      "effects": { "volume": 0.25 }
    }
  ]
}

Combined volume should not exceed ~1.0 total.

Audio Resources

Finding Royalty-Free Music

Popular sources:

  • Epidemic Sound - Large music library
  • Artlist - Curated music for creators
  • AudioJungle - One-time purchase tracks
  • YouTube Audio Library - Free music
  • Free Music Archive - Creative Commons music

Sound Effects Libraries

  • Freesound - Community sound effects
  • Zapsplat - Free sound effects
  • Soundsnap - Professional sound library
  • BBC Sound Effects - Archive of effects

Copyright Notice: Always ensure you have proper licensing for any audio you use. Check usage rights and attribution requirements.

Next Steps

Image Overlays

Add static image overlays and watermarks

GIF Overlays

Add animated GIF stickers and reactions

Video Overlays

Create picture-in-picture effects

Audio Processing

Learn about audio normalization and silence removal

Video Overlays

Add picture-in-picture, B-roll, and video element overlays to your videos

AI Video Analysis

Automated video content analysis for tags, summaries, and location detection

On this page

Audio Element StructureRequired PropertiesOptional PropertiesSupported FormatsTiming ConfigurationEntire VideoTime RangeFrom StartAudio EffectsVolume ControlFade InFade OutCombined EffectsEasing FunctionsLoop PropertyLoop Disabled (Default)Loop EnabledComplete ExamplesBackground MusicSound EffectVoiceoverMultiple Audio TracksCommon Use CasesTutorial Background MusicTransition Sound EffectsIntro MusicAmbient SoundscapeProduct Demo MusicPodcast BackgroundGaming MontageSequential Sound EffectsNarration with Background MusicAdvanced ExamplesDynamic Music IntensityCinematic Audio DesignScene-Based AudioBest PracticesVolume LevelsFade TransitionsAudio Mixing StrategyFile OptimizationLoop ConsiderationsTiming SynchronizationPerformance TipsQuality GuidelinesTroubleshootingAudio Not PlayingAudio Too Quiet or LoudAudio Pops or ClicksAudio Doesn't LoopAudio Clips or DistortsMultiple Audio Tracks Too LoudAudio ResourcesFinding Royalty-Free MusicSound Effects LibrariesNext Steps