Newer versions of the playback code have a feature called “replacement plugins”. If you are unsure
whether your account uses a version that supports replacement plugins, please contact support.
These plugins are developed and maintained internally. Replacement plugins are loaded server-side when
playback URL parameter is provided. When a plugin is loaded, it can optionally replace content
that would normally be played with other content. Whether to replace content or not is determined by the
Before an Owner can load and use a plugin they must be granted authorization to use a specific plugin. If you wish to use a plugin please contact support with a request including your account name and which plugin to enable.
Loading a Plugin
Owners can load a replacement plugin during a playback session by providing the repl parameter in their
playback URL. For example, to use a replacement plugin with my test player at
and the plugin I want to load is named
plug, I would use:
Some plugins accept parameters. To pass parameters to a replacement plugin, use URL parameters with
repl.[param_name]. For example, if a replacement plugin plug takes
param2 and I want
value2 respectively, I would use:
Most plugins also support reading these parameters from the channel's custom metadata. As the database we use behind the scenes doesn't support the '.' character, these parameters are specified with '-' in the custom metadata key field. To build on the previous example, the parameters and values specified could also be put on the channel's custom metadata:
blackout plugin enables content providers to blackout certain assets from their channel’s timeline.
In order for an asset to be blacked out, it must contain custom metadata
blackout_id that matches the
value associated with the playback replacement parameter
boid. If they match, the channel’s blackout
slate (or if not defined, the owner’s blackout slate) will be played. If they don’t match, the asset
The blackout ID to use when determining whether an asset in a timeline should be blacked out. If
the value provided with this parameter matches the
Note that this plugin does not currently support specifying the
boid in channel metadata.
meta parameter on the slicer’s
content_start method to set the asset’s custom metadata, I now
have an asset that contains
meta.blackout_id=blackout_01. If I then play a channel that contains this
asset with the following URL params:
repl.boid value and the
meta.blackout_id match, when the timeline reaches this asset the
viewer will see blackout slate instead of the asset.
rbo, or “reverse blackout”, plugin works in reverse of the
blackout plugin described above. If the
blackout plugin defaults to letting all content through and filters those that match the rules, the
plugin defaults to letting no content through and allows only those that match the given parameters.
Let’s say I have multiple assets in a timeline and I wish to black out all content except those with a
desc property of either “Nightly News”
or "Good Morning, USA". Let's also say that the assets with a description of "Good Morning, USA" are always that exact string. Further, let's say that in the "Nightly News" case the description could also include a suffix, such as "Nightly News - 01",
which means I will want to match any descriptions that start with "Nightly News".
I would use the following playback URL parameters to accomplish this:
Note that the spaces and the '*' are URL-encoded (%20 and %2A, respectively), but unencoded characters can also be passed as long as the client sends them properly.
As an alternative to using the URL parameters, I could specify the
repl-prop,val-<id> parameters (note '.' has been replaced with '-' in the key name) in channel custom metadata by
specifying the following custom metadata on the channel.
|repl-prop,val-gmusa||desc,Good Morning, USA|
Load this plugin by adding this query string parameter to the playback URL:
The Regional Blackout plugin allows content providers to distribute programming based on the viewer's location. Regional Blackout requires a program to contain custom metadata (i.e.,
blackout_id) that identifies a blackout rule within the corresponding channel. The CMS takes into account a viewer's location and this blackout rule to determine whether standard or alternate programming (i.e., slate, an alternate slicer, or VOD) will be streamed to the viewer.
A viewer's location may be overriden via parameters. Additionally, a specific blackout zone may be assigned to a viewer via the following parameter:
|cbz||string||No||Overrides a viewer's location to a specific blackout zone. Identify a blackout zone by its name or ID. Blackout zone names should be URL encoded.|
In this sample scenario, a program is assigned a regional blackout rule with an ID of "blackout_01." This rule is configured to black out the west coast of the United States. By default, viewers within that region will view alternate content, while those outside of this region will view standard programming.
Standard playback URL:
This behavior may be overridden for a specific viewer by adding the cbz query string parameter to the playback URL.
Location-override playback URL:
The above playback URL overrides the viewer's location to one that matches the blackout zone called "blackoutzone1." If the blackout rule applied to the current program excludes the specified blackout zone, then the viewer will play back alternate content instead of the regularly scheduled program.