# How the Token Optimization Technique Reduces Screenshot Data Size

> Discover how token optimization drastically shrinks screenshot data size. Learn how resizing PNGs before encoding reduces JSON payloads for efficient LLM processing.

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

---

**The token optimization technique reduces screenshot data size by resizing full-resolution PNG captures to smaller dimensions before base-64 encoding, shrinking JSON payloads from thousands of tokens to a few hundred while preserving visual usability for LLM processing.**

The **ios-simulator-skill** repository provides Python utilities for capturing and transmitting iOS simulator screenshots to LLM-driven applications. Because these screenshots are embedded as base-64 strings in JSON outputs consumed by language models, the **token optimization technique** is essential for managing API costs and staying within token limits without sacrificing diagnostic value.

## The Token Optimization Workflow

The implementation follows a four-stage pipeline 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) that balances image quality with transmission efficiency.

### Step 1: Capture Full-Resolution Screenshots

The process begins with `capture_screenshot(device_udid)`, which interfaces with the iOS Simulator to extract a raw PNG at full device resolution (e.g., 1240 × 2688 pixels on modern iPhones). This produces approximately 2 MB of binary data that would consume roughly 2,700 tokens if encoded directly to base-64 and embedded in JSON.

### Step 2: Resize with Aspect Ratio Preservation

The core optimization occurs in `resize_screenshot(image_bytes, max_width=800)`, which down-scales the image using Pillow (or the native macOS `sips` tool) while strictly preserving the aspect ratio. Reducing the maximum width to 800 pixels dramatically decreases the total pixel count, resulting in a smaller binary footprint before encoding even begins.

### Step 3: Base-64 Encoding for JSON Transmission

After resizing, the smaller PNG is re-encoded as a base-64 string. Because base-64 expansion is proportional to input size, the reduced image yields a significantly shorter string—often shrinking from ~2.7 KB of base-64 data to ~540 characters. This step ensures the JSON payload remains compact when transmitted via the `--json` output mode.

### Step 4: Transmit the Compact Payload

The optimized string is returned to callers and printed as part of a JSON response. The downstream LLM receives a payload that consumes approximately 80% fewer tokens than the original full-resolution capture, directly reducing API costs for visual-diff analysis or UI-element extraction workflows.

## Implementation Details and Source Files

According to the repository’s architectural documentation in [`CLAUDE.md`](https://github.com/conorluddy/ios-simulator-skill/blob/main/CLAUDE.md) under the *Shared Utilities* section, the `resize_screenshot()` function specifically implements "Token optimization" to support efficient screenshot transmission.

The primary implementation 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), where both `capture_screenshot` and `resize_screenshot` are defined. The design deliberately uses a fast lossless PNG encoder to ensure that runtime overhead remains negligible while token savings are substantial.

## Token Savings and Performance Impact

The technique delivers measurable reductions in token consumption:

- **Before optimization**: A 1240 × 2688 PNG (~2 MB) generates ~2,700 tokens in JSON.
- **After optimization**: Resized to 800 px width (~400 KB) generates ~540 tokens.
- **Net reduction**: Approximately 80% fewer tokens per screenshot.

Because LLM API pricing scales with token count, this reduction directly lowers operational costs for applications processing high volumes of simulator screenshots.

## Practical Implementation Example

The following code demonstrates the complete workflow from capture to optimized JSON payload:

```python
from ios_simulator_skill.scripts.common.screenshot_utils import (
    capture_screenshot,
    resize_screenshot,
)
import base64

# Capture a full-resolution screenshot from the currently booted simulator

full_png_bytes = capture_screenshot(device_udid="ABC123DEF456")

# Apply token optimisation: shrink the image to a max width of 800 px

optimized_png_bytes = resize_screenshot(full_png_bytes, max_width=800)

# Encode for JSON output (base-64 string)

encoded_image = base64.b64encode(optimized_png_bytes).decode()

# Example JSON payload that will now be far smaller in token count

payload = {
    "action": "screenshot",
    "udid": "ABC123DEF456",
    "image_base64": encoded_image,
    "success": True,
}
print(payload)

```

This implementation ensures that screenshots transmitted to LLM services remain lightweight while retaining sufficient resolution for automated visual analysis.

## Summary

- **Token optimization** reduces screenshot payload size by 80% through strategic resizing before base-64 encoding.
- The `resize_screenshot` function 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) performs the down-scaling using Pillow or macOS `sips` while preserving aspect ratio.
- Reducing image width to 800 pixels cuts token consumption from ~2,700 to ~540 tokens per image.
- The technique uses lossless PNG encoding to maintain image quality for visual-diff and UI-extraction tasks without significant runtime overhead.

## Frequently Asked Questions

### What is the token optimization technique in ios-simulator-skill?

The token optimization technique is a preprocessing strategy that resizes full-resolution iOS simulator screenshots to smaller dimensions before base-64 encoding them for JSON transmission. This reduces the character count of the resulting string, minimizing the token consumption when the data is processed by LLM APIs.

### How much does token optimization reduce API costs?

As implemented in [`screenshot_utils.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/screenshot_utils.py), the technique typically reduces token consumption by approximately 80%. For example, a standard iPhone screenshot that would consume 2,700 tokens when encoded at full resolution requires only 540 tokens after resizing to 800 pixels width, directly reducing per-request costs in token-based pricing models.

### Does token optimization impact screenshot quality?

The technique preserves the aspect ratio and uses lossless PNG encoding to maintain visual clarity for automated analysis tasks. While the absolute pixel count decreases, the resized images retain sufficient detail for LLM-driven visual-diff analysis and UI-element extraction workflows.

### Which functions handle token optimization in the codebase?

The optimization logic is implemented in `resize_screenshot()` within [`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). This function is typically called after `capture_screenshot()` processes the raw device capture, and before the image data is base-64 encoded for JSON output.