Quick Start

This guide takes you from a video file to a measured threshold. Budget about an hour for the first run; most of it is marking contact frames by hand.

What you need

An iPad (iPadOS 17+) with Xianji installed
A Mac or Linux machine with ffmpeg and Python 3.11 installed
Receiver-viewpoint footage of an opponent hitting — see Filming Protocol
About 60 usable shots for a full session

Steps

1. Film from the receiver’s position

Camera on the centre line, 0.5–1.0 m behind the baseline, at 1.6–1.8 m height. 120 fps, 1080p, fast shutter, stabilisation off, everything locked.

Side-on footage trains the athlete to read cues a receiver never has. It will produce numbers, and the numbers will be meaningless.

2. Mark the contact frames

Play the video with frame numbers burned in:

ffplay -vf "drawtext=text='%{n}':fontsize=48:fontcolor=yellow:x=20:y=20" VIDEO.MOV

Note the frame of each racket–shuttle contact. Write a CSV, one row per shot — contact_frame,zone[,shot_type]:

4127,BL,clear
5200,FR
6890,FC,drop

Badminton zones: FL FC FR BL BC BR.

3. Cut the clips

python -m zhanyan_pipeline.handmake VIDEO.MOV shots.csv \
    --sport badminton_singles \
    --out ./out/2026-08-10-club-a/ \
    --viewpoint receiver

This writes manifest.json plus a clips/ folder. See Preparing Footage.

4. Copy to the iPad

Move the whole output folder into the iPad’s Files app — AirDrop, iCloud Drive, or cable. Keep manifest.json and clips/ together.

5. Import

Open Xianji, tap Import footage, tap Import footage again, and select manifest.json in the file browser.

You should see a green Imported N shots confirmation. Read any amber warnings — see Importing Footage.

6. Confirm the contact frames

Tap Footage → Annotate contact frames. For each shot: scrub the filmstrip to the exact contact frame, tap the zone on the court map, tap Confirm.

Target is 5 seconds per shot once you find the rhythm. Complete the whole queue in one pass — backing out early loses that pass’s work.

7. Run a session

Tap Start session, choose 60 trials, tap Start session, and hand the iPad to the athlete.

Each trial: a fixation cross, the clip plays, the screen blacks out before contact, the athlete taps a zone.

8. Record the result

The results screen shows the threshold and its standard error.

Write the numbers down before leaving the screen. There is no session history in the app yet.