Screen Recording

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}")

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({ template: 'desktop' });

// Start recording
await sandbox.desktop.startRecording();

// Note: JavaScript SDK may have different parameters
// Check SDK documentation for exact API

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"
)

// Note: JavaScript SDK may have different parameters
await sandbox.desktop.startRecording('output.mp4');

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}")

// Start recording
await sandbox.desktop.startRecording();

// ... perform actions ...

// Stop recording
await sandbox.desktop.stopRecording();

// Get status
const status = await sandbox.desktop.getRecordingStatus();
console.log(`Duration: ${status.duration}s`);
console.log(`File size: ${status.fileSize} bytes`);

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)

// Get recording status
const status = await sandbox.desktop.getRecordingStatus();

console.log(`Status: ${status.status}`);
console.log(`Duration: ${status.duration}s`);
console.log(`File size: ${status.fileSize} bytes`);

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")

// Download recording
const video = await sandbox.desktop.downloadRecording(recordingId);

// Save to file
fs.writeFileSync('recording.mp4', video);

console.log(`Video saved: ${video.length} 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()

import { Sandbox } from '@hopx-ai/sdk';
import fs from 'fs';

const sandbox = await Sandbox.create({ template: 'desktop' });

try {
  // Start recording
  await sandbox.desktop.startRecording();
  console.log('Recording started');
  
  // Perform actions to record
  await sandbox.desktop.mouseClick(400, 300);
  await new Promise(resolve => setTimeout(resolve, 1000));
  await sandbox.desktop.keyboardType('Hello, World!');
  await new Promise(resolve => setTimeout(resolve, 2000));
  
  // Stop recording
  await sandbox.desktop.stopRecording();
  console.log('Recording stopped');
  
  // Wait for processing
  await new Promise(resolve => setTimeout(resolve, 2000));
  
  // Get status and download
  const status = await sandbox.desktop.getRecordingStatus();
  if (status.recordingId) {
    const video = await sandbox.desktop.downloadRecording(status.recordingId);
    fs.writeFileSync('demo.mp4', video);
    console.log(`Video saved: ${video.length} bytes`);
  }
  
} finally {
  await 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.

Screenshots - Capture static screenshots
VNC Server - Remote desktop access
SDK: sandbox.desktop.start_recording() - Python SDK method

Next Steps

Learn about Screenshots for static image capture
Explore VNC Server for live remote access
Review Mouse Control and Keyboard Control for automation
Screenshots - Capture static screenshots
Window Management - Manage windows during recording
CLI System Commands - System operations from CLI

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

Overview

Starting Recording

Recording Options

Stopping Recording

Recording Status

Downloading Recording

Complete Example

Recording Formats

Quality Settings

Frame Rate

Next Steps

​Overview

​Starting Recording

​Recording Options

​Stopping Recording

​Recording Status

​Downloading Recording

​Complete Example

​Recording Formats

​Quality Settings

​Frame Rate

​Related

​Next Steps

Overview

Starting Recording

Recording Options

Stopping Recording

Recording Status

Downloading Recording

Complete Example

Recording Formats

Quality Settings

Frame Rate

Related

Next Steps