Media¶
Resource Containers (RCs) have a media.yaml
file that describes media
generated from the content within the RC. Media is most often generated
for the purpose of distributing a consumable form of the RC’s content.
Media Block¶
RC’s may be compiled into many different forms. Therefore, you may include many different media blocks each representing a single format. A minimal media block requires the following keys:
identifier
an Identifier representing the media typeversion
the version of the media file. This does not necessarily correspond to the RC version.contributor
a list of people who have contributed in generating this media type. e.g. printers, sound engineers, etc.url
the web address where the media file can be downloaded.
Example:
identifier: 'pdf'
version: '1'
contributor: []
url: 'http://cdn.door43.org/en/ta/v1/pdf/en_ta_v1.pdf'
Variable Expansion¶
The value of the url
key may also include variables to make the path dynamic.
However, the variables are limited to keys within the media block and only scalar (non-list) values are allowed.
e.g. you can use the version
key but not contributor
since contributor
is not a scalar value.
Additionally, you may map the version
key to the version found in the Manifest File by settings it’s value to {latest}
.
Example:
identifier: 'pdf'
version: '{latest}'
contributor: []
url: 'http://cdn.door43.org/en/ta/v1/{identifier}/en_ta_v{version}.pdf'
Media Quality¶
For certain media types it is important to note the quality such as audio and video media. For such types an additional key may be added to the media block.
quality
indicates the quality (such as bit rate or frame rate) of the media.
Example:
identifier: 'mp3'
version: '1'
quality: '64kbps'
contributor: []
url: 'https://cdn.door43.org/en/obs/v4/media/mp3/v1/{quality}/obs.zip'
Chapter Media¶
In order to support the concept of chapters. We introduce a new key to the media block:
chapter_url
this is similar to theurl
key except it contains a pseudo variable namedchapter
that can be expanded across all chapters in a resource.
Example:
identifier: 'mp3'
version: '1'
quality: '64kbps'
contributor: []
url: 'https://cdn.door43.org/en/obs/v4/media/mp3/v1/{quality}/obs.zip'
chapter_url: 'https://cdn.door43.org/en/obs/v4/media/mp3/v1/{quality}/obs_{chapter}.mp3'
Media Scope¶
There are two different scopes for media blocks: resource, and projects.
The resource scope allows you to define a media type that encompasses the entire RC while the projects scope encompasses individual projects within the RC.
All resource scoped media blocks should be nested within a top level resource
key.
All projects scoped media blocks should be nested within a top level projects
key.
Example:
---
resource:
version: '1'
media: []
projects: []
The projects scope is a list while the resource scope is simply a dictionary (because there’s only one resource in the RC).
Each project scope must include the following project keys:
identifier
the project identifier as found within the Manifest File.version
the version of the RC that is represented in the subsequent media.
The resource scope only needs the version
key.
If you expect to keep your media up to date with the latest version of the RC, as found within the Manifest File,
you may use the variable expansion {latest}
with the version
key above.
hint: if you use {latest} in a media block you should probably also use it in the parent scope.
Note
The two project keys are currently not available for variable expansion within child media blocks.
Putting It All Together¶
---
resource:
version: '{latest}'
media:
-
identifier: 'pdf'
version: '{latest}'
contributor: []
url: 'https://cdn.door43.org/en/ulb/v{version}/media/{identifier}/ulb.pdf'
projects:
-
identifier: 'gen'
version: '{latest}'
media:
-
identifier: 'mp4'
version: '{latest}'
contributor:
- 'Narrator: Steve Lossing'
- 'Checker: Brad Harrington'
- 'Engineer: Brad Harrington'
quality:
- '360p'
- '720p'
url: 'https://cdn.door43.org/en/ulb/v{version}/media/{identifier}/{quality}/gen_chapter_videos.zip'
chapter_url: 'https://cdn.door43.org/en/ulb/v{version}/media/{identifier}/{quality}/gen_{chapter}.mp4'
-
identifier: 'pdf'
version: '{latest}'
contributor: []
url: 'https://cdn.door43.org/en/ulb/v{version}/media/{identifier}/01-GEN.pdf'
Media Storage¶
The responsibility for storing media is left to those creating it. Media will not be accepted for storage in DCS in order to reduce load on the server and maintain speed and reliability.
When preparing media for distribution we suggest uploading files to a content delivery network (CDN).