iOS Simulator Screenshot Capture Parameters and Options: Complete Guide

The capture_screenshot function in 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) 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:

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:

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

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:

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 demonstrates production usage by wrapping the same utility:

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 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, with workflow examples available in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}