{"record":{"id":"a3b8aa3fc99f6fd8","repo":"deepfakes/faceswap","slug":"output-as-video-selected-but-using-frames-as-inpu","errorCode":null,"errorMessage":"Output as video selected, but using frames as input. You must provide a reference video ('-ref', '--reference-video').","messagePattern":"Output as video selected, but using frames as input\\. You must provide a reference video \\('-ref', '--reference-video'\\)\\.","errorType":"exception","errorClass":"FaceswapError","httpStatus":null,"severity":"error","filePath":"scripts/convert.py","lineNumber":170,"sourceCode":"\n        Ensure that certain cli selections are valid and won't result in an error. Checks:\n            * If frames have been passed in with video output, ensure user supplies reference\n            video.\n            * If \"on-the-fly\" and a Neural Network mask is selected, warn and switch to 'extended'\n            * If a mask-type is selected, ensure it exists in the alignments file.\n            * If a predicted mask-type is selected, ensure model has been trained with a mask\n            otherwise attempt to select first available masks, otherwise raise error.\n\n        Raises\n        ------\n        FaceswapError\n            If an invalid selection has been found.\n\n        \"\"\"\n        if (self._args.writer == \"ffmpeg\" and\n                not self._images.is_video and\n                self._args.reference_video is None):\n            raise FaceswapError(\"Output as video selected, but using frames as input. You must \"\n                                \"provide a reference video ('-ref', '--reference-video').\")\n\n        if (self._args.on_the_fly and\n                self._args.mask_type not in (\"none\", \"extended\", \"components\")):\n            logger.warning(\"You have selected an incompatible mask type ('%s') for On-The-Fly \"\n                           \"conversion. Switching to 'extended'\", self._args.mask_type)\n            self._args.mask_type = \"extended\"\n\n        if (not self._args.on_the_fly and\n                self._args.mask_type not in (\"none\", \"predicted\", \"extended\", \"components\") and\n                not self._alignments.mask_is_valid(self._args.mask_type)):\n            msg = (f\"You have selected the Mask Type `{self._args.mask_type}` but at least one \"\n                   \"face does not have this mask stored in the Alignments File.\\nYou should \"\n                   \"generate the required masks with the Mask Tool or set the Mask Type option to \"\n                   \"an existing Mask Type.\\nA summary of existing masks is as follows:\\nTotal \"\n                   f\"faces: {self._alignments.faces_count}, \"\n                   f\"Masks: {self._alignments.mask_summary}\")\n            raise FaceswapError(msg)","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/deepfakes/faceswap/blob/f530cb7508ae670f6474f8a7d9c4df94705cf96b/scripts/convert.py#L152-L188","documentation":"FaceswapError raised in Convert._check_output_args (scripts/convert.py) when the writer is 'ffmpeg' (video output) but the input is a folder of frames (not a video) and no --reference-video was supplied. The ffmpeg writer needs stream metadata (fps, codec, dimensions) that can only come from a real video file. Frames alone cannot define the output video.","triggerScenarios":"Running convert with -w ffmpeg, an images folder as input (-i /path/frames), and no -r/--reference-video argument. All three conditions in the check are true simultaneously.","commonSituations":"User extracted frames from a video, converts them, and forgets to point back at the source video; or follows a frames-based workflow but selects the ffmpeg writer out of habit.","solutions":["Pass the original video with -r/--reference-video so ffmpeg writer can copy its properties","Or switch the writer to an image writer (png/jpg) and assemble the video afterwards","Or feed the video directly as -i input instead of extracted frames"],"exampleFix":"# before\npython faceswap.py convert -i /data/frames -w ffmpeg -m /models/my_model\n\n# after\npython faceswap.py convert -i /data/frames -w ffmpeg -m /models/my_model \\\n    -r /data/source_video.mp4","handlingStrategy":"validation","validationCode":"writer, is_video, ref = \"ffmpeg\", images_obj.is_video, args.reference_video\nif writer == \"ffmpeg\" and not is_video and ref is None:\n    raise SystemExit(\"ffmpeg writer with frames input requires -r/--reference-video\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep the source video path next to extracted frames so it is easy to pass with -r","Prefer piping the video directly as convert input when you want video output"],"tags":["faceswap","convert","ffmpeg","video","arguments"],"backgroundTag":null,"analyzedSha":"f530cb7508ae670f6474f8a7d9c4df94705cf96b","analyzedAt":"2026-08-15T02:59:26.626Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}