Feed Setup

To ensure a seamless and consistent user experience across all platforms, the precise structuring of metadata is of vital importance. While core specifications—such as IDs, titles, and basic assets—remain uniform across the ecosystem, each content category requires specific extensions to accurately reflect its unique characteristics. The following sections detail the technical requirements and field definitions for our three primary content feeds. The goal is to standardize global attributes like durations, genre mapping, and availability windows, while incorporating type-specific metadata:

Movies: Focusing on standalone events and cinematographic details.
Series: Organizing hierarchical structures, including season and episode management.
Sports: Managing live dynamics, tournament frameworks, and time-sensitive replay logic.

Core Metadata

Scroll the table horizontally to see more.

Field Name	Value & Format	Description	Movies	Series	Seasons	Episodes	Sport
id	`Integer` (e.g. 12345)	ID of the asset	required	required	required	required	required
created_at	`ISO 8601` (e.g. “2025-05-19T14:23:00Z”)	UTC timestamp indicating the last time this item was created	required	required	required	required	required
updated_at	`ISO 8601` (e.g. “2025-05-19T14:23:00Z”)	UTC timestamp indicating the last time this item was modified	required	required	required	required	required
type	`Enum`: “movie”, “tv_show”, “season”, “episode”, “sport_program”	Type of content	required	required	required	required	required
original_title	`String` (e.g. “Inception”)	Official/original title of the content	required	required	required	required	required
titles	Array of `{ locale: string, title: string }`	Localized titles per language	required	required	required	required	required
synopses	Array of `{ locale: string, synopsis: string }`	Localized short synopsis ( $\le$ 200 characters)	required	required	required	required	required
year	`Integer` (e.g. 2010)	Year of release	required	required	required	required	required
duration	`Integer` (seconds) (e.g. 8880)	Total runtime in seconds	required	required	required	required	optional
deeplinkings	Array of `{ market: string, action: string, device_type: "TV", url: string }`	Deep links for launching TV content in partner apps. For more details see the deep links section.	required	required	required	required	required
availabilities	Array of objects	Availability of content per country/business model Add section for availabilities	required	required	required	required	required
availabilities[].market	Array of ISO 3166 country code (e.g. “US”)	Target markets	required	required	required	required	required
availabilities[].business_model	`Enum`: “AVOD”, “HVOD”, “RVOD”, “TVOD”, “SVOD”, “EST”	AVOD (free ad-supported), HVOD (subscription + ads), etc.	required	required	required	required	required
availabilities[].price	`Number`	The numerical value of the content (e.g., 3.99).	If Applicable	If Applicable	If Applicable	If Applicable	If Applicable
availabilities[].currency	ISO 4217 currency code	Currency of the price. (e.g., EUR, GBP, USD).	If Applicable	If Applicable	If Applicable	If Applicable	If Applicable
availabilities[].video_quality	`Enum`: “SD”, “HD”, “UHD”	Supported video resolutions	required	required	required	required	required
availabilities[].availability_start	`ISO 8601` (e.g. “2025-05-19T14:23:00Z”)	UTC timestamp indicating the first day this content is available in the application	optional	optional	optional	optional	optional
availabilities[].availability_end	`ISO 8601` (e.g. “2025-05-19T14:23:00Z”)	UTC timestamp indicating the last day this content is available in the application	optional	optional	optional	optional	optional
artwork_landscape	Array of `{ locale: string, url: string }`	Mandatory horizontal artwork with title treatment ( $\ge$ 960x540, 16:9) Add section for artwork	required	required	required	required	required
screenshot_landscape	Array of `{ locale: string, url: string }`	Horizontal screenshot without TT ( $\ge$ 1920x1080, desired 4K, 16:9)	required	required	required	required	required
screenshot_portrait	Array of `{ locale: string, url: string }`	Optional portrait screenshot ( $\ge$ 400px, ideal $\ge$ 800px)	required	required	required	required	required
artwork_portrait	Array of `{ locale: string, url: string }`	Optional vertical poster/artwork ( $\ge$ 640px, ideal $\ge$ 960px)	required	required	required	required	required
transparent_logo	`{ locale: string, url: string }`	Optional logo with transparent background ( $\ge$ 400px, ideal $\ge$ 640px)	optional	optional	optional	optional	optional
genres	Array of `Enum` or TVA genre codes	Must match predefined list (Action, Drama, etc.) We support TV Anytime (TVA) standard for Genres and strongly recommend using TVA genre codes. Link to section for genres	required	required	required	required	required
dominant_genre	`String` (e.g. “Drama”) OR TVA genre code	The master genre for the title. This single value determines where the content appears in category rows and filters. Link to section for genres	required	required	required	required	If Applicable
classifications	Array of `{ country: string, minimum_age: integer, code: string, system: string }`	Age restrictions per country Add section for AgeRating	required	required	required	required	required
external_id	Array of `{ type: "imdb" \| "tmdb", id: string }`	External content identifier (IMDB or TMDB)	required	required	required	required	optional
actors	Array of `{ name: string }`	Actor Names	required	required	required	required	N/A
directors	Array of `{ name: string }`	Director Names	required	required	required	required	N/A
series_info	array of object	contains relevant information of the series	N/A	required	N/A	N/A	N/A
series_info[].total_numbers_seasons	`Integer` (e.g. 3)	Total numbers of Seasons (for Series)	N/A	required	N/A	N/A	N/A
series_info[].total_numbers_episodes	`Integer` (e.g. 36)	Total numbers of Episodes (for Series)	N/A	required	N/A	N/A	N/A
season_info	array of object	contains relevant information of the season	N/A	N/A	required	N/A	N/A
season_info[].parent_series_id	`Integer` (e.g. 12345)	ID of the series. Correspondents with the content id of the series the season belongs to	N/A	N/A	required	N/A	N/A
season_info[].season_number	`Integer` (e.g. 2)	Number of the current Season	N/A	N/A	required	N/A	N/A
season_info[].total_number_episodes	`Integer` (e.g. 7)	Total numbers of Episodes in this season	N/A	N/A	required	N/A	N/A
episode_info	array of object	contains relevant information of the episode	N/A	N/A	N/A	required	N/A
episode_info[].parent_series_id	`Integer` (e.g. 12345)	ID of the series. Correspondents with the content id of the series the episode belongs to	N/A	N/A	N/A	required	N/A
episode_info[].parent_season_id	`Integer` (e.g. 12345)	ID of the current season this episode belongs to	N/A	N/A	N/A	required	N/A
episode_info[].season_number	`Integer` (e.g. 2)	Number of the season this episode belongs to	N/A	N/A	N/A	required	N/A
episode_info[].episode_number	`Integer` (e.g. 4)	Episode number in this season	N/A	N/A	N/A	required	N/A
sport_event_info		contains relevant information for sport content	N/A	N/A	N/A	N/A	required
sport_event_info[].discipline	`String` (e.g. “Football”)		N/A	N/A	N/A	N/A	required
sport_event_info[].sub_discipline	`String` (e.g. “U21”, “Heavyweight”)	Used for age groups (e.g. “U21”), weight classes (e.g. “Heavyweight”), or specific disciplines within a sport (e.g. “Beach Soccer”)	N/A	N/A	N/A	N/A	If Applicable
sport_event_info[].gender	`Enum`: “male”, “female”, “mixed”		N/A	N/A	N/A	N/A	required
sport_event_info[].tournament	`String` (e.g. “UEFA Champions League”)		N/A	N/A	N/A	N/A	If Applicable
sport_event_info[].league	`String` (e.g. “Primera Division”)		N/A	N/A	N/A	N/A	If Applicable
sport_event_info[].competition_stage	`String` (e.g. “Quarter Final” or “Matchday 12“ or “Qualifying“ or “Race”)		N/A	N/A	N/A	N/A	If Applicable
sport_event_info[].is_olympic	`boolean`	indicates if the event is part of olympic games	N/A	N/A	N/A	N/A	required
sport_event_info[].type_of_event	`Enum`: “full_event”, “highlights”, “magazine”, “documentary”, “press_conference”, “interview”, “full_event_replay”		N/A	N/A	N/A	N/A	required
sport_event_info[].competitor_home	`String` (e.g. “FC Barcelona”)		N/A	N/A	N/A	N/A	If Applicable
sport_event_info[].competitor_away	`String` (e.g. “Real Madrid”)		N/A	N/A	N/A	N/A	If Applicable
sport_event_info[].location		contains relevant information for event location	N/A	N/A	N/A	N/A	required
sport_event_info[].location[].country	`String` (e.g. “Spain”)		N/A	N/A	N/A	N/A	If Applicable
sport_event_info[].location[].city	`String` (e.g. “Barcelona”)		N/A	N/A	N/A	N/A	If Applicable
sport_event_info[].location[].venue	`String` (e.g. “Spotify Camp Nou”)		N/A	N/A	N/A	N/A	If Applicable
sport_event_info[].live_timeline		contains relevant information for event timeline	N/A	N/A	N/A	N/A	required
sport_event_info[].live_timeline[].start_time	`ISO 8601` (e.g. “2025-05-19T14:23:00Z”)	Scheduled start time of the event	N/A	N/A	N/A	N/A	required
sport_event_info[].live_timeline[].actual_start_time	`ISO 8601` (e.g. “2025-05-19T14:23:00Z”)	Scheduled start time of the event	N/A	N/A	N/A	N/A	required
sport_event_info[].live_timeline[].end_time	`ISO 8601` (e.g. “2025-05-19T14:23:00Z”)	Scheduled end time of the event	N/A	N/A	N/A	N/A	required
sport_event_info[].live_timeline[].status	`Enum`: “pre_event”, “live”, “ended”, “delayed”, “postponed”, “cancelled”	Indicates the current status of the event	N/A	N/A	N/A	N/A	required
sport_event_info[].live_timeline[].is_restart_enabled	`boolean`	indicates if the user can start from the beginning	N/A	N/A	N/A	N/A	required

Genres

To maintain a consistent browsing experience and power our recommendation engines, TitanOS requires all content to be tagged with accurate genre metadata. We currently support a native set of fixed genres. We strongly support a industry-standard classification systems like TVA (TV-Anytime) to allow for more granular mapping.

Genre Standards & Recommendations

TitanOS supports both our internal native genre set and the industry-standard TV-Anytime (TVA) classification system.

We strongly recommend providing your genre tags using the TVA standard.

Why use TVA?

Granularity: It offers a deeper level of detail than standard lists, allowing for more precise content placement.
Future-Proofing: It ensures your content is ready for upcoming discovery features and advanced algorithms without needing future metadata changes.
Maintenance: Using an industry standard ensures long-term support for your feed as the TitanOS platform evolves.

Supported Native Genre Set

Currently, TitanOS utilizes a fixed set of primary genres. When providing your feed, please map your internal categories to the following supported values, or TVA values:


Action	Documentary	Mystery
Adventure	Drama	Reality
Animation	Family	Romance
Biography	Fantasy	Sci-Fi
Kids	History	Thriller
Comedy	Horror	War
Crime	Musical	Western

The `dominant_genre` Field

In our updated Metadata Schema, we have introduced the dominant_genre field. This is the primary value used by the TitanOS UI to place your content into grids, filters, and category rows.

Requirement: Every content record must contain one (1) `dominant_genre value.
Logic: While you may provide a list of multiple genres for search and recommendation purposes, the system will prioritize the value in the dominant_genre field for all primary UI displays.
Fallback: If you don’t provide the dominant_genre field our system may use the first assigned genre in the genre set

Implementation Guidelines

*Standard Mapping: If using our native set, ensure the spelling and casing match the table above exactly to avoid ingestion errors.
TVA Integration: If you provide TVA codes, our system automatically maps them to the corresponding TitanOS UI category while retaining the granular data for backend optimization.
Single Value: Unlike general genre tags, the dominant_genre field must contain only one primary classification to ensure consistent UI rendering.

Artwork

To ensure content is displayed correctly across the TitanOS interface, all visual assets must follow specific technical standards. These requirements prevent display issues such as blurred images, incorrect cropping, or ingestion errors.

Core Delivery Rules

Format & Compatibility: All images must be delivered in JPEG or PNG format using the sRGB color space.
Asset Availability: Artwork must be hosted on a stable, public-facing server (HTTPS) that allows the TitanOS ingestion system to download the files.
Update Logic: If you change an image, you must update the image URL or the metadata timestamp. Our system caches images, so keeping the same URL for a new image will prevent the UI from updating.
Resolution & Scaling: Always provide the highest required resolution. Images will be scaled down for lower-end devices, but low-resolution source files may be rejected to avoid pixelation on 4K displays.

UI Safe Zones

When preparing artwork, keep primary visual elements (such as faces or titles) centered. TitanOS may overlay text or other UI elements on the edges of the image.

Technical Specification Overview

Requirement	Standard
File Formats	JPEG (.jpg), PNG (.png)
Max File Size	U2MB (Recommended for fast loading)
Protocol	HTTPS required
Color Profile	sRGB

Note: Providing assets that do not match the required aspect ratios (e.g., sending a 4:3 image for a 16:9 slot) will result in automatic cropping or padding, which may distort the intended look of your content.

Artwork Examples

artwork_portrait

Aspect ratio: 2:3
Resolution: Minimum width of 400px (Recommended: 800px or higher)

screenshot_portrait

Aspect ratio: 2:3
Resolution: Minimum width of 640px (Recommended: 960px)

artwork_landscape

Aspect ratio: 16:9
Resolution: Minimum width of 640px (Recommended: 960px or higher)

screenshot_landscape

Aspect ratio: 16:9
Resolution: Minimum width of 1920px (Recommended: 3840px)

transparent_logo

Size: Minimum width of 400px (Recommended: 640px or higher)

Deeplinks

Deep links are the primary mechanism for navigating users from the TitanOS discovery interface directly to specific titles within your application. Once an application has passed QA and is live on the platform, deep links must function autonomously and lead directly to the content.

Technical Preconditions

To ensure a successful integration, your application and metadata must meet the following standards:

HTML5 Accessibility: The application must be a web-based app accessible via a stable URL.
Routing Logic: For Single Page Applications (SPAs), the internal routing must be configured to parse incoming URL paths or parameters and resolve the correct view state immediately.
Destination Targets: We support and recommend two levels of deep linking: Content Details: Leads the user to the movie or series overview page. Direct Player (Recommended): Navigates the user directly into the video player to start playback.
Geoblocking: Since TitanOS is a global platform, ensure the deep link provided for a specific market (e.g., ES) is not geoblocked for users in that region.

URL Construction & Structure

For HTML5 applications, the final landing URL is created by appending the content-specific path provided in your metadata to the application’s registered Base URL. The Formula: + / +

App Base URL: https://titanos.partner-app.com
Metadata Path: video/12345
Final Result: https://titanos.partner-app.com/video/12345

Example 1: Standard Path Routing Best for: Applications using a traditional folder-based structure.

"deeplinkings": [
  {
    "market": "DE",
    "action": "play",
    "device_type": "TV",
    "url": "https://titanos.partner-app.com/movies/interstellar-2014"
  }
]

Example 2: Direct Player (ID-based) Best for: The recommended “Direct to Player” experience using unique content IDs.

"deeplinkings": [
  {
    "market": "ES",
    "action": "play",
    "device_type": "TV",
    "url": "https://titanos.partner-app.com/player/550e8400-e29b"
  }

Example 3: Query Parameter Routing Best for: SPAs or apps that parse IDs via query strings rather than URL paths.

"deeplinkings": [
  {
    "market": "GB",
    "action": "play",
    "device_type": "TV",
    "url": "https://titanos.partner-app.com/launch?content_id=998877&autoplay=true"
  }
]

Deep Link Action Types & Target Intent

To provide a seamless discovery experience, TitanOS needs to know the exact behavior of an incoming deep link. Partners must categorize their links based on the destination experience to ensure the user journey aligns with the UI action. Supported Action Values We categorize deep link destinations into two distinct behaviors:

action: details (Content Details Page): Navigates the user to the informational overview or landing page of the asset. This value is mandatory for Series and Seasons, as they are containers rather than playable video files.
action: play (Direct Player Launch): Bypasses all menus and launches video playback immediately. This is strongly preferred for Movies and individual Episodes to keep the user journey as short as possible.

Alternative Naming Suggestions If you prefer not to use details and play as the explicit values in your feed, here are a few industry-standard alternative pairs you can implement:

Option A (Intent-Based): details vs. playback
Option B (UX-Based): landing_page vs. direct_play
Option C (Technical): info_view vs. player_view

Availabilities

The availabilities object is used to define the commercial and technical terms under which a title is offered. This data allows the TitanOS to filter content correctly based on the user’s region, their subscription status, and the device’s display capabilities.

Data Structure

Availabilities are delivered as an array of objects. This structure allows a single piece of content to have different business models or video qualities across multiple territories. Requirement: Every content record must contain at least one availability object to be visible in the UI.

Field Specifications

Field	Type	Required	Description
market	Array	Yes	A list of ISO 3166-1 alpha-2 country codes (e.g., `["US", "DE"]`).
business_model	Yes	Reality	The monetization type (e.g., `AVOD`, `SVOD`). See definitions below.
video_quality	Yes	Romance	The highest resolution supported: `SD`, `HD`, or `UHD`.
price	Number	No*	The numerical price (e.g., `4.99`). Required for TVOD/EST.
currency	String	No*	ISO 4217 code (e.g., `EUR`). Required for TVOD/EST.
availability_start	String	No	ISO 8601 format. When the content becomes visible. When not provided content will be visible from the moment the content is included in the feed.
availability_end	String	No	ISO 8601 format. When the content is removed. When not provided content will be visible from the moment the content is removed from the feed.

Supported Business Models

To ensure content appears in the correct UI categories (e.g., “Free” Section), you must map your offer to one of the following enums:

AVOD: Free, ad-supported video on demand
SVOD: Subscription-based video on demand
TVOD: Transactional/Rental (rental / pay-per-view)
HVOD: Hybrid model (subscription + ads)
RVOD: Rental video on demand (specifically for limited windows)
EST: Electronic Sell-Through (digital purchase/buy-to-own)

Implementation Example

"availabilities": [
  {
    "market": ["ES"],
    "business_model": "AVOD",
    "video_quality": "HD",
    "price": null,
    "currency": null,
    "start_date": null,
    "end_date": null
  },
  {
    "market": ["DE"],
    "business_model": "TVOD",
    "video_quality": "UHD",
    "price": 4.99,
    "currency": "EUR",
    "start_date": "2026-06-01T12:00:00Z",
    "end_date": "2026-06-30T23:59:59Z"
  },
  {
    "market": ["GB"],
    "business_model": "SVOD",
    "video_quality": "HD",
    "price": null,
    "currency": null,
    "start_date": "2024-01-01T00:00:00Z",
    "end_date": "2026-12-31T23:59:59Z"
  }
]

Age Rating

To ensure regulatory compliance and support parental control features, TitanOS requires accurate age rating metadata for all content. Partners are responsible for providing the official classification for each market where the content is available.

Data Structure: classifications

Age ratings are provided as an array of objects. This structure allows you to specify different ratings and systems for different territories, as a title may have different legal requirements depending on the country. Requirement: Every content record must contain at least one classification object. TitanOS reserves the right to withhold publication of content lacking valid age rating information to mitigate legal risks.

Field	Type	Required	Description
country	String	Yes	ISO 3166-1 alpha-2 country code (e.g., `DE`, `ES`, `GB`).
system	String	Yes	The official rating body/system (e.g., `FSK`, `BBFC`, `ICAA`).
code	String	Yes	The specific rating code (e.g., `FSK12`, `15`, `PG-13`).
minimum_age	Integer	Yes	The numerical minimum age required (e.g., `12`, `15`, `13`).

Implementation Example

In this example, the content is classified for the German market using the FSK system and for the UK market using the BBFC system.

"classifications": [
  {
    "country": "DE",
    "system": "FSK",
    "code": "FSK12",
    "minimum_age": 12
  },
  {
    "country": "GB",
    "system": "BBFC",
    "code": "15",
    "minimum_age": 15
  }
]

Common Systems & Codes Reference

Country	System	Example Code	Minimum Age
Germany	`FSK`	FSK0, FSK6, FSK12, FSK16, FSK18	`0, 6, 12, 16, 18`
UK	`BBFC`	`U`, `PG`, `12A`, `15`, `18`	`0, 8, 12, 15, 18`
Spain	`ICAA`	`TP`, `7`, `12`, `16`, `18`	`0, 7, 12, 16, 18`
USA	`MPAA`	`G`, `PG`, `PG-13`, `R`, `NC-17`	`0, 10, 13, 17, 18`

Standardizing the code and system strings ensures that the TitanOS UI can dynamically display the correct local rating badges for every title, providing a familiar and safe experience for the end-user.

Get Started

Basics

Titan SDK

Advanced

Metadata

Testing & Debugging

FAST Channels

Partner Portal & FAQ

Core Metadata

Genres

Genre Standards & Recommendations

Supported Native Genre Set

The `dominant_genre` Field

Implementation Guidelines

Artwork

Core Delivery Rules

UI Safe Zones

Technical Specification Overview

Artwork Examples

Deeplinks

Technical Preconditions

URL Construction & Structure

Deep Link Action Types & Target Intent

Availabilities

Data Structure

Field Specifications

Supported Business Models

Implementation Example

Age Rating

Data Structure: classifications

Implementation Example

Common Systems & Codes Reference

Get Started

Basics

Titan SDK

Advanced

Metadata

Testing & Debugging

FAST Channels

Partner Portal & FAQ

Documentation Index

​Core Metadata

​Genres

​Genre Standards & Recommendations

​Supported Native Genre Set

​The dominant_genre Field

​Implementation Guidelines

​Artwork

​Core Delivery Rules

​UI Safe Zones

​Technical Specification Overview

​Artwork Examples

​Deeplinks

​Technical Preconditions

​URL Construction & Structure

​Deep Link Action Types & Target Intent

​Availabilities

​Data Structure

​Field Specifications

​Supported Business Models

​Implementation Example

​Age Rating

​Data Structure: classifications

​Implementation Example

​Common Systems & Codes Reference

Core Metadata

Genres

Genre Standards & Recommendations

Supported Native Genre Set

The `dominant_genre` Field

Implementation Guidelines

Artwork

Core Delivery Rules

UI Safe Zones

Technical Specification Overview

Artwork Examples

Deeplinks

Technical Preconditions

URL Construction & Structure

Deep Link Action Types & Target Intent

Availabilities

Data Structure

Field Specifications

Supported Business Models

Implementation Example

Age Rating

Data Structure: classifications

Implementation Example

Common Systems & Codes Reference