Multi-Fight Cards

Overview

A single MMA broadcast typically contains multiple fights back-to-back — preliminary card + main card, a full 10-fight promotion event, and everything in between. Narrative Sports automatically delineates these fights as they stream, and every highlight from the stream is tagged with three metadata fields so your client can group, filter, and render per-fight views. This page is only relevant when sport is "mma". Soccer streams do not populate these fields.

The Three Fields

All three live inside each highlight’s event_metadata object (see List Highlights).

Field	Type	Description
`fight_number`	integer	1-based index of the fight within the stream. Fight 1 is the first detected fight, fight 2 is the next, etc. Stable across the entire task.
`round_number`	integer or null	1-based round number scoped to this fight. Resets to 1 each new fight. Null for walkouts, intros, and inter-fight filler.
`fight_name`	string	Human-readable fight label. Typically `"<Fighter A> vs <Fighter B>"` once both walkouts are detected; a single name (`"<Fighter A>"`) if only one walkout has been seen yet; `"Fight N"` as a fallback when no walkouts were detected at all.

Example

{
  "id": "e_abc123",
  "event_type": "tko",
  "event_description": "Villarreal lands a flurry of unanswered punches; the referee steps in at 3:17 of round 1.",
  "event_timestamp_seconds": 4199.3,
  "event_metadata": {
    "fight_number": 2,
    "round_number": 1,
    "fight_name": "Kevin Villarreal vs Kevin Arreola"
  }
}

How Fights Are Delineated

The worker tracks fight boundaries using structural events as it processes the stream:

A new fight starts when a fighter_walkout or fight_intro is detected after the previous fight has finished (or at the start of the stream).
A fight is considered finished when any of knockout, tko, submission, decision, or fight_end is detected.
Inter-fight filler (commercials, commentator recaps, arena shots) is attached to the previous fight as other events with round_number: null — it does not trigger a new fight.

Round numbers are stamped based on round_start events within each fight:

The first round_start sets round_number: 1 for all subsequent events in that fight.
Each additional round_start increments the counter.
When a new fight starts, the round counter resets.

Round Numbering by Event Type

Event type	`round_number`
`fighter_walkout`, `fight_intro`	`null` (pre-fight structural)
`round_start`, `round_end`	The round they belong to
`significant_strike`, `takedown`	The round they occur in
`knockout`, `tko`, `submission`, `decision`	The finishing round (e.g., a round-2 KO has `round_number: 2`)
`fight_end`	The finishing round (same as the corresponding finish event)
`other` during a round	The current round
`other` between fights	`null` (inter-fight filler)

Eventual Consistency of `fight_name`

The first event of a new fight (usually the first walkout) may arrive before the second walkout is detected — at that moment, the API only knows one fighter. Early events for that fight are stamped with the partial name ("Morales"); later events, once both walkouts are known, are stamped with the full name ("Morales vs Rodríguez"). This means your database may hold a mix of names for the same fight_number. Clients should resolve the display name per fight using this preference:

Any candidate containing " vs " — use as-is.
Otherwise, any non-fallback candidate (not matching /^Fight \d+$/i).
Otherwise, synthesize "Fight N".

If a fight ends up with only "Fight N" as its name (no walkouts detected), that’s a signal that walkouts were missed — worth surfacing as a warning in your UI but not a failure.

Detecting Multi-Fight Streams

A highlight is part of a multi-fight stream if its event_metadata.fight_number is a number. No stream-level flag is needed; your client can decide to switch UIs (flat grid vs per-fight grouping) based on whether any highlight has fight_number set:

const isMultiFight = highlights.some(
  (h) => typeof h.event_metadata?.fight_number === 'number'
)

Single-fight MMA streams also populate these fields (every fight gets fight_number: 1), so multi-fight UIs render correctly for one-fight streams too.

Championship Rounds

Five-round fights (title bouts, main events) are supported with no configuration changes — round_number simply increments to 5 in the affected fight. Non-title fights with 3 rounds keep the counter at 3. The delineator has no hardcoded cap.

Failure Modes and Tolerances

Missed round_start: if Narrative misses a bell cue, subsequent in-fight events stay tagged with the previous round number until the next round_start is detected. Visible as lopsided round counts in your data; not catastrophic.
Fight with no walkouts: the fight still gets a fight_number, but fight_name falls back to "Fight N". Surface this in your UI as a data-quality warning.
Stream starts mid-fight: the first events are attached to an “orphaned” fight 1. A warning is logged server-side. Round numbers default to 1 until a round_start is observed.
Multiple finish events emitted for one fight: the worker is prompt-guarded against this, but if it slips through, extra finishes may be attributed to a phantom fight. Treat fight_name: "Fight N" single-event fights as suspect.

Creating Recaps from Selected Fights

To recap one fight from a multi-fight event, retrieve project highlight options, find the chosen fight_number, and pass its highlight_ids to Create Recap as selected_edit_ids. For multiple fights, combine their IDs and remove duplicates. Submit only after verifying the list is nonempty. POST /v1/recaps ignores fight_filter and selected_fights; those fields are supported by highlight-package creation. A recap name is a display label, so naming a recap after a fight does not scope its content. See the single-fight recap example.

Event Types — MMA tab for the full category list
List Highlights for the full response schema including event_metadata
Dashboard Integration for how rendered MMA clips appear in the dashboard

Introduction

Concepts

Overview

The Three Fields

Example

How Fights Are Delineated

Round Numbering by Event Type

Eventual Consistency of `fight_name`

Detecting Multi-Fight Streams

Championship Rounds

Failure Modes and Tolerances

Creating Recaps from Selected Fights

​Overview

​The Three Fields

​Example

​How Fights Are Delineated

​Round Numbering by Event Type

​Eventual Consistency of fight_name

​Detecting Multi-Fight Streams

​Championship Rounds

​Failure Modes and Tolerances

​Creating Recaps from Selected Fights

​Related

Overview

The Three Fields

Example

How Fights Are Delineated

Round Numbering by Event Type

Eventual Consistency of `fight_name`

Detecting Multi-Fight Streams

Championship Rounds

Failure Modes and Tolerances

Creating Recaps from Selected Fights

Related