CONTENTS
1. REVISION HISTORY
Version Number | Date | Comment |
|---|---|---|
| 1.1 | 2021-09-30 |
|
1.0 | 2021-03-31 | Publication release |
2. INTRODUCTION
The Vewd software stack has been deployed on a wide range of connected TV & STB devices for more than a decade, addressing web and video rendering. For the last four years, Vewd has invested in building UX and API products focusing on apps and content. The vision is to bring the content closer to the device UX features, so it's easier to search and discover content. Vewd sees metadata ingestion and deep-linking content as an essential activity for bringing additional traffic and exposure to apps and content owners on a device. The use-cases below are described using Vewd turnkey products UX, but they are equally applicable to Vewd customer’s device user interfaces built on top of our API.
2.1 Scope
This document explains the data attributes needed for content metadata ingestion and how it will be shown on the device.
2.2 Abstract
Vewd has an onboarding process for ingesting content metadata of apps, so content discovery and search can be enabled in the device UI. To have content metadata for an app onboarded by Vewd, the owner or developer of the content must share it for a review using the Vewd Submission Portal or over email. This document defines the requirements and the process for ingesting the content metadata and gives an overview of how it will be shown in the device user interface. Compliant metadata feeds are required by Vewd and will have a quicker time to market. While the metadata attributes may not be compliant with this specification, Vewd will review and process the content feed and provide feedback on what may need to change.
2.3 Definitions and acronyms
Item | Description |
Vewd OS | Vewd OS is a complete Over The Top (OTT) management and presentation system for Smart TVs. It includes an user-interface with quick access to OTT apps, content, search, device settings, Linear TV & program guide |
Vewd OpX | Vewd OpX is a cloud-managed Operator-grade set-top box experience, integrating PayTV services with OTT content. It is based on a flexible set of UX modules (UXM) that can be combined to build or enhance a TV experience |
Vewd App Store | The Vewd App Store is an HTML5-based storefront of web apps optimized for TV. The Vewd App Store and its apps run from the cloud and are optimized for the TV user experience and its 4-way navigation remote control |
Vewd Content Suite API | API access of app & content metadata for integrators, so they can easily integrate and launch content from their device |
Content metadata | Access to additional information about the video, such as title, description, genre, thumbnail and other data attributes described above |
CSP | Content service provider, the party who provides the apps & the content |
Deep link | A content deep-link is an URL within the application which either plays out the content or explains more information about the content before it can be played. |
Clip | A video item which is mostly short to medium form. Typical metadata fields include title, description and category. |
Livestream | A video item which is streamed over the Internet without any end duration time. The stream is broadcasting content constantly. Examples include free linear TV channels. |
Movies | A video item which is mostly medium to long-form. It represents movies as a content type. Typically the movie metadata fields include title, year, genre, synopsis, rating, cast & crew, trailers, posters, rating and much more. |
TV Series | A content structure of TV Episodes and TV Seasons for a given TV Series. |
TV Seasons | A content structure of TV Episodes belonging to a TV Series. |
TV Episodes | A video item always associated with a TV Series and optionally with a TV Seasons. The content is mostly medium form. |
2.4 Compliance terminology used in this document
The following keywords used in this specification to indicate the level of compliance needed for the requirements are sourced from RFC2119. In essence:
MUST, REQUIRE or SHALL indicates that you need to comply with the requirement absolutely.
SHOULD or RECOMMENDED indicates that while sometimes there could be valid reasons to ignore the requirement, you need to fully understand and accept the implications and risks to the optimal end-user experience.
MAY or OPTIONAL indicates that you can decide to implement an item at your discretion.
We also use an additional compliance term not described in RFC2119.
CONDITIONALLY REQUIRED - an item or a feature is supported in the browser if the underlying platform supports this capability.
2.5 Metadata use cases
2.5.1 Overview
Enable content discovery for your app
Apps traditionally live inside a device user-interface within the home screen, app section, or category in an app store. The content in the app is not discoverable unless the app is accessed. To solve this, the content owner needs to expose access to metadata and deep-links of their content. The content can be made discoverable on Vewd enabled devices through a compliant content metadata feed. This chapter gives a visual overview of the use-cases Vewd will utilize in the device home screen using metadata feed from content owners. These UX features are called app preview, promotions, and catalog search.
2.5.2 App preview
App preview provides a sneak peek of what type of content the app is providing. The content can be launched directly from the home screen and into the app through a deep-link, so the end-user can quickly discover and launch new content. We recommend that CSPs provide promotional content feeds with the most engaging content assets and keep it maintained and fresh over time(*).
*Vewd will display the content in the order we receive it from the content feed as default, alternatively utilize the publishing date of the content
Example app preview in action:
2.5.3 Promotions
Promotion is used as part of the featured section in Vewd UX products. It autoplay videos on device startup and focuses on a limited set of video promotion items for a given period.
Example promotions in action:
2.5.4 Catalog search
Make the app and its content searchable within Vewd UX products by sharing a compliant full catalog content metadata feed. Vewd will then ingest the content according to the supported content types, for example as movies, TV Series, and clips. From what we have seen, this increases content discoverability and traffic into the app.
Example of catalog search in action:
2.5.5 Data attributes by content types
Element | Description | Clips | Movies | TV Series | TV Seasons | TV Episodes | Livestream |
(base-attributes) | |||||||
id | Unique content id | M | M | M | M | M | M |
media-type | Media type indicates the type of content: clip, movie, tv_series, tv_season, tv_episode, live stream | M | M | M | M | M | M |
metadata-language | Language used in the metadata attribute (ex. title, description) in RFC 3066 format.(1) | M | M | M | M | M | M |
title | Content title | M | M | M | M | M | M |
description | Content description | M | O | O | O | O | O |
publish-date | The date when the content became available in the catalogue in ISO 8601 format | M | M | M | M | M | M |
| (content-attributes) | |||||||
country-availability | List of countries in ISO 3166-1 alpha-2 format for which the content is available | M | M | M | M | M | M |
duration | Content duration in seconds or in ISO 8601 format | M | M | - | - | M | - |
deep-links | List of content deep links URL associated with ISO 3166-1 alpha-2 country code for which the deep-link is targeted. Please note: The deep-link should be pointing to a Vewd enabled Smart TV app version | M | M | O | M | M | M |
audio-language | Content original audio language as RFC 3066 language code | O | O | O | O | O | O |
captions | List of available subtitles languages as RFC 3066 language codes | O | O | O | O | O | O |
aired-date | The UTC date that clip was first aired or made available (aka release date) in ISO 8601 format | O | O | O | O | O | - |
tags | List of content descriptor tags | O | O | O | O | O | O |
genres | List of content categories and genres | M | O | O | O | O | O |
monetisation | Generic pricing indication of the content, typically indicating: 1. "free" - freely available, no ads 2. "avod" - ads based VOD, free with advertisement 3. "tvod" - transaction based VOD, you pay for a single movie 4. "svod"- subscription based VOD, you pay a subscription fee | O | O | O | O | O | O |
images | List of Images, indication image type (thumbnail, poster) URL, width and height Expected Images format:
| M | M | M | O | M | M |
(tv series specific attributes) | |||||||
series-id | Unique TV Series id | - | - | - | M | M | - |
season-id | Unique TV Season id | - | - | - | - | M | - |
number | Season or Episodes number | - | - | - | M | M | - |
M : mandatory
O : optional
- : Not applicable
(1) Please note: metadata-language declares the language used for specific metadata (ex. title, description). It does not mean availability of the content in that region or content audio language.
2.5.6 Images
Image resolution and format
Aspect ratio and content Attributes | Minimum resolution (pixels) | File extension | Clips | Movies | TV Series | TV Episodes | TV Seasons |
16:9, thumbnail | 640x360 | JPEG, PNG, or WebP | ✅ | ✅ | ✅ | ✅ | ✅ |
4:3, thumbnail | 480x360 | JPEG, PNG, or WebP | ✅ | ✅ | ✅ | ✅ | ✅ |
2:3, poster | 300x450 | JPEG, PNG, or WebP |  | ✅ | ✅ | ✅ | ✅ |
3:4, poster | 345x460 | JPEG, PNG, or WebP | | ✅ | ✅ | ✅ | ✅ |
1:1, square | 360x360 | JPEG, PNG, or WebP | | | ✅ | | |
✅ - Format is supported.
- Images in this format will be ignored.
An image can have slightly different aspect ratios than the above. If such is the case, the image will be resized to fill a rectangle corresponding to its target aspect ratio, then centered horizontally and vertically in the said rectangle. Pixels that overflow the target rectangle will be cropped.
In case several formats are supported, Vewd prefers and will prioritise presentation of images in the following order:
16:9 thumbnail -> 4:3 thumbnail -> 1:1 square -> 3:4 poster -> 2:3 poster
Image examples
Thumbnail example (640x360 resolution & 16:9 aspect ratio) | Thumbnail example (480x360 resolution & 4:3 aspect ratio) |
|
|
Poster example ( 300x450 resolution & 2:3 aspect ratio) | Poster example ( 345x460 resolution & 3:4 aspect ratio) |
 |
|
Square example (360x360 resolution & 1:1 aspect ratio) | |
| |
3. Metadata onboarding process
3.1 Onboarding process
- CSP gets familiar with Vewd UX products & metadata use-cases visually
- CSP agrees with Vewd to ingest metadata
- CSP provides access to the metadata (promotional and full catalogue feeds) and describes data elements mapping to Vewd data points - 2.5.5 Data attributes by content types
- Vewd validates and/or maps the metadata to this specification (some feed adaptations may be needed, for example in area of localisations, images formats, genres dictionaries or others)
- Vewd perform onboarding tests
- Vewd team provides test results to the CSP
- If tests are positive the ingestion can start
- If there are major issues, they need to be fixed and validated before the ingestion can start
3.1.1 Onboarding tests insights
During the onboarding tests Vewd team will check if:
- All mandatory data elements are present for each media type for both promotional and full catalogue feeds
- Feed payload is successfully ingested by Vewd software
- Selected elements from metadata are visible in Vewd Content Suite API
3.2 Metadata availability
We require the metadata endpoint to be widely accessible for our distributed servers. In case it’s required to limit the availability of the endpoint by e.g whitelisting IP addresses then please use the below list.
The following IP addresses must be allowed to access metadata endpoint(s):
- 107.167.100.112
- 107.167.100.113
- 185.26.182.90
- 185.26.182.94
- 35.165.86.48
- 217.17.35.152/29
- 157.22.251.128/29
- 91.203.97.128/25
- 185.217.214.0/24
- 185.217.212.0/24
3.2.1 Metadata re-indexing rate
Once the metadata ingestion is officially kicked-off we will periodically check changes in the endpoint and update our index. The refresh rate is around 6 hours but may change in the future without prior notice. It means that any change to your content availability (adding or removing videos or change of metadata) might take up to 6 hours to show in the device user-interface.
Please note: In case of deletions in the metadata payload the respective content shall remain accessible for the next 6 hours to let this change be propagated to devices from which the application is being launched. Otherwise, applications may use deep links leading to no content.
3.3 Metadata format
CSP shall expose metadata payload compliant with the data points described in the 2.5.5 Data attributes by content types providing all mandatory attributes and mapping to them. CSP may expose optional or additional data elements in the content feed not covered by this specification, yet they will be ignored. Vewd reserves the right to normalize and map the metadata set received from the CSP with an additional set of attributes from internal or external sources, making the content more discoverable for the end-user.
At this stage Vewd does not specify metadata format implicitly and is willing to adopt market formats in use, such as but not limited to Google Media Action. However we expect that metadata payload will contain a flat list of content items (one dimension array, no nested subarrays), where TVSeries/TVSeasons/TVEpisode relation is represented by media-type & series-id and/or season-id respectively.