{"record":{"id":"0a9dbc839e30cf3e","repo":"deepinsight/insightface","slug":"video-dimensions-could-not-be-read","errorCode":null,"errorMessage":"Video dimensions could not be read.","messagePattern":"Video dimensions could not be read\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python-package/insightface/gui/pages/face_swap_page.py","lineNumber":245,"sourceCode":"            \"message\": f\"Image face swap saved to {output_path}\",\n        }\n\n    def _swap_video(self, swapper: FaceSwapEngine, source_native, target_path: str, progress=None, is_cancelled=None) -> dict:\n        try:\n            import cv2\n        except Exception as exc:\n            raise ValueError(f\"OpenCV is required for video face swap: {exc}\") from exc\n\n        cap = cv2.VideoCapture(target_path)\n        if not cap.isOpened():\n            raise ValueError(\"Video could not be opened.\")\n        fps = cap.get(cv2.CAP_PROP_FPS) or 25.0\n        width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH) or 0)\n        height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT) or 0)\n        frame_count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT) or 0)\n        if width <= 0 or height <= 0:\n            cap.release()\n            raise ValueError(\"Video dimensions could not be read.\")\n        output_path = Path(self.context.config.export_dir) / f\"face_swap_video_{timestamp_for_filename()}.mp4\"\n        output_path.parent.mkdir(parents=True, exist_ok=True)\n        writer = cv2.VideoWriter(str(output_path), cv2.VideoWriter_fourcc(*\"mp4v\"), fps, (width, height))\n        if not writer.isOpened():\n            cap.release()\n            raise ValueError(\"Video writer could not be opened.\")\n\n        preview = None\n        swapped = 0\n        processed = 0\n        try:\n            while True:\n                if is_cancelled and is_cancelled():\n                    break\n                ok, frame = cap.read()\n                if not ok:\n                    break\n                output_frame = frame","sourceCodeStart":227,"sourceCodeEnd":263,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/python-package/insightface/gui/pages/face_swap_page.py#L227-L263","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-mux/re-encode with ffmpeg to rebuild headers and retry","Read one frame first (cap.read()) then query dimensions again — some backends populate them only after a read","Verify the file with ffprobe to confirm it has valid dimensions","Re-record or re-download the source video if corrupt"],"exampleFix":"# before\nw = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))\n# after\nok, frame = cap.read()\nif ok and frame is not None:\n    h, w = frame.shape[:2]\nelse:\n    raise ValueError(\"Video dimensions could not be read.\")","handlingStrategy":"fallback","validationCode":"w = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)); h = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))\nif w <= 0 or h <= 0:\n    ok, frame = cap.read()\n    if ok and frame is not None: h, w = frame.shape[:2]","typeGuard":null,"tryCatchPattern":"try:\n    return self._swap_video(...)\nexcept ValueError as e:\n    if 'dimensions' in str(e): reencode_with_ffmpeg_then_retry()","preventionTips":["Always read one frame before trusting metadata","Validate videos with ffprobe during ingest","Re-encode unknown-source videos to a canonical format"],"tags":["insightface","opencv","video-metadata"],"backgroundTag":"opencv-video-metadata-missing","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}