ATH-MaaS/Pixelle-Video · error · FileNotFoundError

BGM file not found: '{bgm_path}' Tried paths: 1. {trie

Error message

BGM file not found: '{bgm_path}'
  Tried paths:
    1. {tried_paths[0]}
    2. {tried_paths[1]}{available_msg}

What it means

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.

Source

Thrown at pixelle_video/services/video.py:860

        # Try direct path first (absolute or relative)
        if os.path.exists(bgm_path):
            return os.path.abspath(bgm_path)
        
        # Try as filename in resource directories (custom > default)
        if resource_exists("bgm", bgm_path):
            return get_resource_path("bgm", bgm_path)
        
        # Not found - provide helpful error message
        tried_paths = [
            os.path.abspath(bgm_path),
            f"data/bgm/{bgm_path} or bgm/{bgm_path}"
        ]
        
        # List available BGM files
        available_bgm = self._list_available_bgm()
        available_msg = f"\n  Available BGM files: {', '.join(available_bgm)}" if available_bgm else ""
        
        raise FileNotFoundError(
            f"BGM file not found: '{bgm_path}'\n"
            f"  Tried paths:\n"
            f"    1. {tried_paths[0]}\n"
            f"    2. {tried_paths[1]}"
            f"{available_msg}"
        )
    
    def _list_available_bgm(self) -> list[str]:
        """
        List available BGM files (merged from bgm/ and data/bgm/)
        
        Returns:
            List of filenames (with extensions), sorted
        """
        try:
            # Use resource API to get merged list
            all_files = list_resource_files("bgm")
            

View on GitHub (pinned to 848b054e4f)

Solutions

1. Check the 'Available BGM files' list in the error message and use one of those exact filenames
2. If using a custom track, place it in data/bgm/ (or pass an absolute path via os.path.abspath)
3. Verify the file extension matches an audio type the resource listing recognizes (.mp3/.wav etc.)
4. Run the process from the project root if you rely on relative bgm paths

Example fix

// before
await service.merge_audio_video(..., bgm_path='happy.mp3')
// after
from pixelle_video.utils.os_util import get_resource_path
bgm = get_resource_path('bgm', 'happy_upbeat.mp3')  # verify it exists first
await service.merge_audio_video(..., bgm_path=bgm)

import os
from pixelle_video.utils.resource_util import resource_exists

def validate_bgm(bgm_path: str) -> str:
    if os.path.exists(bgm_path):
        return os.path.abspath(bgm_path)
    if resource_exists('bgm', bgm_path):
        return bgm_path
    raise FileNotFoundError(f'BGM not found before call: {bgm_path}')

try:
    output = await service.merge_audio_video(video, audio, bgm_path=bgm)
except FileNotFoundError as e:
    logger.warning(f'BGM missing, continuing without: {e}')
    output = await service.merge_audio_video(video, audio, bgm_path=None)

When it happens

Trigger: 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.

Common situations: 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).

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Failed to add BGM: {error_msg}
• Image file not found: {image_path}
• Video file not found: {video_path}
• API video generation did not create file: {save_path}
• 文件不存在: {file_path}

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