> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Screen Recording

> Record sandbox screen activity as video for desktop automation in HopX sandboxes. Capture screen recordings of desktop interactions, GUI workflows, and visual demonstrations. Learn how to start and stop recordings, download video files, and use recordings for documentation or testing. Includes Python and JavaScript SDK examples.

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

<Note>
  Desktop automation requires a template with desktop support. Ensure your sandbox has desktop capabilities enabled.
</Note>

## Starting Recording

Start a screen recording:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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}")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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
    ```
  </Tab>
</Tabs>

## Recording Options

Configure recording settings:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # 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"
    )
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    // Note: JavaScript SDK may have different parameters
    await sandbox.desktop.startRecording('output.mp4');
    ```
  </Tab>
</Tabs>

## Stopping Recording

Stop a recording and get final information:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # 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}")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    // 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`);
    ```
  </Tab>
</Tabs>

## Recording Status

Check recording status:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # 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)
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    // 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`);
    ```
  </Tab>
</Tabs>

## Downloading Recording

Download the recorded video:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # 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")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    // Download recording
    const video = await sandbox.desktop.downloadRecording(recordingId);

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

    console.log(`Video saved: ${video.length} bytes`);
    ```
  </Tab>
</Tabs>

## Complete Example

Complete recording workflow:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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();
    }
    ```
  </Tab>
</Tabs>

## 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

<Tip>
  Use lower FPS and quality for longer recordings to reduce file size. Use higher settings for short, high-quality demos.
</Tip>

## Related

* [Screenshots](/core-concepts/desktop/screenshots) - Capture static screenshots
* [VNC Server](/core-concepts/desktop/vnc-server) - Remote desktop access
* **SDK**: [sandbox.desktop.start\_recording()](/sdk/python/desktop#start_recording) - Python SDK method

## Next Steps

* Learn about [Screenshots](/core-concepts/desktop/screenshots) for static image capture

* Explore [VNC Server](/core-concepts/desktop/vnc-server) for live remote access

* Review [Mouse Control](/core-concepts/desktop/mouse-control) and [Keyboard Control](/core-concepts/desktop/keyboard-control) for automation

* [Screenshots](/core-concepts/desktop/screenshots) - Capture static screenshots

* [Window Management](/core-concepts/desktop/window-management) - Manage windows during recording

* **[CLI System Commands](/cli/commands/system)** - System operations from CLI