deepfakes/faceswap · error · FaceswapError

Frame Ranges specified, but could not determine frame number

Error message

Frame Ranges specified, but could not determine frame numbering from filenames

What it means

FaceswapError raised in Convert._get_frame_ranges when --frame-ranges is used with a frames-folder input whose filenames contain no recognizable index numbers. For videos, min/max come from the frame count; for folders, an _image_idx_re regex must find an integer in every basename. If no indices are found, min_frame/max_frame stay None and the range cannot be resolved.

Source

Thrown at scripts/convert.py:428

        Returns
        A list of  frames to be processed, or ``None`` if the command line argument was not used
        """
        if not self._args.frame_ranges:
            logger.debug("No frame range set")
            return None

        min_frame, max_frame = None, None
        if self._images.is_video:
            min_frame, max_frame = 1, self._images.count
        else:
            indices = [int(self._image_idx_re.findall(os.path.basename(filename))[0])
                       for filename in self._images.file_list]
            if indices:
                min_frame, max_frame = min(indices), max(indices)
        logger.debug("min_frame: %s, max_frame: %s", min_frame, max_frame)

        if min_frame is None or max_frame is None:
            raise FaceswapError("Frame Ranges specified, but could not determine frame numbering "
                                "from filenames")

        retval = []
        for rng in self._args.frame_ranges:
            if "-" not in rng:
                raise FaceswapError("Frame Ranges not specified in the correct format")
            start, end = rng.split("-")
            retval.append((max(int(start), min_frame), min(int(end), max_frame)))
        logger.debug("frame ranges: %s", retval)
        return retval

    def _load_extractor(self) -> ExtractRunner[ExtractHandler] | None:
        """Load the CV2-DNN Face Extractor Chain.

        For On-The-Fly conversion we use a CPU based extractor to avoid stacking the GPU.
        Results are poor.

        Returns

View on GitHub (pinned to f530cb7508)

Solutions

1. Rename files to include a numeric frame index (e.g. 000001.png) matching your extractor's numbering pattern
2. Or drop --frame-ranges and convert all frames
3. Or convert from the source video directly, where numbering is inherent

Example fix

# before: folder has face_a.png, face_b.png -> error
python faceswap.py convert -i /frames -m /models/m --frame-ranges 5-10

# after (shell): rename with numeric indices
cd /frames && i=1; for f in *.png; do mv "$f" "$(printf '%06d.png' $i)"; i=$((i+1)); done
python faceswap.py convert -i /frames -m /models/m --frame-ranges 5-10

import os, re
idx_re = re.compile(r"\d+")  # mirror convert's numbering expectation
if not images_obj.is_video and args.frame_ranges:
    if not all(idx_re.search(os.path.basename(f)) for f in images_obj.file_list):
        raise SystemExit("--frame-ranges needs numbered filenames; rename files or drop the flag")

When it happens

Trigger: Running convert with --frame-ranges on an input folder of images whose names lack numeric parts (e.g. 'face_a.png', 'img.png'). The regex findall over each basename yields nothing so indices is empty.

Common situations: Frames extracted with custom renaming scripts, images gathered from mixed sources without numbering, or user assumes frame ranges apply to arbitrary image folders.

Related errors

• Frame Ranges not specified in the correct format
• Output as video selected, but using frames as input. You mus
• You have selected the Mask Type `{self._args.mask_type}` but
• Predicted Mask selected, but the model was not trained with
• Faceswap ran out of RAM running convert. Conversion is very

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