PyBoy Advance

https://github.com/williamckha/pyboyadvance
Admin
PyBoy Advance is a Game Boy Advance emulator written in Python with Cython compilation for efficient...
Tokens:6,499
Snippets:51
Trust Score:8.3
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Build PyBoy Advance from Source

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

Install Cython and NumPy, then install PyBoy Advance in editable mode for building from source.

```bash
pip install cython numpy
pip install -e .
```

--------------------------------

### Run Interactive Windowed Playback

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

Start the emulator and open an SDL2 window for interactive play. Handles input and window events. Default keyboard mappings are provided.

```python
from pyboy_advance import PyBoyAdvance

emulator = PyBoyAdvance("game.gba", bios="gba_bios.bin")
emulator.run()  # Blocks until the window is closed
```

--------------------------------

### Install PyBoy Advance with pip

Source: https://github.com/williamckha/pyboyadvance/blob/master/README.md

Install the PyBoy Advance package using pip. Ensure you have a compatible Python environment.

```bash
pip install pyboy-advance
```

--------------------------------

### Single CPU/DMA Cycle Step

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

Execute a single CPU instruction or DMA transfer batch. Useful for fine-grained control or debugging. This example shows stepping through exactly one frame's worth of cycles.

```python
from pyboy_advance import PyBoyAdvance
from pyboy_advance.ppu.constants import CYCLES_FRAME

emulator = PyBoyAdvance("game.gba", bios="gba_bios.bin", skip_bios=True, emulation_speed=0)

# Manually step through exactly one frame worth of cycles
target = emulator.scheduler.cycles + CYCLES_FRAME
while emulator.scheduler.cycles < target:
    emulator.step()
```

--------------------------------

### Access Frame Buffer as NumPy Array with PyBoyAdvance

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

Retrieve the current rendered frame as a NumPy `ndarray` with shape `(160, 240, 3)` and `uint8` RGB values using `emulator.screen.ndarray`. Requires the `numpy` library to be installed. This can be used for image processing or saving screenshots.

```python
import numpy as np
from pyboy_advance import PyBoyAdvance

emulator = PyBoyAdvance("game.gba", bios="gba_bios.bin", skip_bios=True, emulation_speed=0)
emulator.frame(count=120)

frame = emulator.screen.ndarray
print(frame.shape)   # (160, 240, 3)
print(frame.dtype)   # uint8

# Compute average brightness of the frame
print(frame.mean())  # e.g., 127.4

# Use with OpenCV
import cv2
bgr = cv2.cvtColor(frame, cv2.COLOR_RGB2BGR)
cv2.imwrite("screenshot.png", bgr)
```

--------------------------------

### Run ROM with BIOS and Options

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

Launch a GBA ROM from the command line, specifying the BIOS path and optional arguments like skipping the BIOS animation or setting emulation speed.

```bash
# Run with a real BIOS
pyboy_advance --bios /path/to/gba_bios.bin game_rom.gba

# Skip BIOS boot animation (uses open-source Normatt BIOS replacement)
pyboy_advance --bios /path/to/gba_bios.bin --skip-bios game_rom.gba

# Run at 2× speed
pyboy_advance --bios /path/to/gba_bios.bin --emulation-speed 2 game_rom.gba

# Run uncapped (emulation-speed 0 = no frame limiter)
pyboy_advance --bios /path/to/gba_bios.bin --emulation-speed 0 game_rom.gba
```

--------------------------------

### Create Emulator Instance

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

Initialize the GBA emulator with ROM and BIOS paths. Options include skipping the BIOS and setting emulation speed.

```python
from pyboy_advance import PyBoyAdvance

# Minimal: provide ROM and BIOS paths
emulator = PyBoyAdvance(
    rom="kirby_nightmare.gba",
    bios="gba_bios.bin",
)

# Skip BIOS boot sequence (sets CPU registers to post-boot state)
emulator = PyBoyAdvance(
    rom="kirby_nightmare.gba",
    bios="gba_bios.bin",
    skip_bios=True,
)

# Uncapped speed (useful for headless/fast-forward scenarios)
emulator = PyBoyAdvance(
    rom="kirby_nightmare.gba",
    bios="gba_bios.bin",
    skip_bios=True,
    emulation_speed=0,  # 0 = unlimited; 1.0 = real-time; 2.0 = double speed
)
```

--------------------------------

### PyBoyAdvance.run

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

Opens an SDL2 window and enters the main event loop, rendering at 60 fps. Handles keyboard input, fullscreen toggle (F11), and clean shutdown (Escape or window close).

```APIDOC
## PyBoyAdvance.run — Interactive Windowed Playback

Opens an SDL2 window and enters the main event loop, rendering at 60 fps. Handles keyboard input, fullscreen toggle (F11), and clean shutdown (Escape or window close).

Default keyboard mapping:
| GBA Button     | Key         |
|----------------|-------------|
| A              | `A`         |
| B              | `S`         |
| Select         | `Backspace` |
| Start          | `Enter`     |
| D-Pad          | Arrow keys  |
| L Shoulder     | `Q`         |
| R Shoulder     | `W`         |

```python
from pyboy_advance import PyBoyAdvance

emulator = PyBoyAdvance("game.gba", bios="gba_bios.bin")
emulator.run()  # Blocks until the window is closed
```
```

--------------------------------

### PyBoyAdvance.__init__

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

Constructs and fully initializes the GBA emulator. Accepts a path to a ROM file or a pre-loaded GamePak object.

```APIDOC
## PyBoyAdvance.__init__ — Create an Emulator Instance

Constructs and fully initializes the GBA emulator, wiring together the CPU, memory bus, PPU, DMA, timers, keypad, and scheduler. Accepts a path to a ROM file or a pre-loaded `GamePak` object.

```python
from pyboy_advance import PyBoyAdvance

# Minimal: provide ROM and BIOS paths
emulator = PyBoyAdvance(
    rom="kirby_nightmare.gba",
    bios="gba_bios.bin",
)

# Skip BIOS boot sequence (sets CPU registers to post-boot state)
emulator = PyBoyAdvance(
    rom="kirby_nightmare.gba",
    bios="gba_bios.bin",
    skip_bios=True,
)

# Uncapped speed (useful for headless/fast-forward scenarios)
emulator = PyBoyAdvance(
    rom="kirby_nightmare.gba",
    bios="gba_bios.bin",
    skip_bios=True,
    emulation_speed=0,  # 0 = unlimited; 1.0 = real-time; 2.0 = double speed
)
```
```

--------------------------------

### Running PyBoy Advance Tests

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

Instructions on how to run PyBoy Advance tests using pytest, including the requirement for a GBA BIOS image.

```bash
# Run tests with:
# pytest --bios /path/to/gba_bios.bin tests/
```

--------------------------------

### GamePak.from_file / GamePak constructor

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

Loads a GBA ROM cartridge from a file path or raw bytes. Automatically detects backup storage type.

```APIDOC
## `GamePak` — Load a ROM Cartridge

Represents a GBA ROM cartridge. Automatically detects backup storage type (SRAM, Flash 64K, Flash 128K, EEPROM) from the ROM header string. Can be constructed from a file path or raw bytes.

### Methods
- **`from_file(file_path: str)`**: Creates a `GamePak` instance from a ROM file.
- **`GamePak(rom_bytes: bytes)`**: Creates a `GamePak` instance from raw ROM bytes.

### Attributes
- **`backup_storage_type`**: The detected backup storage type (e.g., `BackupStorageType.SRAM`).

### Example
```python
from pyboy_advance.memory.gamepak import GamePak
from pyboy_advance.memory.constants import BackupStorageType

# Load from file
gamepak = GamePak.from_file("game_rom.gba")
print(gamepak.backup_storage_type)
# e.g., BackupStorageType.SRAM, BackupStorageType.FLASH_64, etc.

# Load from raw bytes
with open("game_rom.gba", "rb") as f:
    rom_bytes = f.read()
gamepak = GamePak(rom_bytes)

# Pass directly to emulator constructor
from pyboy_advance import PyBoyAdvance
emulator = PyBoyAdvance(rom=gamepak, bios="gba_bios.bin", skip_bios=True)
```
```

--------------------------------

### Launch PyBoy Advance from Terminal

Source: https://github.com/williamckha/pyboyadvance/blob/master/README.md

Launch the emulator from the command line, specifying the path to the BIOS file and the Game Boy Advance ROM.

```bash
pyboy_advance --bios /path/to/bios.bin game_rom.gba
```

--------------------------------

### Load GBA ROM Cartridge with GamePak

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

The `GamePak` class represents a GBA ROM cartridge and can be loaded from a file path or raw bytes. It automatically detects the backup storage type. The `GamePak` object can then be passed directly to the `PyBoyAdvance` constructor.

```python
from pyboy_advance.memory.gamepak import GamePak
from pyboy_advance.memory.constants import BackupStorageType

# Load from file
gamepak = GamePak.from_file("game_rom.gba")
print(gamepak.backup_storage_type)
# e.g., BackupStorageType.SRAM, BackupStorageType.FLASH_64, etc.

# Load from raw bytes (e.g., downloaded ROM data)
with open("game_rom.gba", "rb") as f:
    rom_bytes = f.read()
gamepak = GamePak(rom_bytes)

# Pass directly to emulator constructor
from pyboy_advance import PyBoyAdvance
emulator = PyBoyAdvance(rom=gamepak, bios="gba_bios.bin", skip_bios=True)
```

--------------------------------

### PyBoyAdvance.step

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

Executes one CPU instruction (or one DMA transfer batch if DMA is active). Useful for fine-grained emulation control or debugging.

```APIDOC
## PyBoyAdvance.step — Single CPU/DMA Cycle Step

Executes one CPU instruction (or one DMA transfer batch if DMA is active). Useful for fine-grained emulation control or debugging.

```python
from pyboy_advance import PyBoyAdvance
from pyboy_advance.ppu.constants import CYCLES_FRAME

emulator = PyBoyAdvance("game.gba", bios="gba_bios.bin", skip_bios=True, emulation_speed=0)

# Manually step through exactly one frame worth of cycles
target = emulator.scheduler.cycles + CYCLES_FRAME
while emulator.scheduler.cycles < target:
    emulator.step()
```
```

--------------------------------

### Simulate GBA Button Presses with PyBoyAdvance

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

Use `press_key` and `release_key` with the `Key` enum to simulate button inputs. This is useful for scripted gameplay, automated testing, or AI agents. Hold buttons for a specified number of frames using `emulator.frame(count=...)`.

```python
from pyboy_advance import PyBoyAdvance
from pyboy_advance.constants import Key

emulator = PyBoyAdvance("game.gba", bios="gba_bios.bin", skip_bios=True, emulation_speed=0)

# Hold the Start button for 10 frames (e.g., to skip a title screen)
emulator.press_key(Key.BUTTON_START)
emulator.frame(count=10)
emulator.release_key(Key.BUTTON_START)

# Simultaneous inputs: hold A and D-Pad Right
emulator.press_key(Key.BUTTON_A)
emulator.press_key(Key.DPAD_RIGHT)
emulator.frame(count=5)
emulator.release_key(Key.BUTTON_A)
emulator.release_key(Key.DPAD_RIGHT)

# All available Key values:
# Key.BUTTON_A, Key.BUTTON_B, Key.BUTTON_SELECT, Key.BUTTON_START
# Key.DPAD_RIGHT, Key.DPAD_LEFT, Key.DPAD_UP, Key.DPAD_DOWN
# Key.SHOULDER_RIGHT, Key.SHOULDER_LEFT
```

--------------------------------

### Advance N Frames Headless

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

Execute one or more GBA frames without a window. Optionally skip rendering on intermediate frames for performance. Screenshots can be captured.

```python
from pyboy_advance import PyBoyAdvance

emulator = PyBoyAdvance("game.gba", bios="gba_bios.bin", skip_bios=True, emulation_speed=0)

# Advance a single frame (with rendering)
emulator.frame()

# Skip 299 frames of rendering, render only the 300th
emulator.frame(count=300, render=True)

# Fast-forward 600 frames with no rendering at all
emulator.frame(count=600, render=False)

# Capture a screenshot after advancing
img = emulator.screen.image
img.save("frame_600.png")
```

--------------------------------

### PyBoyAdvance.press_key / PyBoyAdvance.release_key

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

Simulates GBA button presses and releases using the Key enum. This is useful for scripted gameplay, automated testing, or AI agents.

```APIDOC
## `PyBoyAdvance.press_key` / `PyBoyAdvance.release_key` — Programmatic Input

Simulates GBA button presses and releases via the `Key` enum. Useful for scripted gameplay, automated testing, or AI agents.

### Parameters
- **key** (`Key`) - Required - The button to press or release.

### Example
```python
from pyboy_advance import PyBoyAdvance
from pyboy_advance.constants import Key

emulator = PyBoyAdvance("game.gba", bios="gba_bios.bin", skip_bios=True, emulation_speed=0)

# Hold the Start button for 10 frames
emulator.press_key(Key.BUTTON_START)
emulator.frame(count=10)
emulator.release_key(Key.BUTTON_START)

# Simultaneous inputs
emulator.press_key(Key.BUTTON_A)
emulator.press_key(Key.DPAD_RIGHT)
emulator.frame(count=5)
emulator.release_key(Key.BUTTON_A)
emulator.release_key(Key.DPAD_RIGHT)
```

### Available Keys
- `Key.BUTTON_A`, `Key.BUTTON_B`, `Key.BUTTON_SELECT`, `Key.BUTTON_START`
- `Key.DPAD_RIGHT`, `Key.DPAD_LEFT`, `Key.DPAD_UP`, `Key.DPAD_DOWN`
- `Key.SHOULDER_RIGHT`, `Key.SHOULDER_LEFT`
```

--------------------------------

### Pytest Fixtures for Automated ROM Testing

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

The Pytest test suite offers reusable fixtures for automated ROM testing. These fixtures handle on-demand ROM downloads, emulator instantiation, and pixel-accurate screenshot comparisons, simplifying the testing process.

```python
# tests/test_example.py
import pytest
from pyboy_advance.constants import Key
```

--------------------------------

### Use PyBoy Advance in Python Scripts

Source: https://github.com/williamckha/pyboyadvance/blob/master/README.md

Import and use the PyBoyAdvance class in your Python scripts to run a Game Boy Advance ROM. Provide the path to the ROM and BIOS files.

```python
from pyboy_advance import PyBoyAdvance

emulator = PyBoyAdvance(rom="game_rom.gba", bios="/path/to/bios.bin")
emulator.run()
```

--------------------------------

### Screen.image

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

Accesses the current rendered frame as a PIL Image object. The image is in RGB mode and sized 240x160 pixels.

```APIDOC
## `Screen.image` — Access Frame Buffer as PIL Image

Returns the current rendered frame as a `PIL.Image.Image` object in RGB mode, sized 240×160 pixels. Requires `Pillow` to be installed.

### Returns
- **image** (`PIL.Image.Image`) - A PIL Image object representing the current frame.

### Example
```python
from pyboy_advance import PyBoyAdvance

emulator = PyBoyAdvance("game.gba", bios="gba_bios.bin", skip_bios=True, emulation_speed=0)
emulator.frame(count=120)

img = emulator.screen.image
print(img.size)   # (240, 160)
print(img.mode)   # 'RGB'

# Save screenshot
img.save("screenshot.png")

# Compare two frames for visual regression testing
import PIL.ImageChops
emulator.frame(count=60)
img2 = emulator.screen.image
diff = PIL.ImageChops.difference(img, img2)
print(diff.getbbox())  # None if frames are identical
```
```

--------------------------------

### Test Button Input Response in PyBoy Advance

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

This test checks the emulator's response to button presses, specifically the 'A' button. It simulates pressing and releasing the button and captures the screen state after a short delay to verify the effect.

```python
@pytest.mark.rom_url("https://example.com/test_roms/input_test.gba")
def test_button_a_response(emulator, assert_expected_image):
    emulator.frame(count=60)
    emulator.press_key(Key.BUTTON_A)
    emulator.frame(count=10)
    emulator.release_key(Key.BUTTON_A)
    emulator.frame(count=60)
    assert_expected_image(emulator.screen.image, expected_img_name="after_button_a.png")
```

--------------------------------

### PyBoyAdvance.frame

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

Executes one or more complete GBA frames (280,896 cycles each) without opening a window. Optionally skips rendering on intermediate frames for maximum throughput.

```APIDOC
## PyBoyAdvance.frame — Advance by N Frames (Headless)

Executes one or more complete GBA frames (280,896 cycles each) without opening a window. Optionally skips rendering on intermediate frames for maximum throughput.

```python
from pyboy_advance import PyBoyAdvance

emulator = PyBoyAdvance("game.gba", bios="gba_bios.bin", skip_bios=True, emulation_speed=0)

# Advance a single frame (with rendering)
emulator.frame()

# Skip 299 frames of rendering, render only the 300th
emulator.frame(count=300, render=True)

# Fast-forward 600 frames with no rendering at all
emulator.frame(count=600, render=False)

# Capture a screenshot after advancing
img = emulator.screen.image
img.save("frame_600.png")
```
```

--------------------------------

### Adjust Emulation Speed at Runtime with PyBoyAdvance

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

Control the frame limiter target speed using `set_emulation_speed`. A value of `1.0` is real-time (60 fps), `0` disables the limiter for maximum speed, and values above `1.0` run faster than real time. Negative speeds will raise a `ValueError`.

```python
from pyboy_advance import PyBoyAdvance

emulator = PyBoyAdvance("game.gba", bios="gba_bios.bin", skip_bios=True)

# Start at real-time speed
emulator.set_emulation_speed(1.0)
emulator.frame(count=60)

# Fast-forward to 4× speed
emulator.set_emulation_speed(4.0)
emulator.frame(count=600)

# Uncapped (maximum speed for headless work)
emulator.set_emulation_speed(0)
emulator.frame(count=6000)

# ValueError raised for negative speeds
try:
    emulator.set_emulation_speed(-1)
except ValueError as e:
    print(e)  # "Emulation speed must be 0 or greater"
```

--------------------------------

### Key Enum

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

An enumeration of all GBA input buttons, mirroring the hardware KEYCNT register bits.

```APIDOC
## `Key` Enum — GBA Button Constants

`IntFlag` enumeration of all GBA input buttons, mirroring the hardware KEYCNT register bits.

### Constants
- `Key.BUTTON_A`
- `Key.BUTTON_B`
- `Key.BUTTON_SELECT`
- `Key.BUTTON_START`
- `Key.DPAD_RIGHT`
- `Key.DPAD_LEFT`
- `Key.DPAD_UP`
- `Key.DPAD_DOWN`
- `Key.SHOULDER_RIGHT`
- `Key.SHOULDER_LEFT`

### Example
```python
from pyboy_advance.constants import Key

# Individual keys
print(Key.BUTTON_A)

# IntFlag allows bitwise combinations
combo = Key.BUTTON_A | Key.BUTTON_B
print(int(combo))   # 3
```
```

--------------------------------

### Access Frame Buffer as PIL Image with PyBoyAdvance

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

Obtain the current rendered frame as a `PIL.Image.Image` object in RGB mode, sized 240x160 pixels, using `emulator.screen.image`. Requires the `Pillow` library. This is useful for saving screenshots or performing visual regression testing.

```python
from pyboy_advance import PyBoyAdvance

emulator = PyBoyAdvance("game.gba", bios="gba_bios.bin", skip_bios=True, emulation_speed=0)
emulator.frame(count=120)

img = emulator.screen.image
print(img.size)   # (240, 160)
print(img.mode)   # 'RGB'

# Save screenshot
img.save("screenshot.png")

# Compare two frames for visual regression testing
import PIL.ImageChops
emulator.frame(count=60)
img2 = emulator.screen.image
diff = PIL.ImageChops.difference(img, img2)
print(diff.getbbox())  # None if frames are identical
```

--------------------------------

### Test Title Screen Rendering with PyBoy Advance

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

This test verifies that the title screen of a GBA ROM renders correctly by comparing it against a reference screenshot. It advances the emulator by 120 frames before capturing the screen image.

```python
@pytest.mark.rom_url("https://example.com/test_roms/hello_world.gba")
def test_title_screen_renders(emulator, assert_expected_image):
    """Verify the title screen matches the expected reference screenshot."""
    # Advance 120 frames (2 seconds at 60 fps)
    emulator.frame(count=120)

    img = emulator.screen.image
    # Compares against tests/expected/title_screen_renders.png
    assert_expected_image(img)
```

--------------------------------

### PyBoyAdvance.set_emulation_speed

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

Adjusts the frame limiter target speed at runtime. A value of 1.0 is real-time (60 fps), 0 disables the limiter, and values above 1.0 run faster than real time.

```APIDOC
## `PyBoyAdvance.set_emulation_speed` — Adjust Speed at Runtime

Changes the frame limiter target speed. A value of `1.0` is real-time (60 fps), `0` disables the limiter entirely, and values above `1.0` run faster than real time.

### Parameters
- **speed** (`float`) - Required - The target emulation speed. `0` disables the frame limiter.

### Example
```python
from pyboy_advance import PyBoyAdvance

emulator = PyBoyAdvance("game.gba", bios="gba_bios.bin", skip_bios=True)

# Start at real-time speed
emulator.set_emulation_speed(1.0)
emulator.frame(count=60)

# Fast-forward to 4x speed
emulator.set_emulation_speed(4.0)
emulator.frame(count=600)

# Uncapped speed
emulator.set_emulation_speed(0)
emulator.frame(count=6000)

# ValueError raised for negative speeds
try:
    emulator.set_emulation_speed(-1)
except ValueError as e:
    print(e)  # "Emulation speed must be 0 or greater"
```
```

--------------------------------

### GBA Button Constants with Key Enum

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

The `Key` enum provides an `IntFlag` enumeration of all GBA input buttons, mirroring the hardware KEYCNT register bits. Bitwise combinations can be created using the `|` operator.

```python
from pyboy_advance.constants import Key

# Individual keys
Key.BUTTON_A        # Bit 0
Key.BUTTON_B        # Bit 1
Key.BUTTON_SELECT   # Bit 2
Key.BUTTON_START    # Bit 3
Key.DPAD_RIGHT      # Bit 4
Key.DPAD_LEFT       # Bit 5
Key.DPAD_UP         # Bit 6
Key.DPAD_DOWN       # Bit 7
Key.SHOULDER_RIGHT  # Bit 8
Key.SHOULDER_LEFT   # Bit 9

# IntFlag allows bitwise combinations
combo = Key.BUTTON_A | Key.BUTTON_B
print(int(combo))   # 3
```

--------------------------------

### Screen.ndarray

Source: https://context7.com/williamckha/pyboyadvance/llms.txt

Accesses the current rendered frame as a NumPy ndarray. The array has a shape of (160, 240, 3) with uint8 RGB values.

```APIDOC
## `Screen.ndarray` — Access Frame Buffer as NumPy Array

Returns the current rendered frame as a NumPy `ndarray` of shape `(160, 240, 3)` with `uint8` RGB values. Requires `numpy` to be installed.

### Returns
- **ndarray** (`np.ndarray`) - A NumPy array representing the current frame's pixel data.

### Example
```python
import numpy as np
from pyboy_advance import PyBoyAdvance

emulator = PyBoyAdvance("game.gba", bios="gba_bios.bin", skip_bios=True, emulation_speed=0)
emulator.frame(count=120)

frame = emulator.screen.ndarray
print(frame.shape)   # (160, 240, 3)
print(frame.dtype)   # uint8

# Compute average brightness of the frame
print(frame.mean())  # e.g., 127.4

# Use with OpenCV
import cv2
bgr = cv2.cvtColor(frame, cv2.COLOR_RGB2BGR)
cv2.imwrite("screenshot.png", bgr)
```
```
Tokens:
Raw