deepfakes/faceswap · error · FaceswapError

Frame Ranges not specified in the correct format

Error message

Frame Ranges not specified in the correct format

What it means

FaceswapError raised in Convert._get_frame_ranges when a --frame-ranges value contains no '-' separator. Each range must be 'start-end'; the code splits on '-' and would fail unpacking without it, so it fails fast with a clear message instead of a ValueError. Everything before this check (index detection) has already succeeded.

Source

Thrown at scripts/convert.py:434

        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
        -------
        The face extraction chain to be used for on-the-fly conversion
        """
        if not self._alignments.have_alignments_file and not self._args.on_the_fly:
            logger.error("No alignments file found. Please provide an alignments file for your "
                         "destination video (recommended) or enable on-the-fly conversion (not "

View on GitHub (pinned to f530cb7508)

Solutions

1. Format each range as START-END, e.g. --frame-ranges 5-10
2. Multiple ranges separated by commas: --frame-ranges 1-100,200-300
3. Check shell quoting so the full argument reaches the parser

Example fix

# before
python faceswap.py convert ... --frame-ranges 5
python faceswap.py convert ... --frame-ranges 5,10

# after
python faceswap.py convert ... --frame-ranges 5-10
python faceswap.py convert ... --frame-ranges 1-100,200-300

for rng in args.frame_ranges:
    parts = rng.split("-")
    if len(parts) != 2 or not all(p.isdigit() for p in parts):
        raise SystemExit(f"Bad frame range {rng!r}; expected START-END (e.g. 5-10)")

def is_valid_frame_range(rng: str) -> bool:
    """True if rng looks like 'START-END' with integer bounds."""
    parts = rng.split("-")
    return len(parts) == 2 and all(p.isdigit() for p in parts)

When it happens

Trigger: Passing --frame-ranges 5 (single number), --frame-ranges 5,10 (comma format), or a typo like '--frame-ranges 5-10-15' variant without dash. rng lacks '-' so the guard fires.

Common situations: User assumes comma syntax from other tools, forgets the end value, or has a shell quoting issue that drops part of the range.

Related errors

• Output as video selected, but using frames as input. You mus
• Frame Ranges specified, but could not determine frame number
• {self._args.model_dir} does not exist.
• You have selected the Mask Type `{self._args.mask_type}` but
• Predicted Mask selected, but the model was not trained with

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