{"record":{"id":"7db4decec5e2b1fa","repo":"ATH-MaaS/Pixelle-Video","slug":"failed-to-add-bgm-error-msg","errorCode":null,"errorMessage":"Failed to add BGM: {error_msg}","messagePattern":"Failed to add BGM: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"pixelle_video/services/video.py","lineNumber":762,"sourceCode":"                ffmpeg\n                .output(\n                    input_video.video,\n                    mixed_audio,\n                    output,\n                    vcodec='copy',\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\"BGM added successfully: {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 BGM error: {error_msg}\")\n            raise RuntimeError(f\"Failed to add BGM: {error_msg}\")\n    \n    def _add_bgm_to_video(\n        self,\n        video: str,\n        bgm_path: str,\n        output: str,\n        volume: float = 0.2,\n        mode: Literal[\"once\", \"loop\"] = \"loop\"\n    ) -> str:\n        \"\"\"\n        Internal helper to add BGM to video with path resolution\n        \n        Args:\n            video: Video file path\n            bgm_path: BGM path (can be preset name or custom path)\n            output: Output file path\n            volume: BGM volume (0.0-1.0)\n            mode: \"once\" or \"loop\"","sourceCodeStart":744,"sourceCodeEnd":780,"githubUrl":"https://github.com/ATH-MaaS/Pixelle-Video/blob/848b054e4fae40dabc62ec58e960b573e83793ac/pixelle_video/services/video.py#L744-L780","documentation":"add_bgm mixes background music under a video's existing audio (with optional volume/loop/fade) using an amix/afilter graph. ffmpeg.Error is caught and re-raised as this RuntimeError with decoded stderr. The real cause is in the FFmpeg stderr text.","triggerScenarios":"BGM file missing, corrupt, or an unsupported codec; filter graph failing because the video has no audio stream to mix with; invalid volume/fade parameters; ffmpeg build lacking a filter (e.g. afade) or encoder used by the graph.","commonSituations":"BGM downloaded as m4p/DRM-protected or zero bytes; calling add_bgm on a silent video that needed merge_audio_video instead; extremely long BGM files causing memory pressure; exotic sample rates rejected by the mix filter.","solutions":["Read the FFmpeg stderr in the exception message to pinpoint the failing filter or stream.","Confirm the BGM file exists, is non-empty, and ffprobe reports a decodable audio stream.","If the video has no audio track, add one first or use merge_audio_video semantics instead of mixing.","Re-encode the BGM to aac mp4 and a standard sample rate (44100/48000) before adding it."],"exampleFix":"// before\nservice.add_bgm(silent_video, 'track.flac', 'out.mp4')  # no audio stream to mix\n// after\nservice.merge_audio_video(silent_video, 'bed.m4a', 'with_audio.mp4')\nservice.add_bgm(with_audio, 'track.m4a', 'out.mp4')","handlingStrategy":"validation","validationCode":"import ffmpeg\nassert os.path.isfile(bgm) and os.path.getsize(bgm) > 0\nassert has_audio_stream(video), 'video must have an audio stream to mix BGM into'\nassert has_audio_stream(bgm)","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.add_bgm(video, bgm, out)\nexcept RuntimeError as e:\n    if 'Failed to add BGM' in str(e):\n        logger.error(f'BGM mix failed: {e}')\n        # re-encode BGM to aac, ensure video has audio, retry\n    else:\n        raise","preventionTips":["Only call add_bgm on videos that already have an audio track; use merge_audio_video otherwise.","Re-encode BGM to aac/m4a at 44100/48000 Hz before mixing.","Validate BGM files (non-empty, decodable) after download and before use.","Test the mix filter graph with a short clip before long renders."],"tags":["ffmpeg","audio","bgm"],"backgroundTag":"ffmpeg-audio-mux-failed","analyzedSha":"848b054e4fae40dabc62ec58e960b573e83793ac","analyzedAt":"2026-08-30T03:24:41.468Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}