{"id":9710,"library":"dxcam","title":"DXcam - High-Performance Windows Screenshot Library","description":"DXcam is a Python library providing high-performance screenshot capabilities specifically for Windows, leveraging the Desktop Duplication API. It's currently at version 0.3.0 and sees active development with irregular but significant updates, focusing on performance, backend options, and robustness.","status":"active","version":"0.3.0","language":"en","source_language":"en","source_url":"https://github.com/ra1nty/DXcam","tags":["windows","screenshot","desktop-duplication-api","performance","graphics"],"install":[{"cmd":"pip install dxcam","lang":"bash","label":"Basic Install"},{"cmd":"pip install dxcam opencv-python numpy","lang":"bash","label":"Install with common dependencies for image processing"}],"dependencies":[{"reason":"Used for efficient array manipulation of captured frames; essential for many processing backends.","package":"numpy","optional":false},{"reason":"Commonly used for image processing with captured frames, and one of DXcam's processor backends.","package":"opencv-python","optional":true}],"imports":[{"note":"While DXcam class exists, dxcam.create() is the recommended factory function for convenience and proper initialization.","wrong":"from dxcam import DXcam\ncamera = DXcam()","symbol":"create","correct":"import dxcam\ncamera = dxcam.create()"}],"quickstart":{"code":"import dxcam\nimport cv2\n\n# dxcam is Windows-only, so this example will only run there.\n# On other OS, it will raise a RuntimeError.\n\ntry:\n    # Create a DXcam instance, auto-detecting the primary display output.\n    # Optionally specify output_idx, region, or device_idx.\n    camera = dxcam.create()\n\n    if camera is None:\n        print(\"Failed to create DXcam instance. Ensure a display is connected and drivers are up to date.\")\n    else:\n        # Start capturing frames. By default, it captures the full screen.\n        camera.start(target_fps=30)\n\n        # Grab a single frame\n        frame = camera.grab()\n\n        if frame is not None:\n            print(f\"Captured frame with shape: {frame.shape}, dtype: {frame.dtype}\")\n            # Example: Display the frame using OpenCV (requires opencv-python)\n            cv2.imshow('DXcam Frame', frame)\n            cv2.waitKey(1000) # Display for 1 second\n            cv2.destroyAllWindows()\n        else:\n            print(\"Failed to grab a frame.\")\n\n        # Stop capturing frames when done\n        camera.stop()\n\nexcept RuntimeError as e:\n    print(f\"Error initializing DXcam: {e}. DXcam is a Windows-only library.\")\nexcept ImportError as e:\n    print(f\"Missing required dependency for quickstart: {e}. Try 'pip install dxcam opencv-python numpy'.\")\n","lang":"python","description":"This quickstart initializes DXcam, starts capturing, grabs a single frame, and displays it using OpenCV (if installed). It includes error handling for non-Windows environments and initialization failures."},"warnings":[{"fix":"Ensure your development and deployment environment is Windows. Consider conditional imports or platform checks if your application needs to support multiple OS.","message":"DXcam is a Windows-only library. Attempting to import or use it on other operating systems will result in a RuntimeError.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Thoroughly test performance and stability when migrating from versions prior to 0.1.0. Monitor for `DXGI_ERROR_DEVICE_REMOVED` or unexpected frame drops.","message":"Version 0.1.0 introduced a 'Major overhaul', switching the default capture path to `IDXGIOutput5.DuplicateOutput1` and changing frame transfer from `CopyResource` to `CopySubresourceRegion`. This may alter performance characteristics or reveal new issues if upgrading from pre-0.1.0 versions, especially for applications sensitive to low-level capture behavior.","severity":"breaking","affected_versions":"<0.1.0 to >=0.1.0"},{"fix":"Consult the DXcam documentation to understand the different backends and processors. Experiment with `processor='numpy_kernels'` or `processor='cv2'` (if `opencv-python` is installed) and different `backend` options to find the best fit for your use case.","message":"Version 0.2.0 introduced a WinRT backend and new processor splits (cv2 backend / numpy Cython-kernel backend). While this adds flexibility, users relying on specific performance profiles from earlier versions might need to re-evaluate their chosen backend/processor for optimal results.","severity":"gotcha","affected_versions":">=0.2.0"},{"fix":"Implement robust error handling for `None` frames returned by `grab()`. Consider re-initializing the DXcam instance if errors persist or if the display configuration changes significantly. Version 0.3.0 improved handling of DXGI mode switches, but device removal remains a challenge.","message":"DXcam relies on the Desktop Duplication API, which can encounter 'device lost' scenarios (e.g., monitor unplugged, GPU driver reset, display mode change). While DXcam attempts to recover, persistent issues can lead to `None` frames or crashes.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"DXcam is explicitly designed for Windows. Use a Windows environment or consider cross-platform alternatives for other operating systems.","cause":"Attempting to run DXcam on a non-Windows operating system.","error":"RuntimeError: DXcam only supports Windows."},{"fix":"Check if `camera` is `None` after `dxcam.create()` and handle the case. Ensure DirectX drivers are up to date and that a display is connected and active. Restarting the application or the system might resolve transient issues.","cause":"The `dxcam.create()` call returned `None`, indicating that a DXcam instance could not be initialized (e.g., no suitable display output found, or an underlying COM error).","error":"AttributeError: 'NoneType' object has no attribute 'grab'"},{"fix":"Ensure your Windows system is up to date and has the latest Visual C++ Redistributable. Reinstalling DXcam might also help: `pip uninstall dxcam && pip install dxcam`.","cause":"This usually indicates missing runtime dependencies (e.g., specific Visual C++ redistributables or DirectX components) or an issue with the Python environment.","error":"ImportError: DLL load failed while importing _dxcam_backend: The specified module could not be found."},{"fix":"Install `opencv-python` alongside `dxcam`: `pip install dxcam opencv-python numpy`. Ensure the installed version is compatible with your Python environment.","cause":"If you are using a processor that relies on OpenCV (e.g., default or explicit `processor='cv2'`) and `opencv-python` is not installed or configured correctly.","error":"cv2.error: OpenCV(4.x.x) error: ..."}]}