/sapi/playout

Contents

Use the /sapi/playout endpoint to manage playouts (player configurations).

1.0 | Playout Object

1.1 | Example Playout Object

JSON Playout object

{
   "id": "9107",
   "main": "false",
   "publicationid": "754",
   "type": "Playout",
   "name": "Blogpost",
   "status": "active",
   "createddate": "2021-10-26T21:46:00Z",
   "updateddate": "2024-06-18T14:22:21Z",
   "createdBy": "support@bluebillywig.com",
   "updatedBy": "support@bluebillywig.com",
   "label": "blogpost",
   "publication": "yourcompanyname",
   "centerButtonType": "ICON",
   "cornerRadius": "10",
   "responsiveSizing": "true",
   "aspectRatio": "",
   "width": "100%",
   "height": "1",
   "maxWidth": "",
   "autoHeight": "false",
   "skin_backgroundColor": "ffffff",
   "skin_foregroundColor": "6699cc",
   "ariaFocusColor": "",
   "skin_widgetColor": "6caedf",
   "bgColor": "ffffff",
   "logoId": "",
   "logoAlign": "TOPRIGHT",
   "logoClickUrl": "",
   "controlBar": "Autohide",
   "showStartControlBar": "Show",
   "controlBarPlacement": "Auto",
   "controlBarSticky": "Hide",
   "timeDisplay": "Hide",
   "timeLine": "Show",
   "disableFramePreview": "false",
   "muteButton": "Show",
   "volume": "Show",
   "volumeOrientation": "vertical",
   "languageSelect": "Show",
   "qualitySelector": "Show",
   "audioTrackSelect": "Show",
   "playbackRateSelector": "Hide",
   "fullScreen": "Show",
   "castButton": "Hide",
   "linkPauseHoverStates": "true",
   "showBigPlayButton": "true",
   "showBigPauseButtons": "false",
   "showBigHoverButtons": "false",
   "showBigReplayButton": "true",
   "title": "Show",
   "titlePause": "Hide",
   "titleHover": "Hide",
   "titleEnd": "Show",
   "authorCopyright": "Hide",
   "authorCopyrightPause": "Hide",
   "authorCopyrightHover": "Hide",
   "authorCopyrightEnd": "Hide",
   "shareButton": "Show",
   "shareButtonPause": "Show",
   "shareButtonHover": "Show",
   "shareButtonEnd": "Show",
   "showStartDuration": "true",
   "disableMovingThumbnail": "false",
   "relatedItems": "Hide",
   "relatedItemsPause": "Hide",
   "noPosterInExitPhase": "true",
   "date": "Hide",
   "authorCopyrightAlign": "TOPRIGHT",
   "authorCopyrightAlignPause": "TOPRIGHT",
   "authorCopyrightPrefixText": "source:",
   "exitscreenItemsListId": "",
   "useDeeplinkForRelatedItems": "false",
   "randomizeRelatedItems": "false",
   "autoPlayNext": "false",
   "autoPlayOnlyWithPrerollAd": "false",
   "autoPlayNextTimeout": "8",
   "shareButtonEmbedCode": "true",
   "shareButtonEmail": "false",
   "shareButtonFacebook": "true",
   "shareButtonLinkedIn": "true",
   "shareButtonPinterest": "false",
   "shareButtonTwitter": "true",
   "shareButtonWhatsApp": "true",
   "useDeeplinkForFacebook": "true",
   "shareText": "Currently watching:",
   "sharePlayout": "",
   "autoPlay": "false",
   "avoidMutedAutoPlay": "false",
   "forceCanAutoPlay": "false",
   "autoMute": "false",
   "mutedIndication": "auto",
   "autoLoop": "false",
   "stickyMode": "",
   "domFloatElement": "",
   "alwaysFloat": "false",
   "showFloatingCloseButton": "false",
   "disableFloatAnimation": "false",
   "floatingWidth": "",
   "minimumFloatWidth": "",
   "distanceFromTop": "",
   "distanceFromBottom": "",
   "startCollapsed": "false",
   "hidePlayerOnEnd": "false",
   "playInOverlay": "false",
   "interactivity_inView": "none",
   "interactivity_outView": "none",
   "forceInview": "false",
   "inviewMargin": "50%",
   "disableKeyboardControls": "false",
   "interactivity_mouseIn": "none",
   "interactivity_mouseOut": "none",
   "interactivity_onClick": "none",
   "clickUrl": "",
   "textAbovePlayer": "",
   "textCommercialSkip": "",
   "placementOption": "default",
   "placementDOMSelector": "",
   "waitForCmp": "false",
   "cmpTimeout": "",
   "showOnlyWhenPrerollAvailable": "false",
   "textAlternative": "",
   "showFrameWhileLoading": "false",
   "fitmode": "FIT_SMART",
   "isolatePlayer": "false",
   "forceNativeFullscreen": "false",
   "noStats": "false",
   "defaultSubtitle": "first",
   "defaultSubtitleOnlyIfMuted": "false",
   "defaultAudioTrack": "first",
   "disableCookies": "false",
   "supportIABConsent": "false",
   "preloadMainroll": "false",
   "disableHtml5VPAID": "false",
   "enableHtml5VPAID": "true",
   "commercialPauseButton": "false",
   "commercialMuteButton": "false",
   "commercials": "true",
   "textCommercialTimeRemaining": "Commercial time remaining:",
   "commercialBehaviour": "Once per clip",
   "minClipDurationPreroll": "",
   "minClipDurationPostroll": "",
   "allowCustomClickLayer": "false",
   "authorCopyrightPrefixTextPause": "source:",
   "pausescreenItemsListId": "",
   "skinOnTimeline": "false",
   "preferHD": "false",
   "autoMuteIfNeededForAutoPlay": "false",
   "float_player": "false",
   "allowBBIma": "false",
   "useDeeplinkForRelatedItemsPause": "false",
   "shareTwitterText": "Currently watching:",
   "adunits": [],
   "adschedules": [],
   "hasAdunits": true,
   "adunitsPreroll": [],
   "positions": []
}

1.2 | Attributes

Most playout properties are stored as strings. Exceptions: hasAdunits (boolean) and adunits, adschedules, adunitsPreroll, positions (arrays).

Playout attributes

Parameter	Description
`id`	(string) Unique identifier of the playout. Read-only.
`main`	(string) “true” if this is the publication’s main (default) playout.
`publicationid`	(string) ID of the publication this playout belongs to. Read-only.
`type`	(string) Fixed value: “Playout”. Read-only.
`name`	(string) Display name of the playout.
`status`	(string) “active” or “inactive”.
`createddate`	(string) ISO 8601 date and time the playout was created. Read-only.
`updateddate`	(string) ISO 8601 date and time the playout was last updated. Read-only.
`createdBy`	(string) Email address of the user who created the playout. Read-only.
`updatedBy`	(string) Email address of the user who last updated the playout. Read-only.
`label`	(string) Unique identifier per publication, used in embed code URLs. Required. Must be unique within the publication.
`publication`	(string) Publication name (subdomain). Read-only.
`centerButtonType`	(string) Style of the centre play button. Accepted values: “ICON”.
`cornerRadius`	(string) Corner radius of the player in pixels.
`responsiveSizing`	(string) “true” to enable responsive sizing.
`aspectRatio`	(string) Aspect ratio of the player (e.g. “16:9”). Leave empty to derive from width/height.
`width`	(string) Player width (e.g. “100%” or pixel value).
`height`	(string) Player height. Use “1” with `responsiveSizing` enabled to auto-calculate from aspect ratio.
`maxWidth`	(string) Maximum player width.
`autoHeight`	(string) “true” to automatically calculate height based on content.
`skin_backgroundColor`	(string) Player background colour as a hex value (without #).
`skin_foregroundColor`	(string) Player foreground/text colour as a hex value (without #).
`ariaFocusColor`	(string) ARIA focus indicator colour as a hex value (without #).
`skin_widgetColor`	(string) Control icon colour as a hex value (without #).
`bgColor`	(string) Background fill colour as a hex value (without #).
`logoId`	(string) Media clip ID of the logo image to display in the player.
`logoAlign`	(string) Logo position. Accepted values: “TOPRIGHT”, “TOPLEFT”, “BOTTOMRIGHT”, “BOTTOMLEFT”.
`logoClickUrl`	(string) URL opened when the logo is clicked.
`controlBar`	(string) Control bar visibility. Accepted values: “Show”, “Hide”, “Autohide”.
`showStartControlBar`	(string) Whether to show the control bar before playback begins. Accepted values: “Show”, “Hide”.
`controlBarPlacement`	(string) Position of the control bar. Accepted values: “Auto”, “Inside”, “Outside”.
`controlBarSticky`	(string) Whether the control bar sticks to the bottom on scroll. Accepted values: “Show”, “Hide”.
`timeDisplay`	(string) Show or hide the time display. Accepted values: “Show”, “Hide”.
`timeLine`	(string) Show or hide the progress timeline. Accepted values: “Show”, “Hide”.
`disableFramePreview`	(string) “true” to disable thumbnail frame preview on timeline hover.
`muteButton`	(string) Show or hide the mute button. Accepted values: “Show”, “Hide”.
`volume`	(string) Show or hide the volume control. Accepted values: “Show”, “Hide”.
`volumeOrientation`	(string) Volume slider orientation. Accepted values: “vertical”, “horizontal”.
`languageSelect`	(string) Show or hide the language selector. Accepted values: “Show”, “Hide”.
`qualitySelector`	(string) Show or hide the quality selector. Accepted values: “Show”, “Hide”.
`audioTrackSelect`	(string) Show or hide the audio track selector. Accepted values: “Show”, “Hide”.
`playbackRateSelector`	(string) Show or hide the playback speed selector. Accepted values: “Show”, “Hide”.
`fullScreen`	(string) Show or hide the fullscreen button. Accepted values: “Show”, “Hide”.
`castButton`	(string) Show or hide the Chromecast button. Accepted values: “Show”, “Hide”.
`linkPauseHoverStates`	(string) “true” to link pause and hover overlay states.
`showBigPlayButton`	(string) “true” to show the large play button overlay.
`showBigPauseButtons`	(string) “true” to show large pause button overlays.
`showBigHoverButtons`	(string) “true” to show large hover state button overlays.
`showBigReplayButton`	(string) “true” to show the large replay button at the end of playback.
`title`	(string) Show or hide the title during playback. Accepted values: “Show”, “Hide”.
`titlePause`	(string) Show or hide the title when paused. Accepted values: “Show”, “Hide”.
`titleHover`	(string) Show or hide the title on hover. Accepted values: “Show”, “Hide”.
`titleEnd`	(string) Show or hide the title at the end of playback. Accepted values: “Show”, “Hide”.
`authorCopyright`	(string) Show or hide the author/copyright overlay during playback. Accepted values: “Show”, “Hide”.
`authorCopyrightPause`	(string) Show or hide the author/copyright overlay when paused. Accepted values: “Show”, “Hide”.
`authorCopyrightHover`	(string) Show or hide the author/copyright overlay on hover. Accepted values: “Show”, “Hide”.
`authorCopyrightEnd`	(string) Show or hide the author/copyright overlay at the end of playback. Accepted values: “Show”, “Hide”.
`shareButton`	(string) Show or hide the share button during playback. Accepted values: “Show”, “Hide”.
`shareButtonPause`	(string) Show or hide the share button when paused. Accepted values: “Show”, “Hide”.
`shareButtonHover`	(string) Show or hide the share button on hover. Accepted values: “Show”, “Hide”.
`shareButtonEnd`	(string) Show or hide the share button at the end of playback. Accepted values: “Show”, “Hide”.
`showStartDuration`	(string) “true” to show the clip duration before playback starts.
`disableMovingThumbnail`	(string) “true” to disable the animated thumbnail on the poster.
`relatedItems`	(string) Show or hide related items at the end of playback. Accepted values: “Show”, “Hide”.
`relatedItemsPause`	(string) Show or hide related items when paused. Accepted values: “Show”, “Hide”.
`noPosterInExitPhase`	(string) “true” to hide the poster image in the exit/end phase.
`date`	(string) Show or hide the publication date overlay. Accepted values: “Show”, “Hide”.
`authorCopyrightAlign`	(string) Position of the author/copyright overlay during playback. Accepted values: “TOPRIGHT”, “TOPLEFT”, “BOTTOMRIGHT”, “BOTTOMLEFT”.
`authorCopyrightAlignPause`	(string) Position of the author/copyright overlay when paused. Accepted values: “TOPRIGHT”, “TOPLEFT”, “BOTTOMRIGHT”, “BOTTOMLEFT”.
`authorCopyrightPrefixText`	(string) Prefix text displayed before the author/copyright value during playback (e.g. “source:”).
`authorCopyrightPrefixTextPause`	(string) Prefix text displayed before the author/copyright value when paused.
`exitscreenItemsListId`	(string) Playlist ID to use as the source for exit screen items.
`pausescreenItemsListId`	(string) Playlist ID to use as the source for pause screen items.
`useDeeplinkForRelatedItems`	(string) “true” to use the clip’s deeplink URL for related item links at the end of playback.
`useDeeplinkForRelatedItemsPause`	(string) “true” to use the clip’s deeplink URL for related item links when paused.
`randomizeRelatedItems`	(string) “true” to randomise the order of related items.
`autoPlayNext`	(string) “true” to automatically play the next related item after playback ends.
`autoPlayOnlyWithPrerollAd`	(string) “true” to only auto-play the next item if a pre-roll ad is available.
`autoPlayNextTimeout`	(string) Countdown duration in seconds before the next item auto-plays.
`shareButtonEmbedCode`	(string) “true” to include the embed code option in the share dialog.
`shareButtonEmail`	(string) “true” to include email as a share option.
`shareButtonFacebook`	(string) “true” to include Facebook as a share option.
`shareButtonLinkedIn`	(string) “true” to include LinkedIn as a share option.
`shareButtonPinterest`	(string) “true” to include Pinterest as a share option.
`shareButtonTwitter`	(string) “true” to include X (Twitter) as a share option.
`shareButtonWhatsApp`	(string) “true” to include WhatsApp as a share option.
`useDeeplinkForFacebook`	(string) “true” to use the clip’s deeplink URL when sharing to Facebook.
`shareText`	(string) Default share text prepended to the shared URL.
`shareTwitterText`	(string) Share text used specifically for X (Twitter).
`sharePlayout`	(string) Label of the playout to use for the share embed code. Defaults to the current playout if empty.
`autoPlay`	(string) “true” to auto-play on page load.
`avoidMutedAutoPlay`	(string) “true” to prevent auto-play if the player would need to be muted.
`forceCanAutoPlay`	(string) “true” to bypass browser auto-play capability detection.
`autoMute`	(string) “true” to mute the player on auto-play.
`autoMuteIfNeededForAutoPlay`	(string) “true” to mute only when required for auto-play to succeed.
`mutedIndication`	(string) Controls the muted indicator. Accepted values: “auto”, “Show”, “Hide”.
`autoLoop`	(string) “true” to loop playback continuously.
`stickyMode`	(string) Sticky/floating mode. Leave empty to disable.
`domFloatElement`	(string) DOM selector of the element used as the floating player anchor.
`alwaysFloat`	(string) “true” to keep the player floating at all times.
`showFloatingCloseButton`	(string) “true” to show a close button when the player is floating.
`disableFloatAnimation`	(string) “true” to disable the float transition animation.
`floatingWidth`	(string) Width of the floating player.
`minimumFloatWidth`	(string) Minimum page width at which the floating player activates.
`distanceFromTop`	(string) Distance from the top of the viewport when floating.
`distanceFromBottom`	(string) Distance from the bottom of the viewport when floating.
`startCollapsed`	(string) “true” to render the player in a collapsed state initially.
`hidePlayerOnEnd`	(string) “true” to hide the player when playback ends.
`playInOverlay`	(string) “true” to open playback in an overlay/lightbox.
`float_player`	(string) “true” to enable the floating player feature.
`interactivity_inView`	(string) Action triggered when the player scrolls into view.
`interactivity_outView`	(string) Action triggered when the player scrolls out of view.
`forceInview`	(string) “true” to force in-view behaviour regardless of scroll position.
`inviewMargin`	(string) Percentage of the player that must be visible to count as in-view (e.g. “50%”).
`interactivity_mouseIn`	(string) Action triggered on mouse enter.
`interactivity_mouseOut`	(string) Action triggered on mouse leave.
`interactivity_onClick`	(string) Action triggered on click.
`clickUrl`	(string) URL opened when the player is clicked.
`textAbovePlayer`	(string) Text displayed above the player.
`placementOption`	(string) Player placement method. Accepted values: “default”, or a custom placement key.
`placementDOMSelector`	(string) DOM selector for custom player placement.
`waitForCmp`	(string) “true” to wait for CMP consent before loading the player.
`cmpTimeout`	(string) Timeout in milliseconds before the player loads without CMP consent.
`showOnlyWhenPrerollAvailable`	(string) “true” to only display the player when a pre-roll ad is available.
`textAlternative`	(string) Alternative text or HTML shown when the player cannot be displayed.
`showFrameWhileLoading`	(string) “true” to show a still frame while the player is loading.
`fitmode`	(string) How the video fits within the player bounds (e.g. “FIT_SMART”).
`isolatePlayer`	(string) “true” to isolate the player within its own CSS scope.
`forceNativeFullscreen`	(string) “true” to force native device fullscreen instead of the custom fullscreen implementation.
`noStats`	(string) “true” to disable analytics and stats reporting for this playout.
`defaultSubtitle`	(string) Default subtitle track to activate. Accepted values: “first”, “none”, or a language code.
`defaultSubtitleOnlyIfMuted`	(string) “true” to only activate the default subtitle track when the player is muted.
`defaultAudioTrack`	(string) Default audio track to activate. Accepted values: “first”, or a language code.
`disableCookies`	(string) “true” to disable cookie usage in the player.
`supportIABConsent`	(string) “true” to enable IAB TCF consent framework support.
`skinOnTimeline`	(string) “true” to render skin elements on the timeline.
`preferHD`	(string) “true” to prefer the highest available quality by default.
`preloadMainroll`	(string) “true” to preload the main ad roll before playback.
`disableHtml5VPAID`	(string) “true” to disable HTML5 VPAID ad support.
`enableHtml5VPAID`	(string) “true” to enable HTML5 VPAID ad support.
`commercialPauseButton`	(string) “true” to show a pause button during ad playback.
`commercialMuteButton`	(string) “true” to show a mute button during ad playback.
`commercials`	(string) “true” to enable ad playback.
`textCommercialTimeRemaining`	(string) Label for the ad countdown timer (e.g. “Commercial time remaining:”).
`textCommercialSkip`	(string) Label for the ad skip button.
`commercialBehaviour`	(string) When ads are served relative to clip plays (e.g. “Once per clip”).
`minClipDurationPreroll`	(string) Minimum clip duration in seconds required to trigger a pre-roll ad.
`minClipDurationPostroll`	(string) Minimum clip duration in seconds required to trigger a post-roll ad.
`allowCustomClickLayer`	(string) “true” to allow a custom click-through overlay on ads.
`allowBBIma`	(string) “true” to enable the Blue Billywig IMA integration.
`adunits`	(array) Ad units assigned to this playout.
`adschedules`	(array) Ad schedules assigned to this playout.
`hasAdunits`	(boolean) Whether the playout has ad units configured. Read-only.
`adunitsPreroll`	(array) Pre-roll ad units assigned to this playout.
`positions`	(array) Ad position configurations for this playout.

2.0 | Create/Update

PUT /sapi/playout

The payload should be a JSON-encoded playout object. The only mandatory field is label. The label must be unique within the publication, as it is used to reference the playout in an embed code URL. Settings that are not specified when submitting a playout object will be derived from the default player settings. The returned playout object will always be fully populated.

The player section should be left at its default. The default (Blue Billywig standard) is maintained by Blue Billywig and receives automatic service updates at least every two weeks. Most other properties can be customised. For a functional description of configurable playout properties, refer to the Playout section of the Online Video Platform user interface.

3.0 | Retrieve

GET /sapi/playout

Retrieves a list of playouts. By default, the 15 most recently created playouts are returned.

3.1 | Parameters

Parameter	Description	Example
`q`	(string) Filter results using a query.	`?q=title:"my fantastic new Playout"`
`sort`	(string) Sort field and direction. Default: `id desc`.	`?sort=title asc`
`limit`	(integer) Number of playouts to return.	`?limit=100`
`offset`	(integer) Number of results to skip, for pagination.	`?offset=100`

3.2 | Result

Returns an items container with the requested playout objects.

GET /sapi/playout/{id}

Retrieves a single, fully populated playout object containing all references and metadata properties.

4.0 | Delete

DELETE /sapi/playout/{id}

Permanently deletes a playout.

Tagged: playout sapi

Was this article helpful?

Yes No

Contact Support

Can't find the answer you're looking for?

Contact Support