VideoDB Documentation
VideoDB Documentation
Build with VideoDB

icon picker
Audio overlay + Video + Timeline

💬 Overview

Welcome to the groovy world of audio overlays with VideoDB! 🎶 In this tutorial, we're going to add audio overlays to your video assets. Picture this 👉🏼 you've got your video content all set, but it's missing that extra oomph 🎧. That's where audio overlays come handy.
With VideoDB's easy-to-use feature, you can seamlessly weave in background music, voiceovers, or funky sound effects, transforming your videos from ordinary to extraordinary. Let's crank up the volume and get ready to rock and roll 🔉

audio overlay.png


📦 Installing packages

%pip install videodb

🔑 API Keys

Before proceeding, ensure access to
Get your API key from . ( Free for first 50 uploads, No credit card required ) 🎉
import os

os.environ["VIDEO_DB_API_KEY"] = ""


🌐 Step 1: Connect to VideoDB

Connect to VideoDB to establish a session for uploading and manipulating video files. Import the necessary modules from VideoDB library to access functionalities.
from videodb import connect

conn = connect()
coll = conn.get_collection()

🎥 Step 2: Upload Video

Upload the video to VideoDB collection. You can upload the video asset from your local device or from a YouTube URL to upload the video from its source.
video = coll.upload(url="")
You can upload from your local file system too by passing file_path in upload()

Here’s the video we’ll be using for this tutorial:

🎥 Step 3: Upload Audio

Upload the audio file to VideoDB collection. You can upload the audio asset from your local device or from a YouTube URL to upload the audio from its source. Make sure to mention media_type if you want to use audio track of a video.
audio = coll.upload(url="", media_type="audio")

🎼 Step 4: Create assets

Create assets for Audio and Video using AudioAsset and VideoAsset class
from videodb.asset import VideoAsset, AudioAsset

video_asset = VideoAsset(,

audio_asset = AudioAsset(, start=0, end=181, fade_out_duration=0, disable_other_tracks= True)

🎼 Step 5: Create a Timeline

Finally, add audio as an overlay to the video using VideoDB's timeline feature.
Add the main video asset inline and overlay audio assets onto the timeline. Generate a stream URL for the timeline, incorporating all assets and overlays, for playback or further processing.
from videodb.timeline import Timeline

# create a new timeline
timeline = Timeline(conn)

# add the main video inline

# add asset overlay
timeline.add_overlay(start=0, asset=audio_asset)

🪄 Final Step: Review and Share

Preview the video with the integrated voiceover to ensure it functions correctly. Once satisfied, generate a stream of the video and share the link for others to view and enjoy this wholesome creation!
from videodb import play_stream

stream = timeline.generate_stream()

🎉 Conclusion

And there you have it, folks! We've unlocked the door to audio awesomeness with VideoDB's audio overlay feature. By seamlessly integrating background music, voiceovers, or sound effects into your videos, you're not just adding layers of sound – you're adding layers of engagement, emotion, and excitement! 🎬🎧
For more pulse-pounding adventures and support, refer to the and join the VideoDB community on or for support and collaboration.
In the meanwhile, check out the other exciting outputs generated using this tutorial and share yours in our too! We’d love to feature you here ⚡️

More Examples

Checkout these fun experiments with Audio Assets 👇

Easy integrations with GenAI tools: Sora videos with music.
Enhance the ambiance of Sora's Tokyo journey with VideoDB's Programmable Streams feature.

Re-imagining context based audio overlays
Immerse yourself in the world of Dune with VideoDB's dynamic overlay, enhancing the trailer with captivating audiovisual elements that transport you to the heart of Arrakis.

Creating synced assets for visual and audio media
Explore stunning landscapes through captivating drone footage, elevated by VideoDB's integrated overlay feature, harmonizing visuals and audio for a mesmerizing viewing experience.

Add emotional depth to narration via mood-based music overlays
Ignite your motivation with VideoDB's seamless overlay, blending inspirational visuals and stirring audio effortlessly. Let every word resonate deeply as you embark on your journey to success.

Different videos require different ambience- this should make it easy!
Achieve mindfulness and relaxation with VideoDB's integrated overlay, merging serene visuals and soothing audio for a harmonious yoga experience tailored to your needs.

Want to print your doc?
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
) instead.