Multilingual Metadata

Introduction

If you have an international audience (or multilingual within the same country), you may want to provide video metadata such as the title and description in multiple languages.

Video Cloud allows multilingual versions of the following:

• images — localized poster and thumbnail images are returned in the Playback API variants array when configured (see below)
• text tracks
• name (via variants)
• description variants)
• long description variants)
• custom field values variants)

Creating a variant

Using the CMS API (Create a Video Variant) you can add and manage an array of variants to provide an alternative name, description, long_description, and map of custom field/values specific to a language.

To create a variant, send a POST request to the endpoint:

https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/variants/

{
  "language": "ja-JP",
  "name": "バーゼル：ライン川",
  "description": "スイス、バーゼルの中心部にあるライン川のパノラマビュー。",
  "long_description": "スイス、バーゼルの中心部にあるライン川のパノラマビュー。",
  "custom_fields": {
    "language": "Japanese"
  }
}

{
  "language": "ja-JP",
  "name": "バーゼル：ライン川",
  "description": "スイス、バーゼルの中心部にあるライン川のパノラマビュー。",
  "long_description": "スイス、バーゼルの中心部にあるライン川のパノラマビュー。",
  "custom_fields": {
    "language": "Japanese"
  }
}

Getting variants

Get all variants

You can get all the variants for a video by sending a GET request to the endpoint:

https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/variants

[
  {
    "language": "es-ES",
    "name": "Basilea: el Rin",
    "description": "Vista panorámica del Rin en el centro de Basilea, Suiza.",
    "long_description": "Vista panorámica del Rin en el centro de Basilea, Suiza.",
    "custom_fields": {
    }
  },
  {
    "language": "de-DE",
    "name": "Basel: Der Rhein",
    "description": "Panoramablick auf den Rhein im Zentrum von Basel, Schweiz.",
    "long_description": "Panoramablick auf den Rhein im Zentrum von Basel, Schweiz.",
    "custom_fields": {
    }
  },
  {
    "language": "ja-JP",
    "name": "バーゼル：ライン川",
    "description": "スイス、バーゼルの中心部にあるライン川のパノラマビュー。",
    "long_description": "スイス、バーゼルの中心部にあるライン川のパノラマビュー。",
    "custom_fields": {
      "language": "Japanese"
    }
  }
  ]

Get a particular variant

To get a particular variant, send a GET request to the endpoint:

https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/variants/{language}

Here language is the language code used in the variant, such as de-DE.

{
  "language": "de-DE",
  "name": "Basel: Der Rhein",
  "description": "Panoramablick auf den Rhein im Zentrum von Basel, Schweiz.",
  "long_description": "Panoramablick auf den Rhein im Zentrum von Basel, Schweiz.",
  "custom_fields": {
  }
}

Updating a variant

You can update a variant by sending a PATCH request to the endpoint:

https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/variants/{language}

Here language is the language code used in the variant, such as de-DE.

You only need to include the fields that are changing. The request body fields are the same as for creating a variant, except that you may not include the language field. (If you do include the language field a VALIDATION_ERROR will be returned.)

{
  "name": "Basilea: el Rin",
  "description": "Vista panorámica del Rin en el centro de Basilea, Suiza.",
  "long_description": "Vista panorámica del Rin en el centro de Basilea, Suiza.",
  "custom_fields": {
    "language": "Spanish"
 }
}

{
  "language": "es-ES",
  "name": "Basilea: el Rin",
  "description": "Vista panorámica del Rin en el centro de Basilea, Suiza.",
  "long_description": "Vista panorámica del Rin en el centro de Basilea, Suiza.",
  "custom_fields": {
    "language": "Spanish"
  }
}

Delete a variant

To delete a variant, send a DELETE request to the endpoint:

https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/variants/{language}

Do not include a request body. A successful deletion, will return a 204 No Content response.

Variants can be retrieved using the Playback API as well as the CMS API. In the Playback API, they are returned when you get a video, as a top-level variants array:

"variants": [
  {
    "language": "de-DE",
    "name": "Basel: Der Rhein",
    "description": "Panoramablick auf den Rhein im Zentrum von Basel, Schweiz.",
    "long_description": "Panoramablick auf den Rhein im Zentrum von Basel, Schweiz.",
    "custom_fields": {}
  },
  {
    "language": "ja-JP",
    "name": "バーゼル：ライン川",
    "description": "スイス、バーゼルの中心部にあるライン川のパノラマビュー。",
    "long_description": "スイス、バーゼルの中心部にあるライン川のパノラマビュー。",
    "custom_fields": {
      "language": "Japanese"
    }
  }
]

Images and text tracks

Localized text tracks can be added using the Dynamic Ingest API. See Ingesting WebVTT Files (Text Tracks/Captions) for details.

Localized poster and thumbnail images are ingested via the Dynamic Ingest API (see Images and the Dynamic Ingest API) and are now also returned by the Playback API inside each language entry of the variants array. When a localized image is configured for a language, the corresponding variant includes poster, thumbnail, poster_sources, and thumbnail_sources fields. When no localized image is configured, those fields are omitted and players should fall back to the top-level poster/thumbnail.

The image URLs returned per variant are identical to the values the CMS API stores as images["poster.<lang>"] and images["thumbnail.<lang>"] — no separate mapping is required.

Example Playback API response (trimmed):

{
  "id": "6393991831112",
  "poster": "https://.../default/poster.jpg",
  "thumbnail": "https://.../default/thumbnail.jpg",
  "variants": [
    {
      "language": "ja-JP",
      "name": "グレートブルー",
      "poster":    "https://.../ja-JP/poster.jpg",
      "thumbnail": "https://.../ja-JP/thumbnail.jpg",
      "poster_sources":    [{ "src": "https://.../ja-JP/poster.jpg" }],
      "thumbnail_sources": [{ "src": "https://.../ja-JP/thumbnail.jpg" }]
    },
    {
      "language": "fr-FR",
      "name": "Le Grand Bleu"
    }
  ]
}