Trailer Narration

Introduction

Narration is the heartbeat of trailers, injecting excitement and intrigue into every frame. With VideoDB, adding narration becomes a seamless, creative process. In this tutorial, we will:

Analyze a movie trailer to understand its scenes.
Generate a dramatic script using VideoDB’s text generation.
Synthesize a deep, trailer-style voiceover using VideoDB’s voice generation.
Edit the narration into specific time slots to match the video’s pacing.
Overlay a movie poster at the end.

All using a single SDK. Here’s an example of weaving a thrilling storyline from a reel of unrelated, but valuable cinematic shots:

Setup

Installing VideoDB

!pip install videodb

API Keys

You only need your VideoDB API Key. Get your API key from VideoDB Console. Free for first 50 uploads, no credit card required.

Step 1: Connect to VideoDB

Establish a connection to your VideoDB project.

import videodb

# Set your API key
api_key = "your_api_key"

# Connect to VideoDB
conn = videodb.connect(api_key=api_key)
coll = conn.get_collection()

import { connect } from 'videodb';

// Connect to VideoDB
const conn = await connect({ apiKey: process.env.VIDEO_DB_API_KEY });
const coll = await conn.getCollection();

Step 2: Upload the Trailer

We’ll upload a sample movie trailer (Chase) to VideoDB. This creates the base video asset we will edit.

video = coll.upload(url='https://www.youtube.com/watch?v=WQmGwmc-XUY')

const video = await coll.uploadURL({ url: 'https://www.youtube.com/watch?v=WQmGwmc-XUY' });

Step 3: Analyze Scenes

We need to understand the visual pacing of the trailer to write a good script. index_scenes() will generate descriptions and timestamps for every shot.

video_scenes_id = video.index_scenes()

const videoScenesId = await video.indexScenes();

Let’s view the description of first scene from the video

video_scenes = video.get_scene_index(video_scenes_id)

import json
print(json.dumps(video_scenes[0], indent=2))

const videoScenes = await video.getSceneIndex(videoScenesId);

console.log(JSON.stringify(videoScenes[0], null, 2));

Output:

{
  "description": "The scene is engulfed in a vast, tumultuous blaze, with vibrant yellow and fiery orange flames swirling and dancing across the entire frame. The intense heat radiating from the inferno creates a mesmerizing, dynamic spectacle, casting a reddish-brown glow that fills the atmosphere. Darker, smoky elements are intermittently visible through the brilliant light, suggesting objects being consumed within the heart of this powerful, destructive force. The fire is alive, constantly shifting and reaching, conveying both destructive power and captivating motion.",
  "end": 1.043,
  "metadata": {},
  "scene_metadata": {},
  "start": 0.0
}

Step 4: Generate Narration Script

We’ll use VideoDB’s generate_text to write a dramatic script. We feed the scene descriptions into the prompt to ensure the narration matches the visual action.

# Construct prompt with scene context
scene_context = "\n".join([f"- {scene['description']}" for scene in video_scenes])

prompt = f"""
Craft a dynamic, dramatic narration script for a movie trailer based on these visual descriptions:
{scene_context}

Requirements:
- Style: Intense, gritty, like a blockbuster action movie trailer.
- Output: Only provide the script for direct voice generation, no stage directions or narration.
"""

script_response = coll.generate_text(
    prompt=prompt,
    model_name="pro")

script_text = script_response["output"]

print("--- Generated Script ---")
print(script_text)

// Construct prompt with scene context
const sceneContext = videoScenes.map(scene => `- ${scene.description}`).join('\n');

const prompt = `
Craft a dynamic, dramatic narration script for a movie trailer based on these visual descriptions:
${sceneContext}

Requirements:
- Style: Intense, gritty, like a blockbuster action movie trailer.
- Output: Only provide the script for direct voice generation, no stage directions or narration.
`;

const scriptResponse = await coll.generateText(
    prompt,
    "pro"
);

const scriptText = scriptResponse.output;

console.log("--- Generated Script ---");
console.log(scriptText);

You can refine the narration script prompt to ensure synchronization with timestamps in the scene index, optimizing the storytelling experience.

Step 5: Generate Voiceover Audio

Now we synthesize the audio.

# Generate speech directly as an Audio Asset
audio = coll.generate_voice(
    text=script_text,
    voice_name="Brian")

print(f"Generated Audio ID: {audio.id}")

// Generate speech directly as an Audio Asset
const audio = await coll.generateVoice(
    scriptText,
    "Brian"
);

console.log(`Generated Audio ID: ${audio.id}`);

Step 6: Edit the Timeline

Now we combine the video and audio.

from videodb.editor import Timeline, Track, Clip, VideoAsset, AudioAsset

timeline = Timeline(conn)

# --- 1. Main Video Track ---
main_track = Track()
video_asset = VideoAsset(id=video.id, volume=0.5)
video_clip = Clip(asset=video_asset, duration=float(video.length))
main_track.add_clip(0, video_clip)
timeline.add_track(main_track)

# --- 2. Narration Track---
audio_track = Track()
audio_asset1 = AudioAsset(id=audio.id, start=0, volume=2.0)
audio_clip1 = Clip(asset=audio_asset1, duration=float(audio.length))
audio_track.add_clip(4, audio_clip1)

timeline.add_track(audio_track)

import { EditorTimeline, Track, Clip, EditorVideoAsset, EditorAudioAsset } from 'videodb';

const timeline = new EditorTimeline(conn);

// --- 1. Main Video Track ---
const mainTrack = new Track();
const videoAsset = new EditorVideoAsset({ id: video.id, volume: 0.5 });
const videoClip = new Clip({ asset: videoAsset, duration: parseFloat(video.length) });
mainTrack.addClip(0, videoClip);
timeline.addTrack(mainTrack);

// --- 2. Narration Track ---
const audioTrack = new Track();
const audioAsset1 = new EditorAudioAsset({ id: audio.id, start: 0, volume: 2.0 });
const audioClip1 = new Clip({ asset: audioAsset1, duration: parseFloat(audio.length) });
audioTrack.addClip(4, audioClip1);

timeline.addTrack(audioTrack);

Preview the trailer with the integrated narration to ensure it aligns with your vision. Once satisfied, share the trailer with others to experience the enhanced storytelling.

from videodb import play_stream

stream_url = timeline.generate_stream()
play_stream(stream_url)

const streamUrl = await timeline.generateStream();
console.log(streamUrl);

Bonus - Add Movie Poster

Let’s add a “Coming Soon” style movie poster at the very end of the trailer. We’ll upload an image URL and overlay it on the video.

from videodb import MediaType

# Upload movie poster
poster_url = "https://img.freepik.com/free-photo/darkly-atmospheric-retail-environment-rendering_23-2151153755.jpg"
image = coll.upload(url=poster_url, media_type=MediaType.image)

import { MediaType } from 'videodb';

// Upload movie poster
const posterUrl = "https://img.freepik.com/free-photo/darkly-atmospheric-retail-environment-rendering_23-2151153755.jpg";
const image = await coll.uploadURL({ url: posterUrl, mediaType: MediaType.image });

from videodb.editor import ImageAsset

# Create an overlay track for the poster
image_track = Track()

# Show poster at the 10 seconds of the trailer
image_asset = ImageAsset(id=image.id)
image_clip = Clip(
    asset=image_asset,
    duration=10.0,
    fit="contain")

image_track.add_clip(float(video.length) - 10, image_clip)
timeline.add_track(image_track)

stream_url = timeline.generate_stream()
play_stream(stream_url)

import { EditorImageAsset } from 'videodb';

// Create an overlay track for the poster
const imageTrack = new Track();

// Show poster at the 10 seconds of the trailer
const imageAsset = new EditorImageAsset({ id: image.id });
const imageClip = new Clip({
    asset: imageAsset,
    duration: 10.0,
    fit: "contain"
});

imageTrack.addClip(parseFloat(video.length) - 10, imageClip);
timeline.addTrack(imageTrack);

const finalStreamUrl = await timeline.generateStream();
console.log(finalStreamUrl);

Conclusion

You’ve successfully built a sophisticated video editing workflow:

Analysis: Automated scene understanding.
Generation: AI Scripting and Voice synthesis.
Composition: Non-linear editing with multi-track audio and image overlays.

Here’s another interesting experiment to generate automatic voiceovers for silent footages. In this example, we’ve added the classic David Attenborough styled documentary narration to this footage of the underwater world. Check out the complete tutorial here

Explore Full Notebook

Open the complete implementation in Google Colab with all code examples.

AI Voiceovers

Add professional narration to silent footage

Voice Cloning

Clone voices for consistent brand audio

Overview

Agentic Workflows

Video Search and Understanding

Live Intelligence

Content Factory

Programmatic Editing

Safety & Compliance

Introduction

Setup

Installing VideoDB

API Keys

Step 1: Connect to VideoDB

Step 2: Upload the Trailer

Step 3: Analyze Scenes

Step 4: Generate Narration Script

Step 5: Generate Voiceover Audio

Step 6: Edit the Timeline

Bonus - Add Movie Poster

Conclusion

Explore Full Notebook

AI Voiceovers

Voice Cloning

​Introduction

​Setup

​Installing VideoDB

​API Keys

​Step 1: Connect to VideoDB

​Step 2: Upload the Trailer

​Step 3: Analyze Scenes

​Step 4: Generate Narration Script

​Step 5: Generate Voiceover Audio

​Step 6: Edit the Timeline

​Step 7: Review and Share

​Bonus - Add Movie Poster

​Conclusion

Explore Full Notebook

​Related Tutorials

AI Voiceovers

Voice Cloning

Introduction

Setup

Installing VideoDB

API Keys

Step 1: Connect to VideoDB

Step 2: Upload the Trailer

Step 3: Analyze Scenes

Step 4: Generate Narration Script

Step 5: Generate Voiceover Audio

Step 6: Edit the Timeline

Step 7: Review and Share

Bonus - Add Movie Poster

Conclusion

Related Tutorials