Skip to main content

Audio Elements

Complete reference for audio elements in the Zvid Package, including background music, sound effects, and audio synchronization.

Overview​

Audio elements allow you to add background music, sound effects, voiceovers, and other audio content to your videos. They support precise timing control, volume management, speed adjustment, and multi-track audio mixing.

AudioItem Interface​

interface AudioItem {
  src: string;
  audioBegin?: number;
  audioEnd?: number;
  audioDuration?: number;
  volume?: number;
  speed?: number;
  track?: number;
  enter?: number;
  exit?: number;
  type?: string;
}

Properties​

Required Properties​

PropertyTypeDescription
srcstringAudio file path or URL

Audio Timing Properties​

PropertyTypeDefaultDescription
audioBeginnumber0Start position in audio file (seconds)
audioEndnumberSource durationEnd position in audio file (seconds)
audioDurationnumberSource durationTotal duration of audio file

Project Timeline Properties​

PropertyTypeDefaultDescription
enternumber0Start time in project timeline (seconds)
exitnumberproject.durationEnd time in project timeline (seconds)

Audio Control Properties​

PropertyTypeDefaultDescription
volumenumber1Audio volume (0-1, can exceed 1 for amplification)
speednumber1Playback speed multiplier
tracknumber0Audio track index for mixing

Metadata Properties​

PropertyTypeDefaultDescription
typestring"AUDIO"Element type identifier

Basic Examples​

Background Music​

{
  src: "https://cdn.pixabay.com/audio/2025/03/19/audio_56ae1dae5f.mp3",
  volume: 0.3,
  enter: 0,
  exit: 10
}

Sound Effect​

{
  src: "https://cdn.pixabay.com/audio/2025/01/13/audio_c2af364af2.mp3",
  volume: 0.8,
  enter: 2,
  exit: 4,
  track: 1
}

Advanced Examples​

Multiple Audio Tracks​

// Background music (track 0)
{
    src: "https://cdn.pixabay.com/audio/2025/04/21/audio_ed6f0ed574.mp3",
    volume: 0.3,
    enter: 0,
    exit: 30,
},
// Sound effects (track 1)
{
    src: "https://cdn.pixabay.com/audio/2024/08/26/audio_41d6f09cb8.mp3",
    volume: 0.6,
    enter: 5,
    exit: 7,
},
// Background music (track 2)
{
    src: "https://cdn.pixabay.com/audio/2025/02/03/audio_502e27ab2b.mp3",
    volume: 0.9,
    enter: 30,
    exit: 60,
}

Audio Segment Selection​

{
  src: "https://cdn.pixabay.com/audio/2025/04/21/audio_ed6f0ed574.mp3",
  audioBegin: 10,    // Start at 1 minute
  audioEnd: 20,     // End at 2 minutes
  volume: 0.5,
  enter: 0,
  exit: 10,          // Use 1-minute segment in 1-minute video
}

Speed-Modified Audio​

{
  src: "https://cdn.pixabay.com/audio/2025/05/20/audio_ec1f11ca43.mp3",
  speed: 1.2,        // 20% faster (higher pitch)
  volume: 0.8,
  enter: 0,
  exit: 10,          // Original 30s audio plays in 25s
}

Audio Timing Explained​

Source Audio Timing​

  • audioBegin: Start point in the source audio file
  • audioEnd: End point in the source audio file
  • audioDuration: Total length of the source audio file
// Play seconds 30-90 from a 3-minute audio file
{
  audioBegin: 30,
  audioEnd: 90,
  audioDuration: 180
}

Project Timeline Timing​

  • enter: When audio starts in project timeline
  • exit: When audio ends in project timeline
// Audio plays from 5s to 25s in the project
{
  enter: 5,
  exit: 25
}

Timing Coordination​

// Use 20 seconds of audio (from 10s-30s in source)
// playing from 5s-25s in project timeline
{
  src: "audio.mp3",
  audioBegin: 10,
  audioEnd: 30,
  audioDuration: 60,
  enter: 5,
  exit: 25
}

Volume and Mixing​

Volume Levels​

{
  volume: 0,     // Muted
  volume: 0.1,   // Very quiet (10%)
  volume: 0.3,   // Background music level
  volume: 0.5,   // Medium volume
  volume: 0.8,   // Prominent audio
  volume: 1.0,   // Full volume
  volume: 1.5    // Amplified (may cause distortion)
}

Speed and Pitch Control​

Speed Effects​

// Slow motion audio (lower pitch)
{
  src: "speech.mp3",
  speed: 0.8,    // 80% speed
  volume: 0.8
},
// Fast audio (higher pitch)
{
  src: "music.mp3",
  speed: 1.25,   // 125% speed
  volume: 0.5
},
// Chipmunk effect
{
  src: "voice.mp3",
  speed: 1.8,    // 180% speed
  volume: 0.7
}

Supported Audio Formats​

All FFMPEG Audio formats are supported, For Example:

Input Formats​

  • MP3 - Most common, good compression
  • WAV - Uncompressed, high quality
  • AAC - Modern compression, good quality
  • OGG - Open source format
  • M4A - Apple format, good quality

Quality Recommendations​

  • Music: 128-320 kbps MP3 or AAC
  • Speech: 64-128 kbps MP3
  • Sound Effects: 128-192 kbps MP3
  • High Quality: WAV or high-bitrate AAC

Best Practices​

Audio Design​

  1. Volume Balance: Keep background music 20-40% of speech volume
  2. Dynamic Range: Use different volume levels for different content types
  3. Fade Handling: Plan audio timing to allow for natural fades
  4. Track Organization: Use consistent track numbering system

Performance Optimization​

  1. File Size: Compress audio appropriately for use case
  2. Format Selection: Use MP3 for most cases, WAV for high quality needs
  3. Segment Selection: Use audioBegin/audioEnd to avoid loading entire files
  4. Caching: URLs are cached automatically for better performance

Technical Guidelines​

  1. Sample Rate: 44.1kHz is standard for most content
  2. Bit Depth: 16-bit is sufficient for most applications
  3. Mono vs Stereo: Use mono for speech, stereo for music
  4. Normalization: Normalize audio levels before use

Common Patterns​

Background Music​

{
  src: "background-music.mp3",
  volume: 0.3,
  enter: 0,
  exit: 60,  // Full video duration
}

Sound Effects Library​

// Transition sound
{
  src: "transition.mp3",
  volume: 0.5,
  enter: 10,
  exit: 11,
},
// Success sound
{
  src: "success.mp3",
  volume: 0.7,
  enter: 25,
  exit: 27,
},
// Alert sound
{
  src: "alert.mp3",
  volume: 0.8,
  enter: 40,
  exit: 42,
}

Narration with Music​

// Background music (ducked during speech)
{
  src: "music1.mp3",
  volume: 0.4,
  enter: 0,
  exit: 5,    // Full volume intro
},
{
  src: "music2.mp3",
  audioBegin: 5,
  volume: 0.15, // Reduced during speech
  enter: 5,
  exit: 55,
},
{
  src: "music3.mp3",
  audioBegin: 55,
  volume: 0.4,  // Full volume outro
  enter: 55,
  exit: 60,
},
// Narration
{
  src: "narration.mp3",
  volume: 0.9,
  enter: 5,
  exit: 55,
}

Troubleshooting​

Common Issues​

  1. Audio Not Playing: Check file format and URL accessibility
  2. Volume Too Low/High: Adjust volume levels and check source audio
  3. Timing Issues: Verify enter/exit times and audio segment selection
  4. Quality Problems: Check source audio quality and compression

Performance Tips​

  1. Preload: Popular audio files are cached automatically
  2. Compression: Use appropriate compression for content type
  3. Segmentation: Use audio segments instead of full files when possible
  4. Testing: Test audio levels across different playback devices

Next Steps​