deepinsight/insightface · error · ValueError

Video dimensions could not be read.

Error message

Video dimensions could not be read.

What it means

The opened video stream reported non-positive frame width or height (CAP_PROP_FRAME_WIDTH/HEIGHT returned 0), so pixel dimensions cannot be determined and processing cannot proceed.

Source

Thrown at python-package/insightface/gui/pages/face_swap_page.py:245

            "message": f"Image face swap saved to {output_path}",
        }

    def _swap_video(self, swapper: FaceSwapEngine, source_native, target_path: str, progress=None, is_cancelled=None) -> dict:
        try:
            import cv2
        except Exception as exc:
            raise ValueError(f"OpenCV is required for video face swap: {exc}") from exc

        cap = cv2.VideoCapture(target_path)
        if not cap.isOpened():
            raise ValueError("Video could not be opened.")
        fps = cap.get(cv2.CAP_PROP_FPS) or 25.0
        width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH) or 0)
        height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT) or 0)
        frame_count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT) or 0)
        if width <= 0 or height <= 0:
            cap.release()
            raise ValueError("Video dimensions could not be read.")
        output_path = Path(self.context.config.export_dir) / f"face_swap_video_{timestamp_for_filename()}.mp4"
        output_path.parent.mkdir(parents=True, exist_ok=True)
        writer = cv2.VideoWriter(str(output_path), cv2.VideoWriter_fourcc(*"mp4v"), fps, (width, height))
        if not writer.isOpened():
            cap.release()
            raise ValueError("Video writer could not be opened.")

        preview = None
        swapped = 0
        processed = 0
        try:
            while True:
                if is_cancelled and is_cancelled():
                    break
                ok, frame = cap.read()
                if not ok:
                    break
                output_frame = frame

View on GitHub (pinned to 7fadd420c2)

Solutions

1. Re-mux/re-encode with ffmpeg to rebuild headers and retry
2. Read one frame first (cap.read()) then query dimensions again — some backends populate them only after a read
3. Verify the file with ffprobe to confirm it has valid dimensions
4. Re-record or re-download the source video if corrupt

Example fix

# before
w = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
# after
ok, frame = cap.read()
if ok and frame is not None:
    h, w = frame.shape[:2]
else:
    raise ValueError("Video dimensions could not be read.")

w = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)); h = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
if w <= 0 or h <= 0:
    ok, frame = cap.read()
    if ok and frame is not None: h, w = frame.shape[:2]

try:
    return self._swap_video(...)
except ValueError as e:
    if 'dimensions' in str(e): reencode_with_ffmpeg_then_retry()

When it happens

Trigger: Opening a video whose header is corrupt, a zero-length/truncated recording, or a stream where metadata probing fails in the OpenCV backend in use.

Common situations: Interrupted screen recordings, partially downloaded files, some AVI/MKV variants where the MMAL/FFmpeg backend returns 0 dimensions, or webcam streams queried before the first frame arrives.

Related errors

• OpenCV is required for video face swap: {exc}
• Video could not be opened.
• Video writer could not be opened.
• NV21 data size is not enough: expected {expected_size} bytes
• skipped multi-face image ({face_count} faces)

AI-assisted analysis of deepinsight/insightface@7fadd420c2 (2026-08-28). Data as JSON: /api/errors/0a9dbc839e30cf3e. Report an issue: GitHub.