Skip to main content
Capture screenshots of the desktop for visual verification, debugging, and documentation.

Overview

Screenshot capture enables:
  • Full screen screenshots
  • Region-specific screenshots
  • Visual verification of GUI state
  • Documentation and debugging
Desktop automation requires a template with desktop support. Ensure your sandbox has desktop capabilities enabled.

Full Screen Screenshot

Capture the entire screen:
  • Python
  • JavaScript
from hopx_ai import Sandbox

sandbox = Sandbox.create(template="desktop")

# Capture full screen
img_bytes = sandbox.desktop.screenshot()

# Save to file
with open('screenshot.png', 'wb') as f:
    f.write(img_bytes)

Region Screenshot

Capture a specific region of the screen:
  • Python
  • JavaScript
# Capture region: x=100, y=100, width=500, height=300
img_bytes = sandbox.desktop.screenshot_region(100, 100, 500, 300)

# Save to file
with open('region.png', 'wb') as f:
    f.write(img_bytes)

Window Screenshot

Capture a specific window (X11 advanced feature):
  • Python
  • JavaScript
# Capture active window
img_bytes = sandbox.desktop.capture_window()

# Capture specific window
windows = sandbox.desktop.get_windows()
if windows:
    window_id = windows[0].id
    img_bytes = sandbox.desktop.capture_window(window_id)

# Save to file
with open('window.png', 'wb') as f:
    f.write(img_bytes)

Screenshot Workflow

Complete screenshot workflow:
  • Python
  • JavaScript
from hopx_ai import Sandbox
import time

sandbox = Sandbox.create(template="desktop")

try:
    # Start application (example)
    # ... application setup ...
    
    # Wait for application to load
    time.sleep(2)
    
    # Capture initial state
    initial = sandbox.desktop.screenshot()
    with open('initial.png', 'wb') as f:
        f.write(initial)
    
    # Perform actions
    sandbox.desktop.click(400, 300)
    time.sleep(1)
    
    # Capture after action
    after = sandbox.desktop.screenshot()
    with open('after.png', 'wb') as f:
        f.write(after)
    
    # Capture specific region
    region = sandbox.desktop.screenshot_region(100, 100, 400, 300)
    with open('region.png', 'wb') as f:
        f.write(region)
    
finally:
    sandbox.kill()

Image Format

Screenshots are returned as PNG image bytes:
  • Format: PNG
  • Color depth: 24-bit RGB
  • Compression: PNG compression

Finding Coordinates

Use screenshots to find coordinates for mouse operations:
  • Python
  • JavaScript
# Take screenshot
img_bytes = sandbox.desktop.screenshot()

# Save and inspect in image viewer
with open('reference.png', 'wb') as f:
    f.write(img_bytes)

# Use coordinates from image viewer
sandbox.desktop.click(400, 300)  # Coordinates from reference.png

Next Steps