Skip to main content
Record screen activity as video files for documentation, testing, and debugging.

​
Overview

Screen recording enables:
  • Recording desktop activity as video
  • Configurable frame rate and quality
  • Downloading recorded videos
  • Monitoring recording status
Desktop automation requires a template with desktop support. Ensure your sandbox has desktop capabilities enabled.

​
Starting Recording

Start a screen recording:
  • Python
  • JavaScript
from hopx_ai import Sandbox

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

# Start recording with default settings
recording = sandbox.desktop.start_recording()

# Start with custom settings
recording = sandbox.desktop.start_recording(
    fps=30,           # 30 frames per second
    format="mp4",     # MP4 format
    quality="high"    # High quality
)

print(f"Recording ID: {recording.recording_id}")
print(f"Status: {recording.status}")

​
Recording Options

Configure recording settings:
  • Python
  • JavaScript
# Low quality, low FPS (smaller file)
recording = sandbox.desktop.start_recording(
    fps=10,
    format="mp4",
    quality="low"
)

# Medium quality (balanced)
recording = sandbox.desktop.start_recording(
    fps=15,
    format="mp4",
    quality="medium"
)

# High quality, high FPS (larger file)
recording = sandbox.desktop.start_recording(
    fps=30,
    format="mp4",
    quality="high"
)

​
Stopping Recording

Stop a recording and get final information:
  • Python
  • JavaScript
# Start recording
recording = sandbox.desktop.start_recording()

# ... perform actions ...

# Stop recording
final_recording = sandbox.desktop.stop_recording(recording.recording_id)

print(f"Duration: {final_recording.duration}s")
print(f"File size: {final_recording.file_size} bytes")
print(f"Format: {final_recording.format}")

​
Recording Status

Check recording status:
  • Python
  • JavaScript
# Get recording status
status = sandbox.desktop.get_recording_status(recording.recording_id)

print(f"Status: {status.status}")
print(f"Duration: {status.duration}s")
print(f"File size: {status.file_size} bytes")

# Check if ready
if status.status == "stopped":
    video = sandbox.desktop.download_recording(recording.recording_id)

​
Downloading Recording

Download the recorded video:
  • Python
  • JavaScript
# Download recording
video_bytes = sandbox.desktop.download_recording(recording.recording_id)

# Save to file
with open('recording.mp4', 'wb') as f:
    f.write(video_bytes)

print(f"Video saved: {len(video_bytes)} bytes")

​
Complete Example

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

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

try:
    # Start recording
    recording = sandbox.desktop.start_recording(
        fps=30,
        format="mp4",
        quality="high"
    )
    print(f"Recording started: {recording.recording_id}")
    
    # Perform actions to record
    sandbox.desktop.click(400, 300)
    time.sleep(1)
    sandbox.desktop.type("Hello, World!")
    time.sleep(2)
    
    # Stop recording
    final = sandbox.desktop.stop_recording(recording.recording_id)
    print(f"Recording stopped: {final.duration}s")
    
    # Wait for processing
    time.sleep(2)
    
    # Download video
    video = sandbox.desktop.download_recording(recording.recording_id)
    with open('demo.mp4', 'wb') as f:
        f.write(video)
    
    print(f"Video saved: {len(video)} bytes")
    
finally:
    sandbox.kill()

​
Recording Formats

Supported video formats:
  • MP4: H.264 encoded MP4 (recommended)
  • WebM: WebM format (if supported)

​
Quality Settings

Quality options:
  • low: Lower file size, lower quality
  • medium: Balanced quality and file size (default)
  • high: Higher quality, larger file size

​
Frame Rate

Frame rate options:
  • 10 fps: Lower file size, choppier video
  • 15 fps: Balanced (default)
  • 30 fps: Smooth video, larger file size
Use lower FPS and quality for longer recordings to reduce file size. Use higher settings for short, high-quality demos.

​
Next Steps