# iOS Simulator Screenshot Capture Parameters and Options: Complete Guide

> Master iOS Simulator screenshot capture with the capture_screenshot function. Explore parameters like udid, output_path, and size for precise image control. Get stunning device snapshots.

- Repository: [Conor/ios-simulator-skill](https://github.com/conorluddy/ios-simulator-skill)
- Tags: how-to-guide
- Published: 2026-02-27

---

**The `capture_screenshot` function in [`screenshot_utils.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/screenshot_utils.py) accepts seven core parameters—`udid`, `output_path`, `size`, `inline`, `app_name`, `screen_name`, and `state`—to control device targeting, image scaling, output format, and semantic naming when capturing iOS Simulator screenshots.**

The `conorluddy/ios-simulator-skill` repository provides a Python utility layer that wraps the `xcrun simctl io` command, adding intelligent resizing, base64 encoding, and semantic filename generation for automation workflows. Understanding these iOS Simulator screenshot capture parameters and options allows you to optimize image size for token-constrained LLM vision models or generate organized file archives during test recording.

## Core Capture Parameters

The primary entry point `capture_screenshot` (defined in [`ios-simulator-skill/scripts/common/screenshot_utils.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/scripts/common/screenshot_utils.py)) exposes a typed interface for controlling every aspect of screenshot acquisition.

### Device Targeting and Output Destination

- **`udid`** (str, required): The device identifier of the target simulator. This maps directly to the `xcrun simctl io <udid> screenshot` command argument.
- **`output_path`** (str | None): Explicit filesystem destination for the captured image. When omitted, the function invokes `generate_screenshot_name` to create a semantic filename based on contextual metadata.

### Image Sizing and Scaling Presets

The **`size`** parameter accepts four string presets that determine scaling factors for token-optimized or storage-efficient captures:

- **`"full"`**: 1.0× scale (original resolution)
- **`"half"`**: 0.5× scale (default)
- **`"quarter"`**: 0.25× scale
- **`"thumb"`**: 0.1× scale

Internally, `capture_screenshot` delegates to `get_size_preset(size)` to map these strings to coordinate tuples, then conditionally calls `resize_screenshot` using Lanczos filtering when the preset differs from `"full"`.

### Inline vs. File Output Modes

The **`inline`** boolean toggles between two distinct return formats:

- **`inline=False`** (default): Returns a dictionary with `'mode': 'file'`, including `'file_path'`, `'size_bytes'`, `'width'`, `'height'`, and `'size_preset'`.
- **`inline=True`**: Returns a dictionary with `'mode': 'inline'`, containing `'base64_data'` (PNG), `'mime_type': 'image/png'`, plus dimensions and preset metadata.

Inline mode is particularly useful for vision-based automation pipelines where images must be passed directly to LLM APIs without filesystem I/O.

### Semantic Filename Components

When `output_path` is omitted, three optional parameters drive the automatic filename generator:

- **`app_name`** (str | None): Application identifier (e.g., "MyApp")
- **`screen_name`** (str | None): Logical screen identifier (e.g., "Login", "Dashboard")
- **`state`** (str | None): Descriptive state (e.g., "Empty", "Error", "Loaded")

These values feed into `generate_screenshot_name`, which concatenates them with a timestamp to produce human-readable paths like `MyApp_Login_Empty_20240115_143022.png`.

## Implementation Details in screenshot_utils.py

The capture workflow follows a strict four-step pipeline inside [`ios-simulator-skill/scripts/common/screenshot_utils.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/scripts/common/screenshot_utils.py):

1. Execute `xcrun simctl io <udid> screenshot <temp_path>` to generate a raw PNG
2. If `size` is not `"full"` and Pillow is available, call `resize_screenshot` to scale the image using the preset factor
3. For **inline mode**: Read the (possibly resized) image, base64-encode it, delete temporary files, and return the data URI structure
4. For **file mode**: Move or save the image to the final `output_path` and return filesystem metadata

### Size Preset Resolution Mapping

The helper `get_size_preset` (lines 78-86) implements the scaling lookup:

```python

# Mapping from screenshot_utils.py

presets = {
    "full": (1.0, 1.0),
    "half": (0.5, 0.5),
    "quarter": (0.25, 0.25),
    "thumb": (0.1, 0.1)
}

```

### Image Processing Pipeline

The `resize_screenshot` function (lines 100-108) handles the actual pixel manipulation:

- Opens source image via Pillow (PIL)
- Computes new dimensions using the preset scaling factor
- Applies Lanczos resampling (high-quality downsampling)
- Saves with JPEG quality 85 by default, or PNG preservation based on context
- Generates suffixed filenames (e.g., `_half`, `_thumb`) when `output_path` is not explicitly provided

## Practical Code Examples

### Capturing Base64 Inline Screenshots

Use this pattern for vision-based automation where you need to send image data directly to an API:

```python
from ios_simulator_skill.scripts.common.screenshot_utils import capture_screenshot

result = capture_screenshot(
    udid="A1B2C3D4-5678-90AB-CDEF-1234567890AB",
    size="quarter",          # Token-friendly reduced size

    inline=True,             # Return base64 data instead of file

    app_name="MyApp",
    screen_name="Login",
    state="Empty"
)

# Access the base64 PNG data

print(result["base64_data"][:60] + "...")
print(f"Dimensions: {result['width']}x{result['height']}")

```

### File Mode with Automatic Semantic Naming

When you want persistent storage with organized filenames:

```python
from ios_simulator_skill.scripts.common.screenshot_utils import capture_screenshot

result = capture_screenshot(
    udid="A1B2C3D4-5678-90AB-CDEF-1234567890AB",
    size="full",             # Preserve original resolution

    inline=False,            # Write to filesystem

    app_name="MyApp",
    screen_name="Home",
    state="Loaded"
)

print("Saved to:", result["file_path"])
print(f"Size on disk: {result['size_bytes']} bytes")

```

### Integration with Test Recorders

The `TestRecorder` class in [`ios-simulator-skill/scripts/test_recorder.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/scripts/test_recorder.py) demonstrates production usage by wrapping the same utility:

```python
recorder.step(
    description="Verify dashboard rendering",
    screen_name="Dashboard",
    state="Ready"
)

# Internally invokes capture_screenshot with the recorder's configured size/inline flags

```

## Summary

- The `capture_screenshot` function in [`screenshot_utils.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/screenshot_utils.py) wraps `xcrun simctl io` with seven configurable parameters for device targeting, sizing, and naming.
- Four size presets (`full`, `half`, `quarter`, `thumb`) control scaling factors from 1.0× down to 0.1×, processed via Lanczos filtering in `resize_screenshot`.
- The `inline` parameter switches between file output (with semantic naming via `app_name`, `screen_name`, `state`) and base64-encoded PNG data for direct API consumption.
- All processing logic resides in [`ios-simulator-skill/scripts/common/screenshot_utils.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/scripts/common/screenshot_utils.py), with workflow examples available in [`test_recorder.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/test_recorder.py).

## Frequently Asked Questions

### What are the valid values for the size parameter in iOS Simulator screenshot capture?

The `size` parameter accepts four string presets defined in `get_size_preset`: `"full"` (1.0×), `"half"` (0.5×), `"quarter"` (0.25×), and `"thumb"` (0.1×). The default value is `"half"`, which provides a balance between image clarity and token efficiency for LLM vision tasks.

### How does inline mode differ from file mode when capturing screenshots?

When `inline=True`, `capture_screenshot` returns a dictionary containing `base64_data` (a base64-encoded PNG string) and removes temporary files after encoding. When `inline=False` (the default), the function writes the image to disk and returns a dictionary with `file_path`, `size_bytes`, and dimensions. Inline mode eliminates filesystem overhead for API-based automation, while file mode is preferable for debugging and archival purposes.

### What happens if I don't specify an output_path when capturing a screenshot?

If `output_path` is `None`, the function calls `generate_screenshot_name` to construct a semantic filename using the optional `app_name`, `screen_name`, and `state` parameters combined with a timestamp. If no semantic components are provided, it falls back to `screenshot_<timestamp>.png` format. The file is saved to the current working directory or the system's temporary folder depending on the execution context.

### Can I capture screenshots without the Pillow library installed?

Yes, but with limitations. If Pillow is not available, `capture_screenshot` will still execute `xcrun simctl io <udid> screenshot` and return the raw PNG. However, any `size` preset other than `"full"` will be ignored because `resize_screenshot` depends on Pillow for Lanczos filtering and dimension calculations. For production use, install Pillow to ensure all scaling presets function correctly.