App Overview

The Xianji app runs the trials and measures the timing. It performs no video analysis — it consumes clips prepared on the desktop.

The iPad is used in landscape. The app locks to it, because a rotation mid-session would relayout the video layer while it is being measured.

Home screen

Four buttons, no navigation bar:

Button	Purpose
Start session	Run a measurement session with an athlete
Footage	Browse imported footage, annotate contact frames, delete
Import footage	Load a `manifest.json` and its clips
T1 Timing Harness	Verify the instrument’s timing accuracy

A English / 中文 toggle sits at the top. It defaults to the device language and switches the interface instantly.

Core concepts

Footage set

One imported video and its shots. Identified by the id from the manifest. Sessions draw from all imported footage for the sport, not from a chosen set — so keep only the footage you intend to test against on the device.

Shot

One stroke: a contact frame, a zone, and a clip that ends on that frame. A shot is either unconfirmed (contact frame not yet checked by a human), confirmed, or excluded.

Annotation

Human confirmation of the contact frame and zone. Human confirmation is the accuracy ceiling of the whole system, which is why the annotation screen exists permanently rather than as a stopgap.

Session

One run of trials with one athlete. A session records its own RNG seed, the device model, the real display refresh rate, and a full snapshot of the sport configuration — so a session can be reproduced and audited later.

Trial

One clip presented, occluded, and responded to. Stores the intended offset, the measured blackout time, the measured response time, the deviation between intended and measured, the response zone, and whether it timed out.

Typical workflow

Import footage  →  Annotate contact frames  →  Start session  →  Record result
   (once)              (once per set)            (repeated)