How to run NRCD Live

Prefer Path A (FinishLynx .lif) for the first meet, then B or C. Path D (HyTek) is a fallback after Meet Manager scoring - not live FAT. If nobody from NRCD is on site, open the standalone meet-day page (print or phone).

Meet-day checklist

Short version on this page. Full stand-alone: Meet day (no NRCD person on site).

Before meet day

1. Host turns on roster registration and clubs enter athletes (how to register).
2. Host assigns bibs on the Live page (manual or auto-assign from a starting number; default start is 1). Optional gender filter for XC-style ranges (for example men from 1, women from 500). Download entries CSV (includes athlete_bibs) for Meet Manager.
3. Optional for Path B/C: map FinishLynx event numbers (001-1-02.lif to Men 1500m) or seed maps from the schedule. Path A can type the event name on each upload instead.
4. Host enables NRCD Live. Path A: add Live crew by email. Path B: download agent.py + starter .bat (Windows) or .command (macOS/Linux) while the token is shown. Path C: share meet id + token + API docs.

Path A · Browser upload

1. Host adds the clock person's NRCD email under Live crew, or the timer opens the meet Live page and clicks Request to be timer when no crew exists (provisional access; host confirms before fans see Live).
2. Timer signs in, opens the meet Live page, expands Live ops.
3. After each heat: upload the FinishLynx .lif. Event name is optional when filenames like 001-1-02.lif are mapped. Confirm the mark in Latest.
4. Optional desk tools: clock, Prev/Next board focus, correct a mark.

Stand-alone checklist: Meet day (no NRCD person on site).

On the timing computer (Path B)

Skip this section for Path A (browser upload) or Path C (your own API client).

1. Load the entries CSV into Meet Manager (or your usual start-list workflow).
2. Time with FinishLynx. Leave LIF files in a watch folder (typical EEE-R-HH.lif names).
3. Host downloads nrcd_live_agent.py and a starter from Timer & crew setup (token must be visible): Windows .bat or macOS/Linux .command. Keep both in one folder, then run the starter (macOS: chmod +x the .command file first, then double-click). Optional second prompt: HyTek/MM export folder. Or run the agent directly:

python scripts/nrcd_live_agent.py \
  --base-url https://nationalrunningclubdatabase.com \
  --meet-id MEET_ID \
  --token "$NRCD_LIVE_TOKEN" \
  --watch /path/to/FinishLynx/LIF \
  --mm-watch /path/to/MM/exports \
  --label "finish-lynx-laptop"

Optional: --mm-watch for a Meet Manager export folder (.json NRCD Live payloads; opaque .html is skipped unless a matching .json sidecar sits beside it), --clock-file / --clock-event for a running clock, and --discipline field (or track / xc) to force type. Default is --discipline auto: use the host event map or infer from the event name (XC meets should use --discipline xc or map events as XC). The agent prints a status line (connected, last upload, pending files) and heartbeats so the host sees Agent on. State persists in .nrcd_live_state.json under the LIF folder (or --state).

Windows: run scripts/nrcd_live_agent.bat or scripts/nrcd_live_agent.ps1 (prompts for base URL, meet id, token, and watch folders; or set NRCD_LIVE_* env vars). Requires Python 3 on the PATH - no separate GUI; use the Live page on NRCD for desk controls.

macOS / Linux: run scripts/nrcd_live_agent.sh (same prompts / env vars), or the host-downloaded .command starter (chmod +x, then double-click on macOS). Requires Python 3 (brew install python or python.org).

Meet-day Timer desk

1. Open the meet’s Live results page (signed in as host or Live crew). Results stay at the top; expand Live ops for the desk.
2. Use Prev / Next (or the focus dropdown + Show) so the heat·flight board and scoreboard follow the current race. Projector URLs: ?mode=heatboard and ?mode=board.
3. Set or clear the running clock so fans see event time on the page and scoreboard.
4. After a camera misread: Correct a mark (time or DNS/DNF/DQ) or delete the row. Event/heat fields prefills from board focus.

Same actions are available via the board / rows API below (Bearer token, no login).

What fans see

• By heat / flight - track heats, or field flight boards (Best + attempts). Start lists from registration appear until marks arrive.
• Compiled - best mark per athlete (fastest time on track; farthest/highest on field).
• Heat / flight board (?mode=heatboard) - one heat or flight at a time for a projector.
• Scoreboard (?mode=board) - full dark display with event nav.
• Search / Women·Men filters, a Latest ticker, and team scores (track 5-3-1; XC NIRCA place-sum when enough finishers).
• After the meet, hosts can download results CSV or promote compiled live marks into the permanent NRCD results DB (relays included when matched to entries or as team anchors; unapproved for non-admins).
• Events follow the host event-map / schedule order. Results refresh automatically; new marks highlight briefly.

Live Timer API (Path C)

This is the HTTP API for custom timing software. It is not the browser upload (A) and not the folder agent script (B), though B calls these same endpoints. Auth: meet ingest token (shown once when the host enables Live). Meet id is the upcoming-meet id from the URL.

Authorization: Bearer <meet_token>

JSON results

POST /api/live/<meet-id>/ingest

{
  "source": "agent",
  "event_name": "Men 1500 Meter Run",
  "gender": "M",
  "heat": 1,
  "discipline": "track",
  "rows": [
    {
      "place": 1,
      "bib": "104",
      "lane": 3,
      "first_name": "Pat",
      "last_name": "Runner",
      "team_name": "Test University A",
      "result_time": "3:55.22"
    }
  ]
}

Non-finishers: send "result_time": "DNS" / "DNF" / "DQ" (or "status": "DNS"). FinishLynx LIF files that put those codes in the place or time column are accepted. They sort after finishers (DNF, then DNS, then DQ) with no place.

Field example: set "discipline": "field" (or name the event clearly, e.g. Men Long Jump) and send one row per attempt with "mark", "attempt_num", and optional "wind". Use "flight" (alias of heat) for flight number. Fouls can be "X" / "FOUL" / "NM". The live page shows a flight board (Best + A1…An); compiled ranks by best mark (higher wins). Discipline may also be xc.

{
  "event_name": "Men Long Jump",
  "discipline": "field",
  "flight": 1,
  "rows": [
    { "bib": "77", "mark": "6.55", "attempt_num": 1, "wind": "+0.8" },
    { "bib": "77", "mark": "FOUL", "attempt_num": 2 },
    { "bib": "77", "mark": "6.85", "attempt_num": 3, "wind": "+1.2" }
  ]
}

LIF upload

POST /api/live/<meet-id>/ingest/lif - multipart form field file, plus optional event_name, heat, gender, discipline.

If the filename encodes an event number and the host mapped that number, the mapped display name / gender / discipline are applied when those fields are not passed explicitly (or when discipline is auto / omitted).

Path D · HyTek Meet Manager (FTP / publish-to-disk)

Closest to AthleticLIVE's FTP path. Prefer FinishLynx Paths A/B for live FAT when you have it. This is not AthleticLIVE's HyTek Windows database connection.

Hands-free (recommended for MM)

1. Enable Live; download agent + starter while the token is shown.
2. Run the starter: paste the FinishLynx LIF folder, optional MM export folder, and FTP port 2121 (or run --mm-watch … --ftp-port 2121).
3. In HyTek Meet Manager → Internet / FTP settings: host 127.0.0.1, port 2121, user nrcd, password live (unless you overrode --ftp-user / --ftp-pass).
4. After scoring: F11 (heat) or F12 (event), or publish results. Files land in the drop folder; the agent settles rewrites then POSTs /api/live/<id>/ingest/hytek.

No FTP? Use Meet Manager publish / export to disk into the same --mm-watch folder.

Manual / API

• Browser: Live ops → Path D → preview → upload.
• API: POST /api/live/<meet-id>/ingest/hytek multipart file.
• Accepted files: classic Meet Manager text, headered CSV/TSV, or light HTML results.

Running clock

POST /api/live/<meet-id>/clock

{
  "clock_display": "3:42.1",
  "clock_event_name": "Men 1500m"
}

Board focus (next heat / event)

Shared focus for heat·flight board and scoreboard. Host / Live crew use Timer desk on the live page (Prev / Next, Set clock, correct mark). Token API:

POST /api/live/<meet-id>/board

{ "action": "next" }
{ "action": "prev" }
{ "event_name": "Men Long Jump", "heat": 2 }

Correct or delete a mark

After a camera error or false start dump: fix time / DNS·DNF·DQ, or remove the row. Live crew can do this on Timer desk; token API:

POST /api/live/<meet-id>/rows/<row-id>

{ "result_time": "4:12.55" }
{ "status": "DNS" }
{ "action": "delete" }

Or DELETE /api/live/<meet-id>/rows/<row-id>.

Agent heartbeat

POST /api/live/<meet-id>/heartbeat

{ "agent_label": "finish-lynx-laptop" }

Public feed

GET /upcoming-meets/<meet-id>/live.json?view=heats|compiled (also returns heat_cards for heat/flight-board mode when view=heats; field cards include field_athletes). Supports ETag / If-None-Match (304 when unchanged). Includes feed_etag in the JSON body.

Related guides

• Meet day (no NRCD person on site)
• Host Kit: claim, list, registration
• How to register: clubs and guests
• Upcoming meets: find the meet