Sunday, 31 August 2025

How to merge audio in MoviePy

Merging audio in MoviePy can be done in several ways depending on your needs. Here are the most common methods with detailed examples:

1. Concatenate audio clips (play one after another)

Method A: Using concatenate_audioclips()

First, use the function AudioFileClip() to load the audio files. Then use the function concatenate_audioclips() to merge the audio files one after another.

from moviepy import AudioFileClip, concatenate_audioclips

# Load audio files
audio1 = AudioFileClip("data/audio_part_0.mp3")
audio2 = AudioFileClip("data/audio_part_1.mp3")
audio3 = AudioFileClip("data/audio_part_2.mp3")

# Concatenate them
final_audio = concatenate_audioclips([audio1, audio2, audio3])

# Save the result
final_audio.write_audiofile("data/combined_audio.mp3")

Method B: Using + Operator (Shortcut)

Alternatively, we can use the + operator to do the same thing.

final_audio = audio1 + audio2 + audio3
final_audio.write_audiofile("data/combined_audio.mp3")

2. Overlay audio (Play simultaneously)

Method A: Using the function CompositeAudioClip()

We can add background music to a voice by using the function CompositeAudioClip(). The function with_effects() can be used to adjust volumes before mixing the audio.

from moviepy import AudioFileClip, afx, CompositeAudioClip

# Load audio files
background_music = AudioFileClip("data/background.mp3")
voice_over = AudioFileClip("data/voice.mp3")

# Adjust volumes if needed
# 30% volume
background_music = background_music.with_effects([afx.MultiplyVolume(0.3)])
# 120% volume
voice_over = voice_over.with_effects([afx.MultiplyVolume(1.2)])

# Overlay them (both play at the same time)
final_audio = CompositeAudioClip([background_music, voice_over])

# Save result
final_audio.write_audiofile("data/mixed_audio.mp3")

Method B: Attaching background music to video

In this example, we can add background music to the original video audio and assign this mixed audio to the original video clip. By default, the write_videofile() function does not attach sound to a video, as its audio_codec parameter is set to None. When saving this new video to a file, make sure to set the audio_codec as aac in the function write_videofile(). AAC, or Advanced Audio Coding, is a lossy audio compression format designed to be the successor of MP3. It offers better sound quality at the same bitrate, making it the standard for many modern applications.

from moviepy import VideoFileClip, AudioFileClip, afx, CompositeAudioClip

# Load video and audio
video = VideoFileClip("data/my-video.mp4")
background_music = AudioFileClip("data/background.mp3")

# Create composite audio (original video audio + background music)
mixed_audio = CompositeAudioClip([
    # Original audio at 80% volume
    video.audio.with_effects([afx.MultiplyVolume(0.8)]), 
    # Background music at 40% volume
    background_music.with_effects([afx.MultiplyVolume(0.4)])  
])

# Apply the mixed audio to video
video.audio = mixed_audio

# Save the result
# set audio_codec as aac to attach sound to the video
video.write_videofile("data/video_with_background_music.mp4", audio_codec="aac")

3. Crossfade between audio clips

In this example, we will create a crossfaded audio from two audio clips. The first audio fades out in the last 2 seconds and the second audio fades in over the first 2 seconds. Before calling the function CompositeAudioClip(), we need define the second audio clip's start time at which it starts at 2 seconds before the first audio ends in the composition. Therefore, the function with_start() is used to set audio2's start time.

from moviepy import AudioFileClip, afx, CompositeAudioClip

# Load audio files
audio1 = AudioFileClip("data/audio1.mp3")
audio2 = AudioFileClip("data/audio2.mp3")

# Add crossfade (2-second overlap)
# Fade out last 2 seconds
audio1 = audio1.with_effects([afx.AudioFadeOut(2)])
# Fade in first 2 seconds
audio2 = audio2.with_effects([afx.AudioFadeIn(2)])

# Define audio2's start time in the composition at which audio2 starts.
# audio1 and audio2 have 2-second overlap
audio2 = audio2.with_start(audio1.end - 2)

# Create the crossfaded audio
crossfaded_audio = CompositeAudioClip([
    audio1, # Starts at 0s
    audio2  # Starts at 2 seconds before audio1 ends
    ])

crossfaded_audio.write_audiofile("data/crossfaded_audio.mp3")

4. Merge multiple audio tracks with time offsets

We can also use the function CompositeAudioClip() to merge multiple audio tracks. With each audio clip's function with_start(), we can set different time offsets in the composition.

from moviepy import AudioFileClip, CompositeAudioClip

# Load audio files
main_track = AudioFileClip("data/audio_main.mp3")
sound_effect = AudioFileClip("data/background.mp3")
voice = AudioFileClip("data/voice.mp3")

# Set start times for each track
sound_effect = sound_effect.with_start(5)  # Start at 5 seconds
voice = voice.with_start(10)               # Start at 10 seconds

# Create composite with timing
final_audio = CompositeAudioClip([
    main_track,    # Starts at 0s
    sound_effect,  # Starts at 5s  
    voice          # Starts at 10s
    ])

final_audio.write_audiofile("data/timed_audio.mp3")