Live events overview

Two flavors, one machine

Tapemetric models a live event as a single record (a match) with a kind discriminator that controls which dashboard panels render and which validation rules apply at create time:

• kind: 'match' — sports. Cricket, football, kabaddi, tennis, basketball, hockey. Tracks match phase, clock, and score.
• kind: 'show' | 'concert' | 'awards' | 'talk_show' | 'election' | 'watch_party' | 'other' — non-sport live events. Tracks segments and audience engagement (votes, polls, reactions, chat, donations).

Both types share concurrency curves, QoS panels, geo-snapshots, and markers. The differences are in the kinds of metadata each one carries and the analytics tailored to each.

How live differs from VOD

Before we get to the API, here’s why live events get their own machinery:

• Concurrency spikes. An IPL playoff or an awards finale can be 50–100× the daytime VOD baseline. Sub-30 second freshness is mandatory.
• Latency tolerance is brutal. Viewers spoil each other on social media. The QoS dashboard tracks each viewer’s drift vs the broadcast source.
• Position means something different. In VOD, position_sec is offset from the file start. In a live match, what matters is the match clock — and we capture it separately from playback position so you can compare events across viewers who joined at different wall-clock times.
• Drop-off curves are event-driven. Per-wicket and per-goal in sports; per-segment in shows. "Did people stay through halftime?" and "Did the In Memoriam segment lose us the audience?" are different questions than "Did people finish episode 3?"

Register the event before broadcast

Whatever kind of event you’re running, register it ahead of time so the dashboard can pre-load the title, the live page can show a countdown, and your events stream can be joined to the event record on the way in.

Sports match

POST /v1/live/matches
Authorization: Bearer eyJ...
Content-Type: application/json

{
  "match_id": "ipl_2026_csk_vs_mi",
  "title": "CSK vs MI — IPL 2026",
  "kind": "match",
  "sport": "cricket",
  "league": "IPL",
  "home_team": "Chennai Super Kings",
  "away_team": "Mumbai Indians",
  "scheduled_start": "2026-04-30T19:30:00+05:30",
  "target_latency_sec": 30
}

Live show

POST /v1/live/matches
Authorization: Bearer eyJ...
Content-Type: application/json

{
  "match_id": "filmfare_2026",
  "title": "Filmfare Awards 2026",
  "kind": "awards",
  "show_type": "awards",
  "venue": "Jio World Centre, Mumbai",
  "headline_act": "Hosted by Karan Johar & Vicky Kaushal",
  "scheduled_start": "2026-05-15T19:00:00+05:30",
  "target_latency_sec": 15
}

SDK — one mental model, two flavors

All three SDKs (web, iOS, Android) expose two parallel APIs. Pick the one that matches the kind of event you’re streaming. They both auto-stamp every event emitted while the context is active, so you don’t need to thread match metadata through every track call.

Sports — auto-stamps phase + score + latency

tm.startLiveMatch({
  matchId: 'ipl_2026_csk_vs_mi',
  phase: 'innings_1',
  scoreA: 0,
  scoreB: 0,
  getLatencyMs: () => Math.round((hls.liveSyncPosition - video.currentTime) * 1000),
});

tm.trackPlayStart({ contentId: 'ipl_2026_csk_vs_mi', contentType: 'live' });

// Score moves
tm.updateLiveMatch({ scoreA: 47 });

// A wicket — fires a marker on the timeline
tm.trackCricketEvent({
  kind: 'wicket',
  label: 'Kohli c. Smith b. Cummins (24)',
  runs: 87,
  wickets: 3,
  overs: 8.4,
});

tm.stopLiveMatch();

Shows — auto-stamps segment + latency

tm.startLiveShow({
  eventId: 'filmfare_2026',
  segment: 'red_carpet',
  segmentIndex: 0,
});

tm.trackPlayStart({ contentId: 'filmfare_2026', contentType: 'live' });

// New segment — fires segment_start marker, updates auto-stamp context
tm.setSegment('Best Actor', 4);

// Audience engagement
tm.trackPoll('best_film_2026', 'Animal');
tm.trackReaction('clap');
tm.trackDonation(500, { display_name: 'Riya' });

// A winner moment
tm.trackShowMarker('winner_announced', 'Best Actor — Shah Rukh Khan');

tm.stopLiveShow();

What you get on the dashboard

Every live event detail page has the basics: a concurrent-viewer curve auto-refreshing every 15 seconds, a QoS panel with buffer and error rates, a geo-snapshot showing where viewers are concentrated, and a markers timeline. Beyond those, the dashboard tailors itself to the event kind:

For sports

• Markers overlaid on the concurrency timeline (wickets, goals, half-time)
• Latency distribution percentiles vs the target_latency_sec you set
• State and ISP breakdowns of viewers, with anomaly detection

For shows

• Per-segment retention bars with hold-rate vs previous segment
• Engagement panel — votes, polls, reactions, chat, donations
• Donation / super-chat ledger with INR amounts grouped by segment

Endpoints

All endpoints live under /v1/live. The same paths work for both kinds.

Where to next

For the per-kind details:

• Live sports — cricket, football, and more covers match registration, the SDK auto-stamp model, the cricket and football helper methods, and how latency tracking works.
• Live shows — concerts, awards, talk shows covers segment registration, audience engagement helpers, the segment retention algorithm, and donation tracking.