{"record":{"id":"0d7ebd249b7d5571","repo":"ATH-MaaS/Pixelle-Video","slug":"bgm-file-not-found-bgm-path-tried-paths","errorCode":null,"errorMessage":"BGM file not found: '{bgm_path}'\n  Tried paths:\n    1. {tried_paths[0]}\n    2. {tried_paths[1]}{available_msg}","messagePattern":"BGM file not found: '(.+?)'\n  Tried paths:\n    1\\. (.+?)\n    2\\. (.+?)(.+?)","errorType":"exception","errorClass":"FileNotFoundError","httpStatus":null,"severity":"error","filePath":"pixelle_video/services/video.py","lineNumber":860,"sourceCode":"        # Try direct path first (absolute or relative)\n        if os.path.exists(bgm_path):\n            return os.path.abspath(bgm_path)\n        \n        # Try as filename in resource directories (custom > default)\n        if resource_exists(\"bgm\", bgm_path):\n            return get_resource_path(\"bgm\", bgm_path)\n        \n        # Not found - provide helpful error message\n        tried_paths = [\n            os.path.abspath(bgm_path),\n            f\"data/bgm/{bgm_path} or bgm/{bgm_path}\"\n        ]\n        \n        # List available BGM files\n        available_bgm = self._list_available_bgm()\n        available_msg = f\"\\n  Available BGM files: {', '.join(available_bgm)}\" if available_bgm else \"\"\n        \n        raise FileNotFoundError(\n            f\"BGM file not found: '{bgm_path}'\\n\"\n            f\"  Tried paths:\\n\"\n            f\"    1. {tried_paths[0]}\\n\"\n            f\"    2. {tried_paths[1]}\"\n            f\"{available_msg}\"\n        )\n    \n    def _list_available_bgm(self) -> list[str]:\n        \"\"\"\n        List available BGM files (merged from bgm/ and data/bgm/)\n        \n        Returns:\n            List of filenames (with extensions), sorted\n        \"\"\"\n        try:\n            # Use resource API to get merged list\n            all_files = list_resource_files(\"bgm\")\n            ","sourceCodeStart":842,"sourceCodeEnd":878,"githubUrl":"https://github.com/ATH-MaaS/Pixelle-Video/blob/848b054e4fae40dabc62ec58e960b573e83793ac/pixelle_video/services/video.py#L842-L878","documentation":"Raised by _resolve_bgm_path when the requested background-music file cannot be located. The resolver checks the path directly, then bundled resource dirs (bgm/ and data/bgm/), and raises FileNotFoundError listing every path tried plus available BGM files. It exists to give an actionable message instead of a silent missing-asset failure later in ffmpeg.","triggerScenarios":"Calling merge_audio_video (via _add_bgm_to_video) with a bgm_path that is neither an existing file path nor a filename present in data/bgm/ or bgm/ — e.g. a typo like 'happy.mp3' when the file is 'happy_upbeat.mp3', or a custom path that is relative to a different working directory.","commonSituations":"Passing a BGM name from documentation that is not bundled; running the app from a different CWD so relative paths break; forgetting to place custom tracks in data/bgm/; wrong file extension (e.g. .m4a provided, code filters to audio types).","solutions":["Check the 'Available BGM files' list in the error message and use one of those exact filenames","If using a custom track, place it in data/bgm/ (or pass an absolute path via os.path.abspath)","Verify the file extension matches an audio type the resource listing recognizes (.mp3/.wav etc.)","Run the process from the project root if you rely on relative bgm paths"],"exampleFix":"// before\nawait service.merge_audio_video(..., bgm_path='happy.mp3')\n// after\nfrom pixelle_video.utils.os_util import get_resource_path\nbgm = get_resource_path('bgm', 'happy_upbeat.mp3')  # verify it exists first\nawait service.merge_audio_video(..., bgm_path=bgm)","handlingStrategy":"validation","validationCode":"import os\nfrom pixelle_video.utils.resource_util import resource_exists\n\ndef validate_bgm(bgm_path: str) -> str:\n    if os.path.exists(bgm_path):\n        return os.path.abspath(bgm_path)\n    if resource_exists('bgm', bgm_path):\n        return bgm_path\n    raise FileNotFoundError(f'BGM not found before call: {bgm_path}')","typeGuard":null,"tryCatchPattern":"try:\n    output = await service.merge_audio_video(video, audio, bgm_path=bgm)\nexcept FileNotFoundError as e:\n    logger.warning(f'BGM missing, continuing without: {e}')\n    output = await service.merge_audio_video(video, audio, bgm_path=None)","preventionTips":["List available BGM files once at startup and validate user-supplied names against it","Store custom tracks in data/bgm/ with the exact filename referenced in config","Use absolute paths for custom BGM to avoid CWD dependence"],"tags":["file-not-found","bgm","ffmpeg","assets"],"backgroundTag":"file-not-found","analyzedSha":"848b054e4fae40dabc62ec58e960b573e83793ac","analyzedAt":"2026-08-30T03:24:41.468Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}