Clipping Reference

A clip is defined by two markers: start and end. Each marker locates a position in the transcript by phrase or by raw timestamp.

Marker types

`phrase` — locate by words

{ "type": "phrase", "value": "and that's a wrap" }

The service finds this phrase in the transcript (case-insensitive, punctuation-tolerant) and resolves it to the word’s start timestamp. The clip includes the matched word.

Selecting an occurrence

If a phrase appears more than once, occurrence_index picks which one (0-based, default 0):

{ "type": "phrase", "value": "next up", "occurrence_index": 2 }

Resolving by proximity

near_timestamp selects the occurrence closest to a known time in seconds, overriding occurrence_index. Useful when you know roughly where in the video the phrase appears:

{ "type": "phrase", "value": "next up", "near_timestamp": 142.0 }

`timestamp` — raw seconds

{ "type": "timestamp", "value": "30.5" }

Value is a decimal string representing seconds from the start of the media. occurrence_index and near_timestamp are ignored.

Rules

start must resolve to an earlier timestamp than end — the API returns 400 otherwise.
Clips are cached by content: submitting the same media_id + start + end returns the existing clip instantly (no re-encode).
The download_url in the response is a signed URL valid for 1 hour. Re-fetch GET /clips/{id} for a fresh URL after expiry.

Examples

Clip from the first mention of a phrase to the end of a sentence:

{
  "media_id": "med_abc123",
  "start": { "type": "phrase", "value": "the results are in" },
  "end":   { "type": "phrase", "value": "back after the break" }
}

Clip a specific segment using timestamps:

{
  "media_id": "med_abc123",
  "start": { "type": "timestamp", "value": "45.0" },
  "end":   { "type": "timestamp", "value": "90.0" }
}

Second occurrence of a repeated phrase:

{
  "media_id": "med_abc123",
  "start": { "type": "phrase", "value": "chapter one", "occurrence_index": 1 },
  "end":   { "type": "phrase", "value": "chapter two" }
}