Troubleshooting

Beta — research prototype

Xianji is an early-stage research instrument, not a shipping product. The trial engine and its timing are verified; much of the surrounding workflow is not built yet. Tennis is configured but not runnable. See Current Limitations before planning around it.

Import fails with a schema version error

The desktop script and the app are different versions.

1. Check which app version is installed
2. Re-cut the clips with the matching version of the preparation script
3. Re-import

Import fails: “This video has already been imported”

1. Go to Footage
2. Find the existing card with the same id
3. Tap the trash icon and confirm
4. Re-import

Import fails: zone code not defined

The shot list uses codes from a different sport.

• Badminton singles: FL FC FR BL BC BR
• Check the --sport flag matches the zones in your CSV

Import fails: contact_time_ms disagrees with contact_frame

The frame rate was assumed rather than read from the file. Phones record 119.88 fps, not 120.0.

1. Re-run the preparation script, which reads the exact rate from container metadata
2. Never hand-edit fps in a manifest

”N of M clips are missing from disk”

The clips/ folder did not come across with the manifest, or was moved after import. Clip files are checked before a session opens, so this appears at setup rather than mid-run.

1. Delete the footage from the Footage screen
2. Copy the whole output folder to the iPad, manifest and clips together
3. Re-import

Do not move or rename the folder after importing — clips are located relative to where the manifest was when you imported it.

”No annotated shots available”

Nothing eligible is imported. The setup screen names the specific reason:

Message	Action
No annotated shots available	Nothing imported, or every shot was excluded during annotation. Import footage
N shots are imported but none have a confirmed contact frame	Annotate them — Footage → Annotate contact frames
N annotated shots cannot be used… re-import that footage	Imported by a version that did not record where clips live. Delete and re-import

Session will not converge

The staircase needs at least 6 reversals and reasonable consistency.

1. Use 60 trials, not 20 or 40 — this is the most common cause
2. Check the athlete had a familiarisation run first
3. Check for fatigue or distraction. Performance that drifts mid-session produces scattered reversals
4. Confirm the athlete understands they should guess rather than let trials time out

Many timing-invalid trials

1. Confirm the app stayed in the foreground for the whole session
2. Check the iPad is not thermally throttled — let it cool if it is warm
3. Close other apps and re-run
4. Run the T1 harness. If T1 fails, thresholds from this device are not trustworthy

Accuracy looks suspiciously high

1. Check the import warnings for missing zone coverage. If some zones have no shots, the athlete’s real choice is narrower than 6 and accuracy inflates
2. Confirm you are reading guessing-corrected accuracy, not raw
3. Check the footage viewpoint is receiver

Threshold moved a lot between sessions

1. Compare the change against 2 × the standard error. Smaller than that is noise
2. Confirm both sessions used the same footage set. Different opponents are different stimuli
3. Confirm both sessions used the same device and the same trial count
4. If the athlete has fewer than two baseline sessions, single results are not yet trustworthy

Annotation work disappeared

Annotations are written only when the queue completes.

• Complete the whole queue in one pass. Use Skip to defer a difficult shot rather than backing out

Athlete’s data is mixed with someone else’s

The app currently has no athlete management — all sessions pool into one implicit athlete.

• Keep your own written records per athlete. See Current Limitations

The interface language reset

The language toggle is not saved between launches. Set it again from the home screen.

Next steps

• Current Limitations →
• Timing Verification →