deepfakes/faceswap · error · FaceswapError

Output as video selected, but using frames as input. You mus

Error message

Output as video selected, but using frames as input. You must provide a reference video ('-ref', '--reference-video').

What it means

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.

Source

Thrown at scripts/convert.py:170

        Ensure that certain cli selections are valid and won't result in an error. Checks:
            * If frames have been passed in with video output, ensure user supplies reference
            video.
            * If "on-the-fly" and a Neural Network mask is selected, warn and switch to 'extended'
            * If a mask-type is selected, ensure it exists in the alignments file.
            * If a predicted mask-type is selected, ensure model has been trained with a mask
            otherwise attempt to select first available masks, otherwise raise error.

        Raises
        ------
        FaceswapError
            If an invalid selection has been found.

        """
        if (self._args.writer == "ffmpeg" and
                not self._images.is_video and
                self._args.reference_video is None):
            raise FaceswapError("Output as video selected, but using frames as input. You must "
                                "provide a reference video ('-ref', '--reference-video').")

        if (self._args.on_the_fly and
                self._args.mask_type not in ("none", "extended", "components")):
            logger.warning("You have selected an incompatible mask type ('%s') for On-The-Fly "
                           "conversion. Switching to 'extended'", self._args.mask_type)
            self._args.mask_type = "extended"

        if (not self._args.on_the_fly and
                self._args.mask_type not in ("none", "predicted", "extended", "components") and
                not self._alignments.mask_is_valid(self._args.mask_type)):
            msg = (f"You have selected the Mask Type `{self._args.mask_type}` but at least one "
                   "face does not have this mask stored in the Alignments File.\nYou should "
                   "generate the required masks with the Mask Tool or set the Mask Type option to "
                   "an existing Mask Type.\nA summary of existing masks is as follows:\nTotal "
                   f"faces: {self._alignments.faces_count}, "
                   f"Masks: {self._alignments.mask_summary}")
            raise FaceswapError(msg)

View on GitHub (pinned to f530cb7508)

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

Example fix

# before
python faceswap.py convert -i /data/frames -w ffmpeg -m /models/my_model

# after
python faceswap.py convert -i /data/frames -w ffmpeg -m /models/my_model \
    -r /data/source_video.mp4

Defensive patterns

Strategy: validation

Validate before calling

writer, is_video, ref = "ffmpeg", images_obj.is_video, args.reference_video
if writer == "ffmpeg" and not is_video and ref is None:
    raise SystemExit("ffmpeg writer with frames input requires -r/--reference-video")

Prevention

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

When it happens

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

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

Related errors

AI-assisted analysis of deepfakes/faceswap@f530cb7508 (2026-08-15). Data as JSON: /api/errors/a3b8aa3fc99f6fd8. Report an issue: GitHub.