How to run NRCD Live

A · Manual upload works as soon as Live is on and crew can sign in (upload each FinishLynx .lif after the heat). B / D automatic needs host setup first (Enable Live, bibs, one-time token) plus the agent running on the timing laptop - that is why auto is not instant. C is for custom software. D is for Meet Manager scoring (FTP / publish), not a FinishLynx substitute. Printable organizer + timer steps: preflight checklists.

Preflight checklists

Step-by-step for the meet organizer and the timer (login, deadlines, scratches, seeding, Live paths, finals). Same lists printable: Preflight checklists. Practice by role: Meet tools.

Host · before meet day

1. Turn on roster registration and clubs enter athletes (how to register).
2. Assign bibs on the Live page (manual or auto-assign; default start is 1). Optional gender filter for XC-style ranges. Download entries CSV (includes athlete_bibs) so the timing crew can load Meet Manager / FinishLynx start lists as usual.
3. Optional for Path B/C/D: 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. Enable NRCD Live. Path A: add Live crew by email. Path B: download agent.py + starter while the token is shown. Path C: share meet id + token + API docs. Path D: if scoring in Meet Manager, plan FTP/publish or Live ops HyTek upload (Path D).

Path A · Browser upload

1. Host adds one or more NRCD emails under Live crew (timer, field judge, or both), 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.

Printable path steps: Preflight checklists.

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 \
  --require-ready \
  --label "finish-lynx-laptop"

Starters pass --require-ready (refuse to watch until Live preflight is green). Check once without watching: --preflight. 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).

Scratches: NRCD roster scratch (register / check-in / clerk) shows as Out on Live start lists. Timer race marks DNS / SCR appear on result rows. A matched DNS also scratches the NRCD entry so start lists stay aligned; export scratches CSV for FinishLynx / Meet Manager when the laptop needs the same list.

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). Needs Python 3.9+ on PATH (easy install if needed: python.org/downloads, check Add to 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). Needs Python 3.9+ (easy install if needed from python.org/downloads or brew install python).

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, ?mode=board, ?mode=monitor (square timer TV), and ?mode=finish (finish line).
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).

During the meet · 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.
• Timer monitor (?mode=monitor) - square live monitor with huge clock and focused heat.
• Finish line (?mode=finish) - diagonal finish-line board of latest finishers.
• Race clock: Timer desk has Lynx-style Zero → Start → Stop, False start (restart), and Next/Prev + zero. Shortcuts: Space / Z / R / N / P. Open Monitor tabs tick from the shared start (~50ms) and update instantly via desk AJAX sync. Agent clock file may contain a time or START/STOP/ZERO/FALSE_START. Token API: POST /api/live/<id>/clock with {"action":"start"} (or zero/stop/clear/false_start).
• Search / Women·Men filters, a Latest ticker, and team scores (track place points from meet/series settings, default 10-8-6-…; XC NIRCA place-sum when enough finishers).
• Events follow the host event-map / schedule order. Results refresh automatically; new marks highlight briefly.

Host · after the meet

Permanent NRCD results are a host job. Meet Manager does not write them into the NRCD database by itself (Path D only feeds Live during the meet).

• On the meet Live page (Meet director): promote compiled live marks into the permanent results DB, and/or download results CSV (relays included when matched to entries or as team anchors; unapproved for non-admins).
• If you did not run Live: use Add Results (CSV or form). Same path as other club meets without Live. See Meet tools · host post-meet.

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" (m/s). 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)

Full Path D for clubs that score in HyTek Meet Manager. Closest to AthleticLIVE's FTP path - not AthleticLIVE's HyTek Windows database connection. If you also run FinishLynx, Paths A/B .lif remain the smoothest for heat-by-heat FAT; Path D is the right primary path when MM is your results source.

Hands-free after agent setup (MM)

1. Enable Live; download agent + starter while the token is shown (or paste token later to re-download).
2. Run the starter: leave FinishLynx blank for HyTek-only, set FTP port 2121 (or run --ftp-port 2121 with optional --mm-watch …).
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 tools: practice sandboxes by role (host pre / timer / during / host post)
• Preflight checklists (printable / phone)
• Host Kit: claim, list, registration
• How to register: clubs and guests
• Upcoming meets: find the meet