Repository navigation
Add standard metadata format specifications #203
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
defagos
wants to merge
7
commits into
main
Choose a base branch
from
177-document-standard-metadata-format
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
8efabe1
Prepare new standard connector specification
defagos 3f5f2f2
Add standard metadata format spec
defagos d74fd19
Add example
defagos 1a6c170
Add standard metadata schema
defagos 66c30e1
Fix links
defagos 29f601c
Add link to schema
defagos 0e840e8
Improve introduction
defagos File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,166 @@ | ||
| # Standard Metadata Specification | ||
|
|
||
| --- | ||
|
|
||
| **Version:** 1.0 | | ||
| **Date:** October 05, 2026 | ||
|
|
||
| --- | ||
|
|
||
| ## Introduction | ||
|
|
||
| Metadata associated with media playback is usually pretty standard. A player namely expects to know what is being played (stream URL) and have basic metadata (title, subtitle, artwork) that can be displayed to the user. | ||
|
|
||
| For products that do not already provide this metadata through a dedicated backend, Pillarbox defines a comprehensive, standard metadata format that can be adopted when implementing a playback metadata endpoint. All Pillarbox players natively understand this format, eliminating the need for custom metadata connector implementations. | ||
|
|
||
| ## JSON Format | ||
|
|
||
| The Pillarbox standard metadata format is made of the following top-level structure: | ||
|
|
||
| | Key | Description | Format | Examples | | ||
| |----------------|--------------------------------------------|-----------------------------------------|-------------------------------------------------------| | ||
| | `chapters` | Chapters | JSON array (of _Chapters_, see below) | `[ ... ]` | | ||
| | `customData` | Custom data | JSON dictionary | `{ ... }` | | ||
| | `description` | A long description of the content | String | `Picking up the story where Back to the Future (...)` | | ||
| | `drm` | DRM information | JSON dictionary (_DRM_, see below) | `{ ... }` | | ||
| | `episodeNumber`| The episode number | Integer | 2 | | ||
| | `identifier` | A unique content identifier | String | `back_to_future_2` | | ||
| | `posterUrl` | The URL of an image describing the content | String | `https://...` | | ||
| | `seasonNumber` | The season number | Integer | 1 | | ||
| | `source` | Source information | JSON dictionary (_Source_, see below) | `{ ... }` | | ||
| | `subtitle` | A subtitle describing the content | String | `Science-fiction` | | ||
| | `subtitles` | Information about external subtitles | JSON array (of _Subtitles_, see below) | `[ ... ]` | | ||
| | `timeRanges` | Time ranges | JSON array (of _Time range_, see below) | `[ ... ]` | | ||
| | `title` | A title describing the content | String | `Back to the Future II` | | ||
| | `version` | The version of the JSON format | Number | 1 | | ||
| | `viewport` | The viewport | `STANDARD`, `MONOSCOPIC` (360°) | `STANDARD` | | ||
|
|
||
| > [!INFO] | ||
| > All keys listed above are optional. | ||
|
|
||
| Objects appearing as JSON dictionaries or arrays are described below. | ||
|
|
||
| ### Chapter | ||
|
|
||
| Describes a chapter associated with the content. | ||
|
|
||
| | Key | Description | Format | Examples | Mandatory? | | ||
| |--------------|--------------------------------------------|----------------------|---------------------|------------| | ||
| | `endTime` | The chapter's end time | Time in milliseconds | `30000` | Y | | ||
| | `identifier` | A unique identifier | String | `hill_valley_1955` | N | | ||
| | `posterUrl` | The URL of an image describing the chapter | String | `https://...` | N | | ||
| | `startTime` | The chapter's start time | Time in milliseconds | `10000` | Y | | ||
| | `title` | A title describing the chapter | String | `Hill Valley, 1955` | Y | | ||
|
|
||
| ### Custom data | ||
|
|
||
| A JSON dictionary which can be used to convey any arbitrary useful information. | ||
|
|
||
| ### DRM | ||
|
|
||
| The DRM configuration. | ||
|
|
||
| | Key | Description | Format | Examples | Mandatory? | | ||
| |------------------|-----------------------------|---------------------------------------------------|---------------------|------------| | ||
| | `certificateUrl` | The certificate URL | String | `https://...` | N | | ||
| | `keySystem` | The key system | `WIDEVINE`, `FAIRPLAY`, `CLEAR_KEY`, `PLAY_READY` | `FAIRPLAY` | Y | | ||
| | `licenseUrl` | The license acquisition URL | String | `https://...` | Y | | ||
| | `multisession` | If multi session is enabled | Boolean | `true` | N | | ||
|
|
||
| ### Source | ||
|
|
||
| Describes the source of the content. | ||
|
|
||
| | Key | Description | Format | Examples | Mandatory? | | ||
| |-----------------------|---------------------------------------------------|----------------------------|-------------------------|------------| | ||
| | `audioFragmentFormat` | The audio fragment format | String | `TS` | N | | ||
| | `mimeType` | The MIME type | String | `application/x-mpegURL` | N | | ||
| | `type` | The type of content | `ON-DEMAND`, `LIVE`, `DVR` | `ON-DEMAND` | N | | ||
| | `url` | The URL to be played | String | `https://...` | Y | | ||
| | `videoFragmentFormat` | The video fragment format | String | `FMP4` | N | | ||
|
|
||
| ### Subtitles | ||
|
|
||
| Describes external subtitles provided for the content. | ||
|
|
||
| | Key | Description | Format | Examples | | ||
| |------------|---------------------------------------------------|----------------------------------------|---------------| | ||
| | `kind` | The kind of subtitles | `SUBTITLES`, `DESCRIPTION`, `CAPTIONS` | `SUBTITLES` | | ||
| | `label` | A label describing the subtitles | String | `English` | | ||
| | `language` | The language code | String (BCP 47) | `en` | | ||
| | `url` | The URL where the subtitles can be loaded | String | `https://...` | | ||
|
|
||
| > [!INFO] | ||
| > All keys listed above are mandatory. | ||
|
|
||
| ### Time range | ||
|
|
||
| Describes a time range associated with the content. | ||
|
|
||
| | Key | Description | Format | Examples | | ||
| |-------------|--------------------------|-------------------------------------------------|-----------| | ||
| | `endTime` | The chapter's end time | Time in milliseconds | `60000` | | ||
| | `startTime` | The chapter's start time | Time in milliseconds | `50000` | | ||
| | `type` | The type of time range | `BLOCKED`, `OPENING_CREDITS`, `CLOSING_CREDITS` | `BLOCKED` | | ||
|
|
||
| > [!INFO] | ||
| > All keys listed above are mandatory. | ||
|
|
||
| ## Example | ||
|
|
||
| ```json | ||
| { | ||
| "chapters": [ | ||
| { | ||
| "endTime": 30000, | ||
| "identifier": "hill_valley_1955", | ||
| "posterUrl": "https://...", | ||
| "startTime": 10000, | ||
| "title": "Hill Valley, 1955" | ||
| } | ||
| ], | ||
| "customData": { | ||
| }, | ||
| "description": "Picking up the story where Back to the Future (...)", | ||
| "drm": { | ||
| "certificateUrl": "https://...", | ||
| "keySystem": "FAIRPLAY", | ||
| "licenseUrl": "https://...", | ||
| "multisession": true | ||
| }, | ||
| "episodeNumber": 2, | ||
| "identifier": "back_to_future_2", | ||
| "posterUrl": "https://...", | ||
| "seasonNumber": 1, | ||
| "source": { | ||
| "audioFragmentFormat": "TS", | ||
| "mimeType": "application/x-mpegURL", | ||
| "type": "ON-DEMAND", | ||
| "url": "https://...", | ||
| "videoFragmentFormat": "FMP4" | ||
| }, | ||
| "subtitle": "Science-fiction", | ||
| "subtitles": [ | ||
| { | ||
| "kind": "SUBTITLES", | ||
| "label": "English", | ||
| "language": "en", | ||
| "url": "https://..." | ||
| } | ||
| ], | ||
| "timeRanges": [ | ||
| { | ||
| "endTime": 60000, | ||
| "startTime": "50000", | ||
| "type": "BLOCKED" | ||
| } | ||
| ], | ||
| "title": "Back to the Future II", | ||
| "version": 1, | ||
| "viewport": "STANDARD" | ||
| } | ||
| ``` | ||
|
|
||
| ## JSON Schema | ||
|
|
||
| [metadata-schema.json](specifications/standard-connector/schemas/metadata-schema.json ':ignore') | ||
189 changes: 189 additions & 0 deletions
189
public/specifications/standard-connector/schemas/metadata-schema.json
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,189 @@ | ||
| { | ||
| "$id": "https://github.com/SRGSSR/pillarbox-documentation/blob/main/public/specifications/standard-connector/schemas/metadata-schema.json", | ||
| "$schema": "http://json-schema.org/draft-07/schema#", | ||
| "type": "object", | ||
| "properties": { | ||
| "chapters": { | ||
| "type": "array", | ||
| "uniqueItems": true, | ||
| "minItems": 1, | ||
| "items": { | ||
| "required": [ | ||
| "endTime", | ||
| "startTime", | ||
| "title" | ||
| ], | ||
| "properties": { | ||
| "endTime": { | ||
| "type": "number" | ||
| }, | ||
| "identifier": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| }, | ||
| "posterUrl": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| }, | ||
| "startTime": { | ||
| "type": "number" | ||
| }, | ||
| "title": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "customData": { | ||
| "type": "object", | ||
| "properties": { | ||
| }, | ||
| "required": [ | ||
| ] | ||
| }, | ||
| "description": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| }, | ||
| "drm": { | ||
| "type": "object", | ||
| "properties": { | ||
| "certificateUrl": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| }, | ||
| "keySystem": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| }, | ||
| "licenseUrl": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| }, | ||
| "multisession": { | ||
| "type": "boolean" | ||
| } | ||
| }, | ||
| "required": [ | ||
| "keySystem", | ||
| "licenseUrl" | ||
| ] | ||
| }, | ||
| "episodeNumber": { | ||
| "type": "number" | ||
| }, | ||
| "identifier": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| }, | ||
| "posterUrl": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| }, | ||
| "seasonNumber": { | ||
| "type": "number" | ||
| }, | ||
| "source": { | ||
| "type": "object", | ||
| "properties": { | ||
| "audioFragmentFormat": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| }, | ||
| "mimeType": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| }, | ||
| "type": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| }, | ||
| "url": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| }, | ||
| "videoFragmentFormat": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| } | ||
| }, | ||
| "required": [ | ||
| "url" | ||
| ] | ||
| }, | ||
| "subtitle": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| }, | ||
| "subtitles": { | ||
| "type": "array", | ||
| "uniqueItems": true, | ||
| "minItems": 1, | ||
| "items": { | ||
| "required": [ | ||
| "kind", | ||
| "label", | ||
| "language", | ||
| "url" | ||
| ], | ||
| "properties": { | ||
| "kind": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| }, | ||
| "label": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| }, | ||
| "language": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| }, | ||
| "url": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "timeRanges": { | ||
| "type": "array", | ||
| "uniqueItems": true, | ||
| "minItems": 1, | ||
| "items": { | ||
| "required": [ | ||
| "endTime", | ||
| "startTime", | ||
| "type" | ||
| ], | ||
| "properties": { | ||
| "endTime": { | ||
| "type": "number" | ||
| }, | ||
| "startTime": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| }, | ||
| "type": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "title": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| }, | ||
| "version": { | ||
| "type": "number" | ||
| }, | ||
| "viewport": { | ||
| "type": "string", | ||
| "minLength": 1 | ||
| } | ||
| }, | ||
| "required": [ | ||
| ] | ||
| } |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Must rather be
com.apple.fps(and other similar values, see Pillarbox backend Sources configuration).