ATH-MaaS/Pixelle-Video · error · RuntimeError

Failed to overlay image on video: {error_msg}

Error message

Failed to overlay image on video: {error_msg}

What it means

overlay_image_on_video composites a PNG/image over a video using an ffmpeg overlay filter. ffmpeg.Error is caught and re-raised as this RuntimeError including decoded stderr. Typical causes are invalid overlay images or filter/dimension issues.

Source

Thrown at pixelle_video/services/video.py:599

            output_stream = ffmpeg.overlay(scaled_video, input_overlay)
            
            (
                ffmpeg
                .output(output_stream, output, 
                        vcodec='libx264',
                        pix_fmt='yuv420p',
                        preset='medium',
                        crf=23)
                .overwrite_output()
                .run(capture_stdout=True, capture_stderr=True)
            )
            
            logger.success(f"Image overlaid on video: {output}")
            return output
        except ffmpeg.Error as e:
            error_msg = e.stderr.decode() if e.stderr else str(e)
            logger.error(f"FFmpeg overlay error: {error_msg}")
            raise RuntimeError(f"Failed to overlay image on video: {error_msg}")
    
    def create_video_from_image(
        self,
        image: str,
        audio: str,
        output: str,
        fps: int = 30,
    ) -> str:
        """
        Create video from static image and audio
        
        Args:
            image: Image file path
            audio: Audio file path
            output: Output video path
            fps: Frames per second
        
        Returns:

View on GitHub (pinned to 848b054e4f)

Solutions

1. Read the FFmpeg stderr in the message to identify the failing filter or input.
2. Verify the overlay image exists and is a decodable raster format (PNG/JPG); convert SVG to PNG first.
3. Check overlay x/y coordinates fit within the video dimensions.
4. ffprobe the video input to confirm it is valid before overlaying.

Example fix

// before
service.overlay_image_on_video(video, 'logo.svg', 'out.mp4', x=5000, y=5000)  # fails
// after
convert_svg_to_png('logo.svg', 'logo.png')  # rasterize first
service.overlay_image_on_video(video, 'logo.png', 'out.mp4', x=20, y=20)

assert os.path.isfile(overlay) and os.path.getsize(overlay) > 0
from PIL import Image
with Image.open(overlay) as im:
    im.verify()  # raises if not a decodable raster image
assert 0 <= x and 0 <= y

def is_decodable_image(path: str) -> bool:
    try:
        from PIL import Image
        with Image.open(path) as im:
            im.verify()
        return True
    except Exception:
        return False

try:
    service.overlay_image_on_video(video, overlay, out, x=x, y=y)
except RuntimeError as e:
    if 'Failed to overlay image on video' in str(e):
        logger.error(f'overlay failed: {e}')
        # convert image to PNG, fix coordinates, retry
    else:
        raise

When it happens

Trigger: Overlay image missing, zero-byte, or not decodable as an image; RGBA PNG handling issues; position coordinates outside the video frame; timing (enable/between) expressions invalid; video input unreadable.

Common situations: A watermark file that got deleted or moved; corrupted download of a logo PNG; passing an SVG (ffmpeg cannot decode without librsvg); placing overlay at x/y beyond video bounds with strict builds.

Related errors

• FFmpeg not found. Please install it: macOS: brew install f
• Failed to concatenate videos: {error_msg}
• Failed to concatenate videos: {e}
• Failed to add audio to video: {error_msg}
• Failed to merge audio and video: {error_msg}

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