Skip to Content
PublisherPlayerAPI ReferenceIntegration APIInterfacesMediaItem

Interface: MediaItem

Represents the input description of a media asset for the player.

A minimal playable MediaItem requires only a source — every other field is optional. Additional fields can be supplied to support analytics, monetization, UI enhancements, and other use cases. In general, the richer the metadata, the more likely the MediaItem can satisfy all integration requirements.

Alternatively, a MediaItemReference can be passed to the player instead of a full MediaItem. A reference carries only an id and a provider, letting the player resolve the complete media item from that provider by ID.

When the player processes a MediaItem (or a resolved MediaItemReference) it produces a MediaItemResolved — an expanded version where missing fields are filled with defaults (e.g. id, language, aspectRatio) and additional data is derived automatically.

Properties

actors?

optional actors: string[]

Name of actors appearing in the given media item

Example

["Cate Blanchett", "Leonardo DiCaprio"]

additionalIds?

optional additionalIds: object

Additional ids that identify the media item in other systems

externalId?

optional externalId: string

originId?

optional originId: string

ageRatingDetails?

optional ageRatingDetails: string[]

Additional details to show for the age rating (e.g. ['Alcohol']) next to the minimum age.

aspectRatio?

optional aspectRatio: string

Aspect ratio of the media item. Useful when vertical variants are used.

Default Value

16:9

branding?

optional branding: object

Additional content branding

logoLinkUrl?

optional logoLinkUrl: string

Optional link target for the logo

logoUrl?

optional logoUrl: string

Logo that should appear in the corner

category?

optional category: object

Category id and name of the media item

name

name: string

id?

optional id: string

channel?

optional channel: Channel

Channel (or often referred to as brand) of the media item.

competition?

optional competition: object

Competition the media item belongs to

id?

optional id: string

name?

optional name: string

compilation?

optional compilation: object

Compilation the media item belongs to

id?

optional id: string

name?

optional name: string

contentOwner?

optional contentOwner: object

Content owner id and name of the media item

name

name: string

id?

optional id: string

description?

optional description: string

Description of the media item.

duration?

optional duration: number

Duration of the media item in seconds. Not defined when livestream.

endDate?

optional endDate: number

Time when the media item expires. Unix timestamp in milliseconds. Useful for JSON-LD generation.

error?

optional error: MediaItemError

Error information if the media item is not available upfront.

genre?

optional genre: string

Genre of the media item (e.g. Documentary)

hasProductPlacement?

optional hasProductPlacement: boolean

Whether the media item has product placements. Shows a product placement indicator in the UI.

iabCategories?

optional iabCategories: string[]

IAB categories (as iabCategoryTaxonomy) of the media item. Used for monetization.

iabCategoryTaxonomy?

optional iabCategoryTaxonomy: number

IAB category taxonomy used for iabCategories (see IAB spec for details )

Default Value

9 for IAB Tech Lab Content Taxonomy 3.1

id?

optional id: string

Unique identifier of the media item.

isRecommendation?

optional isRecommendation: boolean

Mark this media item as a recommendation.

keywords?

optional keywords: string[]

Keywords of the media item

labels?

optional labels: object[]

Additional labels for this media item.

id

id: string

name

name: string

language?

optional language: string

Language of the media item. 2-letter ISO language code.

Default Value

de (German)

optional links: object[]

Links to related content (e.g., a news article or blog post).

caption

caption: string

type

type: "article"

url

url: string

liveOnDemandChannel?

optional liveOnDemandChannel: object

The live on demand channel (livestream using a VoD playlist, often called ODC) the media item belongs to

id?

optional id: string

name?

optional name: string

livestream?

optional livestream: object

Livestream details

startTime

startTime: number

UTC start time of the livestream in milliseconds

endTime?

optional endTime: number

UTC end time of the livestream in milliseconds

epgEntries?

optional epgEntries: object[]

EPG entries containing UTC start and end times in milliseconds. Can be used for timeshift functionality (e.g., jump markers within the DVR window).

optional logo: string

Logo of the media item in size 220x90 (e.g. for shows, movies, sports events etc.)

logoAccentColor?

optional logoAccentColor: string

Accent color of the media item that is shown behind the logo

logoAltText?

optional logoAltText: string

Alt text for the logo of the media item

markers?

optional markers: (Marker | CustomMarker)[]

Markers control ad breaks and custom time-based events during playback.

⚠️ Important: When providing custom markers, the default PREROLL is not added automatically. You must explicitly include a PREROLL marker if you want ads to play.

Reserved marker names: Only PREROLL, MIDROLL, and POSTROLL from KnownMarkerName can be used for ad markers. All other KnownMarkerName values are reserved for internal use. Use custom string names (e.g., 'halfwayPoint') for your own markers.

Listening for custom markers: When a custom marker is reached, the player dispatches an IntegrationEvent.CONTENT_MARKER_REACHED event. Listen for this event to react to your custom markers:

player.addEventListener('contentmarkerreached', (event) => {
  const { markerName, markerData } = event.detail;
  if (markerName === 'showEndCreditsOverlay') {
    // Show your overlay
  }
});

Examples

// Default: pre-roll ads only (same as omitting markers)
markers: [{ name: KnownMarkerName.PREROLL, type: MarkerType.TIME_IN_SECONDS, threshold: 0 }]
// Pre-roll + mid-roll at 60 seconds
markers: [
  { name: KnownMarkerName.PREROLL, type: MarkerType.TIME_IN_SECONDS, threshold: 0 },
  { name: KnownMarkerName.MIDROLL, type: MarkerType.TIME_IN_SECONDS, threshold: 60 }
]
// Custom marker at 50% of content
markers: [
  { name: KnownMarkerName.PREROLL, type: MarkerType.TIME_IN_SECONDS, threshold: 0 },
  { name: 'halfwayPoint', type: MarkerType.PERCENT, threshold: 0.5 }
]
// Custom marker 15 seconds before end (e.g., for end credits overlay)
markers: [
  { name: KnownMarkerName.PREROLL, type: MarkerType.TIME_IN_SECONDS, threshold: 0 },
  { name: 'showEndCreditsOverlay', type: MarkerType.TIME_IN_SECONDS, threshold: -15 }
]

Default Value

[{ name: KnownMarkerName.PREROLL, type: MarkerType.TIME_IN_SECONDS, threshold: 0 }]

metadataSource?

optional metadataSource: string

Indicates the source from which additional metadata was derived (e.g., “joyn”).

minimumAge?

optional minimumAge: number

Minimum age to watch the media item. Shows a minimum age indicator in the UI.

Default Value

0 (no minimum age)

poster?

optional poster: string

Poster image of the media item.

regionsAllowed?

optional regionsAllowed: string[]

In which country can this media item be played (e.g. ['de', 'at'])? Useful for JSON-LD generation.

Default Value

['all'] (worldwide)

releaseDate?

optional releaseDate: number

Release date of the media item. Unix timestamp in milliseconds. Useful for JSON-LD generation.

resumePosition?

optional resumePosition: number

Position (in seconds) at which playback should resume. Applied automatically when the media item is loaded.

seoContentUrl?

optional seoContentUrl: string

JSON-LD contentUrl that allows search engines to crawl the media source. You should only allow known crawlers (how to verify Googlebot & Crawler ) to access those media sources.

show?

optional show: object

Show (often referred to as series, format or tv-show) the media item belongs to

name

name: string

episodeNumber?

optional episodeNumber: number

id?

optional id: string

seasonNumber?

optional seasonNumber: number

sources?

optional sources: Partial<SourceMediaItem>[]

Sources of the media item.

teaser?

optional teaser: object

Additional teaser options that improve the loading experience and enable additional integration variants.

firstFrame?

optional firstFrame: string

Image of the first frame of the media item. Used for initially showing the first frame of the media item.

firstFrameBlurHash?

optional firstFrameBlurHash: string | null

Blurhash  of the first frame of the media item. Used for coloring the background.

firstFrameBlurred?

optional firstFrameBlurred: string

Blurred version of the first frame of the media item. Used to show something early while loading.

posterBlurHash?

optional posterBlurHash: string | null

Blurhash  of the poster of the media item. Used for coloring the background.

posterBlurred?

optional posterBlurred: string

Blurred version of the poster of the media item. Used to show something early while loading.

video?

optional video: string

Teaser video URL which is used for previewing the media item for some integrations.

textTracks?

optional textTracks: MediaItemTextTrack[]

Array of text tracks for subtitles, captions, etc. These tracks apply to the whole media item, not to individual sources.

Note: This is only useful for progressive sources or when the adaptive stream (HLS/DASH) does not deliver the text tracks / subtitles within the manifest.

title?

optional title: string

Title of the media item.

Last updated on
MarkerMediaItemElement