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.
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
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:
{
"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
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
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}
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:
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/get
curl -X POST "https://api-metadata-connect.tunedglobal.com/api/v2.4/tracks/get" \
-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}
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.
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-metadata-connect.tunedglobal.com/api/v2.3/tracks/validatetracks
curl -X POST "https://api-metadata-connect.tunedglobal.com/api/v2.3/tracks/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.
Important: Run validation for each territory your routes cover. A track cleared for Australia may not be cleared for the United States. Build territory-specific playlists or filter at the route level.
6
Step 6: Export audio via Delivery Assets API
The Delivery Assets API is the primary mechanism for exporting audio files for offline IFE builds. Unlike consumer streaming (which uses short-lived play tokens on the Services API), this endpoint returns a signed CDN URL for each track so you can download and package full-length audio into your IFE content build.
Asset requests use HMAC authentication (Tuned-HMAC). Generate a fresh signature for every request — see the HMAC Authentication section for how to build the Authorization header.
Every call to the Stream API automatically creates a fetch log used for monthly billing. Download each asset once per build cycle where possible.
Request audio files
For each validated track, request a signed download URL from the Delivery Assets Stream endpoint:
👉 Endpoint: POST https://api-delivery-connect.tunedglobal.com/api/v5/assets/{trackId}/stream
curl -X GET "https://api-delivery-connect.tunedglobal.com/api/v5/assets/987654/stream?quality=High&assetType=AAC" \
-H "StoreId: YOUR_STORE_ID" \
-H "Authorization: Tuned-HMAC YOUR_ACCESS_KEY:YOUR_SIGNATURE:YOUR_NONCE:YOUR_TIMESTAMP" \
-H "Accept: application/json"
The response is a signed CDN URL string. Download the file promptly — URLs are time-limited (typically around 30 seconds).
Optional: retrieve artwork for the same packaging pass:
👉 Endpoint: POST https://api-delivery-connect.tunedglobal.com/api/v5/assets/{id}/image
curl -X GET "https://api-delivery-connect.tunedglobal.com/api/v5/assets/987654/image?type=Track" \
-H "StoreId: YOUR_STORE_ID" \
-H "Authorization: Tuned-HMAC YOUR_ACCESS_KEY:YOUR_SIGNATURE:YOUR_NONCE:YOUR_TIMESTAMP" \
-H "Accept: application/json"
Use type=Album or type=Track as needed, then resize via the Tuned Global image engine if your seatback or BYOD screens require specific resolutions.
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:
[
{
"When": "2026-07-24T02:15:30.0000000Z",
"Log": {
"UserId": 12345,
"TrackId": 987654321,
"Country": "AU",
"LogPlayType": "Start",
"Seconds": 30,
"Source": "Playlist",
"PlayType": "Stream",
"SourceId": 1001,
"UserIp": "203.0.113.10",
"DeviceId": 55501,
"Latitude": -33.8688,
"Longitude": 151.2093,
"SubId": 201,
"Guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"AudioQuality": "high",
"ExternalPlanId": "plan_premium_monthly",
"PlayerType": "MobilePhone",
"Extras": "{\"session\":\"abc\"}",
"LogPlaySourceType": "Online"
}
}
]
Required event types:
LogPlayType When
--------------- -------------------------------------------
Start The track has started being played
Progress A track that has already started is continuing to be played
End The track successfully finished being played
Skip The track was skippedBatch Upload
👉 Endpoint: POST https://api-delivery-connect.tunedglobal.com/api/v5/play/logbatchplay
curl -X POST "https://api-delivery-connect.tunedglobal.com/api/v5/play/logbatchplay \
-H "StoreId: YOUR_STORE_ID" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '[
{
"When": "2026-07-24T02:15:30.0000000Z",
"Log": {
"UserId": 12345,
"TrackId": 987654321,
"Country": "AU",
"LogPlayType": "Start",
"Seconds": 30,
"Source": "Playlist",
"PlayType": "Stream",
"SourceId": 1001,
"UserIp": "203.0.113.10",
"DeviceId": 55501,
"Latitude": -33.8688,
"Longitude": 151.2093,
"SubId": 201,
"Guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"AudioQuality": "high",
"ExternalPlanId": "plan_premium_monthly",
"PlayerType": "MobilePhone",
"Extras": "{\"session\":\"abc\"}",
"LogPlaySourceType": "Online"
}
}
]'
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.
Critical: Play logs are legally required for royalty payments to rights holders. Retain all logs until confirmed uploaded. Missing logs create compliance gaps that affect your licensing agreements.
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/get
👉 Fetch playlist - GET /api/v2.4/playlists/{playlistId}
👉 Validate tracks - POST /api/v2.3/tracks/validatetracks
👉 Request audio file - POST /api/v5/assets/{trackId}/stream
👉 (Optional) Retrieve artwork - POST /api/v5/assets/{id}/image
👉 Upload play log - POST /api/v5/play/logbatchplay
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.
On this page
- Quickstart