Articles in this section

Wurl Fast Path Streamer Integration Specifications

  • Updated

Document Scope

Wurl's cloud solution enables the delivery of adaptive bitrate HLS linear streams with advertising support through AdSpring. This distribution workflow utilizes multiple distribution networks, multiple cloud services and ad servers in parallel. 

This document describes the formats delivered by Wurl’s platform to Streamers. Streamers who are able to support these Specifications qualify for a Fast Path integration, Wurl’s automated option for turn-key technical setup as a Streamer in Wurl’s network.  

 

HLS Linear Streams

Wurl delivers an adaptive bitrate HLS linear stream of 24x7 content to Streamers. 

HLS Linear Description

  1. Creation of HLS linear streams based on scheduled lineups created by Content Companies.
  2. Streams run continuously to support 24x7 linear playout.
  3. An HLS stream delivers up to 6 renditions, HD and SD resolutions (Additional specifications can be found below in the “HLS Linear Renditions”).
  4. HLS streams carry H.264 video and AAC audio.
  5. HLS streams support ssDAI.
  6. Closed caption support within an HLS stream, in either WebVTT or Embedded 608 formats. (Contingent on the Content Company providing a minimum of .srt closed caption files as an input.)

HLS Linear Renditions 

Wurl’s standard renditions may vary depending on a Content Company’s video files. Wurl requires Content Companies to deliver input video at a minimum resolution of 1280x720 to ensure a good video experience. 

ID

Width

Height

Video Bitrate (kbps)

Framerate (fps)

Audio Bitrate (kbps)

Audio Sample Rate (khz)

Encoding Profile

HD4300

1920

1080

4300

30

128

48

Main, 4.1

HD3000

1280

720

3000

30

128

48

Main, 4.1 

SD2000

960

540

2000

30

128

48

Main, 4.1

SD1200

640

360

900

30

96

48

Main, 4.1 

SD512

384

216

512

30

64

48

Main, 4.1

SD192

384

216

192

30

64

48

Main, 4.1

HLS Rendition Variances

Please note that some specifications may vary. As an example, framerate will be normalized to 30 for most content, however, in some special cases assets and ads within a stream may not be set to 30.

Wurl HLS Restreaming Channels are linear streams that do not originate with Wurl but utilize Wurl’s SSAI, CDN and EPG delivery. Because Wurl Restreaming Channels do not originate with Wurl, the stream specifications are more variable than HLS Playout Channels. 

Closed Captions

Wurl provides valid Closed Captions for assets when required, assuming the source file received by Wurl from the Content Company carries valid data. 

  • Closed Caption Formats: 608 and webVTT
  • Single track, no multi-track support
  • No live caption support

Closed Captions will be provided if the source is also valid. If the source is not a valid caption, then Wurl is unable to produce a proper WebVTT caption file for the channel. 

AdSpring Server-Side Dynamic Ad Insertion 

Wurl’s AdSpring solution monetizes video delivery using Server-Side Dynamic Ad Insertion (SSDAI). Ads can be routed through a Streamer’s Ad Decisioning Server (ADS) or split with a Content Company’s ADS.

When the SSDAI detects ad markers in a video stream viewed by a user, ads are requested from an ad server using VAST 3.0.  The VAST request carries various data, including contextual metadata (e.g. genre), stream-related data (e.g. break duration), and device-level metadata (e.g. device ID).  The sections below discuss the Wurl SSDAI workflow, Ad Marker Examples, and the integration and passing of metadata from the application/device to the SSDAI via the playback URL and from the SSDAI to the ad server via the VAST URL.

Wurl SSDAI Workflow

  1. SSDAI is supported in HLS linear streams.
  2. SCTE-35 markup in the HLS manifests are used to trigger an ad decision request. 
  3. Wurl’s Manifest server initiates ad requests with Wurl’s ad router using VAST 3.0.
  4. If an ad is requested for the first time, the Ad ingest workflow communicates with the ADS Graphic Engine to create multiple versions for each Ad, then transcodes the files using similar HLS profile to the content files (bit rates, frame rate, PIDs, resolution) and pushes it to the CDN.
  5. Ads requested that have the necessary transcoded files are served to the client via Wurl’s CDN.

Ad Marker Example

#EXTM3U

#EXT-X-VERSION:3

#EXT-X-MEDIA-SEQUENCE:247347

#EXT-X-TARGETDURATION:10

#EXT-X-PROGRAM-DATE-TIME:2017-03-07T18:01:48.81434232Z

#EXTINF:2.467,

https://s3.amazonaws.com/wurl-zencoder/output/39150329/hls/512-00021.ts

#EXT-OATCLS-SCTE35:WURL35

#EXT-X-ASSET:CAID=”contentid”,GENRE=”contentgenre”,EPISODE=”episodetitle”,

SERIES=”series_name”,SEASON=”season_number

#EXT-X-CUE-OUT:30

#EXT-X-DISCONTINUITY

#EXTINF:6.000,

https://s3.amazonaws.com/wurl-zencoder/output/39155954/hls/512-00001.ts

#EXT-X-CUE-OUT-CONT:ElapsedTime=6,Duration=30,SCTE35=WURL35

#EXTINF:6.000,

https://s3.amazonaws.com/wurl-zencoder/output/39155954/hls/512-00002.ts

#EXT-X-CUE-OUT-CONT:ElapsedTime=12,Duration=30,SCTE35=WURL35

#EXTINF:6.000,

https://s3.amazonaws.com/wurl-zencoder/output/39155954/hls/512-00003.ts

#EXT-X-CUE-OUT-CONT:ElapsedTime=18,Duration=30,SCTE35=WURL35

#EXTINF:6.000,

https://s3.amazonaws.com/wurl-zencoder/output/39155954/hls/512-00004.ts

#EXT-X-CUE-OUT-CONT:ElapsedTime=24,Duration=30,SCTE35=WURL35

#EXTINF:6.000,

https://s3.amazonaws.com/wurl-zencoder/output/39155954/hls/512-00005.ts

#EXT-X-CUE-IN

#EXT-X-DISCONTINUITY

#EXTINF:6.000,

https://s3.amazonaws.com/wurl/output/70155954/hls/512-00004.ts

 

SSDAI Integration

When an ad maker is encountered during playback, the SSDAI system sends a VAST request for advertising creatives which are stitched into the stream for that device.  The VAST URL passes information to an Ad Server, which responds with specific advertisements to be inserted.  Information is passed to the Ad Server via VAST Tag key value pairs.  Device-specific metadata are delivered by the video player when requesting the playback URL.  Additional metadata may be static in the VAST call or dynamically populated by the SSDAI system.  All dynamic values are dependent on data availability.  For example, content-based data can only be passed in the VAST request if it is included in the asset metadata delivered by video publishers.

Playback URL

Device-level metadata is passed by the app/device via the playback URL.  These values are mapped and passed in the VAST request, replacing corresponding VAST macros.  Values that are not available dynamically should be left blank or hard-coded by the app in the playback URL.  Client applications should not depend on key names to fill in macro values - macro values should be filled in based on the macro string. For example, in the URL below, the macro “%7BDEVICE_ID%7D” - url-encoded {DEVICE_ID} - should be filled in with the device ID of the player, but the player should not assume the key name will always be “ads.device_id”. 

Example Playback URL w/ Device ID, DNT and US_PRIVACY Macros:

https://WURL_SSDAI/channel_name/manifest.m3u8?ads.device_id=%7BDEVICE_ID%7D&ads.dnt=%7BDNT%7D&ads.us_privacy=%7BUS_PRIVACY%7D

Example resulting Playback URL request w/ DNT value blanked:

https://WURL_SSDAI/channel_name/manifest.m3u8?ads.device_id=9f926419-c194-99c1-6590-4877bba29ab7&ads.dnt=&ads.us_privacy=1YNN

 

VAST Tag Example

Macro values that are not available should be left blank or hardcoded.  Key value pairs highlighted in blue are delivered by the client application through the playback URL.

Example VAST Tag:

https://PublisherAdServer.com/vast/3.0/12345?​app_bundle​={{APP_BUNDLE}}&dnt={{DNT}}&did={{DEVICE_ID}}&app_name={{APP_NAME}}&us_privacy={{US_PRIVACY}}&content_genre={{GENRE}}&player_width=1920&player_height=1080&pod_max_dur=​{{POD_MAX_DUR}}​&cb={{CACHEBUSTER}}

Example resulting VAST call:

https://PublisherAdServer.com/vast/3.0/12345?​app_bundle=MyBundle&dnt=0&did=9f926419-c194-99c1-6590-4877bba29ab7&app_name=MyApp&us_privacy=1YNN&content_genre=GV&player_width=1920&player_height=1080&pod_max_dur=​120​&cb=123456789

 

Ad Server Integration Fields

Ad Server integration relies on the following VAST Tag Macros.  The rows in blue indicate device-level metadata that is passed by the application in the playback URL request.

Name

VAST Tag Macro

Playback URL Macro

Description

Example Value

Device ID

{{DEVICE_ID}}

%7BDEVICE_ID%7D

Device / TV Identifier

9f926419-c194-99c…

DNT / LMT

{{DNT}}

%7BDNT%7D

Do Not Track / Limit Ad Tracking

1 or 0

CCPA

{{US_PRIVACY}}

%7BUS_PRIVACY%7D

CCPA Option (US)

1YNN

GDPR

{{GDPR}}

%7BGDPR%7D

GDPR Boolean

1 or 0

GDPR Consent

{{CONSENT}}

%7BCONSENT%7D

User Consent (EU)

1 or 0, or TCF string

App Name

{{APP_NAME}}

%7BAPP_NAME%7D

Application

MyApp

Bundle ID

{{APP_BUNDLE}}

%7BAPP_BUNDLE%7D

Bundle ID

MyBundle

App Store URL

{{APP_STORE_URL}}

%7BAPP_STORE_URL%7D

App Store URL

http://my_app_store_url.com/MyBundle

IFA_TYPE

{{IFA_TYPE}}

%7BIFA_TYPE%7D

IFA Type

rdid

Device model

{{DEVICE_MODEL}}

%7BDEVICE_MODEL%7D

Device Model

iPhone

Device make

{{DEVICE_MAKE}}

%7BDEVICE_MAKE%7D

Device Make

Apple

Custom

{{QP_CUSTOM}}

%7BCUSTOM%7D

Optional String

MyCustomString

Wurl Channel Name

n/a - hardcoded

n/a - hardcoded

Static Wurl value for channel name

MyChannel

Wurl Channel ID

n/a - hardcoded

n/a - hardcoded

Static Wurl value for channel ID

151

Content ID

{{CONTENT_ID}}

  

Content ID

12345

Content Genre

{{CONTENT_GENRE}}

  

Content Genre (Nielsen DAR)

GV

Content Title

{{CONTENT_TITLE}}

  

Content Title

My%20Show%20Title

Content Season

{{CONTENT_SEASON}}

  

Content Season

S1

Content Series

{{CONTENT_SERIES}}

  

Content Series

My%20Show%20Serie

Width

1920

  

Static Width

1920

Height

1080

  

Static Height

1080

pod_max_dur

{{POD_MAX_DUR}}

  

Ad Break Duration (seconds)

120

Cachebuster

{{CACHEBUSTER}}

  

Random Number

123456789

IP Address*

{{IP}}

  

Device IP

127.0.0.1

User Agent*

{{USER_AGENT}}

  

Device User-Agent

Mozilla%2F5.0%20...

* IP address and User-agent are passed via VAST 3.0 compliant HTTP X-Forwarded-For headers

CCPA

The US_PRIVACY string contains information about disclosures made and choices selected by a user regarding consumer data privacy under U.S. Privacy regulation.  For details on the application of CCPA (California Consumer Privacy Act), refer to: https://iabtechlab.com/standards/ccpa

 

GDPR and TCF

The GDPR consent string is dependent on the service provider's implementation for handling GDPR consent.  At the simplest form, this can be a value of “0” for no consent and “1” for consent.  However, it is highly recommended to use a Consent Manage Platform utilizing Transparent and Consent Framework (TCF) to deliver a TCF consent string signal from the device.

The IAB also provides a recommendation here around the TCF consent string: https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/TCF-Implementation-Guidelines.md

 

IFA Types

The IAB’s suggestions for IFA Types which should correspond to different types of Device IDs are available in IAB's IFA Type guidelines at: https://iabtechlab.com/wp-content/uploads/2018/12/OTT-IFA-guidelines.final_Dec2018.pdf

 

Electronic Programming Guides (EPG)

Wurl produces an Electronic Programming Guides (EPG) metadata that is used as a data input into a Streamer’s EPG.

Schedule EPG

The schedule EPG is an endpoint that provides both schedule and program metadata in the same location. Wurl supports an XML and JSON format. 

Schedule EPG Description

  1. EPG metadata is accessed via API endpoint that can be queried by day and number of days of data (up to 14 days).
  1. EPG endpoint can be formatted as an .XML or .JSON format. The EPG delivers the below standard sets of metadata depending on the formatting option chosen.
  2. For certain program fields such as program thumbnails, the EPG sends backup metadata derived from the channel if a Content Company doesn’t provide metadata at the program level.

Schedule EPG API Parameters

API endpoint will provide the following parameters to allow support for format and date. Below are the methods to which a Streamer can query the API

Base URL 

Format

Date

  • Date of the EPG data can be added to the “&date=” parameter to grab data for a specific date. The input format is  <YYYY-MM-DD>
    • November 20th, 2018 https://platform.wurl.com/api/schedule/<channelslug>/schedule?appid=<X>&secret=<X>&date=2018-11-20&format=<format>
    • Date can be excluded as a parameter all together from this URL. If so the API will provide tomorrow’s schedule and the next 7 days of epg data.

Days of Data

  • Additional days of data can be requested “&num_days=” parameter to grab subsequent days after the date requested above. This parameter values are <1-14>

Sample Schedule XML and JSON EPG

 

 

Schedule EPG Standard Metadata XML fields

 

Field

Example

Description

ProgramType

OTO

Program Type as defined by the Content Company:

Series, Movie, OTO

ProgramTitle

Nasa 50th Anniversary

For Series or OTO only

SeriesId

11246766

Wurl Episode ID

SeriesEpisodeNumber

2

Episode Number, for Series or OTO ProgramTypes only

SeriesEpisodeTitle

Ask Nasa 2

Show title or movie title depending on ProgramType above

SeriesSeasonNumber

3

Season Number, For Series or OTO ProgramTypes only

Runtime

30

Length of Program in minutes

OriginalAirDate

2021-04-30T14:58:15Z

The original TV air date of the program

YearOfRelease

2021

Year of the original TV air date of the program

PgmRating Type

US TV or MPAA

Episode or Channel Rating Type

PgmRating

TV-PG

Episode or Channel Rating value

PgmDescription

Descriptionum Lorem ipsum dolor sit amet.

Episode Description

Image FileLocation

https://dki01q1l7yn3y.cloudfront.net/thumbnails-platform-prod/assets/cs::content::episodes/5491-7539/Ask-Nasa-2-default_v5.jpeg

Image URL. If not set at the program level, the Channel thumbnail will be sent.

Image Type

Program: Key

Image type: Default (Key) or non-default (Supporting). If not set at the program level, the Channel thumbnail will be sent.

Image AssetID

168172284

Image ID. If not set at the program level, the Channel thumbnail will be sent.

Image Title

default

Image title input in the Scheduler. If not set at the program level, the Channel thumbnail will be sent.

Image FileName

Ask-Nasa-2-default_v5.jpeg

Image filename. If not set at the program level, the Channel thumbnail will be sent.

Image FileFormat

JPEG

Image file format. If not set at the program level, the Channel thumbnail will be sent.

Schedule CalendarDT

2021-07-26T00:00:00.000Z

Schedule Datetime

Schedule StartTime

18:00

Start time of the Schedule program instance, in UTC

Schedule Duration

30

Duration of the Scheduled program instance, in minutes

 

Schedule EPG XML Example

 

<ns0:Rovi_Listings xmlns:ns0="http://Rovi.Ingest.Listings.External" SourceRegion="North America" Station="">

<Programs>

<Program StationProgramID="" ProgramType="Series" Category="Other" ProgramTitle="The Finish Line" OriginalTitle="The Finish Line : Will we Make It" SeriesId="19576" Runtime="30" PrimaryLanguage="English" OriginalTitleLanguage="English" CountryOfOrigin="United States" ProdCompany="" DistName="Wurl" PgmColorType="Color" Caption="None"  AiringType=”Repeat” AudioLevel="Stereo" HDTVLevel="720p" DVI="false" ThreeDFormat="3D Level Unknown" OriginalAirDate=”2013-06-06T07:00:00Z” YearOfrelease=”2013” SeriesEpisodeNumber="1" SeriesSeasonNumber="1" SeriesEpisodeTitle=”Will We Make It”>

<Ratings>

<PgmRating Type="US TV" Rating="TV-MA">

<RatingReasons/>

</PgmRating>

</Ratings>

<PgmDescriptions>

<PgmDescription>

<Type>ShortDescription</Type>

<Description>

Focusing on all aspects of the U.S. national track team and the challenges they face as they go for the gold. 

</Description>

</PgmDescription>

</PgmDescriptions>

<RichMedia>

<Images>

<Image FileLocation="https://dki01q1l7yn3y.cloudfront.net/thumbnails-platform/assets/cs::content::channels/0-1898/The-Finish-Line-1280x720.png" Type="Program: Key" AssetID="61857042" Title="Image 1" FileName="The-Finish-Line-1280x720.png" FileFormat="PNG">

<Rights>

<Right Title="VideoProducer" StartDate="2020-04-26" EndDate="2030-04-26"/>

</Rights>

</Image>

</Images>

</RichMedia>

<Schedules>

<Schedule TimeZone="UTC" CalendarDT="2018-11-14T00:00:00.000Z" StartTime="00:00" Duration="30" AspectRatio="16:9 Unknown" SAP="false" Subtitled="false" PgmColorType="Color" Caption="None" AudioLevel="Stereo" HDTVLevel="720p" DVI="false" JoinedInProgress="false" SubjectToBlackout="false"IsEncrypted="false" StarRating="None" ThreeDFormat="3D Level Unknown" AffiliateStation=""/>

</Schedules>

</Program>

<Program StationProgramID="" ProgramType="Movie" Category="Other" ProgramTitle="Top Stories Tonight" OriginalTitle="Top Stories Tonight with John Patrick" SeriesId="19577" SeriesSeasonNumber="1" Runtime="60" PrimaryLanguage="English" OriginalTitleLanguage="English" CountryOfOrigin="United States"ProdCompany="" DistName="Wurl" PgmColorType="Color" Caption="None" AiringType=”Repeat” AudioLevel="Stereo" HDTVLevel="720p" DVI="false" ThreeDFormat="3D Level Unknown" OriginalAirDate=”2013-06-06T07:00:00Z” YearOfrelease=”2013”>

<Ratings>

<PgmRating Type="US TV" Rating="TV-MA">

<RatingReasons/>

</PgmRating>

</Ratings>

<PgmDescriptions>

<PgmDescription>

<Type>ShortDescription</Type>

<Description>

A newsflash of the day's biggest stories from Hip Hop to Wall Street.

</Description>

</PgmDescription>

</PgmDescriptions>

<RichMedia>

<Images>

<Image FileLocation="https://dki01q1l7yn3y.cloudfront.net/thumbnails-platform/assets/cs::content::channels/0-1898/The-Finish-Line-1280x720.png" Type="Program: Key" AssetID="61857042" Title="Image 1" FileName="The-Finish-Line-1280x720.png" FileFormat="PNG">

<Rights>

<Right Title="VideoProducer" StartDate="2020-04-26" EndDate="2030-04-26"/>

</Rights>

</Image>

</Images>

</RichMedia>

<Schedules>

<Schedule TimeZone="UTC" CalendarDT="2018-11-14T00:30:00.000Z" StartTime="00:30" Duration="60" AspectRatio="16:9 Unknown" SAP="false" Subtitled="false" PgmColorType="Color" Caption="None" AudioLevel="Stereo" HDTVLevel="720p" DVI="false" JoinedInProgress="false" SubjectToBlackout="false"IsEncrypted="false" StarRating="None" ThreeDFormat="3D Level Unknown" AffiliateStation=""/>

</Schedules>

</Program>

Schedule EPG Standard Metadata JSON fields

 

Field

Example

Description

id

4cc90c26-a6a-11b-5f4-7ef631ed79a

Unique ID for Wurl Episode

airDate

2021-07-24

Schedule Date in UTC

originalAirDate

2021-04-30

The original TV air date of the program

description

Descriptionum Lorem ipsum dolor sit amet.

Program Description

duration

30

Duration of the Scheduled program, in minutes

episodeNumber

2

Episode Number, if available.

image name

default

Image title input in the Scheduler. If not set at the program level, the Channel thumbnail will be sent.

image width

1920

Image pixel width

image height

1080

Image pixel height

image uri

https://dki01q1l7yn3y.cloudfront.net/thumbnails-platform-prod/assets/cs::content::episodes/5491-7539/Ask-Nasa-2-default_v5.jpeg

Image URL. If not set at the program level, the Channel thumbnail will be sent.

externalIds

as_1671

Program external IDs, such as TMS ID

position

3

Position of this program in the day's schedule

seasonNumber

2

Season Number, if available.

showId

666127

Wurl Series ID

showTitle

Nasa 50th Anniversary

Series Title, if available.

title

Ask Nasa

Episode Title

timeSlot

12:00 AM

Start time of the Schedule program instance, in UTC

timeZone

UTC

Schedule Timezone, Schedule EPG is always sent in UTC time.




Schedule EPG JSON Example

  •  

{

  • links: 
  • [
  • ],
  • entities: 
  • [
    • {
      • links: [ ],
      • entities: [ ],
      • actions: [ ],
      • class: 
      • [
        • "experimental",
        • "channel-schedule",
        • "wurl-channel-schedule"
      • ],
      • properties: 
      • {
        • airDate: "2018-11-14",
        • description: "Focusing on all aspects of the U.S. national track team and the challenges they face as they go for the gold.",
        • duration: 106,
        • episodeNumber: 1,
        • images: [ ],
        • position: 0,
        • seasonNumber: 1,
        • showId: 55,
        • showTitle: Track Races,
        • title: "The Journey",
        • timeSlot: "12:00 am",
        • timeZone: "UTC"
      • }
    • },
    • {
      • links: [ ],
      • entities: [ ],
      • actions: [ ],
      • class: 
      • [
        • "experimental",
        • "channel-schedule",
        • "wurl-channel-schedule"
      • ],
      • properties: 
      • {
        • airDate: "2020-07-09",
        • description: "A newsflash of the day's biggest stories from Hip Hop to Wall Street.",
        • duration: 125,
        • episodeNumber: 7,
        • images: 
        • [

{

name: "Image 1",

width: 600,

height: 900,

uri: "https:/wurl.com/samplethumbnail-1"

},

{

name: "Image 2",

width: 1280,

height: 720,

uri: "https:/wurl.com/samplethumbnail-2"

}

  • ],
  • position: 1,
  • seasonNumber: 1,
  • showId: 2424,
  • showTitle: Top Stories,
  • title: "Top Stories Tonight",
  • timeSlot: "1:46 am",
  • timeZone: "UTC"
  • }
  • },
  • {
    • links: [ ],
    • entities: [ ],
    • actions: [ ],
    • class: 
    • [
      • "experimental",
      • "channel-schedule",
      • "wurl-channel-schedule"
    • ],
    • properties: 
    • {
      • airDate: "2017-03-02",
      • description: "After learning that he’s the heir to the throne, Westfield seeks a new path from the fate his family decided for him.",
      • duration: 101,
      • episodeNumber: 3,
      • images: 
      • [

{

name: "Image 1",

width: 600,

height: 900,

uri: "https:/wurl.com/samplethumbnail-3"

},

{

name: "Image 2",

width: 1280,

height: 720,

uri: "https:/wurl.com/samplethumbnail-4"

}

  • ],
  • position: 2,
  • seasonNumber: 1,
  • showId: 4232,
  • showTitle: Westfield heads west,
  • title: "Trouble In The Woods",
  • timeSlot: "3:51 am",
  • timeZone: "UTC"
  • }
  • }
  • ],
  • actions: [ ],
  • class: 
  • [
    • "experimental",
    • "channel-schedules",
    • "wurl-channel-schedules",
    • "collection"
  • ]

}

 

Entry Type EPG

The Entry Type EPG lists the program's metadata first, followed by the schedule metadata. It organizes the content by entry types and provides required metadata depending on the entry type. 

 

Entry Type EPG Description

  1. EPG metadata is accessed via JSON API endpoint, one url per channel. 
  2. EPG delivers channel, program and schedule metadata listed below.
  3. Program metadata is listed first, organized by entry types ShortForm, Series, TV Special and Movie. A unique identifier is provided per program.
  4. Schedule data is provided after the program metadata. A unique identifier is provided to allow for metadata mapping between program and schedule.
  5. The JSON API endpoint provides 7 days of data forward from yesterday.
  6. For certain program fields such as program thumbnails, the EPG sends backup metadata derived from the channel if a Content Company doesn’t provide metadata at the program level.

Sample Entry Type EPG

Entry Type Channel Level Metadata

Field

Example

Description

title

Integration Channel 1

Channel Title

lastUpdated

2021-07-23T12:47:16+0000

The date that the feed was last modified in the ISO 8601 format: {YYYY}-{MM}-{DD}T{hh}:{mm}:{ss}+{TZ}.

dateAdded

2019-08-01

Date of Channel creation within the Wurl platform

url

https://wurl-integrationchannel-1-us.wurlintegrationsrdf.wurl.tv/playlist.m3u8

Channel Stream Playback URL

thumbnail

https://dki01q1l7yn3y.cloudfront.net/thumbnails-platform-prod/assets/cs::content::channels/0-2048/Integration-Channel-1-default_v1.jpg

Channel primary thumbnail

brandedThumbnail

https://dki01q1l7yn3y.cloudfront.net/thumbnails-platform-prod/assets/cs::content::channels/0-2048/Integration-Channel-1-default_v1.jpg

Channel secondary thumbnail, if provided. If no secondary image is provided, the primary will be sent here as well.

shortDescription

A new short channel description

Channel Short Description, max 200 chars

longDescription

A new long channel description

Channel Long Description, max 500 chars

rating

TVY

Channel Parental Rating value

ratingSource

USA_PR

Channel Parental Rating Type

Entry Type Program Metadata 

Below is the list of fields provided in the JSON for programs along with a description of the fields.

Field

Example

Description

Program types

Movies, series, shortFormVideos, tvSpecials

Type of Program

id

US-11401746-14224-1417359

Unique ID used to map a Program to the Schedule

title

Inside the Nasa World

Program Title

thumbnail

https://dki01q1l7yn3y.cloudfront.net/thumbnails-platform-prod/assets/cs::content::episodes/5567-7615/Ask-Nasa-4-default_v5.jpeg

16:9 artwork for programs, minimum 800x450. If not set at the program level, the Channel thumbnail will be sent.

shortDescription

Fourth Lorem ipsum dolor sit amet!

Description of episode, max 200 characters

longDescription

Fourth Descriptionum Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Description of episode, max 500 characters

releaseDate

2021-04-30T14:58:15.432Z

The original air date of the episode. If not set by the Content Company, the program creation date will be sent.

tags

science

Program keywords. One or more tags (e.g., “dramas”, “korean”, etc.) may be set.

genres

news

The genre of the program, if available.

rating

TVPG

Program Parental Rating Type. If none is set, the Channel Rating will be sent.

ratingSource

USA_PR

Program Rating Type. If none is set, the Channel Rating will be sent.

series id

US-2620

Wurl Series ID (for Series Entry Types only)

series title

NASA's 50th Anniversary

Series title (for Series Entry Types only)

seasonNumber

1

Season Number (for Series Entry Types only)

episodeNumber

2

Episode Number (for Series Entry Types only)

series genre

news

Series genre (for Series Entry Types only)

series thumbnail

https://dki01q1l7yn3y.cloudfront.net/thumbnails-platform-prod/assets/cs::content::channels/0-2048/Integration-Channel-1-default_v1.jpg

16:9 artwork for Series, minimum 800x450. If not set at the series level, the Channel thumbnail will be sent.

series releaseDate

2020-09-18T19:08:36.466Z

Series Release Date (for Series Entry Types only)

series shortDescription

Neil Armstrong guides us through the history of the NASA.

Description of episode, 200 characters max (for Series Entry Types only)

series rating

TVPG

Series Parental Rating (for Series Entry Types only). If none is set on the Series by the Channel Partner, the Channel Rating will be sent.

series ratingSource

USA_PR

Series Parental Rating Type (for Series Entry Types only). If none is set on the Series by the Channel Partner, the Channel Rating will be sent.

externalIds id

SH984729384723

One or more external IDs.

externalIds idType

TMS

External ID Type, such as TMS or any custom ID type defined by the Channel Partner.

 

Entry Type Program Metadata By Entry Type

Wurl supports four different entry types. Short Form, Movie, Series and TV Special. Below lists the fields that are sent in the JSON per each entry type.

Entry Type

Required Fields

Recommended Fields

Optional Fields

Short Form

- Title

- Thumbnail: 16:9, min 800x450 

- Release Date

- LongDescription

- ShortDescription

- Genre

- Rating 

- Tags

Movie

- Title

- Genres

- Thumbnail

- Box Cover 2:3

- Release Date

- LongDescription

- ShortDescription

- Rating

- TMS ID

- Tags

Series

- Series Title

- Episode Title

- Season Number

- Episode Number

- Thumbnail 16:9

- Genres

- Release Date

- LongDescription

- ShortDescription

- Rating

- TMS ID

- Tags

TV Special

- Title

- Thumbnail 16:9

- Genres

- Release Date

- LongDescription

- ShortDescription

- Rating

- TMS ID

- Tags

 

Entry Type Schedule Metadata

Field

Example

Description

id

US-11246766-1425224-1417359

Unique ID used to map a Program to the Schedule

durationInSeconds

1800

Schedule episode duration in seconds

date

2021-07-22

Schedule date

times

23:30:00

Schedule time

attributes

CC

Whether the Content Company has provided Closed Captions for this program to Wurl

 

Entry Type EPG Examples 

shortForm Metadata Example

“shortFormVideos”: 

[

  • {
    • id: "US-123456",
    • title: "Test | Many Tests!",
    • thumbnail: "https://iamtest.net/thumbnails/episodes/123456789/TestTV---Many-Tests--default.jpg",
    • shortDescription: "Sometimes, being a test is hard. Many days, I cannot get out of my bed, because I am a test - and nothing more",
    • releaseDate: "",
    • longDescription: "Sometimes, being a test is hard. Many days, I cannot get out of my bed, because I am a test - and nothing more. It haunts me",
    • tags: new, drama
    • genres: [ ],
    • credits: null,
    • rating: 
    • {
      • rating: "UNRATED",
      • ratingSource: "USA_PR"
    • }
  • }

],

Movies Metadata Example

“movies”: 

[

  • {
    • id: "US-1234567",
    • title: "I Must Test",
    • genres: 
    • [
      • "Animated"
    • ],
    • thumbnail: "https://iamtest.net/thumbnails/episodes/123456789/TestTV---Many-Tests--default.jpg",
    • releaseDate: "2019-07-03T14:44:03.849Z",
    • shortDescription: "Sometimes, being a test is hard. Many days, I cannot get out of my bed, because I am a test - and nothing more",
    • longDescription: "Sometimes, being a test is hard. Many days, I cannot get out of my bed, because I am a test - and nothing more. It haunts me!",
    • tags: test, fancy
    • credits: null,
    • rating: 
    • {
      • rating: "TVG",
      • ratingSource: "USA_PR"
    • }
  • }

],

 

Series Metadata Example

"series": [

  • {
    • "id": "US-369DSF",
    • "title": "A Boy and His Dog",
    • "seasons": [
      • {
        • "seasonNumber": 1,
        • "episodes": [
          • {
            • "id": "US-32334-32332-232",
            • "title": "A Dog and His Bone",
            • "thumbnail": "https://iamtest.net/thumbnails/episodes/123456789/TestTV---Many-Tests--default.jpg,
            • "episodeNumber": 1,
            • "releaseDate": "2020-04-28T00:58:59.267Z",
            • "shortDescription": "A telepathic dog wanders in search of his bone.",
            • "longDescription": "A telepathic dog wanders in search of his bone, where he uncovers many mysteries along the way.",
            • "credits": null,
            • "rating": {
              • "rating": "R",
              • "ratingSource": "MPAA"
            • }
          • }
        • ]
      • }
    • ],
    • "genres": [],
    • "thumbnail": "",
    • "releaseDate": "2000-02-24",
    • "shortDescription": A telepathic dog stumbles upon a new mystery after a camel approaches in the desert.",
    • "tags": null,
    • "credits": null,
    • "rating": {
      • "rating": "R",
      • "ratingSource": "MPAA"

TV Special Metadata  Example

“tvSpecial”: 

[

  • {
    • id: "US-1234567",
    • title: "(test)",
    • thumbnail: "https://iamtest.net/thumbnails/episodes/123456789/TestTV---Many-Tests--default.jpg",
    • genres: "Reality",
    • releaseDate: "1999-01-18T05:00:00.000Z",
    • shortDescription: "An inside-the-walls look at the bloody story of how tests are done, a horrifying experience that anyone with a",
    • longDescription: "An inside-the-walls look.jpg at the bloody story of how tests are done, a horrifying experience that anyone with a heart will understand!",
    • credits: null,
    • rating: 
    • {
      • rating: "TVPG",
      • ratingSource: "USA_PR"
    • },
    • tags: null
  • }

],

Schedule Example

{

"id": "320302",

"durationInSeconds": 2041,

"isLive": false,

"date": "2019-02-23",

"times": [

"00:00:00"

]

},

{

"id": "239323",

"durationInSeconds": 1669,

"isLive": false,

"date": "2019-02-23",

"times": [

"00:34:01"

]

},

{

"id": "959595",

"durationInSeconds": 2260,

"isLive": false,

"date": "2019-02-23",

"times": [

"01:01:50"

]

},

{

"id": "340340",

"durationInSeconds": 1635,

"isLive": false,

"date": "2019-02-23",

"times": [

"01:39:31"

]

Channel Metadata Example

{

"id": "Wurl24",

"title": "Wurl-Channel",

"content": {

"dateAdded": "2017-08-01",

"videos": [

{

"url": "https://wurlstream.com/test-stream.m3u8",

"quality": "HD",

"videoType": "HLS"

}

],

"language": "en",

 

},

"thumbnail": "https://iamtest.net/thumbnails/episodes/123456789/TestTV---Many-Tests--default.jpg",

"brandedThumbnail": "https://iamtest.net/thumbnails/episodes/123456789/TestTV---Many-Tests--default2.jpg",

"shortDescription": "This is an example of a short description",

"longDescription": "This is an example of a very long, description which is much longer than the short description.",

"startTime": "2020-04-22T18:51:37Z",

"endTime": "2025-01-19T18:51:37Z",

"tags": [

"Test"

]

}

]

Related articles

Comments

0 comments

Please sign in to leave a comment.