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 type
  • version 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 the url key except it contains a pseudo variable named chapter 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).