{"record":{"id":"e58e0c7edb7af1d0","repo":"ATH-MaaS/Pixelle-Video","slug":"failed-to-overlay-image-on-video-error-msg","errorCode":null,"errorMessage":"Failed to overlay image on video: {error_msg}","messagePattern":"Failed to overlay image on video: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"pixelle_video/services/video.py","lineNumber":599,"sourceCode":"            output_stream = ffmpeg.overlay(scaled_video, input_overlay)\n            \n            (\n                ffmpeg\n                .output(output_stream, output, \n                        vcodec='libx264',\n                        pix_fmt='yuv420p',\n                        preset='medium',\n                        crf=23)\n                .overwrite_output()\n                .run(capture_stdout=True, capture_stderr=True)\n            )\n            \n            logger.success(f\"Image overlaid on 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 overlay error: {error_msg}\")\n            raise RuntimeError(f\"Failed to overlay image on video: {error_msg}\")\n    \n    def create_video_from_image(\n        self,\n        image: str,\n        audio: str,\n        output: str,\n        fps: int = 30,\n    ) -> str:\n        \"\"\"\n        Create video from static image and audio\n        \n        Args:\n            image: Image file path\n            audio: Audio file path\n            output: Output video path\n            fps: Frames per second\n        \n        Returns:","sourceCodeStart":581,"sourceCodeEnd":617,"githubUrl":"https://github.com/ATH-MaaS/Pixelle-Video/blob/848b054e4fae40dabc62ec58e960b573e83793ac/pixelle_video/services/video.py#L581-L617","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the FFmpeg stderr in the message to identify the failing filter or input.","Verify the overlay image exists and is a decodable raster format (PNG/JPG); convert SVG to PNG first.","Check overlay x/y coordinates fit within the video dimensions.","ffprobe the video input to confirm it is valid before overlaying."],"exampleFix":"// before\nservice.overlay_image_on_video(video, 'logo.svg', 'out.mp4', x=5000, y=5000)  # fails\n// after\nconvert_svg_to_png('logo.svg', 'logo.png')  # rasterize first\nservice.overlay_image_on_video(video, 'logo.png', 'out.mp4', x=20, y=20)","handlingStrategy":"validation","validationCode":"assert os.path.isfile(overlay) and os.path.getsize(overlay) > 0\nfrom PIL import Image\nwith Image.open(overlay) as im:\n    im.verify()  # raises if not a decodable raster image\nassert 0 <= x and 0 <= y","typeGuard":"def is_decodable_image(path: str) -> bool:\n    try:\n        from PIL import Image\n        with Image.open(path) as im:\n            im.verify()\n        return True\n    except Exception:\n        return False","tryCatchPattern":"try:\n    service.overlay_image_on_video(video, overlay, out, x=x, y=y)\nexcept RuntimeError as e:\n    if 'Failed to overlay image on video' in str(e):\n        logger.error(f'overlay failed: {e}')\n        # convert image to PNG, fix coordinates, retry\n    else:\n        raise","preventionTips":["Use PNG/JPG raster overlays; rasterize SVGs and avoid exotic formats first.","Validate overlay coordinates against the video dimensions.","ffprobe the base video before overlay steps in automated pipelines.","Keep watermark assets in stable, versioned locations."],"tags":["ffmpeg","overlay","filter"],"backgroundTag":"ffmpeg-filter-failed","analyzedSha":"848b054e4fae40dabc62ec58e960b573e83793ac","analyzedAt":"2026-08-30T03:24:41.468Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}