D3DShot Documentation

Windows allows only one instance of Desktop Duplication per process. To prevent errors, d3dshot.create() implements a singleton pattern. Any subsequent calls to create() will return the existing instance rather than creating a new one. Note that because it returns the existing instance, you cannot change the capture_output configuration after the first instance is created.

d = d3dshot.create(capture_output="numpy")

# This returns the same instance 'd', and capture_output remains 'numpy'
d2 = d3dshot.create(capture_output="pil")

print(d == d2)  # True

When using continuous capture (capture()), frames are stored in a thread-safe collections.deque called the frame buffer. The default size is 60 frames. You can increase this size during initialization, but be aware that larger buffers consume significantly more RAM as they store uncompressed images.

# Initialize with a larger buffer (e.g., 100 frames)
d = d3dshot.create(frame_buffer_size=100)

To use D3DShot, you must use the d3dshot.create() helper function. Do not attempt to instantiate the D3DShot class directly, as the create function performs necessary initialization and validation.

create accepts the following optional keyword arguments:

• capture_output: Specifies the format of the captured frames (e.g., pil, numpy, pytorch). See the Capture Outputs section for details.
• frame_buffer_size: The maximum size the internal frame buffer can grow to.

import d3dshot

d = d3dshot.create()

To use D3DShot, ensure your environment meets the following requirements:

• OS: Windows 8.1+ (64-bit)
• Python: Python 3.6+ (64-bit)

Note for Laptop Users: If you are using a hybrid-GPU system (e.g., Intel integrated graphics + NVIDIA discrete GPU), you may need to follow specific installation notes due to how Windows handles Desktop Duplication on hybrid systems.

Install the d3dshot package using pip. The library automatically installs its core dependencies: comtypes and Pillow.

pip install d3dshot

D3DShot allows you to inspect and select specific monitors in a multi-monitor setup.

• Use d.displays to get a list of all detected displays.
• Assign a specific display to d.display to change the capture target. By default, the primary display is selected.

# List all displays
print(d.displays)

# Select the second display
d.display = d.displays[1]

For high-speed or continuous capture, use capture() and stop(). This starts a non-blocking, threaded capture process that fills an internal frame buffer. You can then retrieve frames using get_latest_frame() or get_frame_stack().

import d3dshot
import time

d = d3dshot.create()

# Start non-blocking capture
d.capture()

# Wait for the desired duration
time.sleep(5)

# Stop the capture process
d.stop()

# Retrieve the most recent frame
latest_frame = d.get_latest_frame()

You can capture a single frame using screenshot() or save it directly to a file using screenshot_to_disk().

screenshot()

Returns a single frame in the format specified by your capture_output setting.

• Optional kwarg: region (a region tuple).

screenshot_to_disk()

Saves a single frame to a file and returns the full path to the saved image.

• Optional kwargs:
  • directory: Path to write the file (defaults to working directory).
  • file_name: Filename with permitted extensions .png or .jpg. If omitted, uses <time.time()>.png.
  • region: A region tuple.

# Capture a screenshot to memory
img = d.screenshot()

# Capture a specific region
img = d.screenshot(region=(0, 0, 1920, 1080))

# Save a screenshot to disk
d.screenshot_to_disk(directory='captures', file_name='shot.png')

D3DShot automatically detects all available displays. You can access the list of detected displays via d.displays and switch the active capture target by assigning a display object to d.display.

d = d3dshot.create()

# List all detected displays
print(d.displays)

# Set capture to the second monitor
d.display = d.displays[1]

# Verify current display
print(d.display)