Background Music

The .backgroundMusic() stage adds a music track to your video. The music automatically ducks (lowers volume) during voiceover segments and fades out at the end.

Basic usage

await Recast
  .from('./traces')
  .parse()
  .subtitlesFromSrt('./narration.srt')
  .voiceover(OpenAIProvider({ voice: 'nova' }))
  .backgroundMusic({ path: './music/background.mp3' })
  .render({ format: 'mp4' })
  .toFile('demo.mp4')

Configuration options

Full example

.backgroundMusic({
  path: './music/ambient.mp3',
  volume: 0.25,
  ducking: true,
  duckLevel: 0.08,
  duckFadeMs: 600,
  fadeOutMs: 3000,
  loop: true,
})

Auto-ducking

When ducking is enabled (the default), the music volume drops to duckLevel whenever voiceover audio is playing. The transition uses a smooth fade over duckFadeMs milliseconds. This keeps the narration clear without manually adjusting levels.

To disable ducking and keep music at a fixed volume throughout:

.backgroundMusic({
  path: './music/background.mp3',
  ducking: false,
  volume: 0.15,
})

Coverage

Background music covers the full output duration, including Intro and Outro segments. The music track is mixed as a post-processing step after intro/outro assembly.

Tips

• Music is looped by default. If your track is shorter than the video, it repeats seamlessly. Set loop: false if your track is already the right length.
• The fade-out starts fadeOutMs before the end of the video and reaches silence at the last frame.
• Keep volume low (0.2-0.3) when used with voiceover. The ducking ensures narration is audible, but a lower base volume gives a more polished feel.
• Background music works without voiceover too — set ducking: false for a fixed-volume music bed.