Overview

Quickstart

Catalogue-to-cabin content delivery for airline IFE systems

Outcome

This quickstart demonstrates API integration to deliver and load music into an in-flight entertainment (IFE) system

Step you will complete

Auth → Catalogue access → Playlist curation → content delivery → Export→ Royalty reporting

Timed required

~15-20 minutes

Prerequisites

A StoreId issued by Tuned Global for your airline environment
OAuth2 client credentials (client ID and secret) from Tuned Global
Access to the Catalogue Delivery Service (CDS) — confirm with Tuned Global
HMAC credentials if using authenticated CDS endpoints
A content staging environment where IFE builds are assembled before upload to aircraft

Architecture: catalogue to cabin

In-flight entertainment operates on a fundamentally different model to consumer streaming. There is no real-time API access at 35,000 feet — everything is pre-loaded.

Title

Description

Aspect	Consumer Streaming	Store-and-Forward
Connectivity	Always online	Offline during flight
Content delivery	Stream on demand	Pre-loaded content builds
Update frequency	Real-time	Monthly or per-cycle builds
Playlist control	User-driven	Curated by airline/content team
Rights model	Per-territory streaming	Per-territory, per-route clearance
Reporting	Real-time play logs	Post-flight batch reporting

The typical sync cycle

Curate — Content team builds playlists using Tuned Global's CMS (Autotune) or via API
Validate — Confirm all tracks are rights-cleared for the airline's routes and territories
Export — Download audio files and metadata via the CDS API
Build — Assemble the content package for your IFE system format
Load — Deploy the build to aircraft (via ground-based upload or portable media)
Report — After flights, submit play logs for royalty reporting

Step-by-step implementation

1

Step 1: Authenticate

Obtain a JWT token using your service account credentials.

👉 Endpoint: POST https://api-authentication-connect.tunedglobal.com/oauth2/token

Bash

 curl -X POST "https://api-authentication-connect.tunedglobal.com/oauth2/token" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Response:

Bash

 {
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 86400
}

Save the access_token for all subsequent requests.

2

Step 2: Browse and search the catalogue

Search the licensed catalogue to discover tracks available for your IFE programme. Only tracks cleared under your agreement will be returned.

Search by Keyword

👉 Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/search/songs

Bash

 curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/search/songs?q=Bohemian%20Rhapsody&offset=0&count=10" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Country: AU"

Advanced Search

Use advanced search to filter by genre, mood, BPM, decade, or custom tags — useful for building themed playlists (e.g. "relaxing jazz for long-haul", "upbeat pop for boarding").

👉 Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/search/songs/advanced

Bash

 curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/search/songs/advanced?genre=Jazz&mood=Relaxing&offset=0&count=50" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Country: AU"

Browse by artist or album

👉 Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/artists/{artistId}/songs

👉 Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/albums/{albumId}

Note the Track IDs from search results — you'll need them when building playlists and requesting audio files.

3

Step 3: Retrieve track and Album Metadata

Fetch detailed metadata for tracks you plan to include in the IFE build. This metadata populates the on-screen display for passengers.

Track details

👉 Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/tracks/{trackId}

Bash

 curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/tracks/987654" \
  -H "StoreId: YOUR_STORE_ID"

Returns: track name, artist, album, duration, ISRC, genre, and image URLs.

Album artwork

Use the image engine to generate artwork sized for your IFE screen resolutions:

HTTP

 https://[THUMBOR_URL]/unsafe/fit-in/600x600/filters:quality(80):format(jpeg)/[image_path]

See the Image Handling guide for full details on resizing and format options.

Bulk metadata

For large playlist builds, fetch multiple tracks in a single request:

👉 Endpoint: POST https://api-metadata-connect.tunedglobal.com/api/v2.4/tracks/multiple

Bash

 curl -X POST "https://api-metadata-connect.tunedglobal.com/api/v2.4/tracks/multiple" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Content-Type: application/json" \
  -d '{"TrackIds": [987654, 987655, 987656, 987657]}'

4

Step 4: Manage playlists

IFE playlists are typically curated by the airline's content team or an in-flight entertainment content porvider (CSP). Playlists can be created and managed via the Autotune CMS or programmatically via the API.

Fetch an existing playlist

👉 Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/{playlistId}

Bash

 curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/55001?offset=0&count=500" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The response contains the full track listing with metadata — this becomes your playlist manifest for the IFE build.

Check for playlist updates

Before rebuilding content packages, check whether playlists have changed since your last export:

👉 Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/{playlistId}/updated

Bash

 curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/55001/updated" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Compare the returned timestamp against your last build to decide if a refresh is needed.

5

Step 5: Validate content rights

Before exporting audio, validate that every track in your playlist is cleared for the territories your airline operates in. This is critical — playing unlicensed content on international routes creates legal exposure.

Validate tracks

👉 Endpoint: POST https://api-services-connect.tunedglobal.com/api/v3/contentcontrol/validatetracks

Bash

 curl -X POST "https://api-services-connect.tunedglobal.com/api/v3/contentcontrol/validatetracks" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"TrackIds": [987654, 987655, 987656]}'

The response identifies any tracks that are invalid or have restricted territorial rights. Remove flagged tracks from your build before export.

6

Step 6: Export audio via CDS

The Catalogue Delivery Service (CDS) is the primary mechanism for exporting audio files for offline IFE builds. Unlike consumer streaming (which uses short-lived signed URLs), the CDS provides bulk audio delivery designed for content packaging workflows.

Request audio files

For each validated track, request the audio asset through the CDS:

👉 Endpoint: POST https://api-services-connect.tunedglobal.com/api/v3/plays/{deviceId}/{trackId}/token

Bash

 curl -X POST "https://api-services-connect.tunedglobal.com/api/v3/plays/IFE-BUILD-01/987654/token" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Then retrieve the download URL:

👉 Endpoint: POST https://api-services-connect.tunedglobal.com/api/v3/plays/{deviceId}/{trackId}/stream

Bash

 curl -X POST "https://api-services-connect.tunedglobal.com/api/v3/plays/IFE-BUILD-01/987654/stream?streamType=Music&streamProvider=Tuned" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '"STREAM_TOKEN_FROM_ABOVE"'

Download the file promptly — URLs are time-limited.

Build the content package

Once all audio files and metadata are downloaded:

Organise audio files by playlist and track order
Generate metadata manifests in your IFE system's required format (XML, JSON, or proprietary)
Include artwork at the resolutions your seatback or BYOD screens require
Package everything according to your IFE vendor's specification (e.g. Panasonic, Thales, Safran)

Content freshness

IFE content is typically refreshed on a monthly cycle. Plan your build schedule to:

Pull updated playlists and new releases at the start of each cycle
Validate rights for all territories on the airline's route network
Allow time for QA testing before deployment to aircraft
Coordinate with your IFE vendor's upload windows

7

Step 7: Report playback

After each flight, the IFE system generates play logs detailing which tracks passengers played. These logs must be submitted to Tuned Global for royalty reporting and compliance.

Log Format

Each play event should include:

Bash

 {
  "TrackId": 987654,
  "LogPlayType": "Start",
  "Seconds": 0,
  "Source": "Playlist",
  "SourceId": "55001",
  "Guid": "unique-play-event-id",
  "Country": "AU",
  "PlayerType": "IFE"
}

Required event types:

Plain text

LogPlayType       When                                          Seconds
---------------   -------------------------------------------   ----------------
Start             Passenger begins playback                     0
30SecondMark      30 seconds elapsed (mandatory for royalties)  30
EndOfFile         Track finishes                                Total duration
Skip              Passenger skips track                         Current position LogPlayType       When                                          Seconds
---------------   -------------------------------------------   ----------------
Start             Passenger begins playback                     0
30SecondMark      30 seconds elapsed (mandatory for royalties)  30
EndOfFile         Track finishes                                Total duration
Skip              Passenger skips track                         Current position

Batch Upload

👉 Endpoint: POST https://api-services-connect.tunedglobal.com/api/v3/plays/{deviceId}

Bash

 curl -X POST "https://api-services-connect.tunedglobal.com/api/v3/plays/IFE-AIRCRAFT-9MXYZ" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "TrackId": 987654,
    "LogPlayType": "Start",
    "Seconds": 0,
    "Source": "Playlist",
    "SourceId": "55001",
    "Guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "Country": "AU",
    "PlayerType": "IFE"
  }'

Upload logs in batch after each flight or group of flights. The aircraft's tail number or registration makes a good device identifier for tracking.

BYOD (Bring Your Own Device) model

Some airlines offer a wireless IFE model where passengers stream content on their personal devices via the aircraft's onboard Wi-Fi network. In this model:

The aircraft runs a local media server with pre-cached content
Passengers connect to the cabin Wi-Fi and access a web portal or companion app
Streaming happens locally (aircraft server to passenger device) — no ground internet required
The integration follows the same content preparation steps above, but the media server handles playback and logging

For BYOD deployments, Tuned Global can provide white-label streaming applications that passengers use before, during, and after their journey. Contact Tuned Global for BYOD-specific integration guidance.

Troubleshooting

403 on content export: Token expired or licence lapsed. Re-authenticate (Step 1), verify CDS access.
Track validation fails: Track removed or rights changed. Remove track from build, check for replacement.
Missing metadata fields: Track not fully ingested. Contact Tuned Global support.
Artwork returns 404: Image URL changed since last build. Re-fetch metadata (Step 3) for updated URLs.
Play logs rejected: Invalid device ID or malformed payload. Verify JSON format matches schema.
Territory mismatch: Playlist contains tracks not cleared. Re-validate per territory (Step 5).

Quick Reference — Sync Endpoints

👉 Authenticate - POST /oauth2/token

👉 Search catalogue - GET /api/v2.4/search/songs

👉 Advanced search - GET /api/v2.4/search/songs/advanced

👉 Track metadata - GET /api/v2.4/tracks/{trackId}

👉 Bulk track metadata - POST /api/v2.4/tracks/multiple

👉 Fetch playlist - GET /api/v2.4/playlists/{playlistId}

👉 Check playlist update - GET /api/v2.4/playlists/{playlistId}/updated

👉 Validate tracks - POST /api/v3/contentcontrol/validatetracks

👉 Request stream token - POST /api/v3/plays/{deviceId}/{trackId}/token

👉 Get download URL - POST /api/v3/plays/{deviceId}/{trackId}/stream

👉 Upload play log - POST /api/v3/plays/{deviceId}

Notes

Replace YOUR_STORE_ID, YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_ACCESS_TOKEN, and example IDs with your actual credentials from Tuned Global.
Metadata endpoints use API version 2.4 or above. Services endpoints use v3.
Aviation licensing is distinct from consumer streaming. Your agreement covers specific content, territories, and usage rights — the API
enforces these restrictions automatically. For large fleet deployments or custom CDS workflows, contact Tuned Global about dedicated build pipelines and RAPPORT reporting integration.

Sections

Quickstart

Outcome

Step you will complete

Timed required

~15-20 minutes

Prerequisites

Architecture: catalogue to cabin

The typical sync cycle

Step-by-step implementation

1

Step 1: Authenticate

2

Step 2: Browse and search the catalogue

Search by Keyword

Advanced Search

Browse by artist or album

3

Step 3: Retrieve track and Album Metadata

Track details

Album artwork

Bulk metadata

4

Step 4: Manage playlists

Fetch an existing playlist

Check for playlist updates

5

Step 5: Validate content rights

Validate tracks

6

Step 6: Export audio via CDS

Request audio files

Build the content package

Content freshness

7

Step 7: Report playback

Log Format

Batch Upload

BYOD (Bring Your Own Device) model

Troubleshooting

Quick Reference — Sync Endpoints

Notes

What made this section helpful for you?

What made this section unhelpful for you?

On this page