{"record":{"id":"93f7c73cf5a188b8","repo":"ATH-MaaS/Pixelle-Video","slug":"failed-to-add-audio-to-video-error-msg","errorCode":null,"errorMessage":"Failed to add audio to video: {error_msg}","messagePattern":"Failed to add audio to video: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"pixelle_video/services/video.py","lineNumber":460,"sourceCode":"                    ffmpeg\n                    .output(\n                        video_stream,\n                        audio_stream,\n                        output,\n                        vcodec='libx264',  # Re-encode video if padded\n                        acodec='aac',\n                        audio_bitrate='192k'\n                    )\n                    .overwrite_output()\n                    .run(capture_stdout=True, capture_stderr=True)\n                )\n                \n                logger.success(f\"Audio added to silent video: {output}\")\n                return output\n            except ffmpeg.Error as e:\n                error_msg = e.stderr.decode() if e.stderr else str(e)\n                logger.error(f\"FFmpeg error adding audio to silent video: {error_msg}\")\n                raise RuntimeError(f\"Failed to add audio to video: {error_msg}\")\n        \n        # Video has audio, proceed with merging\n        logger.info(f\"Merging audio with video (replace={replace_audio})\")\n        \n        try:\n            if replace_audio:\n                # Replace audio: use only new audio, ignore original\n                (\n                    ffmpeg\n                    .output(\n                        video_stream,\n                        audio_stream,\n                        output,\n                        vcodec='libx264',  # Re-encode video if padded\n                        acodec='aac',\n                        audio_bitrate='192k'\n                    )\n                    .overwrite_output()","sourceCodeStart":442,"sourceCodeEnd":478,"githubUrl":"https://github.com/ATH-MaaS/Pixelle-Video/blob/848b054e4fae40dabc62ec58e960b573e83793ac/pixelle_video/services/video.py#L442-L478","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the FFmpeg stderr in the message — it names the failing stream or codec.","Verify the audio file exists, is non-empty, and ffprobe reports a valid audio stream.","Re-encode the audio to aac 44.1kHz stereo mp4/m4a before merging.","Confirm the ffmpeg build includes the needed decoders/encoders (`ffmpeg -codecs | grep aac`)."],"exampleFix":"// before\nservice.merge_audio_video(silent.mp4, 'voice.opus', 'out.mp4')  # decoder error\n// after\nconvert_audio('voice.opus', 'voice.m4a', codec='aac')\nservice.merge_audio_video(silent.mp4, 'voice.m4a', 'out.mp4')","handlingStrategy":"validation","validationCode":"import ffmpeg\nassert os.path.isfile(audio) and os.path.getsize(audio) > 0\nprobe = ffmpeg.probe(audio)\nassert any(s.get('codec_type') == 'audio' for s in probe['streams']), 'no audio stream'","typeGuard":"def has_audio_stream(path: str) -> bool:\n    try:\n        return any(s.get('codec_type') == 'audio' for s in ffmpeg.probe(path)['streams'])\n    except Exception:\n        return False","tryCatchPattern":"try:\n    service.merge_audio_video(video, audio, out)\nexcept RuntimeError as e:\n    if 'Failed to add audio to video' in str(e):\n        logger.error(f'audio mux failed: {e}')\n        # re-encode audio to aac and retry\n    else:\n        raise","preventionTips":["Always validate the audio file with ffprobe (exists, non-empty, audio stream) before merging.","Use aac/m4a (or mp3) audio intermediates to avoid exotic-codec decode failures.","Check TTS/export outputs for zero-byte files before passing them in.","Use an ffmpeg build with common decoders/encoders (aac, mp3) installed."],"tags":["ffmpeg","audio","muxing"],"backgroundTag":"ffmpeg-audio-mux-failed","analyzedSha":"848b054e4fae40dabc62ec58e960b573e83793ac","analyzedAt":"2026-08-30T03:24:41.468Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}