Touch anything. Automate everything.

Quick start

Install the tweak (see Installation), make sure python3 from the Procursus repo is present, then connect to the daemon on port 6000. The zxtouch Python module ships with the tweak.

from zxtouch.client import zxtouch
from zxtouch.touchtypes import *
import time

device = zxtouch("127.0.0.1")   # on-device, or your iPhone IP for remote

# a one-finger swipe down: down → move → up
device.touch(TOUCH_DOWN, 5, 400, 400)
time.sleep(0.4)
device.touch(TOUCH_MOVE, 5, 400, 600)
device.touch(TOUCH_UP,   5, 400, 600)

device.disconnect()

Connecting

The tweak runs a daemon listening on port 6000. Construct a client with the target IP — "127.0.0.1" when your script runs on the device itself, or the iPhone's LAN IP to drive it remotely from a computer.

• › Every call returns a standard tuple (success: bool, data_or_error) — check the first element before trusting the second.
• › Coordinates are in screen points; use get_screen_size() / get_screen_scale() to write resolution-independent scripts.
• › Call device.disconnect() when done to close the socket cleanly.

Touch model

Each touch carries a type (TOUCH_DOWN / TOUCH_MOVE / TOUCH_UP), a finger index from 1–19, and x, y coordinates. A gesture is a down, any number of moves, then an up on the same finger. For multi-finger gestures, dispatch several events in one frame with touch_with_list().

device.touch_with_list([
    {"type": TOUCH_DOWN, "finger_index": 1, "x": 350, "y": 600},
    {"type": TOUCH_DOWN, "finger_index": 2, "x": 450, "y": 700},
])
for i in range(20):
    device.touch_with_list([
        {"type": TOUCH_MOVE, "finger_index": 1, "x": 350-i*8, "y": 600-i*8},
        {"type": TOUCH_MOVE, "finger_index": 2, "x": 450+i*8, "y": 700+i*8},
    ])
    device.accurate_usleep(16000)  # ≈ one 60fps frame, precise

Vision & OCR

Stop hardcoding coordinates. image_match() locates a template on the live screen and returns its bounding box; ocr() reads on-screen text so scripts react to real state. pick_color() samples a pixel's RGB.

ok, m = device.image_match("/var/mobile/button.png",
                        acceptable_value=0.8, max_try_times=4)
if ok and float(m["width"]) > 0:        # width==0 means no match
    x = float(m["x"]) + float(m["width"])  / 2
    y = float(m["y"]) + float(m["height"]) / 2
    device.touch(TOUCH_DOWN, 1, x, y)
    device.touch(TOUCH_UP, 1, x, y)

# read a score region (x, y, w, h), accurate mode
ok, lines = device.ocr((40, 120, 300, 60), recognition_level=0)
print(lines)   # → ["Score: 1240"]

Text & system UI

Type into the focused field, nudge the cursor, switch apps, and surface native feedback — alert boxes and four styles of toast.

from zxtouch.toasttypes import *

device.switch_to_app("com.apple.MobileSMS")
device.insert_text("sent by zxtouch")
device.insert_text("\b\b")              # backspace x2
device.move_cursor(-3)               # move left 3
device.show_toast(TOAST_SUCCESS, "Done!", 1.5)
device.show_alert_box("ZXTouch", "Message ready", 3)

Recording & the floating panel

Double-click volume-down anywhere in iOS to open the ZXTouch panel — run saved scripts, start/stop recording, and adjust settings without a computer. Recordings save as replayable ZXTouch scripts.

Programmatically, start_touch_recording() begins capture (double-click volume-down or call stop_touch_recording() to end), and play_script(path) replays one. Use force_stop_script_play() to abort.

Constants