Skip to content

Make clips

LIGR cuts clips from the stream of a match in two ways.

  • A highlight rule clips every fact of one event, for example every GOAL. The rule belongs to a competition and applies to each of its matches.
  • A moment is a fact that you add by hand, with its own clip. Use it for a save, a celebration or anything that has no fact of its own.

A rule makes clips only while the stream of the match runs with generateHighlights on. A moment clip needs a recording of the match: a stream with archiveFullFeed on. See Configure a stream.

This guide needs a key with the competitions:write and matches:write scopes, and the streams:write scope to turn on the stream switch.

  1. Read the rules of the competition.

    Terminal
    curl 'https://api.ligr.live/rest/v2/competitions/2311/highlight-rules' \
    -H "Authorization: Bearer $LIGR_API_KEY"
    200 OK
    { "rules": [] }

    A competition with no rule makes no clips from facts, even with generateHighlights on.

  2. Set a rule for goals.

    Terminal
    curl -X PUT 'https://api.ligr.live/rest/v2/competitions/2311/highlight-rules/GOAL' \
    -H "Authorization: Bearer $LIGR_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{ "lead": 8, "lag": 15 }'
    200 OK
    { "factName": "GOAL", "lead": 8, "lag": 15, "conditions": null }

    Each goal now makes a clip from 8 seconds before the goal to 15 seconds after it. The event in the path is a fact name of the competition’s sport, for example GOAL or YELLOW_CARD, or MOMENT for manual moments.

  3. Turn on highlights for the stream of the match.

    Terminal
    curl -X POST 'https://api.ligr.live/rest/v1/streams/90412' \
    -H "Authorization: Bearer $LIGR_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{ "generateHighlights": true, "archiveFullFeed": true }'

    90412 is the streamSettingsId of the match’s stream. archiveFullFeed keeps the recording that moment clips need. To turn generateHighlights on while the stream runs, archiveFullFeed must already be on.

  4. Mark a moment.

    Terminal
    curl -X POST 'https://api.ligr.live/rest/v2/matches/1188213/moments' \
    -H "Authorization: Bearer $LIGR_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{ "title": "Great save", "teamId": 5120, "lead": 6, "lag": 10 }'
    201 Created
    { "factId": 88123401, "highlightId": 412093 }

    LIGR adds a MOMENT fact to the match and cuts its clip from the recording that ran at the moment. Without date the moment is now. Without lead and lag the clip runs from 10 seconds before to 20 seconds after. The clip is ready a short time after the lag has passed.

  5. Remove a rule.

    Terminal
    curl -X DELETE 'https://api.ligr.live/rest/v2/competitions/2311/highlight-rules/GOAL' \
    -H "Authorization: Bearer $LIGR_API_KEY"

    The answer is 204 No Content. Goals stop making clips. A second delete answers 404.

A competition holds one rule per event. PUT creates the rule or replaces it, and the same request twice gives the same result.

The body replaces lead, lag and conditions. A field that you leave out, or send as null, goes back to its default. The rule also has settings that only the dashboard edits: auto-posting, its destinations, and the pre-roll and post-roll videos. A PUT keeps them, on the rule it changes and on every other rule.

FieldMeaningDefault
leadWhole seconds before the fact, from 0 to 720null: 10
lagWhole seconds after the fact, from 0 to 720null: 20
conditionsExtra conditions a fact must meetnull: every fact of the event

lead and lag together must be at least 5 seconds. A moment that sends its own lead and lag uses them instead of the rule’s.

ConditionEventsThe rule clips
teamIdEvery event except MOMENTFacts of this team
clubIdEvery event except MOMENTFacts of a team of this club
subEventEvery event except MOMENTFacts whose data sets this key, for example a tennis ace
homeTeam, awayTeamPOINT_SCORED onlyPoints of the home team, or of the away team
tagMOMENT onlyMoments that carry this tag

A condition that the event does not take answers 400. A MOMENT rule without tag clips moments that carry no tag.

The dashboard can save two rules for one event, for example two MOMENT rules with different tags. GET lists both. PUT and DELETE for that event answer 409 with the code HIGHLIGHT_RULE_AMBIGUOUS and change nothing. Change those rules in the dashboard.

FieldMeaning
dateWhen the moment happened, ISO 8601. Default: now. At most 60 seconds ahead of now
titleThe title of the clip. Default: MOMENT
teamId, playerIdThe team and the player of the moment
tagsNames of tags of your organization
lead, lagSeconds of the clip before and after date, from 0 to 720
highlighttrue (default) cuts a clip now. false saves the moment only
recordingIdThe recording to cut from: a stream or an upload of the match. Default: the recording that covers date

A clip needs a recording of the match that covers date. A recording is one of these:

  • A stream of the match with archiveFullFeed on that ran at date.
  • A video of the match that you uploaded and synced in the dashboard, and that shows date. A part that you cut out of the video, such as half-time, does not cover a moment.

When a stream and an upload both cover date, the clip comes from the stream. When the video of the stream has a gap at date, for example after an encoder failure, the clip comes from the upload. When two uploads cover date, the clip comes from the newest upload. Send recordingId to cut from one recording.

Without a recording that covers date, the request answers 409 with the code NO_RECORDING and creates nothing. Send "highlight": false to save the moment without a clip. The answer then has "highlightId": null.

A moment saved with "highlight": false still gets a clip from a matching MOMENT rule while the stream runs with generateHighlights on. Without highlight, send lead and lag together or leave both out: the rule supplies the values that you leave out.

StatusCodeCause
400BAD_USER_INPUTAn event that the sport does not have, a condition that the event does not take, a clip under 5 seconds, an unknown tag, or a date too far ahead
400A body field of the wrong type, or seconds outside 0 to 720. details names the field
403INSUFFICIENT_SCOPEA key without competitions:read, competitions:write or matches:write
404A competition or match of another organization, an id that does not exist, or a delete of an event with no rule
409HIGHLIGHT_RULE_AMBIGUOUSThe competition has two or more rules for the event, saved in the dashboard
409NO_RECORDINGA moment asked for a clip, and no recording of the match covers its date