{"record":{"id":"fd76a9fddb9ff913","repo":"deepfakes/faceswap","slug":"an-unexpected-ffruntimeerror-occurred-ffe","errorCode":null,"errorMessage":"An unexpected FFRuntimeError occurred: {ffe}","messagePattern":"An unexpected FFRuntimeError occurred: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"tools/effmpeg/effmpeg.py","lineNumber":507,"sourceCode":"                items_to_check.append(\"input\")\n            elif i == \"o\":\n                items_to_check.append(\"output\")\n\n        return all(getattr(self, i).fps is None for i in items_to_check)\n\n    @staticmethod\n    def __run_ffmpeg(exe=str(ffmpeg.FFMPEG_PATH), inputs=None, outputs=None):\n        \"\"\"Run ffmpeg\"\"\"\n        logger.debug(\"Running ffmpeg: (exe: '%s', inputs: %s, outputs: %s\", exe, inputs, outputs)\n        ffm = FFmpeg(executable=exe, inputs=inputs, outputs=outputs)\n        try:\n            ffm.run(stderr=subprocess.STDOUT)\n        except FFRuntimeError as ffe:\n            # After receiving SIGINT ffmpeg has a 255 exit code\n            if ffe.exit_code == 255:\n                pass\n            else:\n                raise ValueError(f\"An unexpected FFRuntimeError occurred: {ffe}\") from ffe\n        except KeyboardInterrupt:\n            pass  # Do nothing if voluntary interruption\n        logger.debug(\"ffmpeg finished\")\n\n    @staticmethod\n    def __convert_fps(fps):\n        \"\"\"Convert to Frames per Second\"\"\"\n        if \"/\" in fps:\n            _fps = fps.split(\"/\")\n            retval = float(_fps[0]) / float(_fps[1])\n        else:\n            retval = float(fps)\n        logger.debug(retval)\n        return retval\n\n    @staticmethod\n    def __get_duration(start_time, end_time):\n        \"\"\"Get the duration\"\"\"","sourceCodeStart":489,"sourceCodeEnd":525,"githubUrl":"https://github.com/deepfakes/faceswap/blob/f530cb7508ae670f6474f8a7d9c4df94705cf96b/tools/effmpeg/effmpeg.py#L489-L525","documentation":"Wrapper error around ffmpeg-python's FFRuntimeError: the ffmpeg subprocess run by effmpeg exited with a code other than 255 (255 is tolerated as the post-SIGINT status) and not via KeyboardInterrupt. The original FFRuntimeError is chained (`from ffe`), so the real ffmpeg stderr is embedded in the message.","triggerScenarios":"Any effmpeg action where the ffmpeg binary fails: unsupported/missing codec, unreadable input file, unwritable output path, invalid filter string, or a broken ffmpeg install — ffm.run() raises FFRuntimeError and it is re-raised as ValueError.","commonSituations":"Converting to a codec not compiled into the distro ffmpeg; output directory missing or no write permission; input file truncated; ffmpeg not on PATH / FFMPEG_PATH pointing to the wrong binary.","solutions":["Read the tail of the message — it contains ffmpeg's own stderr; fix the reported cause (codec, path, filter).","Test the same operation manually with the ffmpeg CLI to reproduce and isolate.","For codec issues, install full ffmpeg builds (e.g. from johnvansickle static builds or distro ffmpeg-full) rather than minimal ones.","For path issues, create the output directory and check write permissions."],"exampleFix":"# before: fails because output dir does not exist\npython tools.py effmpeg -a rescale -i in.mp4 -o newdir/out.mp4\n\n# after\nmkdir -p newdir\npython tools.py effmpeg -a rescale -i in.mp4 -o newdir/out.mp4","handlingStrategy":"try-catch","validationCode":"import os, shutil\n\ndef ffmpeg_ready(input_path: str, output_dir: str) -> bool:\n    return (shutil.which(\"ffmpeg\") is not None\n            and os.path.exists(input_path)\n            and os.path.isdir(output_dir))","typeGuard":null,"tryCatchPattern":"from ffmpy import FFRuntimeError\ntry:\n    run_ffmpeg_action(...)\nexcept ValueError as err:\n    if \"FFRuntimeError\" in str(err):\n        # original ffmpeg stderr is embedded — surface it verbatim for diagnosis\n        print(\"ffmpeg failed:\", err)\n        raise SystemExit(1) from err\n    raise","preventionTips":["Pre-create output directories and check input readability before running effmpeg.","Install a full-featured ffmpeg build; verify needed codecs with `ffmpeg -encoders | grep <codec>`.","Test new action/filter combinations manually with the ffmpeg CLI first."],"tags":["faceswap","effmpeg","ffmpeg","runtime","wrapper"],"backgroundTag":null,"analyzedSha":"f530cb7508ae670f6474f8a7d9c4df94705cf96b","analyzedAt":"2026-08-15T02:59:26.626Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}