pymobiledevice3 11.22.0 reports when an iPhone stops drawing, once a second: too coarse and too strict to replace a phone agent's settle wait

A new pymobiledevice3 command reads the iPhone's own frame counter: 0 means nothing on the display rendered for about a second. For a phone agent that is tempting as a settle signal. The release's own numbers say it is twice as slow as the screenshot gate phoneshell already uses, and blind on the screens that gate was built for.

pymobiledevice3 11.22.0, released on 4 October 2026 at 17:06 UTC, adds developer dvt fps: the iPhone's own Core Animation frame rate for the whole display, which reads 0 while nothing on screen changes. The device sends one sample about every 1.02 seconds and ignores the interval it is asked for. phoneshell's screenshot-based settle gate averages 504 ms, so the counter's fastest possible "nothing is moving" takes about twice as long as the check it might replace.

Two DVT instruments in one day, both by a first-time contributor

The author is plain about the limits. It is one count per second, not per-frame timing, so frame time and jank cannot be derived from it and issue #871 stays open for those. It counts the whole display, so it reflects whatever is in the foreground, including system overlays. And no iPhone on iOS 17 or later was in the test set. Our phone runs iOS 26, where developer services go through the RemoteXPC tunnel, so whether the channel answers there is not established.

Why a phone agent would want it, and why the numbers say no

Every phoneshell step reads the screen only after it stops moving. A tree read taken mid-animation is a half-built screen: the docstring of snapshot() records a home-screen read with 6 elements at 1.0 s and 12 at 2.0 s. The current gate, wait_until_stable() in phoneshell/perception/screen.py, grabs a screenshot, waits 0.3 s (0.12 s on a screen memory already knows), grabs again, and accepts once two grabs differ by at most 1.2% of pixels, with a 3.5 s cap. phoneshell/memory.py records what this costs on a real iPhone: tree read 159 ms, screenshot 72 ms, stability gate 504 ms, fixed settle sleep 600 to 800 ms.

A device-side "nothing rendered" signal looks like a cleaner answer than comparing pictures. The sample period rules it out as a replacement. A zero needs one whole window in which nothing was drawn, so the earliest verdict comes 1.02 s after a transition ends if it ends exactly on a window boundary, and close to 2.04 s if it ends just after one. In the worked example below, the gate is done at about 0.7 s and the counter at about 2.04 s.

The second problem is strictness. The gate tolerates 1.2% of pixels changing because, as its docstring says, "a countdown timer, a carousel, a spinner or a blinking cursor changes a handful of pixels every tick", and an exact-match test on Grab's "40% off flash deals 14:19" sheet never converged and turned a 2 s step into a 50 s one. A counter that must read 0 is an exact-match test at the compositor level. Core Animation counts every frame it renders, so a blinking cursor in a focused text field should keep the count above zero indefinitely. That is our expectation from how the counter is defined; we have not measured it.

What it is good for on a phone agent

It answers "did anything at all render" with no screenshot and no image comparison. That fits the check phoneshell makes after every action: _after() in phoneshell/actions.py sleeps 0.6 s (0.8 s after typing or opening an app, 0.7 s after a swipe), then calls a change real if more than 2% of pixels differ, and the MCP layer turns a "no" into the "THE SCREEN DID NOT CHANGE" notice. A tap that lights a button highlight for a few frames and then does nothing passes neither test cleanly. A zero across the sample after a tap would say that nothing was drawn at all, which is stronger evidence of a dead tap than a pixel threshold. A frame count above zero proves nothing, though, because a cursor or a clock also renders.

The decision for anyone building on this: keep the screenshot gate for settling, consider the counter as a second witness on the "nothing happened" path, and budget a full second of latency wherever you read it. Pinning matters too. Going from 11.8.0 to 11.22.0 crosses fourteen minor releases, so phoneshell's bring-up checks would need a re-run after the bump.

Check it yourself

• Release times: curl -s https://pypi.org/pypi/pymobiledevice3/json | python3 -c "import json,sys;r=json.load(sys.stdin)['releases'];[print(v,r[v][0]['upload_time']) for v in ['11.21.0','11.22.0']]"
• The device facts (1.02 s period, ignored intervals, iOS 16.7 only): the description of https://github.com/doronz88/pymobiledevice3/pull/1999.
• On your own phone: pip install pymobiledevice3==11.22.0, then pymobiledevice3 developer dvt fps (on iOS 17 or later, start sudo pymobiledevice3 remote tunneld first). Leave the phone on a static screen, then focus a text field and watch whether the count returns to 0.
• phoneshell's gate: grep -n "def wait_until_stable" -A20 phoneshell/perception/screen.py; the step timings are in the docstring at the top of phoneshell/memory.py; the after-action sleeps are grep -n "settle=" phoneshell/actions.py.

We did not run the counter on our rig for this note. The rig's automation-off marker (runtime/automation-off) has been set since 17 September, and an unattended run does not wake a parked phone.

What would prove this wrong

If developer dvt fps on an iOS 26 iPhone reads 0 within one sample while a text field with a blinking cursor is focused, our strictness argument is wrong. If a later pymobiledevice3 release samples faster than once a second on any iOS version, the latency argument falls. We expect neither by 31 March 2027: the 1.02 s period comes from the device, not from the library.