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.
-
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
generateHighlightson. -
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
GOALorYELLOW_CARD, orMOMENTfor manual moments. -
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 }'90412is thestreamSettingsIdof the match’s stream.archiveFullFeedkeeps the recording that moment clips need. To turngenerateHighlightson while the stream runs,archiveFullFeedmust already be on. -
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
MOMENTfact to the match and cuts its clip from the recording that ran at the moment. Withoutdatethe moment is now. Withoutleadandlagthe clip runs from 10 seconds before to 20 seconds after. The clip is ready a short time after the lag has passed. -
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.
Highlight rules
Section titled “Highlight rules”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.
| Field | Meaning | Default |
|---|---|---|
lead | Whole seconds before the fact, from 0 to 720 | null: 10 |
lag | Whole seconds after the fact, from 0 to 720 | null: 20 |
conditions | Extra conditions a fact must meet | null: 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.
Conditions
Section titled “Conditions”| Condition | Events | The rule clips |
|---|---|---|
teamId | Every event except MOMENT | Facts of this team |
clubId | Every event except MOMENT | Facts of a team of this club |
subEvent | Every event except MOMENT | Facts whose data sets this key, for example a tennis ace |
homeTeam, awayTeam | POINT_SCORED only | Points of the home team, or of the away team |
tag | MOMENT only | Moments 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.
Rules made in the dashboard
Section titled “Rules made in the dashboard”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.
Moments
Section titled “Moments”| Field | Meaning |
|---|---|
date | When the moment happened, ISO 8601. Default: now. At most 60 seconds ahead of now |
title | The title of the clip. Default: MOMENT |
teamId, playerId | The team and the player of the moment |
tags | Names of tags of your organization |
lead, lag | Seconds of the clip before and after date, from 0 to 720 |
highlight | true (default) cuts a clip now. false saves the moment only |
recordingId | The 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
archiveFullFeedon that ran atdate. - 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.
Errors
Section titled “Errors”| Status | Code | Cause |
|---|---|---|
| 400 | BAD_USER_INPUT | An 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 |
| 400 | A body field of the wrong type, or seconds outside 0 to 720. details names the field | |
| 403 | INSUFFICIENT_SCOPE | A key without competitions:read, competitions:write or matches:write |
| 404 | A competition or match of another organization, an id that does not exist, or a delete of an event with no rule | |
| 409 | HIGHLIGHT_RULE_AMBIGUOUS | The competition has two or more rules for the event, saved in the dashboard |
| 409 | NO_RECORDING | A moment asked for a clip, and no recording of the match covers its date |