Skip to main content
Version: v2

Origins

An origin is a manifest URL that a channel monitors for ad markers. While break detection is running on the channel, OptiView Ads fetches the channel's enabled origins and parses their manifests for markers. A channel can have multiple origins so that detection keeps working when one source goes offline.

Origin identity​

Every origin has an id that is unique within its channel. The id is optional when creating an origin: if you omit it, OptiView Ads generates one for you. When you supply your own, we recommend using a UUID. For a human-readable label, use the name property instead — it is shown in the dashboard.

Enabling and disabling origins​

An origin can be enabled or disabled at any time. Disabling an origin removes it from detection immediately; the origin itself is kept, so you can re-enable it later without recreating it.

How multiple origins are used​

Only enabled origins are considered for detection. Enabled origins are ordered by priority, and detection uses the first online origin: the first one whose manifest is fetched and parsed successfully.

  • Lowest priority value first.
  • First online wins. An origin counts as online when its manifest can be fetched and parsed. A manifest that is reachable but currently advertises no markers still counts as online, so lower-priority origins are not consulted. If an origin cannot be fetched or parsed, detection falls back to the next enabled origin in priority order.

This lets you configure a primary origin and one or more lower-priority backups: when the primary source is unreachable, detection automatically falls back to a backup.

Supported origin types​

Origins can be HLS, DASH, or HESP:

Origin typeBreak detection
HLSReads #EXT-X-CUE-OUT and #EXT-X-DATERANGE tags from the playlists. See Supported markers.
DASHReads SCTE-35 events from the MPD's EventStream elements. In-band emsg events are not supported. See SCTE-35 events on DASH.
HESPNot read. Detection moves on to the next enabled origin in priority order.

Mixed HLS and DASH origins​

A channel can combine HLS and DASH origins of the same stream, for example a DASH primary and an HLS backup. Detection still reads one origin per poll, the first online one, so the other format only serves as failover. It does not combine markers from both.

Marker rules apply to one stream type, so give the channel rules for each format it can fail over to:

  • Without marker rules, every enabled origin is a candidate, and the markers of the selected origin are recorded in detection history.
  • With marker rules, detection only considers origins whose stream type has at least one enabled rule. A channel with only HLS rules skips its DASH origins, and does not fall back to them when the HLS origins go offline.
  • To keep breaks coming after a failover, create equivalent HLS and DASH rules, for example the national, local, and catch-all rules from the HLS and DASH examples.

DRM-protected origins​

When your stream is DRM-protected, describe its DRM configuration in the origin's optional drm property:

{
"id": "primary-hls",
"url": "https://cdn.example.com/live/index.m3u8",
"type": "HLS",
"enabled": true,
"drm": {
"integration": "ezdrm",
"widevine": { "licenseUrl": "https://license.example.com/widevine" },
"playready": { "licenseUrl": "https://license.example.com/playready" },
"fairplay": {
"licenseUrl": "https://license.example.com/fairplay",
"certificateUrl": "https://license.example.com/fairplay/certificate"
}
}
}
PropertyDescription
integrationOptional. The player DRM integration that shapes the license requests, such as ezdrm or drmtoday.
widevineWidevine: { licenseUrl }.
playreadyPlayReady: { licenseUrl }.
fairplayFairPlay: { licenseUrl, certificateUrl }. certificateUrl is optional.
clearkeyClearKey: { licenseUrl, keys }, with a license URL, static keys, or both. keys is a list of { id, value } pairs, the key ID and the key, both base64url-encoded.

Each key system is optional, but drm must contain at least one. License and certificate URLs must be public http or https URLs. A request with any other URL is rejected with 400 Bad Request. When you update an origin, leave out drm to keep it, or set it to null to remove it.

The DRM configuration is used in two places:

  • Viewing the origin in the Dashboard. The Dashboard player uses it to play the protected stream.
  • Google DAI server-side beaconing streams. When a Google DAI live stream with server-side beaconing is backed by this origin, the Break Manifest carries the origin's DRM configuration for that stream, which uses the same DRM as your origin.

Break detection does not use it: detection only reads the manifests, not the protected media.

Poll status​

Every origin reports its most recent poll by break detection in the read-only lastPoll property. Use it to check whether an origin is reachable and whether its manifest carries ad markers.

Detection polls the origin it uses at the pace of the stream. Enabled origins that the failover does not reach, such as backups behind an online primary, are still polled, less often (about once an hour), so every enabled origin reports a state. lastPoll is absent until detection has polled the origin, and is cleared when you change the origin's url or type.

{
"id": "primary-hls",
"url": "https://cdn.example.com/live/index.m3u8",
"type": "HLS",
"enabled": true,
"priority": 0,
"lastPoll": {
"at": "2026-11-11T18:00:00.000Z",
"state": "ONLINE",
"requests": [
{
"at": "2026-11-11T18:00:00.120Z",
"kind": "MANIFEST",
"file": "index.m3u8",
"state": "ONLINE",
"httpStatus": 200,
"responseTimeMs": 95,
"downloadTimeMs": 120
},
{
"at": "2026-11-11T18:00:00.270Z",
"kind": "PLAYLIST",
"file": "720p.m3u8",
"state": "ONLINE",
"httpStatus": 200,
"responseTimeMs": 110,
"downloadTimeMs": 150
}
],
"markersDetected": 2,
"markersSkipped": 0
}
}
PropertyDescription
atWhen the poll started.
stateThe outcome of the poll: ONLINE, OFFLINE, or ERROR. See Poll states.
errorWhy the poll failed: a reason and a message. Absent when state is ONLINE.
requestsEvery file the poll fetched, in order. See Fetched files.
markersDetectedThe ad markers the manifest carried, before marker rules are applied. See Marker counts.
markersSkippedThe marker tags and events in the manifest that could not be used as a marker. See Marker counts.
derivedLiveOffsetMs, derivedDvrWindowMsThe live offset and DVR window measured on the manifest. See Measured live offset and DVR window.

Poll states​

The state of a poll is the state of its last request:

stateMeaningerror.reason
ONLINEThe manifest was fetched and parsed. Detection can use the origin.—
OFFLINEThe manifest could not be fetched. Detection falls back to the next enabled origin.TIMEOUT, NETWORK, or HTTP
ERRORThe manifest was fetched but cannot be used. Detection falls back to the next enabled origin.PARSE, UNSUPPORTED, or NOT_VOD
error.reasonMeaning
TIMEOUTThe origin did not respond in time.
NETWORKThe connection failed, for example because the host name does not resolve or the connection was refused.
HTTPThe origin answered with an error status. The request's httpStatus holds it.
PARSEThe file is not a valid HLS playlist or DASH MPD.
UNSUPPORTEDDetection does not read this origin type, such as HESP.
NOT_VODOn a VOD channel, the origin serves a live manifest.

error.message adds the details, such as the HTTP status line or the parser message.

Fetched files​

requests lists every file the poll fetched. For an HLS origin, that is the multivariant playlist, then the media playlist that detection reads, with every variant it tried. For a DASH origin, it is the MPD.

PropertyDescription
atWhen the file was fetched.
kindMANIFEST for the file at the origin url, PLAYLIST for an HLS media playlist.
fileThe file name, without path or query, such as 720p.m3u8 or live.mpd.
state, errorThe outcome of this request, as described in Poll states.
httpStatusThe HTTP status of the response. Absent when no response arrived.
responseTimeMsMilliseconds until the response headers arrived.
downloadTimeMsMilliseconds until the whole file was downloaded.

Marker counts​

The marker counts describe the manifest of that one poll:

  • markersDetected is the number of ad markers the manifest carried: HLS #EXT-X-CUE-OUT and #EXT-X-DATERANGE tags, or DASH SCTE-35 events, before marker rules are applied. 0 means the manifest was read but carries no markers.
  • markersSkipped is the number of marker tags and events that did not become a marker: a DASH event that does not open an ad break, a malformed marker, or a marker without a resolvable start.

Both are absent when the manifest could not be parsed.

The counts relate to detection history as follows:

  • A marker stays in the manifest for several polls, so it is counted on every poll, but recorded once in detection history.
  • Each skipped marker is recorded in detection history as SKIPPED, with MARKER_NOT_AD_OUT, MARKER_MALFORMED, or MARKER_MISSING_START as the reason.
  • Only the origin that detection uses records markers in detection history and creates breaks. On an origin the failover does not reach, the counts show what its manifest carries without recording anything.

Poll history​

Each poll is also kept in the origin's poll history:

GET /channels/{channelId}/origins/{originId}/history

The history lists the polls of the origin, newest first, in the same shape as lastPoll plus the originId. The list is paginated, can be filtered on at and state, and sorted on at. For example, ?filter=state==OFFLINE returns the polls that could not fetch the manifest.

Poll history is kept for a limited time, one day by default. Older polls are no longer returned.

Unreachable origin or manifest without markers?​

When a channel creates no breaks, the poll status tells you where to look:

lastPollWhat it means
state is OFFLINEDetection cannot reach the origin. Check error.reason and the httpStatus of the last request, and that the URL is reachable from the public internet.
state is ERRORThe origin answers, but its manifest cannot be used. Check error.reason and error.message.
state is ONLINE, markersDetected is 0The origin is reachable, but its manifest currently carries no ad markers. Check that your packager writes the markers into the manifest. See Supported markers.
state is ONLINE, markersDetected above 0The origin and its markers are fine. Check detection history to see why the markers did not become breaks.

Use the poll history to see since when an origin is offline, or whether it fails only now and then.

Measured live offset and DVR window​

Each time detection polls an origin, it also measures the origin's live offset and DVR window from its manifest. The live offset is how far a player following that manifest trails real time, and the DVR window is how much media the manifest makes available behind its live edge. In the Dashboard, the channel's Break Detection tab shows the detected live offset and DVR window of each origin.

These measurements are used in two ways:

  • A channel without its own live offset or DVR window follows the values measured on its highest-priority enabled origin that is online. When the channel has marker rules, only origins that a marker rule can match count.
  • Breaks created from an ad marker are timed against the live point of the origin the marker was found on.

Because each origin is measured on its own, backups with a different latency or DVR window don't need matching channel settings. When detection fails over, a channel that follows the measurements switches to those of the origin now in use.

ResourceRelationship
ChannelsThe parent of an origin. An origin always belongs to one channel.
Break detectionConfigure marker rules to turn ad markers in your stream into breaks.
TemplatesReusable break presets that marker rules schedule when a marker matches.
BreaksThe breaks created when detection matches a marker against a marker rule.
Google DAIUses the DRM configuration of the origin for its server-side beaconing stream.