ATH-MaaS/Pixelle-Video · error · RuntimeError

Failed to add audio to video: {error_msg}

Error message

Failed to add audio to video: {error_msg}

What it means

merge_audio_video adds an audio track to a video that has no audio stream using ffmpeg. When that ffmpeg invocation raises ffmpeg.Error, the handler decodes stderr and re-raises it as this RuntimeError. The root cause is always in the FFmpeg stderr text.

Source

Thrown at pixelle_video/services/video.py:460

                    ffmpeg
                    .output(
                        video_stream,
                        audio_stream,
                        output,
                        vcodec='libx264',  # Re-encode video if padded
                        acodec='aac',
                        audio_bitrate='192k'
                    )
                    .overwrite_output()
                    .run(capture_stdout=True, capture_stderr=True)
                )
                
                logger.success(f"Audio added to silent video: {output}")
                return output
            except ffmpeg.Error as e:
                error_msg = e.stderr.decode() if e.stderr else str(e)
                logger.error(f"FFmpeg error adding audio to silent video: {error_msg}")
                raise RuntimeError(f"Failed to add audio to video: {error_msg}")
        
        # Video has audio, proceed with merging
        logger.info(f"Merging audio with video (replace={replace_audio})")
        
        try:
            if replace_audio:
                # Replace audio: use only new audio, ignore original
                (
                    ffmpeg
                    .output(
                        video_stream,
                        audio_stream,
                        output,
                        vcodec='libx264',  # Re-encode video if padded
                        acodec='aac',
                        audio_bitrate='192k'
                    )
                    .overwrite_output()

View on GitHub (pinned to 848b054e4f)

Solutions

1. Read the FFmpeg stderr in the message — it names the failing stream or codec.
2. Verify the audio file exists, is non-empty, and ffprobe reports a valid audio stream.
3. Re-encode the audio to aac 44.1kHz stereo mp4/m4a before merging.
4. Confirm the ffmpeg build includes the needed decoders/encoders (`ffmpeg -codecs | grep aac`).

Example fix

// before
service.merge_audio_video(silent.mp4, 'voice.opus', 'out.mp4')  # decoder error
// after
convert_audio('voice.opus', 'voice.m4a', codec='aac')
service.merge_audio_video(silent.mp4, 'voice.m4a', 'out.mp4')

import ffmpeg
assert os.path.isfile(audio) and os.path.getsize(audio) > 0
probe = ffmpeg.probe(audio)
assert any(s.get('codec_type') == 'audio' for s in probe['streams']), 'no audio stream'

def has_audio_stream(path: str) -> bool:
    try:
        return any(s.get('codec_type') == 'audio' for s in ffmpeg.probe(path)['streams'])
    except Exception:
        return False

try:
    service.merge_audio_video(video, audio, out)
except RuntimeError as e:
    if 'Failed to add audio to video' in str(e):
        logger.error(f'audio mux failed: {e}')
        # re-encode audio to aac and retry
    else:
        raise

When it happens

Trigger: Silent video + audio file where the audio file is missing, corrupt, or in a format ffmpeg cannot decode; mismatched sample rates/codecs requiring -ar/-ac flags the call does not set; the silent video itself was produced incorrectly.

Common situations: TTS output saved with a wrong extension or zero bytes; audio in an exotic container (e.g. opus in webm) not supported by the ffmpeg build; inputs from different pipelines with incompatible audio encoders.

Related errors

• Failed to merge audio and video: {error_msg}
• Failed to add BGM: {error_msg}
• str(e)
• 参考音频不存在: {reference_audio_path}
• 驱动音频不存在: {audio_path}

AI-assisted analysis of ATH-MaaS/Pixelle-Video@848b054e4f (2026-08-30). Data as JSON: /api/errors/93f7c73cf5a188b8. Report an issue: GitHub.