Guides and Use Cases

## Sections
• [Overview](https://guide.tunedglobal.com/introduction-overview.md): Build music and audio products faster — from full DSPs to background music — with Tuned Global’s 500+ APIs. More than a content feed: we provide the backend services (auth, entitlements, geo/rights, playback tokens, play logging, reporting) so you don’t have to build the infrastructure. Use cases Pick a use case to start. 🎧 Music & Audio Streaming Service Launch a DSP-style experience with search, playback, play logging, playlists, radio and subscription gating. 📱Telco / MVNO / VAS Add a music offer into your mobile plan or super-app. Packages & subscriptions and telco integration ties into Streaming Service blocks. ✈️ Aviation and In-flight entertainment Catalogue-to-cabin content delivery for airline IFE systems. 🏪 Background Music Services Store-and-forward audio caching for venue and retail players. 🎮 Gaming / XR [SOON] Enhance the gaming experience with music: device-centric playback, unified listening across contexts, low-latency cues and stems. 👶 Kids & Family [SOON] Deliver explicit-safe music on watches and other devices with allow/block lists and profile filtering. 👥 Social Media / UGC / Short-form video [SOON] Add music to short videos: scrubbing, preview clips, rights-aware usage checks, and safe playback for user-generated experiences. 📻 Radio and unified listening [SOON] Build DMCA-compliant non-interactive radio with station and playlist APIs. 🧘‍♀️ Fitness & Wellness [SOON] Enhance workouts sessions with tailored music: live on on-demand, voice sync, BPM/mood-driven selection,… Why Tuned Global Deeper building blocks. Rich Search & Recommendations (global type-ahead + entity searches for Artists/Tracks/Albums/Playlists) for better UX out of the box. Real-world access models. Flexible packages & subscriptions (family and enterprise hierarchies) without brittle workarounds. Operationally ready. Built-in play logging & reporting aligned to licensing and compliance. Use cases. Connect APIs into complete flows (search → play → log → library), reducing integration work. Prefer specs? See API Reference (top-nav) for Services & Metadata .
• [🎧 Music Streaming Service](https://guide.tunedglobal.com/use-cases/build-a-streaming-service.md): Launch a DSP-style music and audio experience. Tuned Global's API handles search, recommendations, playback, play logging, playlists, radio, subscription gating and billing. Quickstart Create a first DSP experiment in 10-15 min: search a track, play it and log it. Playground Interactive tool to test the quickstart scenario At a glance Flexible packages & subscriptions (family/enterprise hierarchies) so real-world plans are easy to model. Billing support (Stripe, In App Payments) and User Management Rich search & recommendations building blocks: fast type-ahead plus precise entity tabs (Artists / Tracks / Albums / Playlists). Built-in reporting hooks aligned to licensing/compliance, so play data is captured correctly from day one. What you’ll build A simple but fully functional flow: Authenticate → Search → Stream track → Log a play. This lets you demonstrate “time-to-first-play” quickly, then build out more advanced production-ready flows afterward. Connecting APIs to UX You can either use our white-label applications or build your own front-end solutions using our APIs. Our white-label applications (outlined below) serve as a reference implementation of a streaming service powered by our platform. They demonstrate what you can build using our APIs, including a complete streaming experience with features such as search, playback, artist pages, and home screens. A significant amount of functionality is driven by our CMS , regardless of whether you use our white-label apps or develop your own front end. This includes: Multi-country management of homepages Creation of custom pages with curated content Creation and display of catalogue groupings (e.g. genres and other collections) If you have access to our Sandbox or Production environments, you will also have access to a Turnkey Web Application. This allows you to directly see how CMS configurations and API integrations impact application layouts and content in real Title Description Title Description SEARCH NOW PLAYING ARTIST PAGE HOMEPAGE API REFERENCES API REFERENCES API REFERENCES API REFERENCES
  • [Quickstart](https://guide.tunedglobal.com/use-cases/build-a-streaming-service/api-quick-start-guide.md): Outcome This quickstart demonstrates end-to-end music streaming API integration, covering authentication through playback logging Step you will complete Auth → Retrieve user profile → Search the catalogue → Retrieve metadata → Stream track → Log playback Timed required ~10-15 minutes Prerequisites API keys from Tuned Global Postman workspace configured Test user account credentials Step-by-step implementation 1 Authenticate Request a JWT token from the authentication server using test credentials. Purpose: Establishes user session within the system. Example: Bash curl --location 'https://api-authentication-connect.tunedglobal.com/oauth2/token' \ --header 'StoreId: XXYY' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=password' \ --data-urlencode 'username=testUserName' \ --data-urlencode 'password=testPassword' 2 Retrieve user profile Fetch account subscriptions and device information. Purpose: Determines user access rights and playback restrictions. Example: Bash curl --location 'https://api-services-connect.tunedglobal.com/api/v3/users/{user_id}/profile' \ --header 'StoreId: XXYY' \ --header 'Authorization: Bearer xxxyyyy' Returns: Active subscriptions Registered devices Basic user profile information 3 Search catalogue Find tracks using flexible search endpoints supporting: ISRC codes Genre filters Artist names Track titles with duration Advanced metadata filters Purpose: Mirrors user discovery patterns. Example: Bash curl --location 'https://api-metadata-connect.tunedglobal.com/api/v2.4/search/songs?q=Bohemian%20Rhapsody' \ --header 'StoreId: XXYY' 4 Retrieve metadata Obtain detailed information for selected tracks, albums, and artists. Track Metadata: Endpoint returns track name, artist, duration, and metadata fields. Album Metadata: Returns album title, artist, artwork, and release information. Artist Metadata: Returns artist name and imagery. Image Optimization: Use image engine to generate appropriately-sized artwork for UI performance. 5 Get stream URL (Stream a track) Request signed streaming URL for playback. Purpose: Validates entitlements and device-level rights enforcement. Required Inputs: Tuned Global Track ID Device ID Bearer authentication token Example: First request a token > Then get stream URL Bash curl --location --request POST \ 'https://api-services-connect.tunedglobal.com/api/v3/plays/1001/987654/stream?streamType=Music&streamProvider=Tuned' \ --header 'StoreId: XXYY' \ --header 'Authorization: Bearer xxxyyyy' 6 Log playback Submit playback events for analytics and royalty reporting. Example: Bash curl -X POST "https://api-services-connect.tunedglobal.com/api/v3/plays/1001" \ -H "StoreId: XXYY" \ -H "Authorization: Bearer xxxyyyy" \ -H "Content-Type: application/json" \ -d '{ "TrackId": 987654, "LogPlayType": "Start", "Seconds": 0, "Source": "Album", "SourceId": 12345, "Country": "AU", "PlayerType": "MobilePhone" }' Recommended Events: Play start 30-second milestone (mandatory for reporting) Skip events with timestamps End of file Expected results Audio playback functionality Play history entries recorded Playlist creation confirmed HTTP 200 responses with valid payloads Streaming URLs with valid expiration Play log entries for user and track Troubleshooting 403 on playback: Token expired or user not entitled. Re-authenticate; check subscription/package status. Missing play logs: Verify timestamps, user ID, and duration threshold. Empty playlist: Check track ID scope and user permissions; retry add-item.
• [📱 Telco / MVNO / VAS](https://guide.tunedglobal.com/use-cases/music-for-telcos.md): Launch a telco-owned music experience, bundled to your mobile plan or super-app. Tuned Global's API handdles user integration, vouchers, localised discovery, playback, reporting, flexible subscription models and entitlement checks. Quickstart Create a first telco-style prototype in 10–15 minutes: connect a user, validate access, search, play, and log. Playground Interactive tool to test the quickstart scenario. At a glance This section will detail what is often different between a standalone Music Streaming Service and a Telco-owned Music service. We recommend that you look at the Music Streaming Service use case for functional examples of working with a music streaming service (DSP). So, what's different for a Telco Authentication - Often using their own system as primrary authentication. Tuned Global support oAuth methods to use 3rd Party authentication systems. Subscriptions - Ability to assign users with subscriptions using MSISDN, even before that user has every accessed the music streaming service. Billing - Use your own billing systems or combine in-app payments with Telco billing. Datalake - Enrich your own data sets with our datalake feed for a unified view of your customers. What you’ll build A telco-branded music flow:
  • [Quickstart](https://guide.tunedglobal.com/use-cases/music-for-telcos/quickstart.md): Get started with TConnect APIs for telco subscriber music streaming Outcome Test the end-to-end flow for integrating a music offer into a telco environment. Step you will complete Auth → Register subscriber → Verify user profile → Search the catalogue → Stream track → Log playback Timed required ~10-15 minutes Prerequisites A StoreId issued by Tuned Global for your telco environment OAuth2 client credentials (client ID and secret) from Tuned Global A test MSISDN (phone number) or external user ID cURL or Postman installed Step-by-step implementation 1 Step 1: Register a user (TConnect) Register a new subscriber using their MSISDN or external user ID via the TConnect endpoint. 👉 Endpoint: POST https://api-services-connect.tunedglobal.com/api/v1/tconnect/users Bash curl -X POST "https://api-services-connect.tunedglobal.com/api/v1/tconnect/users" \ -H "Content-Type: application/json" \ -H "StoreId: YOUR_STORE_ID" \ -d '{ "ExternalUserId": "+601234567890", "FirstName": "Jane", "LastName": "Doe", "Email": "jane.doe@example.com", "Gender": "Female", "BirthYear": 1990, "Country": "MY" }' Note: The ExternalUserId is typically the subscriber's MSISDN. This creates the user in TConnect and returns their Tuned Global user ID. 2 Step 2: Validate the user Confirm the user exists and is correctly linked to your store before proceeding. 👉 Endpoint: POST https://api-services-connect.tunedglobal.com/api/v1/tconnect/users/validate Bash curl -X POST "https://api-services-connect.tunedglobal.com/api/v1/tconnect/users/validate" \ -H "Content-Type: application/json" \ -H "StoreId: YOUR_STORE_ID" \ -d '{ "Msisdn": "+601234567890", "StoreId": "YOUR_STORE_ID", "ExternalUserId": "+601234567890" }' A successful response returns the user's internal ID, confirming registration. 3 Step 3: Authenticate (Get Bearer Token) Obtain a JWT token to authorise subsequent API calls. 👉 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=password&username=YOUR_TEST_USERNAME&password=YOUR_TEST_PASSWORD" Response: Bash { "access_token": "eyJhbGciOiJSUzI1NiIs...", "token_type": "bearer", "expires_in": 86400 } Save the access_token — you'll use it as a Bearer token in all authenticated requests below. 4 Step 4: Check subscription status Verify the subscriber has an active package/subscription before allowing playback. 👉 Endpoint: GET https://api-services-connect.tunedglobal.com/api/v1/tconnect/sub-status Bash curl -X GET "https://api-services-connect.tunedglobal.com/api/v1/tconnect/sub-status?msisdn=%2B601234567890&storeId=YOUR_STORE_ID" \ -H "StoreId: YOUR_STORE_ID" Response: Bash [ { "Id": 12345, "StartDate": "2026-01-01T00:00:00", "EndDate": "2026-12-31T23:59:59", "PackageName": "Premium Music", "PlanName": "Monthly", "UserId": 67890, "PhoneNumber": "+601234567890" } ] This confirms the user's subscription is active and which package they're on. 4.5 Step 4.5: Get user profile Retrieve the registered user's profile to confirm their account details, active subscriptions, and device entitlements. 👉 Endpoint: GET https://api-services-connect.tunedglobal.com/api/v3/users/{user_id}/profile Bash curl -X GET "https://api-services-connect.tunedglobal.com/api/v3/users/67890/profile" \ -H "StoreId: YOUR_STORE_ID" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" Replace 67890 with the UserId returned in Step 4 (sub-status response). Response includes: user profile data active subscriptions registered devices. You can also retrieve the subscriber's total listening minutes — useful for engagement reporting and telco dashboards: 👉 Endpoint: GET https://api-services-connect.tunedglobal.com/api/v1/tconnect/listening-minutes Bash curl -X GET "https://api-services-connect.tunedglobal.com/api/v1/tconnect/listening-minutes?msisdn=%2B601234567890&storeId=YOUR_STORE_ID" \ -H "StoreId: YOUR_STORE_ID" Response: a numeric value representing total listening minutes for the subscriber. 5 Step 5: Search the catalogue Search for tracks, artists, or albums across the catalogue. 👉 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=5" \ -H "StoreId: YOUR_STORE_ID" \ -H "Country: MY" Other search endpoints available: Markdown /api/v2.4/search/albums Search albums /api/v2.4/search/artists Search artists /api/v2.4/search/playlists Search playlists /api/v2.4/search Search across all types /api/v2.4/search/songs/advanced Advanced search (BPM, duration, year, key, tags) Note the Track ID from the response — you'll need it for streaming. 6 Step 6: Get stream URL First, request a security token for the stream, then obtain the signed CDN streaming URL. 6a. Request Stream Token 👉 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/1001/987654/token" \ -H "StoreId: YOUR_STORE_ID" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" Save the token value from the response. 6b. Get stream location 👉 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/1001/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_STEP_6A"' The response is a signed streaming URL with a TTL (time-to-live) expiration. Use this URL in your audio player for playback. 8 Log playback events Log play events for royalty reporting, analytics, and compliance. You should log at minimum: Start, 30-second mark, and End of File. 👉 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/1001" \ -H "StoreId: YOUR_STORE_ID" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "TrackId": 987654, "LogPlayType": "Start", "Seconds": 0, "Source": "Search", "SourceId": "0", "Guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "Country": "MY", "PlayerType": "MobilePhone" }' Recommended logging events: Plain text LogPlayType When Seconds --------------- ------------------------------------------- ---------------- Start Playback begins 0 30SecondMark 30 seconds elapsed (mandatory for royalties) 30 Skip User skips track Current position EndOfFile Track finishes Total duration LogPlayType When Seconds --------------- ------------------------------------------- ---------------- Start Playback begins 0 30SecondMark 30 seconds elapsed (mandatory for royalties) 30 Skip User skips track Current position EndOfFile Track finishes Total duration Troubleshooting 403 on stream: Token expired or no subscription. Re-authenticate (Step 3), verify sub (Step 4). 401 Unauthorized: Missing or invalid Bearer token: Check Authorization header: Bearer <token>. Empty search results: Country filter or catalogue issue: Verify Country header matches store territory. User validation fails: MSISDN not registered: Complete Step 1 (registration) first. Missing play logs: Invalid device ID or bad payload: Verify deviceId matches a registered device. Quick Reference — Headers Every request requires at minimum: Plain text Header Value Required By --------------- ----------------------------------- ---------------------------- StoreId Your Tuned Global store identifier All endpoints Authorization Bearer <access_token> Authenticated endpoints (5-7) Content-Type application/json POST/PUT requests Country ISO country code (e.g. MY, AU) Metadata/search endpoints Header Value Required By --------------- ----------------------------------- ---------------------------- StoreId Your Tuned Global store identifier All endpoints Authorization Bearer <access_token> Authenticated endpoints (5-7) Content-Type application/json POST/PUT requests Country ISO country code (e.g. MY, AU) Metadata/search endpoints Notes Replace YOUR_STORE_ID, YOUR_ACCESS_TOKEN, YOUR_TEST_USERNAME, YOUR_TEST_PASSWORD, and the example IDs (1001, 987654) with your actual test credentials provided by Tuned Global.
• [✈️ Airlines / IFE](https://guide.tunedglobal.com/use-cases/music-for-airlines.md): Integrate licensed music playlists into an airline in-flight entertainment (IFE) system. Aviation is an offline-first environment — aircraft have no reliable internet during flight, so all music content must be delivered, validated, and loaded onto the IFE system before departure. This is usually managed by a Content Service Provider (CSP). This document is intended for CSPs wishing to utilise Tuned Global's API suite to deliver their music offering directlt to airlines. Tuned Global's platform handles the full pipeline: catalogue access, playlist curation, rights-cleared content delivery, audio and metadata file export. By the end of this guide you'll understand the end-to-end workflow from catalogue to cabin. Quickstart 15-20 minutes experiment to curate playlists, deliver content and load music into an in-flight entertainment (IFE) system. Playground Interactive tool to test the quickstart scenario. At a glance Curation - use APIs or our CMS to curate playlists in minutes not hours. Airline schedule - ability to assign artists, albums and playlists to an Airline schedule, i.e. Feb 2027 Rights - ability to ensure that you are rights compliant from both a master rights and publsihing perspective Export - ability to export and entire Airline schedule in a format that will be able to be imported into your system, including custom codecs per IFE system What you’ll build A music playlist that you can export eady to be uplaoed into your in-flight entertainment system.
  • [Quickstart](https://guide.tunedglobal.com/use-cases/music-for-airlines/quickstart.md): 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. 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 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. 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/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.
• [🏪 Background music service](https://guide.tunedglobal.com/use-cases/music-in-stores.md): Integrate music catalogues for background music services - the kind used in retail stores, restaurants, hotels, and venues. Unlike consumer music streaming services, background music players can be web or app based but often operate as store-and-forward systems. This means that cache audio locally on the playback device so music continues uninterrupted even when the network drops. Here we focus on Store-and-forward devices. Tuned Global's API handdles venue device authentication, playlist management, music caching, offline playback, and play log for reporting. If you are using an Web or Mobile application, you can follow the Music Streaming Service Guide for functionality. Quickstart Test our API integration in ~15-20 minutes to integrate music in a store-and-forward systems with audio cached locally on the playback device. Playground Interactive tool to test the quickstart scenario. At a glance This section will detail what is often different between a Music Streaming Service and a Background Music Service. We recommend that you look at the Music Streaming Service use case for functional examples of working with a music streaming app. So, what's different for a Background Music Service Offline/Caching - Critical support for feature, whether store-and-forward or applications with no connectivity. Subscriber hierachy - Ability to set how many “child” accounts are available under a main account, including management of these accounts Billing - Use Stripe billing AI Messaging - Ability to generate AI messaging or advertising that can be delivered directly to client What you’ll build A simple Background music flow:
  • [Quickstart](https://guide.tunedglobal.com/use-cases/music-in-stores/quickstart.md): Store-and-forward audio caching for venue and retail background music players Outcome This quickstart demonstrates API integration for BGM operating a store-and-forward systems with audio cached audio locally on the playback device. Step you will complete Auth → Fetch a playlist → Cached tracks → Stream track offline→ Log playback Timed required ~15-20 minutes Prerequisites A StoreId issued by Tuned Global for your background music environment OAuth2 client credentials (client ID and secret) from Tuned Global A registered device ID for the venue player cURL or Postman installed Local storage available on the playback device (minimum 2 GB recommended) Architecture: store-and-forward Background music players differ from consumer apps in several key ways: Title Description Aspect Consumer Streaming Store-and-Forward Playback model Stream on demand Pre-cache, play locally Network dependency Continuous Periodic sync only Playlist control User-driven Centrally scheduled Device type Phone/tablet Dedicated player, Raspberry Pi, POS system Failover Buffering/stop Seamless from local cache The typical sync cycle Device connects to the API on a schedule (e.g. every 4 hours, or overnight) Fetches the current playlist assignment and any updates Downloads and caches any new tracks not already stored locally Removes expired tracks that are no longer in any active playlist Plays from local cache — no network required during playback Logs play events locally and uploads them in batch when connectivity is available Step-by-step implementation 1 Step 1: Authenticate the device Obtain a JWT token using your device's service account credentials. Background music devices typically use client credentials grant rather than user/password. 👉 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 store-and-forward devices, implement token refresh logic that requests a new token before expiry — the device may need to sync while unattended. Tip: Store the token expiry timestamp locally so the device knows whether to re-authenticate before attempting a sync, even after a reboot. 2 Step 2: Fetch playlist assignment Retrieve the playlist(s) currently assigned to this device or venue location. Background music playlists are typically managed centrally by the venue operator or brand team. 👉 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 includes the full track listing with Track IDs, durations, and metadata. Store this response locally as your playlist manifest. To check for schedule or playlist changes without downloading the full track list: 👉 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 sync to decide whether a full refresh is needed. 3 Step 3: Cache audio to device This is the critical step for store-and-forward reliability. For each track in the playlist, request a download URL and save the audio file to local storage. 3a. Request download token 👉 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/VENUE-PLAYER-01/987654/token" \ -H "StoreId: YOUR_STORE_ID" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" 3b. Get 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/VENUE-PLAYER-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_STEP_3A"' 3c. Download and Store Locally Bash curl -L -o /cache/music/987654.mp3 "SIGNED_URL_FROM_STEP_3B" Important: The signed URL has a TTL (time-to-live). Download the file promptly after receiving the URL. Do not store the URL for later — store the audio file itself. Caching best practices Use the Track ID as the filename (e.g. 987654.mp3) so you can easily check which tracks are already cached Check before downloading — compare the playlist manifest against files already on disk to avoid re-downloading unchanged tracks Download in batches — process 5–10 tracks concurrently to speed up initial sync without overwhelming bandwidth Verify file integrity — check that the downloaded file size is non-zero and matches expected duration; re-download corrupt files Implement retry logic — transient network errors are expected; retry failed downloads with exponential backoff Reserve disk space — monitor available storage and alert if cache usage exceeds 80% of allocated space Handle storage full gracefully — if the device runs out of space, keep existing cached tracks playable and flag the sync as incomplete Example cache management pseudocode: Plain text # On each sync cycle: remote_tracks = fetch_playlist_tracks(playlist_id) local_tracks = list_cached_files("/cache/music/") to_download = remote_tracks - local_tracks # New tracks to cache to_remove = local_tracks - remote_tracks # Expired tracks to clean up for track_id in to_remove: delete("/cache/music/{track_id}.mp3") for track_id in to_download: token = request_stream_token(device_id, track_id) url = request_stream_url(device_id, track_id, token) download(url, "/cache/music/{track_id}.mp3") # On each sync cycle: remote_tracks = fetch_playlist_tracks(playlist_id) local_tracks = list_cached_files("/cache/music/") to_download = remote_tracks - local_tracks # New tracks to cache to_remove = local_tracks - remote_tracks # Expired tracks to clean up for track_id in to_remove: delete("/cache/music/{track_id}.mp3") for track_id in to_download: token = request_stream_token(device_id, track_id) url = request_stream_url(device_id, track_id, token) download(url, "/cache/music/{track_id}.mp3") 4 Step 4: Local playback Once tracks are cached, playback happens entirely from local storage with no network dependency. Playback loop The player should: Read the locally stored playlist manifest Play tracks in the defined order (or shuffle, depending on venue configuration) Loop continuously — background music should never stop Record play events to a local log file for later upload Handling gaps If a track file is missing or corrupt: Skip to the next track immediately Log the error locally Flag the track for re-download on the next sync cycle Never stop playback because of a single missing file Scheduling Many background music deployments use daypart scheduling — different playlists for morning, lunch, evening, etc. The device should: Store multiple playlist manifests if assigned a schedule Switch playlists at the configured times using the device's local clock Sync all scheduled playlists during the cache cycle, not just the currently active one 5 Step 5: Log playback events Logging is mandatory for royalty reporting and compliance, even for background music. The key difference: store-and-forward players log locally first and upload in batch when connectivity is available. 5a. Log locally during playback For each track played, record: Bash { "TrackId": 987654, "LogPlayType": "Start", "Seconds": 0, "Source": "Playlist", "SourceId": "55001", "Guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "Country": "AU", "PlayerType": "BackgroundPlayer", "Timestamp": "2026-03-31T09:15:00Z", "DeviceId": "VENUE-PLAYER-01" } Log the same event types as consumer playback: Plain text LogPlayType When Seconds --------------- ------------------------------------------- ---------------- Start Playback begins 0 30SecondMark 30 seconds elapsed (mandatory for royalties) 30 EndOfFile Track finishes Total duration Skip Track skipped (e.g. schedule change) Current position LogPlayType When Seconds --------------- ------------------------------------------- ---------------- Start Playback begins 0 30SecondMark 30 seconds elapsed (mandatory for royalties) 30 EndOfFile Track finishes Total duration Skip Track skipped (e.g. schedule change) Current position 5b. Batch upload play logs During each sync cycle, upload accumulated play logs to the API. 👉 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/VENUE-PLAYER-01" \ -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": "BackgroundPlayer" }' Upload each log entry individually or iterate through the local log file. After a successful upload (HTTP 200), mark the entry as synced so it isn't re-uploaded. Critical: Do not delete local logs until you have confirmed successful upload. If the upload fails, retain the logs and retry on the next sync cycle. Play logs are legally required for royalty reporting — losing them is not acceptable. 6 Step 6: Sync cycle summary Tie it all together in a single sync routine that runs on a timer (e.g. every 4–6 hours): Plain text 1. Re-authenticate if token is expired or near expiry 2. Check for playlist updates (Step 2 — /updated endpoint) 3. If playlist changed: a. Fetch new playlist manifest b. Remove tracks no longer in any active playlist c. Download and cache new tracks (Step 3) 4. Upload pending play logs (Step 5b) 5. Report sync status (success/failure, tracks cached, logs uploaded) 1. Re-authenticate if token is expired or near expiry 2. Check for playlist updates (Step 2 — /updated endpoint) 3. If playlist changed: a. Fetch new playlist manifest b. Remove tracks no longer in any active playlist c. Download and cache new tracks (Step 3) 4. Upload pending play logs (Step 5b) 5. Report sync status (success/failure, tracks cached, logs uploaded) Network resilience The sync cycle should be fully idempotent — if it fails partway through, the next run picks up where it left off: Partially downloaded files should be discarded and re-downloaded Play logs that failed to upload remain in the local queue Playlist manifest updates are atomic: apply the new manifest only after all new tracks are cached Troubleshooting 403 on stream/download: Token expired or subscription lapsed. Re-authenticate (Step 1), check licence status. Playback silence: Cache file missing or corrupt. Check disk, trigger manual sync. Play logs not appearing : Upload failed or entries not synced. Check local log queue, verify network on sync. Disk full: Cache exceeds allocated storage. Increase storage or reduce playlist size. Playlist not updating: Sync cycle not running or /updated stale. Verify cron/timer, check API connectivity. Tracks re-downloading: Track IDs not matching local filenames. Ensure filename matches Track ID exactly. Quick Reference — Sync Endpoints 👉 Authenticate - POST /oauth2/token 👉 Fetch playlist - GET /api/v2.4/playlists/{playlistId} 👉 Check playlist update - GET /api/v2.4/playlists/{playlistId}/updated 👉 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. Background music licensing is separate from consumer streaming. Confirm your licence covers public performance rights for the territories where devices are deployed. For large venue networks (100+ devices), contact Tuned Global about bulk sync endpoints and fleet management APIs.
• [🔎 Search & Recommendations](https://guide.tunedglobal.com/guides/search-and-recommendations.md): Search should help users find what they already know. Recommendations should help them keep going once they have started. Tuned Global’s Metadata APIs support both parts of that journey, with enough breadth for universal discovery and enough depth for more advanced, product-specific experiences. Overview This guide explains how Tuned Global supports content discovery across music and audio products. It shows how to build discovery experiences using Tuned Global's Metadata APIs , from broad catalogue search through to more precise track retrieval and recommendation-driven continuation. It should help you understand: How users can search for tracks, artists, albums, playlists, stations, and other entities How global search, advanced search, and recommendations work together How search supports browse, editorial pages, carousels, tags, and recommendation modules Which discovery patterns are best suited to different product types How discovery supports engagement, retention, and stronger product experiences Search in Tuned Global is not limited to a single keyword endpoint. The platform supports: A broad global search layer for universal catalogue discovery A deeper advanced song search layer for more precise track retrieval Recommendation flows based on track relationships, tags, and seeded IDs Similarity and matching utilities that help extend discovery and improve result quality How search and recommendation fits into the product In most products, search is the first step in a wider journey: Plain text Search --> Get Results --> Playback / Add to Playlist / Get Recommendations Search --> Get Results --> Playback / Add to Playlist / Get Recommendations A strong implementation does more than return matches. It: Supports different levels of search precision Returns enough metadata to power the next UI step Helps users move from known-item search into broader discovery Connects naturally into playback, artist pages, album pages, playlists, stations, and recommendation modules Tuned Global's discovery stack is designed to support full discovery journeys across a catalogue, from universal search and track-first retrieval through to browse-led discovery and deeper recommendation flows. The strongest discovery experiences use these layers together. A practical pattern is: Global search Use when the user starts with a broad free-text query. Advanced song search Use when the product needs more precise track retrieval or stronger control over the result set. Recommendations Use once the user has selected or played something and needs help deciding what to do next. This creates a discovery stack that supports both known-item search and deeper continuation once the user is engaged. Global Search Endpoint: GET /api/v2.4/search Swagger: Metadata API — Search Global Search is the best starting point when the product needs a universal search bar and the user may be looking for different kinds of content. This endpoint provides the broadest response, while the other search endpoints are more specific. It searches across the available catalogue and reflects licensing and territory availability, including an available territory node in the response. That makes it well suited to real-world music products where availability matters as much as relevance. Global Search returns results that can move directly into richer metadata retrieval, playback, browse surfaces, and downstream recommendation flows. It supports broad discovery while still respecting catalogue availability and territories, which makes it suitable for commercial implementations across multiple markets. Advanced Song Search Endpoint: GET /api/v2.4/search/songs/advanced Swagger: Metadata API — Advanced Song Search Advanced Song Search is the deeper track discovery layer. It moves beyond a basic keyword search and supports products that need greater precision, filtering, and richer query behaviour. This endpoint returns highly structured song-level results with substantial metadata depth, including scoring and ranking fields, identifiers, artist data, label and owner fields, tags, countries, translations, plugin metadata, and release context. That makes it useful not only for retrieval, but also for ranking, filtering, merchandising, and more deliberate discovery workflows. Advanced Song Search is built for implementation depth, giving teams more room to refine discovery, ranking, filtering, and merchandising. Recommendations Search helps the user find something they already want. Recommendations help the product continue the journey once that intent has been expressed. Tuned Global exposes multiple recommendation patterns rather than a single generic recommendation endpoint. That gives teams flexibility to support different types of continuation across the same catalogue. Similar artists Endpoint: GET /api/v2.4/artists/{id}/similar Swagger: Metadata API — Artist Returns artists similar to a specified artist based on overlapping listening patterns and catalogue attributes. This is the primary similarity endpoint in the Metadata API and supports artist-led continuation when the user's intent is performer-led rather than track-led. This is especially useful when you want: Artist-page continuation Fan-led journeys Performer exploration Artist-based recommendation modules Similar artists by tags Endpoint: GET /api/v2.4/artists/{id}/similarbytags Swagger: Metadata API — Artist Returns artists similar to a specified artist based on tag overlap rather than behavioural data. Useful when you want tag-driven similarity without relying on listening patterns. Similar stations Endpoint: GET /api/v2.4/stations/{id}/similar Swagger: Metadata API — Station Returns stations that share the most tracks by the same artists. Useful for radio-style continuation and "more like this" station modules. Similar podcasts Endpoint: GET /api/v2.4/podcasts/{id}/similar Swagger: Metadata API — Podcast Returns similar podcasts based on matching channel tags. Playlists by track Endpoint: GET /api/v2.4/playlists/by-track Swagger: Metadata API — Playlist Returns playlists that contain a specific track. This is useful for track-led discovery — once a user selects or plays a song, you can surface playlists that feature it, creating a natural bridge from a single track into a broader listening experience. Tag-driven recommendations Endpoint: GET /api/v2.4/tags/artists?tag={tag} , GET /api/v2.4/tags/albums?tag={tag} , GET /api/v2.4/playlists/by-tags Swagger: Metadata API — Tag / Playlist Returns content filtered by tags associated to tracks, albums, or artists. This approach uses the tag system to determine similarity rather than behavioural data. This is useful when you want: Related content after a user views or plays something Tag-driven continuation Recommendation rows that stay close to the source item's musical profile TunedIQ — Personalised track recommendations Note: TunedIQ is a separately licensed feature. Track-level recommendation endpoints (seeded recommendations, track similarity, IQ-driven recommendations) are not part of the public Metadata API Swagger . They are provisioned per-store once TunedIQ is activated. Contact Tuned Global to enable TunedIQ and receive endpoint documentation specific to your integration. Reference: Search & Recommendations guide — TunedIQ TunedIQ is Tuned Global's collaborative-filtering recommendation engine. It learns from real listening behaviour rather than static metadata, making it effective even for catalogues with limited or inconsistent tagging. Once enabled, TunedIQ provides track-level recommendation capabilities including: Seeded recommendations — recommended tracks based on up to 3 specified track IDs Tag-driven related tracks — recommendations using tags associated to tracks or derived from albums and artists Track similarity — related tracks with rich metadata including identifiers, ISRC, explicit flags, image fields, and linked release data Daily Discovery Mixes — blends of familiar favourites and new tracks Personalised Trending — trending tracks filtered by the user's taste profile Continuous Play — automatically extends listening sessions from a seed track These are useful when you want: A "similar tracks" or "you might also like" module Seeded recommendations from a small set of known tracks Smarter continuation from a user's recent behaviour Recommendation flows that feel more intentional than simple nearest-neighbour similarity What's available without TunedIQ The following similarity and discovery endpoints are available in the public Metadata API and do not require TunedIQ: There is currently no track-level similarity endpoint (e.g. "similar songs") in the public Metadata API. Track-level recommendations require TunedIQ. Summary Tuned Global supports multiple recommendation models: Similar artists via GET /api/v2.4/artists/{id}/similar (public API) Similar artists by tags via GET /api/v2.4/artists/{id}/similarbytags (public API) Similar stations via GET /api/v2.4/stations/{id}/similar (public API) Similar podcasts via GET /api/v2.4/podcasts/{id}/similar (public API) Playlists by track via GET /api/v2.4/playlists/by-track (public API) Tag-driven related content via tag discovery endpoints (public API) Seeded track recommendations, track similarity, and personalised discovery via TunedIQ (requires activation) This makes it easier to design recommendation experiences that fit the product. Additional discovery tools that strengthen the stack Beyond search and recommendations, Tuned Global also includes supporting discovery tools that help improve result quality, handle catalogue matching, and extend discovery into richer product experiences. ISRC Matching Endpoint: GET /api/v2.4/search/search-matching Swagger: Metadata API — Song Matching This endpoint returns tracks that share the same ISRC. It supports matching by ISRC, song name, artist name, and duration — useful for prioritising a single track per ISRC when multiple tracks exist. This is useful for: Cleaner search results De-duplication workflows Metadata reconciliation Catalogue operations and matching Display-Ready Similarity Responses The similar content endpoints ( GET /api/v2.4/artists/{id}/similar , GET /api/v2.4/artists/{id}/similarbytags , GET /api/v2.4/stations/{id}/similar , GET /api/v2.4/podcasts/{id}/similar ) include not only identifiers, but also artist arrays, release objects, translations, image fields, and other display-ready data. Recommendation modules can therefore be wired directly into product experiences without needing a separate minimal similarity layer. Supporting Discovery Surfaces Search and recommendations become even more powerful when combined with supporting discovery surfaces such as: Content pages Carousels Tags (via GET /api/v2.4/search/tags and GET /api/v2.4/tags/{type}?tag={tag} ) Editorial modules Browse-led collections These surfaces help turn discovery into a broader product experience rather than a single search box. Catalogue filtering and availability Discovery quality depends on more than relevance alone. Tuned Global's search and recommendation stack can also reflect catalogue availability, licensing, territories, and richer metadata such as tags, genres, language, owner, label, and release context. This makes it possible to build discovery experiences that are not only relevant, but also commercially usable in the markets and contexts where the product operates. Getting started A practical way to start implementing search and recommendation capabilities is: 1 Step 1 — Start with Global Search Build a universal search bar using GET /api/v2.4/search . This proves: Catalogue coverage Basic discovery flow Result handling in the UI 2 Step 2 — Add Advanced Song Search Introduce GET /api/v2.4/search/songs/advanced where the product needs stronger track precision. This helps: Refine discovery Improve known-item retrieval Support richer track-led search experiences 3 Step 3 — Add similarity endpoints Use the public Metadata API similarity endpoints to build "more like this" experiences: GET /api/v2.4/artists/{id}/similar — similar artists (behavioural) GET /api/v2.4/artists/{id}/similarbytags — similar artists (tag-based) GET /api/v2.4/stations/{id}/similar — similar stations GET /api/v2.4/podcasts/{id}/similar — similar podcasts GET /api/v2.4/playlists/by-track — playlists containing a specific track 4 Step 4 — Add tag-driven discovery and matching Use: GET /api/v2.4/tags/{type}?tag={tag} and GET /api/v2.4/playlists/by-tags for tag-driven browse and recommendation surfaces GET /api/v2.4/search/search-matching for ISRC/name/duration matching and de-duplication 5 Step 5 — Enable TunedIQ for track-level recommendations Contact Tuned Global to activate TunedIQ on your store. This unlocks track-level recommendation endpoints including seeded recommendations, track similarity, and personalised discovery features that are not available in the public Metadata API. 6 Step 6 — Extend into browse and editorial Editorial shelves Carousels Themed or tagged collections Recommendation rows after playback That is where search stops being a utility and becomes part of the product experience. When to use each endpoint Title Description Global search GET /api/v2.4/search The user starts with one search bar, content type is not yet known, you want the broadest catalogue response. Advanced song search GET /api/v2.4/search/songs/advanced The product needs tighter track retrieval, the result set needs more structure, precision matters more than breadth. Similar artists GET /api/v2.4/artists/{id}/similar You want clean artist-led continuation from an already selected artist. Similar artists (tags) GET /api/v2.4/artists/{id}/similarbytags You want artist similarity based on tag overlap rather than behavioural data. Similar stations GET /api/v2.4/stations/{id}/similar You want radio-style "more like this" station continuation. Similar podcasts GET /api/v2.4/podcasts/{id}/similar You want podcast continuation based on channel tags. Playlists by track GET /api/v2.4/playlists/by-track You want to surface playlists containing a specific track for track-led discovery. Tag-driven discovery GET /api/v2.4/tags/{type}?tag={tag} GET /api/v2.4/playlists/by-tags You want recommendation modules driven by track, album, or artist tags. TunedIQ recommendations TunedIQ endpoints (requires activation) You want seeded track recommendations, track similarity, or personalised discovery. Not in the public Swagger — contact Tuned Global. ISRC matching GET /api/v2.4/search/search-matching You want to reconcile duplicates or support same-recording matching logic. Why this is powerful Tuned Global's discovery capability is strong because it is not built around only one search pattern. It combines: A broad universal search layer ( GET /api/v2.4/search ) A deeper advanced track-search layer ( GET /api/v2.4/search/songs/advanced ) Entity-level similarity in the public API — artists ( GET /api/v2.4/artists/{id}/similar , /similarbytags ), stations ( GET /api/v2.4/stations/{id}/similar ), podcasts ( GET /api/v2.4/podcasts/{id}/similar ) Track-to-playlist discovery ( GET /api/v2.4/playlists/by-track ) Tag-driven browse and recommendation surfaces ISRC and metadata matching ( GET /api/v2.4/search/search-matching ) Track-level personalised recommendations via TunedIQ (separately licensed) Rich metadata responses that are already useful for downstream UI and playback flows That gives technical teams more freedom to design discovery experiences around product intent, not just around whichever endpoint exists. Swagger References: Metadata API (v2.4) — Search, discovery, tags, trending, similar content Services API (v3) — Play history, personalised playlists, authenticated similar artists
• [🔗 Unified listening](https://guide.tunedglobal.com/guides/unified-listening.md): Unified listening enables multiple listeners to hear the same music experience at the same time, without each listener managing their own playback queue independently. It is designed for use cases where a shared or synchronised music experience is required, such as live listening rooms, social audio features, interactive radio, gaming sessions, fitness classes, in-venue experiences, or other environments where users should hear the same sequence of tracks. Rather than asking the client application to build and manage all playback logic locally, Unified listening provides the backend structure needed to generate, control, and deliver a shared queue or radio-style stream. Unified listening is not a single implementation method. It is a shared listening model that can be delivered either through an API-controlled queue with ShadowQ , or through a stream-based radio approach with Plaidio . How it works Unified listening can be implemented in different ways depending on the product experience you want to build. At a high level, the workflow is: Define the music experience, such as a playlist, station, or curated music source. Generate or retrieve the listening sequence. Deliver the sequence to users through the appropriate implementation method. Keep listeners aligned so they experience the same content flow. Update or refresh the queue as required. The exact implementation depends on whether you are using Shadow Queue or Plaidio. ShadowQ On-beat synchronisation at scale API-driven, perfect (on-beat) sync across devices and contexts Plaidio From playlists to radio broadcast URL-based shared music stations for simple, reliable delivery Core concepts Concept Description Session A shared listening experience that users can join. Queue The ordered list of tracks used for playback. Listener A user or device participating in the session. Sync The logic used to keep listeners aligned in the same playback experience. Source The playlist, station, or music selection used to generate the experience. Implementation options ShadowQ Use ShadowQ when your application needs more control over the playback logic and queue behaviour. ShadowQ allows your backend or client application to create and manage a queue of tracks that users can follow in sync. It is useful when you need control over the listening session, user playback, queue refreshes, personalised logic, or real-time interaction. Key capabilities: Keep audiences precisely aligned across the same tracks, beats, or audio moments. Support music, podcasts, voice-over, sound effects, or mixed audio experiences. Use audience feedback, such as likes, skips, voting, or other interactions, to influence the queue. Support AI-assisted curation for evolving shared queues. Typical use cases include: synchronised listening rooms shared music sessions in apps gaming or interactive experiences fitness classes or guided audio sessions dynamic music queues controlled by an application experiences where the app needs to manage playback behaviour directly See the ShadowQ quick start page for setup steps and API examples. Plaidio Use Plaidio when you want to turn a playlist or music source into a radio-style stream. Plaidio is suited to experiences where the output needs to behave more like a linear audio stream, such as a web radio station, branded stream, or lean-back listening experience. It can help simplify playback because the client consumes the stream rather than managing each individual track in the queue. Key capabilities: Spin up a station, curate in our CMS , and stream via browser or your player. A simple option when ease and consistency matter more than exact on-beat synchronisation. Music-only, linear listening with minimal setup and operational overhead. Support timed call-outs and dynamic inserts for global announcements or promos at exact times. Typical use cases include: playlist-to-radio experiences branded digital radio streams lean-back music channels background music experiences browser-based or player-based radio-style streams Choosing the right approach The right approach depends on how much control you need over playback, how closely listeners must be synchronised, and whether the experience should be queue-based or stream-based. Use case ShadowQ Plaidio You need a radio-style linear stream URL for mass listening ✅ You need fewer than 50 unique Unified Listening playlists or experiences ✅ You need hundreds of unique Unified Listening playlists or experiences ✅ It is critical that listeners are aligned to the exact beat ✅ You are building synchronised listening inside an app ✅ You want a URL to point to and it is acceptable if listeners are a few seconds apart ✅ Cost is critical and you are comfortable with a bigger technical lift ✅ Your application needs more flexibility over user experience and playback logic ✅ You want to insert timed call-outs ✅ Personalised inserts ✅ Broadcast to all You want audience feedback, interaction or AI-assisted curation to shape the queue ✅ You want to support ad break signalling ✅ Project-dependent ✅ SCTE-35 cue support for future SSAI integration You want to support music, podcasts, voice-over, or sound effects in adaptive flows ✅ Next steps Start with the quick start page that matches your implementation: ShadowQ quick start , for API-controlled shared playback queues [SOON] Plaidio quick start , for playlist-to-radio or stream-based listening experiences
  • [ShadowQ quickstart](https://guide.tunedglobal.com/guides/unified-listening/shadowq-quickstart.md): Build shared, in-sync listening experiences such as social rooms, hosted radio sessions, watch parties, and bot-driven rooms. Shadow Queue is the API-controlled implementation option for Unified listening. It allows your application to create and manage a single server-side queue that multiple listeners can follow in sync. A ShadowQ “shadows” what a room is playing. One participant, usually the host, builds the queue. Other participants, including read-only users or non-interactive bots, read the same queue and play it in lockstep. Because every track includes epoch-stamped start and end times, clients can calculate the current playback position and stay synchronised without talking to each other. The ShadowQ APIs support queue creation, track management, synchronised playback state, device entitlement, signed CDN playback, and play logging. For a high-level explanation of Unified listening and how ShadowQ compares with Plaidio, see the Unified listening overview . Quickstart Build a working ShadowQ in ~10–15 min. Auth → Register device → Build a queue → Fetch the shared queue → Play a track from a signed CDN URL Playground Interactive tool to test the ShadowQ scenario end-to-end. At a glance One shared queue, many listeners. A queue is created once and read by every participant in the room from a single queueId . Synchronised by design. Each queued track returns EpochStart and EpochEnd , so clients can calculate the accurate “now playing” position and support seamless transitions without peer-to-peer sync. Read it without a user context. Fetching the queue uses the Metadata API so it can be shared without a user session. This is useful for read-only participants, dashboards, and bots that need to join or leave a room while clients continue to fetch the current queue. Build it with a user context. Creating a queue and adding tracks uses the Services API , authenticated as the host user. Production playback built in. Device entitlement, signed CDN stream URLs, and licensing-compliant play logging use the same endpoints used by full DSP integrations. How it works and why two APIs ShadowQ deliberately spans two APIs ,. The API used depends on whether the operation needs a user context. Creating a queue and adding tracks happen on the Services API because these actions require a user context. Reading the queue happens on the Metadata API because the queue needs to be shareable without a user context. Operation API Title Endpoint Create a queue Services v3 Yes, the host user POST /api/v3/shadow-queues Add tracks to a queue Services v3 Yes, the host user POST /api/v3/shadow-queues/{queueId}/tracks Read the queue Metadata v2.4 No, shareable GET /api/v2.4/shadow-queues/{queueId}/tracks Read recent play history Metadata v2.4 No, shareable GET /api/v2.4/shadow-queues/{queueId}/play-history Why is GET ShadowQ on the Metadata API? Reading the queue is intentionally kept on the Metadata API so it can be shared without a user session. Some rooms may create a queue without tying every participant to the same user context. You may also want bots or read-only participants to join and leave a room while clients keep fetching the current queue. Keeping queue reads on the Metadata API makes the queue a shared, cacheable resource rather than something tied to one user’s session. What you'll build A complete, in-sync social-listening flow: This gets you to time-to-first synchronised play quickly. You can then layer on rooms, presence, bots, adaptive queues, feedback, and play-history catch-up afterwards. Important: Do not skip device registration. Before any participant can turn a queued track into a playable CDN URL, the device must be registered and authorised for that user . This step is easy to miss because it sits between building the queue and playback. Connecting APIs to UX A typical room UI maps onto the APIs like this: UI surface Backed by Room queue / Up next GET /api/v2.4/shadow-queues/{queueId}/tracks Now playing and progress bar EpochStart / EpochSEnd on each queued track Host add-to-queue control POST /api/v3/shadow-queues/{queueId}/tracks Play button POST /api/v3/plays/{deviceId}/{trackId}/stream (signed CDN URL) Recently played GET /api/v2.4/shadow-queues/{queueId}/play-history API Quick Start Guide (~10–15 minutes) This quick start demonstrates an end-to-end Unified listening integration with ShadowQ. You will authenticate, register a playback device, search the catalogue, build a shared queue, fetch that same queue without a user context, stream a track from a signed CDN URL, and log the play. Prerequisites Before you start, make sure you have: API keys from Tuned Global, including a StoreId A test user account A user token with the required scopes Postman workspace configured, or curl Test user account credentials Your user token should include scopes for: shadow-queue:read shadow-queue:write user:read user:write catalogue:read track:play Step-by-step 1 Step 1: Authenticate Request a JWT token from the authentication server using your test credentials. Purpose: Establishes the host user's session and the scopes needed to build and play a ShadowQ. Bash curl --location 'https://api-authentication-connect.tunedglobal.com/oauth2/token' \ --header 'StoreId: XXYY' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=password' \ --data-urlencode 'username=testUserName' \ --data-urlencode 'password=testPassword' Use the returned access_token as Authorization: Bearer xxxyyyy on every call below. The authorisation server URL can be discovered at runtime via GET /api/v3/application/grantURL . 2 Step 2: Register a device Authorise a playback device for the user before attempting to stream. Purpose: Playback is entitled per-device. A queued track cannot be turned into a CDN URL until the device that will play it is registered to the user. This step is easy to miss — it sits between building the queue and playing it. Bash curl --location --request POST 'https://api-services-connect.tunedglobal.com/api/v3/users/me/device' \ --header 'StoreId: XXYY' \ --header 'Authorization: Bearer xxxyyyy' \ --header 'Content-Type: application/json' \ --data '{ "DeviceType": "iPhone 15 Pro", "DisplayName": "Living Room iPhone", "UniqueId": "F2A1C0DE-1234-4A5B-9C8D-0011AABBCCDD", "DeviceOS": "iOS", "DeviceManufacturer": "Apple", "DeviceCategory": "Mobile", "LastOSVersion": "17.4.1", "LastAppVersion": "3.2.0" }' Required fields ( AuthDeviceModel ): Field Required Title Example / notes DeviceType Yes string Model or device type, e.g. iPhone 15 Pro DisplayName Yes string Human-friendly name shown to the user UniqueId Yes string Stable per-device identifier (e.g. IDFV / install UUID) DeviceOS Yes string iOS, Android, Web, … DeviceManufacturer Yes string Apple, Samsung, … DeviceCategory Yes string (enum) One of Mobile, TV, Wearable LastOSVersion No string e.g. 17.4.1 LastAppVersion No string e.g. 3.2.0 ApplicationId No integer App/store application id, if applicable Carrier No string Mobile carrier, if applicable Returns — Response[UserAuthDeviceResponseModel] : JSON { "Value": true, "Device": { "DeviceId": 23750200, "DeviceType": "iPhone 15 Pro", "UniqueId": "F2A1C0DE-1234-4A5B-9C8D-0011AABBCCDD", "DisplayName": "Living Room iPhone", "DeviceOS": "iOS" } } Keep Device.DeviceId — you'll pass it to every playback call as {deviceId} . Already have a device, or it stopped working? A device can be deauthorized when a different user logs into it, so for the most reliable, current device list, read the user's profile and pick the device from Devices[] : GET /api/v3/users/{userId}/profile . The response contains a Devices array of UserDevice objects, each with a DeviceId . 3 Step 3 — Search the catalogue Find the tracks you want to seed the queue with, and collect their Tuned Global track IDs. Purpose: Queue creation and track-add operations both take arrays of track IDs. Bash curl --location 'https://api-metadata-connect.tunedglobal.com/api/v2.4/search/songs?q=Bohemian%20Rhapsody&count=5' \ --header 'StoreId: XXYY' Note the TrackId of each result you want to queue. 4 Step 4: Create a ShadowQ Create the shared queue. This is a Services API call made as the host user. Purpose: Returns a queueId that every participant in the room will use to read the queue. Bash curl --location --request POST 'https://api-services-connect.tunedglobal.com/api/v3/shadow-queues' \ --header 'StoreId: XXYY' \ --header 'Authorization: Bearer xxxyyyy' \ --header 'Content-Type: application/json' \ --data '{ "SourceType": "Station", "TrackIds": [987654, 987655, 987656] }' Body ( CreateShadowQueuePayload ): Field Description Type Notes SourceType Yes string (enum) Station TrackIds Yes integer[] Initial tracks to seed the queue Returns the queueId as a string. Hand this to clients and bots so they can read the queue. The queueId is continuous across both APIs — pass it straight to the Metadata read in Step 6. SourceType is not strictly enforced; send Station (Playlist/Album are also accepted). 5 Step 5: Add tracks to the queue Append more tracks to an existing queue as the room evolves. Purpose: Lets the host (or your room logic) extend the shared queue after creation. Bash curl --location --request POST 'https://api-services-connect.tunedglobal.com/api/v3/shadow-queues/QUEUE_ID/tracks' \ --header 'StoreId: XXYY' \ --header 'Authorization: Bearer xxxyyyy' \ --header 'Content-Type: application/json' \ --data '[987657, 987658]' The body is a plain JSON array of track IDs. 6 Step 6 — Read the shared queue Fetch the current queue. This is a Metadata API call and needs no user context — any participant or bot can call it with just the StoreId . Purpose: This is the shared, synchronised view of the room. Every client reads the same queue and uses the epoch timestamps to render an accurate 'now playing' position. Bash curl --location 'https://api-metadata-connect.tunedglobal.com/api/v2.4/shadow-queues/QUEUE_ID/tracks?lastTrackEnd=0' \ --header 'StoreId: XXYY' Returns — ShadowQueueTracksResponseModel : JSON { "QueueStatus": "Active", "Tracks": [ { "TrackId": 987654, "EpochStart": 1709596800, "EpochEnd": 1709597154, "Track": { "TrackId": 987654, "Name": "…", "Duration": 354 } } ] } EpochStart / EpochEnd are wall-clock seconds — use them to compute the current playback position so every participant stays in sync. Pass lastTrackEnd (seconds) to fetch only the tracks that come after a point you've already seen. To show recently played tracks (last 3 hours), call GET /api/v2.4/shadow-queues/QUEUE_ID/play-history . 7 Step 7: Stream a track (signed CDN URL) Turn the current track into a playable, signed CDN URL for the registered device. This is a single call — POST the stream endpoint with an empty body (no prior token call needed). Purpose: Validates the user's entitlement and the device's rights, then returns a short-lived CDN URL. Required inputs: Tuned Global TrackId , the registered DeviceId from Step 2, and the bearer token. Bash curl —location —request POST \ ‘https:÷api-services-connect.tunedglobal.com/api/v3/plays/23750200/987654/stream?streamType=Music&streamProvider=Tuned’ \ —header ‘StoreId: XXYY’ \ —header ‘Authorization: Bearer xxxyyyy’ \ —header ‘Content-Length: 0’ Returns the signed CDN URL as a string. CDN URLs are short-lived — request one close to playback time. Query parameters: streamType (Music | Podcast | Audiobook, default Music), streamProvider (Tuned | External, default Tuned), and optional assetType to override audio quality. 8 Step 8: Log playback Submit playback events for analytics and royalty reporting. For ShadowQ playback, set Source to Queue . Purpose: Captures play data correctly from day one for licensing/compliance. Bash curl --location --request POST 'https://api-services-connect.tunedglobal.com/api/v3/plays/23750200' \ --header 'StoreId: XXYY' \ --header 'Authorization: Bearer xxxyyyy' \ --header 'Content-Type: application/json' \ --data '{ "TrackId": 987654, "LogPlayType": "Start", "Seconds": 0, "Source": "Queue", "Country": "AU", "PlayerType": "MobilePhone" }' Recommended events: play start, the 30-second milestone (mandatory for reporting), skip events with timestamps, and end of file. LogPlayType is one of Start, Progress, End, Skip. Expected results A registered device with a usable DeviceId A queueId that returns the same queue to every participant A queue read that returns tracks with EpochStart / EpochEnd A signed CDN URL that plays audio Play log entries recorded for the user, device and track HTTP 200 responses with valid payloads throughout Troubleshooting 403 on the stream call: Token expired, user not entitled, or the device isn't registered/authorised — revisit Step 2 and confirm the DeviceId belongs to this user via GET /api/v3/users/{userId}/profile . Device shows as unknown / playback denied after a re-login: The device may have been deauthorized when another user logged into it. Re-register it (Step 2) or pick the current device from the profile's Devices[] . Queue read returns empty: Confirm you're calling the Metadata host ( api-metadata-connect ), that the queueId is correct, and that tracks were added. Drop or lower lastTrackEnd — too high a value filters everything out. Shadow-queue calls return 401/403: The token is missing shadow-queue:read / shadow-queue:write scopes — re-authenticate with a user/app that has them. Missing play logs: Verify TrackId , DeviceId , Seconds and that you sent the 30-second milestone.
• [Fingerprinting](https://guide.tunedglobal.com/refrence-documents/fingerprinting.md): Our fingerprinting solutions are designed to give you full control over your environment, infrastructure, and processing workflows - while maintaining strict compliance with licensing requirements. In order to use the fingerprinting solution you will require access to the metadata and assets via a Catalogue Feed. We offer three choices for how you may Fingerprint on our system; We can host VMs in our environment > low costs asset access and managed services; or If your fingerprint applications are in AWS, use DirectConnect > lowest cost asset access; or Use your environment and access assets via our APIs > minimal changes required to your workflow Deployment models: Hosted A fast, VM-based solution for immediate integration. Hosted provides simplicity. DirectConnect A fully integrated model for advanced workflows, control, and cost efficiency. DirectConnect provides control, scale, and efficiency. Hosted (Managed VMs) The Hosted model provides a managed virtual machine environment for running fingerprinting workloads. Hosted environments are provisioned ready for use and designed to integrate directly into your existing applications and workflows. Infrastructure We provision EC2-based virtual machines within a managed environment. You can: Select instance types aligned to your workload requirements, including CPU or GPU-based compute Choose from standard configurations, including: Title Description Title Description Title Configuration vCPU Memory GPU Storage options Standard 2 8 GB — SSD or Standard Medium 4 16 GB — SSD or Standard Performance 8 32 GB — SSD or Standard High Performance 16 64 GB — SSD or Standard Large Scale 32 128 GB — SSD or Standard GPU Small 4 16 GB 1× NVIDIA GPU SSD or Standard GPU Medium 8 32 GB 1× NVIDIA GPU SSD or Standard GPU Large 16 64 GB 1–4× NVIDIA GPU SSD or Standard Configure storage options including SSD or standard disk Scale the number of instances within your allocated limits Instances are securely accessible over the public internet and can be configured to support your fingerprinting workflows. Audio access Audio is accessed via controlled service endpoints configured directly on your provisioned instances. Requests are made using: Track identifiers Format selection Partner credentials These endpoints can be called from any application or service, enabling straightforward integration into your fingerprinting workflows. Example request Plain text GET /audio/track/{trackId}/format/{format} Authorization: Bearer <token> GET /audio/track/{trackId}/format/{format} Authorization: Bearer <token> Audio is delivered directly to the requesting application based on your access permissions, allowing immediate use within processing pipelines. Security & rights enforcement Access to content is governed by: Partner-level authentication Source access controls Catalogue and label-level permissions Only content you are licensed to use is made available. Formats Audio is available in formats suitable for fingerprinting workflows, ranging from high-efficiency AAC encodings through to higher bitrate AAC formats, with availability optimised for broad catalogue coverage. Cost efficiency The Hosted model provides predictable, usage-based costs aligned to compute and request volumes. As audio is delivered per request, costs scale with: Processing activity Data transfer volumes Format selection and delivery This model is efficient for moderate workloads and standardised processing pipelines. Benefits Hosted is best suited for: Fast onboarding with minimal setup Standard fingerprinting workflows Teams without dedicated cloud infrastructure Use cases where simplicity and speed of deployment are prioritised DirectConnect (Your AWS - connected) DirectConnect enables you to run fingerprinting workflows entirely within your own AWS environment. DirectConnect is designed to integrate directly into existing cloud architectures, allowing audio access to become a native part of your processing pipelines. Infrastructure You provision and manage your infrastructure, including: Compute (CPU or GPU) Instance types and scaling Storage and lifecycle policies Supporting services and tooling This ensures complete sovereignty over your code, processes, and resulting intellectual property. Audio access Audio access is enabled via our Catalogue Feed APIs. These APIs provide: Track and catalogue identifiers Metadata required for processing Product availability based on your licensed rights Using this data, your systems can directly resolve and access audio within your environment for fingerprinting - without requiring external delivery or intermediary APIs. This enables tightly integrated, code-level access to audio as part of your processing workflows, whether via direct file paths or service-based requests. Example access pattern Plain text audio_path = resolve_audio(track_id, format) process(audio_path) audio_path = resolve_audio(track_id, format) process(audio_path) Audio is accessed natively within your environment, allowing it to be incorporated directly into high-performance processing pipelines. Audio is made available in a range of formats suitable for fingerprinting workflows, from high-efficiency AAC encodings (such as AAC-HEv2-48) through to higher bitrate AAC-LC-256 formats , and up to high-fidelity, lossless audio where required. Default formats are optimised for availability and processing efficiency, with higher fidelity options accessible based on your requirements and licensing. Audio access & processing models You can choose the processing model that best fits your compliance and infrastructure requirements: Stream-and-process - in-memory processing without storing files Download-and-delete - batch processing with controlled lifecycle We work with you to align implementation with licensor requirements. Security & rights enforcement All access is governed by rights configured at the catalogue and partner level. This ensures: Only licensed content is accessible Access aligns with contractual obligations Processing remains within approved environments Cost efficiency DirectConnect minimises data movement by enabling audio access directly within your environment. This results in: Significantly lower access costs compared to hosted or external delivery models Reduced data transfer and storage overhead More efficient processing at scale Benefits DirectConnect is best suited for: Large-scale or continuous processing workloads Advanced workflows (GPU, serverless, hybrid compute) Cost-sensitive environments requiring optimisation Teams requiring full control over infrastructure and processing APIs (In Your Environment) Where the two solutions detailed above are not ideal, you can maintain your current environment and utilise our APIs to request assets. Asset request is a cost effective solution that requires minimal changes for your environment, often providing the fastest execution. Where using this process you will need to complete technical due dilegence in the handling and destruction of assets once fingerprinted, Comparison Overview Title Description Title Category Hosted DirectConnect Via APIs Deployment model Managed VM environment Runs in your AWS environment Runs in your current environment Setup speed Ready for immediate integration Designed for direct integration into existing workflows Minimal setup - integrate our APIs Infrastructure control Limited Full control Your infrastructure Compute flexibility VM-based (CPU/GPU selection) VM, GPU, serverless, custom workflows Your infrastructure Audio access method Instance-level endpoints callable from any application Direct, code-level access within your environment API, tokenised requests Data flow Audio delivered per request Audio accessed natively within your environment Audio delivered per API request Storage model Managed externally Fully controlled (stream, temp, or persist) Access Audio, Fingerprint, destroy audio Security model Endpoint-based access control Integrated rights enforcement within environment Tokenised API requests Scalability Limited to provisioned VMs Native AWS scaling Your infrastructure Performance Dependent on request throughput High - no external bottlenecks Your infrastructure Cost Efficiency Usage-based, scales with requests and data transfer Significantly lower due to minimal data movement Good but less efficient than the first 2 methods but less changes to any systems IP ownership Processing in managed environment Full ownership of code, workflows, outputs Your infrastructure Best for Quick start, simple pipelines Advanced workflows, scale, optimisation Minimal changes to your environment, full control
• [Countries / Territories](https://guide.tunedglobal.com/refrence-documents/countries-territories.md): Global Coverage & Territory Handling Tuned Global supports all ISO 3166-1 countries and territories through a consistent country parameter model. The way territory rules are applied depends on the integration model: Catalogue Feed clients receive territory and rights data in the feed and enforce those rules client-side. API clients using the broader Tuned Global API suite receive territory-aware responses directly from the platform. Catalogue Feed: territory and rights data for client-side enforcement The Catalogue Feed provides detailed metadata that allows clients to determine where and how products can be used. This includes: Territory availability by country Rights information by territory Supported use types by territory Publishing clearance status, including whether products have 100% publishing clearance where the relevant publishing deals are in place For Catalogue Feed integrations, Tuned Global supplies the required territory and rights data. The client receiving the feed is responsible for enforcing those rules in their own systems, applications and playback environments. This model is suitable for clients who ingest catalogue data into their own infrastructure and need to manage rights logic within their own platform. Broader APIs: territory-aware responses For clients using the broader range of Tuned Global APIs beyond the Catalogue Feed, the APIs are territory-aware. When country is passed in an API request, Tuned Global returns products and content that are relevant for that territory. This means API responses account for the required rights in the requested country, including: Master rights Publishing rights This applies across experiences such as: Catalogue browsing Playlists Radio stations Content discovery Item-level territory handling Territory handling applies at the item level. For example, a playlist may contain 50 tracks in its underlying configuration, but the response may differ by territory: country=AU may return all 50 tracks country=DE may return 42 tracks country=AU may return a different set again Where a track does not have the required master and publishing rights for the requested country, it will not be returned for that territory. Supported Countries and Territories Below is the full list of supported countries and ISO codes. Title Description 🇦🇫 Afghanistan AF 🇦🇽 Åland Islands AX 🇦🇱 Albania AL 🇩🇿 Algeria DZ 🇦🇸 American Samoa AS 🇦🇩 Andorra AD 🇦🇴 Angola AO 🇦🇮 Anguilla AI 🇦🇬 Antigua and Barbuda AG 🇦🇷 Argentina AR 🇦🇲 Armenia AM 🇦🇼 Aruba AW 🇦🇺 Australia AU 🇦🇹 Austria AT 🇦🇿 Azerbaijan AZ 🇧🇸 Bahamas BS 🇧🇭 Bahrain BH 🇧🇩 Bangladesh BD 🇧🇧 Barbados BB 🇧🇾 Belarus BY 🇧🇪 Belgium BE 🇧🇿 Belize BZ 🇧🇯 Benin BJ 🇧🇲 Bermuda BM 🇧🇹 Bhutan BT 🇧🇴 Bolivia BO 🇧🇶 Bonaire, Sint Eustatius and Saba BQ 🇧🇦 Bosnia and Herzegovina BA 🇧🇼 Botswana BW 🇧🇻 Bouvet Island BV 🇧🇷 Brazil BR 🇮🇴 British Indian Ocean Territory IO 🇧🇳 Brunei Darussalam BN 🇧🇬 Bulgaria BG 🇧🇫 Burkina Faso BF 🇧🇮 Burundi BI 🇰🇭 Cambodia KH 🇨🇲 Cameroon CM 🇨🇦 Canada CA 🇨🇻 Cape Verde CV 🇰🇾 Cayman Islands KY 🇨🇫 Central African Republic CF 🇹🇩 Chad TD 🇨🇱 Chile CL 🇨🇳 China CN 🇨🇽 Christmas Island CX 🇨🇨 Cocos (Keeling) Islands CC 🇨🇴 Colombia CO 🇰🇲 Comoros KM 🇨🇬 Congo CG 🇨🇰 Cook Islands CK 🇨🇷 Costa Rica CR 🇨🇮 Côte d'Ivoire CI 🇭🇷 Croatia HR 🇨🇺 Cuba CU 🇨🇼 Curaçao CW 🇨🇾 Cyprus CY 🇨🇿 Czech Republic CZ 🇨🇩 Democratic Republic of the Congo CD 🇩🇰 Denmark DK 🇩🇯 Djibouti DJ 🇩🇲 Dominica DM 🇩🇴 Dominican Republic DO 🇪🇨 Ecuador EC 🇪🇬 Egypt EG 🇸🇻 El Salvador SV 🇬🇶 Equatorial Guinea GQ 🇪🇷 Eritrea ER 🇪🇪 Estonia EE 🇪🇹 Ethiopia ET 🇫🇰 Falkland Islands FK 🇫🇴 Faroe Islands FO 🇫🇯 Fiji FJ 🇫🇮 Finland FI 🇫🇷 France FR 🇬🇫 French Guiana GF 🇵🇫 French Polynesia PF 🇹🇫 French Southern Territories TF 🇬🇦 Gabon GA 🇬🇲 Gambia GM 🇬🇪 Georgia GE 🇩🇪 Germany DE 🇬🇭 Ghana GH 🇬🇮 Gibraltar GI 🇬🇷 Greece GR 🇬🇱 Greenland GL 🇬🇩 Grenada GD 🇬🇵 Guadeloupe GP 🇬🇺 Guam GU 🇬🇹 Guatemala GT 🇬🇳 Guinea GN 🇬🇼 Guinea-Bissau GW 🇬🇾 Guyana GY 🇭🇹 Haiti HT 🇭🇲 Heard Island and McDonald Islands HM 🇭🇳 Honduras HN 🇭🇰 Hong Kong HK 🇭🇺 Hungary HU 🇮🇸 Iceland IS 🇮🇳 India IN 🇮🇩 Indonesia ID 🇮🇶 Iraq IQ 🇮🇪 Ireland IE 🇮🇲 Isle of Man IM 🇮🇱 Israel IL 🇮🇹 Italy IT 🇯🇲 Jamaica JM 🇯🇵 Japan JP 🇯🇪 Jersey JE 🇯🇴 Jordan JO 🇰🇿 Kazakhstan KZ 🇰🇪 Kenya KE 🇰🇮 Kiribati KI 🇰🇷 Korea, Republic of KR 🇰🇼 Kuwait KW 🇰🇬 Kyrgyzstan KG 🇱🇦 Laos LA 🇱🇻 Latvia LV 🇱🇧 Lebanon LB 🇱🇸 Lesotho LS 🇱🇷 Liberia LR 🇱🇮 Liechtenstein LI 🇱🇹 Lithuania LT 🇱🇺 Luxembourg LU 🇲🇴 Macau MO 🇲🇰 North Macedonia MK 🇲🇬 Madagascar MG 🇲🇼 Malawi MW 🇲🇾 Malaysia MY 🇲🇻 Maldives MV 🇲🇱 Mali ML 🇲🇹 Malta MT 🇲🇭 Marshall Islands MH 🇲🇶 Martinique MQ 🇲🇷 Mauritania MR 🇲🇺 Mauritius MU 🇾🇹 Mayotte YT 🇲🇽 Mexico MX 🇫🇲 Micronesia FM 🇲🇩 Moldova MD 🇲🇨 Monaco MC 🇲🇳 Mongolia MN 🇲🇪 Montenegro ME 🇲🇸 Montserrat MS 🇲🇦 Morocco MA 🇲🇿 Mozambique MZ 🇲🇲 Myanmar MM 🇳🇦 Namibia NA 🇳🇷 Nauru NR 🇳🇵 Nepal NP 🇳🇱 Netherlands NL 🇦🇳 Netherlands Antilles AN 🇳🇨 New Caledonia NC 🇳🇿 New Zealand NZ 🇳🇮 Nicaragua NI 🇳🇪 Niger NE 🇳🇬 Nigeria NG 🇳🇺 Niue NU 🇳🇫 Norfolk Island NF 🇲🇵 Northern Mariana Islands MP 🇳🇴 Norway NO 🇴🇲 Oman OM 🇵🇰 Pakistan PK 🇵🇼 Palau PW 🇵🇸 Palestine PS 🇵🇦 Panama PA 🇵🇬 Papua New Guinea PG 🇵🇾 Paraguay PY 🇵🇪 Peru PE 🇵🇭 Philippines PH 🇵🇳 Pitcairn PN 🇵🇱 Poland PL 🇵🇹 Portugal PT 🇵🇷 Puerto Rico PR 🇶🇦 Qatar QA 🇷🇪 Réunion RE 🇷🇴 Romania RO 🇷🇺 Russia RU 🇷🇼 Rwanda RW 🇧🇱 Saint Barthélemy BL 🇸🇭 Saint Helena SH 🇰🇳 Saint Kitts and Nevis KN 🇱🇨 Saint Lucia LC 🇲🇫 Saint Martin MF 🇵🇲 Saint Pierre and Miquelon PM 🇻🇨 Saint Vincent and the Grenadines VC 🇼🇸 Samoa WS 🇸🇲 San Marino SM 🇸🇹 Sao Tome and Principe ST 🇸🇦 Saudi Arabia SA 🇸🇳 Senegal SN 🇷🇸 Serbia RS 🇸🇨 Seychelles SC 🇸🇱 Sierra Leone SL 🇸🇬 Singapore SG 🇸🇽 Sint Maarten SX 🇸🇰 Slovakia SK 🇸🇮 Slovenia SI 🇸🇧 Solomon Islands SB 🇸🇴 Somalia SO 🇿🇦 South Africa ZA 🇬🇸 South Georgia and the South Sandwich Islands GS 🇪🇸 Spain ES 🇱🇰 Sri Lanka LK 🇸🇷 Suriname SR 🇸🇯 Svalbard and Jan Mayen SJ 🇸🇿 Eswatini SZ 🇸🇪 Sweden SE 🇨🇭 Switzerland CH 🇹🇼 Taiwan TW 🇹🇯 Tajikistan TJ 🇹🇿 Tanzania TZ 🇹🇭 Thailand TH 🇹🇱 Timor-Leste TL 🇹🇬 Togo TG 🇹🇰 Tokelau TK 🇹🇴 Tonga TO 🇹🇹 Trinidad and Tobago TT 🇹🇳 Tunisia TN 🇹🇷 Turkey TR 🇹🇲 Turkmenistan TM 🇹🇨 Turks and Caicos Islands TC 🇹🇻 Tuvalu TV 🇺🇬 Uganda UG 🇺🇦 Ukraine UA 🇦🇪 United Arab Emirates AE 🇬🇧 United Kingdom GB 🇺🇸 United States US 🇺🇲 United States Minor Outlying Islands UM 🇺🇾 Uruguay UY 🇺🇿 Uzbekistan UZ 🇻🇺 Vanuatu VU 🇻🇪 Venezuela VE 🇻🇳 Vietnam VN 🇻🇬 British Virgin Islands VG 🇻🇮 US Virgin Islands VI 🇼🇫 Wallis and Futuna WF 🇪🇭 Western Sahara EH 🇾🇪 Yemen YE 🇿🇲 Zambia ZM 🇿🇼 Zimbabwe ZW
• [Podcast ingestion](https://guide.tunedglobal.com/refrence-documents/podcast-ingestion.md): Podcasts are fully supported within the Tuned Global Platform. Whether a podcast is distributed through an open RSS feed or a secured feed, Tuned Global can ingest, host, manage, and maintain the podcast catalogue as part of a single integrated content platform. Podcast ingestion is designed to be simple for the service operator: connect the RSS feed and Tuned Global looks after the rest. Overview The Tuned Global Podcast Ingestion system manages the end-to-end ingestion of podcast content, including the podcast series, episode metadata, audio assets, images, and transcriptions. Once a podcast feed is connected, the platform ingests the full podcast and its available episodes. After the initial ingestion is complete, the feed is automatically checked every 6 hours to identify whether new episodes have been published. When new episodes are detected, they are ingested and made available through the platform without requiring manual intervention. Feed support Tuned Global supports podcast ingestion from RSS feeds, including: Open RSS feeds Secured RSS feeds This allows services to support a broad range of podcast providers and distribution models. Initial podcast ingestion When a podcast feed is connected, Tuned Global ingests the full podcast catalogue available from that feed. This includes: Podcast series metadata Episode metadata Audio assets Podcast and episode imagery Available transcription assets The result is a complete podcast experience managed within the Tuned Global Platform. Ongoing episode updates Podcast catalogues are dynamic. New episodes may be released daily, weekly, or on any other schedule determined by the publisher. To ensure the platform remains current, Tuned Global automatically queries each podcast feed every 6 hours. During each check, the platform determines whether: New episodes have been published Existing episode metadata has changed New or updated assets are available Where new content or updates are detected, the platform processes and ingests them automatically. Asset Hosting Tuned Global can host the key assets required to deliver podcast experiences, including: Podcast audio files Episode audio files Podcast images Episode images Transcriptions This provides a single platform for managing podcast content alongside music and other supported media types. Transcriptions Where transcriptions are available or generated as part of the configured workflow, Tuned Global can manage and host transcription assets. Transcriptions can support: Search and discovery Accessibility User experience enhancements Editorial and moderation workflows Operational Model Podcast ingestion is designed to operate automatically after feed connection. The platform: Ingests the full podcast and available episodes Checks each feed every 6 hours Detects newly published episodes Processes updated metadata and assets Hosts required podcast assets Makes content available through the platform This reduces operational overhead while ensuring podcast catalogues remain up to date. APIs Podcasts are also available via a comprehensive set of APIs, allowing full integration into client applications and services. These APIs support: Podcast series retrieval Episode retrieval and playback Metadata access Search and discovery Access to associated assets (audio, images, transcriptions) This enables partners to seamlessly incorporate podcast content into their user experiences alongside music and other media types. Podcast delivery specifictions are available here.
• [Overview](https://guide.tunedglobal.com/cms/cms.md): The Tuned Global CMS, Autotune, is where teams create, organise, and manage the content that powers their digital music and media experiences. It is used to manage editorial and operational content such as playlists, stations, carousel items, promotional pages, tags, discovery structures, and other CMS-driven experiences. For API-led services, the CMS acts as the editorial layer behind your application. Your team manages content in the CMS, while your front end retrieves and displays that content through Tuned Global APIs. This means that some of the values developers need, such as a content key, playlist ID, station ID, carousel item, or tag value, originate in the CMS rather than in code. What you can do in the CMS Use the CMS to: Create and manage playlists, stations, and radio experiences Configure homepage content, featured carousels, shelves, and promotional pages Organise catalogue content using tags Manage artwork and content metadata Publish content so it can be surfaced in your app Refresh or clear cache when content updates need to appear quickly Who this section is for This section is useful for: Content and editorial teams managing app experiences in the CMS Product teams planning how content should appear in the app Developers integrating CMS-managed content through Tuned Global APIs Implementation teams who need to understand how CMS objects map to API responses If you are building an app or integration, start with CMS and API integration to understand how CMS-managed content is consumed through the APIs.
• [CMS and API integration](https://guide.tunedglobal.com/cms/cms-and-api-integration-copy.md): When building with Tuned Global APIs, it is helpful to think in terms of two layers. The CMS layer Where your content, editorial, or product team creates and manages objects such as pages, playlists, stations, carousels, tags, and promotional content. The API layer Where your application retrieves CMS-managed content, metadata, and structures, then displays them to users. For example: A developer may retrieve a content page by its content key A product team may configure a homepage carousel in the CMS A curator may create a system playlist Tags may be assigned in the CMS, then used to return grouped content returned by the API A station or radio experience may be created editorially in the CMS and then exposed through the APIs. Note: The CMS is not only used to create editorial objects such as pages, playlists, stations, and carousels. It is also used to search and manage the underlying catalogue. Content teams can find tracks, review metadata, apply tags, use chart data, and add catalogue items to playlists, stations, or other CMS-managed experiences that are later consumed through the APIs. If you are a content manager or want to understand how these actions are performed in the CMS, see the Training videos section. If you are implementing these experiences in an app, see the Developer quickstarts . IDs, keys and values you will encounter Not every CMS-driven reference is a numeric ID. In practice, API clients usually work with a mix of identifiers. Title Description Content key A unique page identifier used to retrieve a CMS-managed content page. This is especially important for content pages, homepages, and deep links. Playlist ID The identifier of a CMS-managed system playlist. Station ID The identifier of a CMS-managed station or radio experience. Tag value A CMS-managed value used to group and retrieve content in discovery, shelf, search, and homepage experiences. Carousel destination The object or destination linked from a carousel item, such as a playlist, station, album, artist, page, or external link. Catalogue item ID The identifier of a catalogue item, such as a song, album, artist, or release, that may be searched, tagged, added to playlists or stations, and surfaced through the APIs. CMS object to API reference Title Description Title CMS object Main identifier or value Typical technical use Content page Content key Retrieve a CMS-managed page, support routing, and support deep links. System playlist Playlist ID Retrieve or surface editorial playlist. Station Station ID Retrieve or surface editorial stations. Tag-driven discovery Tag value Populate shelves, group content, and support discovery. Carousel item Destination object identifier Link to a page, playlist, station, album, artist, or external destination. Catalogue item Song, album, artist, or release ID Search, retrieve, tag, organise, or add catalogue content to CMS-managed experiences such as playlists, stations, shelves, and pages. Why this matters for implementation teams A common integration mistake is to treat content structure as something that must be handled entirely in the front end. This often creates unnecessary complexity. In many cases, it is better to let the CMS handle: Page composition Promotional linking Playlist curation Station curation Carousel management Discovery and merchandising logic through tags This allows your technical team to build against stable API contracts while giving your content team direct control over what appears in the experience. For practical implementation examples, see the Developer quickstarts in this CMS section.
• [Training Videos](https://guide.tunedglobal.com/cms/training-videos.md): This page brings together short CMS training videos to help you understand how to manage and surface content through the Tuned Global platform. They are designed to help teams quickly learn how content can be configured in the CMS and made available in apps or through Tuned Global APIs. The videos cover key CMS workflows such as: Creating playlists Creating radio stations Managing carousels of content Managing content pages and homepage Using tags Searching the catalogue Finding charting tracks Generating artwork Adding radio call-outs Clearing tag cache 🎧 Creating and managing playlist This video walks you through how to create a playlist in the Tuned Global CMS, add and organise songs , generate or upload playlist artwork , apply tags , and publish the playlist so it can be surfaced in your app or accessed via Tuned Global APIs. It also introduces key playlist management features, including content tiers , language settings, track metadata , rights information, Automix enhancement, priority settings, carousel placement, offline play logging, deep links , and playlist duplication or deletion. By the end of the video, you’ll understand how to create a fully configured playlist in just a few minutes and make it available to users through your streaming experience. Chapters 0:00 CMS playlist overview and access 1:12 Create a new playlist 2:05 Add and organise songs 3:46 Upload or generate playlist artwork 5:36 Add playlist tags 6:23 Priority, carousel, deep links and other actions 7:02 Publish the playlist 📻 Create a programmatic radio station This video walks you through how to create a programmatic radio station in the Tuned Global CMS, add songs , manage access levels , upload station artwork , apply tags , and publish the station so it can be surfaced in your app or accessed via Tuned Global APIs. It also introduces the different radio station options supported by the CMS, including programmatic stations, external live radio URLs, and HLS live radio stations . You’ll learn how to search and filter existing stations, configure multilingual names and descriptions, add identifiers , manage track activity , use bulk actions, set priority weighting , add the station to a carousel , generate deep links , and schedule or publish the station. By the end of the video, you’ll understand how to create a fully configured CMS-managed radio station and make it available to users through your streaming experience. Chapters 0:00 Radio overview and CMS access 1:24 Create a new radio station 2:01 Configure station details and access 2:25 Images, songs, tags and publishing 2:54 Priority, carousel and deep links 3:20 Add and manage songs 4:13 Add tags and wrap up 🔍 Mastering advanced search This video walks you through how to use Power Search in the Tuned Global CMS to search and filter your licensed catalogue by song name, artist, tags, rights holder, label, language, genre, release date, BPM, key, duration, explicit content, lyrics availability, and tag matching rules. It also shows how to review track information, including BPM, key, duration, tags, and rights details, then select multiple songs and add them directly to a playlist or radio station . By the end of the video, you’ll understand how to quickly find the right tracks for specific playlists, radio stations, moods, genres, or energy levels. Chapters 0:00 Advanced search overview 0:23 Open song search in the CMS 0:53 Use Power Search filters 2:19 Search by song or artist 2:56 Search by genre 3:20 Add search results to playlists or stations 4:05 Filter by BPM, genre and energy level 5:02 Wrap up 📊 Searching Billboard and iTunes charts This video walks you through how to access chart and trending track data in the Tuned Global CMS, including Billboard charts and iTunes top charts by country, then automatically match those tracks against your available licensed catalogue . It also shows how to select matched tracks and add them directly to a playlist or programmatic radio station . By the end of the video, you’ll understand how to quickly identify trending songs , check whether they are available in your catalogue, and use them to keep playlists and stations fresh. Chapters 00:00 Chart search overview 0:28 Open Charts in the catalogue 0:53 View Billboard chart data 1:37 Filter iTunes charts by country 2:01 Add matched tracks to a playlist or station 2:33 Review added songs in the playlist 2:47 Wrap up 📣 Radio station call outs and identifiers This video walks you through how to add identifiers to a radio station in the Tuned Global CMS, including custom audio call-outs, intros, promos, adverts, or sound logos . It also shows how to set the frequency of a call-out, upload an MP3 or AAC audio file, activate it, and save it against the station. By the end of the video, you’ll understand how to add custom audio snippets to your radio stations and control how often they play within the listening experience. Chapters 0:00 Radio call-outs overview 0:17 Open a radio station 0:43 Add an identifier or call-out 1:24 Set call-out frequency 1:38 Upload and activate the audio file 1:55 Use call-outs, intros or promos 2:09 Wrap up 🏷️ Easy tagging explained This video walks you through how to create tags in the Tuned Global CMS, including general tags, genre tags, and system tags , then use them to group and surface content such as songs, albums, artists, playlists, and radio stations. It also shows how to set display names, manage multilingual tag labels , upload or generate tag artwork , view assigned products, export tagged content as a CSV, and apply tags to individual songs. By the end of the video, you’ll understand how to use tags to organise catalogue content and make it easier to surface through your apps or Tuned Global APIs. Chapters 0:00 Tagging overview 0:20 Open Tags in the CMS 0:41 Understand tag types 1:07 Create a general tag 1:30 Set display names and languages 1:57 View products assigned to a tag 2:46 Add tag artwork 3:35 Export tagged content 4:07 Apply a tag to a song 4:40 Search and autocomplete tags 🖼️ Automatic image generation for playlists and tags This video walks you through how to automatically generate artwork in the Tuned Global CMS by entering a simple image description, then choosing from multiple generated image options. It also shows how to apply generated images to playlists and tags , upload your own artwork , and manage different images by language where required. By the end of the video, you’ll understand how to quickly create and assign visual assets to help surface playlists, tags, and other CMS content in your apps or through Tuned Global APIs. Chapters 0:00 Artwork generation overview 0:36 Open a playlist image section 1:00 Upload your own artwork 1:42 Generate artwork from a description 2:51 Choose and save a generated image 3:13 Generate artwork for tags 4:52 Apply generated images across CMS content ✅ How to clear tag cache quickly This video walks you through how to clear the cache for a specific tag in the Tuned Global CMS so recent tag changes can appear immediately in your app. It also explains why apps use caching for performance and how tag updates for albums, mixes, playlists, and other content may take time to appear unless the cache is cleared . By the end of the video, you’ll understand how to clear the cache for tagged content and refresh the app to see the latest changes. Chapters 0:00 Tag cache overview 0:13 Why clear the tag cache 0:18 Select the tag and product type 0:31 Clear the cache 0:42 Refresh the app to see updates 🎠 Managing carousel items This video walks you through how to create and manage carousel items in the Tuned Global CMS, including homepage carousel banners that can be displayed in turnkey applications or retrieved via Tuned Global APIs. It also shows how to add carousel items linked to pages, artists, albums, songs, radio stations or playlists, upload custom images, schedule or publish items, reorder banners, clear the carousel cache, and preview updates in the app. By the end of the video, you’ll understand how to use carousels to promote content and keep your app experience fresh. Chapters 0:00 Carousel overview and access 0:44 Review an existing carousel 1:30 Add and publish carousel items 2:20 Add a custom banner and link 3:07 Upload images and reorder items 3:38 Clear cache and preview updates 4:22 Wrap up and API availability 📄 Managing homepage and content pages This video walks you through how to manage content pages in the Tuned Global CMS, including homepage layouts that can be used in turnkey applications or retrieved via Tuned Global APIs. It also shows how to add dynamic content shelves, select content types such as playlists by tag, preview page layouts, manage language versions, review history and settings, publish changes, and see updates reflected in the app. By the end of the video, you’ll understand how content pages help structure app experiences and give curation teams more control over what content is surfaced.
• [Developer quickstarts](https://guide.tunedglobal.com/cms/overview.md): These quickstarts show developers how to retrieve and display CMS-managed content using Tuned Global APIs. Use this section when your app needs to consume content configured by editorial, content, or marketing teams in the Tuned Global CMS. The CMS is where the content is created and managed. The APIs are how your app retrieves and displays that content. Choose a quickstart Title Description Quickstart Use it when Build a homepage You need to render a CMS-managed homepage using content pages, carousels, shelves, tags, and linked content. Use featured carousels You need to display carousel items, featured shelves, promotional banners, or campaign placements configured in the CMS. Use system playlists in your app You need to retrieve and display CMS-managed playlists created by your editorial or content team. Display tagged content You need to retrieve playlists, albums, artists, stations, or other content grouped by CMS tags. Before you start Make sure the relevant content has already been created and published in the CMS. Depending on what you are building, you may need one or more CMS-managed values, such as a content key, playlist ID, station ID, tag value, or carousel destination. These values usually come from the CMS configuration rather than from your app code. For more background on how CMS-managed objects map to API implementation, see CMS and API integration .
  • [Build a homepage](https://guide.tunedglobal.com/cms/overview/build-a-homepage.md): A homepage is usually made of several CMS-managed content areas, such as featured carousels, playlist shelves, radio station rows, tagged content collections, campaign banners, new releases, or editorial recommendations. The Tuned Global CMS is used by content, editorial, or marketing teams to decide what appears on the homepage. Your app retrieves that configuration through Tuned Global APIs and renders the homepage in the front-end experience. This approach allows non-technical teams to update homepage content without requiring an app release. Developer guide: This page is for developers who want to build and render a homepage using CMS-managed content and Tuned Global APIs. To learn how to configure homepage content in the Tuned Global CMS, watch our video Create and manage homepage and content pages in the CMS . How a CMS-managed homepage works A typical workflow looks like this: A CMS user configures the homepage structure and content in the Tuned Global CMS. They add featured items, shelves, carousels, banners, playlists, radio stations, albums, artists, or tagged content groups. They apply any required language, country, content tier, or visibility rules. Your app retrieves the homepage configuration using Tuned Global APIs. Your front end renders each homepage section using the data returned by the API. When a user selects an item, your app routes them to the correct destination. The CMS controls what appears on the homepage. The app controls how that content is displayed. Retrieve homepage items These endpoints are part of the Metadata API and are used to retrieve CMS-managed page content. To retrieve CMS-managed homepage content, use the Get Items endpoint for the relevant CMS page. 👉 Endpoint: GET /api/v2.4/pages/{name}/items Use this endpoint when your app needs to load the configured items for a homepage or another CMS-managed page. Example request: 👉 Endpoint: GET /api/v2.4/pages/home/items StoreId: YOUR_STORE_ID Replace home with the page name configured for your service. The response should be used to determine which sections and items to render on the homepage. Your app should not hardcode the homepage layout if the page is intended to be managed from the CMS. Retrieve public homepage items Use the Get Public Items endpoint when the homepage or page content should be available without the same user-specific context as authenticated areas. 👉 Endpoint: GET /api/v2.4/pages/{name}/publicitems Example request: 👉 Endpoint: GET /api/v2.4/pages/home/publicitems StoreId: YOUR_STORE_ID Use the API Reference to confirm whether your implementation should use items or public items, depending on your app’s authentication flow and content visibility requirements. Build homepage sections A homepage response may include different item types or content blocks. Your front end should inspect the returned item data and render each section using the appropriate component. For example: Title Description Homepage item Recommended app behaviour Featured carousel Render as a hero carousel or featured shelf. Playlist Render as a playlist card and open the playlist detail page when selected. Radio station Render as a station card and open or start the radio experience. Album Render as an album card and open the album detail page. Artist Render as an artist card and open the artist page. Tag Render a tagged collection or use the tag to load related content. Custom banner Render the banner and follow the configured link or deep link. Content page Navigate to the configured CMS-managed page. The exact front-end layout is controlled by your application, but the content, ordering, and destination should come from the CMS-managed API response. Use carousels on the homepage If your homepage includes a featured carousel, retrieve the carousel content using the relevant Content Pages & CMS Content endpoint. 👉 Endpoint: GET /api/v2.4/pages/{name}/items For language-specific carousel content, use: 👉 Endpoint: GET /api/v2.4/pages/carouselbylanguage For country-specific carousel content, use: 👉 Endpoint: GET /api/v2.4/pages/carousel-by-country Use these endpoints when the CMS team needs to show different homepage content by language, country, or market. Use playlists on the homepage If the homepage includes CMS-managed playlists, your app should use the playlist ID returned by the homepage response to retrieve the relevant playlist details and tracks. For example, when a homepage item links to a playlist, your app can: Display the playlist card using the metadata returned in the homepage response. Open the playlist detail page when the user selects it. Retrieve the playlist details and track list using the relevant Playlist endpoints. This keeps the homepage lightweight while allowing the playlist detail page to load the full playlist experience only when needed. Use tags on the homepage Tags can be used to power flexible homepage shelves, such as mood, genre, campaign, or activity-based sections. For example, a CMS user may tag several playlists, albums, songs, or radio stations with a tag such as workout , kids , new releases , or local artists . Your app can use the configured tag to retrieve and display the related content. This allows the CMS team to change which content appears in a homepage shelf by changing tag assignments, rather than requiring a code change. Route users from homepage items When a user selects a homepage item, your app should route them based on the item type and destination returned by the API. For example: If the item is a playlist, open the playlist detail page; If the item is a radio station, open or start the station experience; If the item is an album, open the album detail page; If the item is an artist, open the artist page; If the item is a custom banner, follow the configured link or deep link; If the item points to another CMS-managed page, open that page in the app. Where additional data is required, call the relevant API endpoint for that content type after the user selects the item. Recommended implementation pattern Confirm the homepage is configured in the CMS The homepage structure, featured areas, shelves, banners, and linked content should be configured by a CMS user. Retrieve the homepage configuration Use GET /api/v2.4/pages/{name}/items to retrieve the CMS-managed homepage content. Use GET /api/v2.4/pages/{name}/publicitems where public access is required. Choose the correct localisation approach If the homepage changes by language or country, use the relevant language-specific or country-specific carousel endpoint. Render each homepage section Use the item type, title, image, order, and destination returned by the API to choose the correct front-end component. Load detailed data only when needed If a user selects a playlist, station, album, artist, or other content item, call the relevant API endpoint to retrieve the full detail view. Respect visibility and catalogue rules Your app should respect any content tier, language, country, territory, rights, access, or availability rules returned or enforced by the API. Handle unavailable content gracefully If a homepage item points to content that is no longer available, your app should hide it, skip it, or show a fallback state. Handle updates and caching If homepage content, linked content, artwork, tags, or carousel items are updated in the CMS, the change may not appear instantly in the app because caching may be used for performance. If an immediate update is required, the relevant cache may need to be cleared or refreshed. Related API Reference sections Developers should refer to the API Reference for endpoint-level details: Title Description API Reference section When to use it Content Pages & CMS Content Retrieve CMS-managed homepage, page, and carousel items. Carousel by Language Retrieve language-specific carousel content. Carousel by Country Retrieve country-specific carousel content. Playlists Retrieve playlist details and tracks when homepage items link to playlists. Stations & Radio Retrieve station details when homepage items link to radio stations. Tags Retrieve content grouped by CMS tags. Search Support user-driven discovery from the homepage. Albums & Releases Retrieve album or release details when homepage items link to albums. Artists Retrieve artist details when homepage items link to artists. Important notes The homepage should be treated as a CMS-managed experience. Developers should avoid hardcoding featured content if the homepage is intended to be managed by editorial, content, or marketing teams. The app should render the homepage based on the items returned by the API, including their order, images, content type, and destination. If your service uses language-specific or country-specific homepage rules, make sure the app calls the correct endpoint and passes the required context. If the homepage includes content that is restricted by user tier, market, territory, or catalogue availability, your app should respect those rules before displaying or playing the content.
  • [Use featured carousels](https://guide.tunedglobal.com/cms/overview/use-featured-carousels.md): Featured carousels are configured in the Tuned Global CMS and can be used to promote content in your app, such as playlists, radio stations, albums, artists, content pages, campaigns, or custom banners. They are typically managed by an editorial, content, or marketing team in the CMS, then retrieved by your app through Tuned Global APIs. This allows non-technical teams to update what appears in featured areas of the app without requiring a front-end release. Developer guide: This page explains how to retrieve and display featured carousels using Tuned Global APIs. To learn how to create and manage featured carousels in the CMS, watch the relevant CMS carousel management video. CMS Training Videos How featured carousels work A typical workflow looks like this: A CMS user creates or updates a featured carousel in the Tuned Global CMS . They add the content or banners they want to promote. They configure any required language, country, or visibility rules. Your app retrieves the carousel items using Tuned Global APIs. Your front end renders the carousel and routes users to the correct destination when they select an item. The CMS is used to configure the carousel. The APIs are used to retrieve and display the carousel content in your app. Retrieve carousel items for a page To retrieve carousel or page items configured in the CMS, use the Get Items endpoint. 👉 Endpoint: GET /api/v2.4/pages/{name}/items Use this endpoint when your app needs to retrieve the configured items for a specific CMS page or carousel area. For example, your CMS team may configure a homepage carousel with: a featured playlist, a promoted radio station, a campaign banner, a new album, a seasonal collection. Your app can request the items for that page and render them in the order returned by the API. Example request: 👉 Endpoint: GET /api/v2.4/pages/{name}/items StoreId: YOUR_STORE_ID Replace {name} with the page or carousel name configured for your service. Retrieve public carousel items Use the Get Public Items endpoint when you need to retrieve public items for a CMS page. 👉 Endpoint: GET /api/v2.4/pages/{name}/publicitems This can be useful when the page or carousel contains content that should be available without the same user-specific context as authenticated app areas. Example request: 👉 Endpoint: GET /api/v2.4/pages/{name}/publicitems StoreId: YOUR_STORE_ID Use the API Reference to confirm when your implementation should use items or publicitems , based on your app’s authentication flow and content visibility rules. Retrieve carousel items by language If your service supports multiple languages, the CMS may be configured with language-specific carousel content. Use the Carousel by Language endpoint to retrieve the carousel content for the relevant language. 👉 Endpoint: GET /api/v2.4/pages/carouselbylanguage Use this when your app needs to display different carousel content depending on the user’s selected language or app locale. For example, a service may show one carousel for English-speaking users and another for Thai-speaking users. Your app should request the appropriate language version and render the content returned by the API. Retrieve carousel items by country If your service supports country-specific carousel content, use the Carousel by Country endpoint. 👉 Endpoint: GET /api/v2.4/pages/carousel-by-country Use this when carousel content should vary by country, territory, or market. For example, your CMS team may promote different playlists, radio stations, or campaigns in Australia, Thailand, or Italy. Your app should request the correct country version and display the carousel items returned by the API. Display and open carousel items in your app The API response should be used to render the carousel in your app. Your front end should use the returned item data to display the correct title, image, content type, and destination. Title Description Item type Depending on the configuration, a carousel item may represent different types of content, such as: Recommended app behaviour When a user selects a carousel item, your app should route the user based on the item type and destination returned by the API. Playlist Open the playlist detail page. Radio station Open or start the station experience. Album Open the album detail page. Artist Open the artist page. Content page Navigate to the configured page. Custom banner Follow the configured link, deep link, or destination. Your app should not hardcode carousel content. The CMS should control what appears in the carousel, while the app renders the items returned by the API. Where additional detail is required, call the relevant API endpoint for that content type after the user selects the item. For example, if the carousel item links to a playlist, your app can use the playlist ID returned in the carousel item to retrieve the playlist details and tracks. Recommended implementation pattern Confirm the carousel is configured in the CMS The carousel, page, or featured content area should first be configured by a CMS user. Choose the correct carousel endpoint Use GET /api/v2.4/pages/{name}/items for a configured CMS page or carousel area. Use the language or country-specific endpoints when your carousel should vary by locale or market. Retrieve the carousel items Call the relevant endpoint and include the required headers, such as StoreId . Render the carousel in your app Display the title, image, and content returned by the API. Keep the order returned by the API unless your product requirements say otherwise. Route users based on item type When a user selects an item, open the correct destination, such as a playlist, radio station, album, artist page, content page, or custom banner link. Respect content and visibility rules Your app should respect any access rules, territory restrictions, language settings, country settings, content tiers, or availability rules returned or enforced by the API. Handle updates and caching If carousel content, artwork, or linked content is updated in the CMS, the update may not appear instantly in the app because caching may be used for performance. If an immediate update is required, the relevant cache may need to be cleared or refreshed. Related API Reference sections Developers should refer to the API Reference for endpoint-level details: Title Description API Reference section When to use it Content Pages & CMS Content Retrieve CMS-managed page and carousel items. Carousel by Language Retrieve language-specific carousel content. Carousel by Country Retrieve country-specific carousel content. Playlists Retrieve playlist details when a carousel item links to a playlist. Stations & Radio Retrieve station details when a carousel item links to a station. Albums & Releases Retrieve album or release details when a carousel item links to an album. Artists Retrieve artist details when a carousel item links to an artist. Important notes Featured carousels are configured in the CMS and consumed through the APIs. Developers should not hardcode featured content if the carousel is intended to be managed by the CMS. The app should render the carousel based on the items returned by the API, including their order, images, destination, and content type. If your service uses language-specific or country-specific carousel rules, make sure the app calls the correct endpoint and passes the required context. If a carousel item points to content that is no longer available, your app should handle that gracefully, for example by hiding the item, skipping it, or showing a fallback state.
  • [Use system playlists in your app](https://guide.tunedglobal.com/cms/overview/manage-system-playlists.md): System playlists are playlists created and managed in the Tuned Global CMS. They are typically curated by an editorial, content, or operations team, then published so they can be retrieved and displayed in your app through Tuned Global APIs. Use system playlists when you want to power curated music experiences such as editorial playlists, featured collections, mood-based playlists, genre pages, homepage shelves, campaign playlists, or playlists promoted to specific user tiers. Developer guide: This page explains how to retrieve and display published system playlists using Tuned Global APIs. To learn how to create and manage playlists in the CMS, watch our video Creating and Managing Playlists in the Tuned Global CMS. CMS Training Videos How system playlists work A typical workflow looks like this: A CMS user creates a playlist in the Tuned Global CMS . They add tracks, artwork, tags, language settings, content tier rules, and other metadata. The playlist is published. Your app retrieves the playlist using Tuned Global APIs. Your front end displays the playlist metadata, artwork, and track list to users. The CMS is where the playlist is managed. The APIs are how your app consumes the published playlist. Retrieve published system playlists To retrieve a list of published playlists, use the Get Playlists endpoint. 👉 Endpoint: GET https://api-services-connect.tunedglobal.com/api/v3/collection/playlists?type=System This endpoint can be used to return playlists that are available to your service. Depending on your API version and configuration, you may be able to filter the response using query parameters such as: Title Description Parameter Description mediaType Filter playlists by media type, such as Audio , Video , or All . count Number of playlists to return. offset Starting point for pagination. sort Sort order, for example newest first. type Playlist type, such as System , User , or All . Use System when you only want CMS-managed playlists. Include your StoreId in the request header so the API returns playlists for the correct service. StoreId: YOUR_STORE_ID Example: display CMS playlists on a homepage For example, your CMS team may create several system playlists: New Releases Workout Hits Chill Evening Kids Favourites Local Artists Once these playlists are published, your app can call the playlist endpoint with type=System to retrieve the CMS-managed playlist collection. Example request: 👉 Endpoint: GET https://api-services-connect.tunedglobal.com/api/v3/collection/playlists?type=System&mediaType=Audio&count=10&offset=1&sort=Newest HttpHeader : StoreId:YOUR_STORE_ID Your app can then use the response to display a playlist shelf, including the playlist title, description, artwork, and playlist ID. Retrieve a specific playlist by ID If your app already knows the playlist ID, for example because the playlist was selected from a homepage shelf, tag page, search result, or carousel item, use the playlist details endpoint. Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/{id} HttpHeader : StoreId:YOUR_STORE_ID Use this when you need to open a playlist detail page and display information for one specific playlist. Example: 👉 Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/123456 HttpHeader : StoreId:YOUR_STORE_ID The response can be used to display the playlist title, description, artwork, duration, track count, and other playlist metadata available for that playlist. Retrieve the playlist tracks After retrieving a playlist, your app will usually need to display or play the tracks inside it. Use the relevant playlist or collection track endpoint from the API Reference to retrieve the track list for the selected playlist. In the API mapping, playlist track retrieval is associated with: 👉 Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/{id}/tracks HttpHeader : StoreId:YOUR_STORE_ID Use the API Reference for the exact request parameters required to retrieve tracks for a playlist in your implementation. Retrieve playlists by tag If your CMS team uses tags to organise playlists, your app can retrieve playlists by tag instead of hardcoding playlist IDs. This is useful for experiences such as: mood pages genre pages campaign collections personalised shelves homepage modules managed by the content team Use the Get Playlists by Tag endpoint. 👉 Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/tags/playlists HttpHeader : StoreId:YOUR_STORE_ID For example, if the CMS team tags several playlists with workout , your app can request playlists linked to that tag and display them in a Workout section. This approach gives non-technical teams more control because they can update which playlists appear in the app by changing the tag assignments in the CMS, without requiring a front-end release. Search for playlists If your app includes search, use the playlist search endpoint to allow users to find playlists by keyword. 👉 Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/search/playlists HttpHeader : StoreId:YOUR_STORE_ID Use this for user-facing search experiences where playlists should appear alongside other searchable content, or in a dedicated playlist search tab. Display playlists through CMS content pages or carousel items If playlists are promoted through a CMS-managed page, shelf, or carousel, retrieve the configured page or carousel items rather than manually requesting individual playlist IDs. Relevant API areas include: Title Description API area Use it when Content Pages & CMS Content The playlist is part of a CMS-managed page or app layout. Carousel The playlist is promoted in a featured carousel or shelf. Playlists You need playlist details or playlist content. Tags You need playlists grouped by CMS tags. Search You need users to search for playlists. This is often the best approach for homepage and discovery experiences because the CMS controls what is featured, while the app simply renders the configured content. Check explicit status Before displaying a playlist in a restricted experience, such as a kids' profile or family-safe mode, you can check whether the playlist contains explicit content. 👉 Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/{id}/explicit-status HttpHeader : StoreId:YOUR_STORE_ID Use this endpoint before showing a playlist in an environment where explicit content should be excluded. Validate playlist availability Before displaying or playing a playlist, you may need to confirm that it is still active and visible in the catalogue for your service. Use catalogue validation with Playlist as the content type. POST https://api-metadata-connect.tunedglobal.com/api/v2.4/catalogue/Playlist/validate This is useful when playlist IDs are cached, stored in your app, or linked from a previous CMS configuration. Validation helps confirm that the playlist is still available before you show it to the user. Recommended implementation pattern Retrieve all system playlists Use GET https://api-metadata-connect.tunedglobal.com/api/v3/collection/playlists?type=System when you need a list of published system playlists. Open a selected playlist Use GET https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/{id} when the user selects a playlist. Load the track list Use GET https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/{id}/tracks to retrieve the songs in the playlist. Use tags for flexible grouping Use GET https://api-metadata-connect.tunedglobal.com/api/v2.4/tags/playlists when playlists are grouped by CMS tags. Use search when the user enters a keyword Use GET https://api-metadata-connect.tunedglobal.com/api/v2.4/search/playlists for playlist search experiences. Validate before display or playback Use explicit-status and catalogue validation endpoints where required, especially for restricted, kids, or profile-based experiences. Related API Reference sections Developers should refer to the API Reference for endpoint-level details: Title Description API Reference section When to use it Playlists Retrieve playlist details, playlist tracks, playlist metadata, and playlist-related data. Search Search for playlists using the Playlist Search endpoint. Tags Retrieve playlists grouped by CMS tags. Content Pages & CMS Content Display playlists as part of CMS-managed pages, shelves, homepage sections, or carousel areas. Catalogue Controls Validate whether a playlist is still available before displaying or playing it. Important notes Only published playlists should be treated as available for production app experiences. Your app should respect the access rules, content tier, rights availability, territory restrictions, and catalogue rules configured for your service. If a playlist, tag, artwork, or carousel placement is updated in the CMS, the change may not appear instantly in the app because caching is used for performance. If an immediate update is required, the relevant cache may need to be cleared from the CMS. Developers should not use public APIs to create or manage CMS system playlists. System playlists are created and managed in the CMS, then retrieved and displayed through Tuned Global APIs.
  • [Display tagged content](https://guide.tunedglobal.com/cms/overview/display-tagged-content.md): Tags are used in the Tuned Global CMS to group content such as artists, albums, playlists, radio stations, audiobooks, podcast channels, and other catalogue items. They are typically managed by a content, editorial, or operations team in the CMS, then used by your app to build shelves, collections, category pages, discovery areas, or personalised content experiences. This allows non-technical teams to update which content appears in the app by changing tag assignments in the CMS, without requiring a front-end release. Developer guide: This page is for developers who want to retrieve and display content grouped by CMS tags using Tuned Global APIs. To learn how to create, configure, or manage tags in the Tuned Global CMS, watch our video Create and manage tags in the CMS . How tagged content works A typical workflow looks like this: A CMS user creates or selects a tag in the Tuned Global CMS . They assign the tag to relevant content, such as playlists, albums, artists, or stations. Your app retrieves the tag or tagged content using Tuned Global APIs. Your front end displays the returned content in the relevant area of the app. If the tag assignments change in the CMS, the app can display the updated content after the relevant cache refreshes. The CMS controls which content is linked to the tag. The APIs are used to retrieve and display that tagged content in your app. Use tagged content to power: mood-based shelves, such as Chill, Workout, Focus, or Sleep genre pages, such as Pop, Rock, Classical, or Hip Hop campaign collections editorial recommendations local music collections kids or family-safe content areas artist or album discovery pages homepage rows managed by the CMS dynamic playlist, station, or album groupings Retrieve a tag by name If your app needs to look up a specific tag, use the Get by Name endpoint. 👉 Endpoint: GET /api/v2.4/tags Use this when your app already knows the tag name and needs to retrieve the tag details before loading tagged content. Example request: 👉 Endpoint: GET /api/v2.4/tags?name=workout StoreId: YOUR_STORE_ID Use the API Reference for the exact query parameters required by your implementation. Retrieve multiple tags by name If your app needs to resolve several tags at once, use the Get Multiple by Name endpoint. 👉 Endpoint: GET /api/v2.4/tags/multiple This can be useful when building a page that contains several tagged sections, such as: Workout New Releases Kids Local Artists Trending Instead of resolving each tag individually, your app can retrieve multiple tag records and then use them to load the relevant tagged content. Retrieve tags by tag type Use the Get Tags by Tag Type endpoint when your app needs to display a list of tags from a specific tag category. 👉 Endpoint: GET /api/v2.4/tags/tagtype This is useful when building browse or discovery experiences where users select from a group of tags, such as genres, moods, activities, or editorial categories. For example, your app could retrieve a list of genre tags and display them as selectable tiles. When a user selects one of those tags, your app can retrieve the relevant content for that tag. Retrieve artists by tag Use the Get Artists by Tag endpoint to display artists linked to a specific tag. 👉 Endpoint: GET /api/v2.4/tags/artists Use this when building artist discovery pages, genre-based artist collections, or campaign areas that promote specific groups of artists. Example use cases: show local artists tagged with greenlandic show artists linked to a genre tag show artists associated with a campaign or editorial theme Retrieve albums by tag Use the Get Albums by Tag endpoint to display albums linked to a specific tag. 👉 Endpoint: GET /api/v2.4/tags/albums Use this when building album shelves, genre pages, campaign collections, or editorial album recommendations. For example, a CMS user may tag several albums with new releases , summer , or local favourites . Your app can retrieve the albums linked to that tag and render them as a shelf or collection page. Retrieve stations by tag Use the Get Stations by Tag endpoint to display radio stations linked to a specific tag. 👉 Endpoint: GET /api/v2.4/tags/stations Use this when your app needs to show grouped radio stations, such as: workout stations kids stations mood-based stations country-specific stations editorial station collections When a user selects a station, your app should route them to the relevant station experience. Retrieve playlists by tag Use the Get Playlists by Tag endpoint to display playlists linked to a specific tag. 👉 Endpoint: GET /api/v2.4/tags/playlists Use this when building playlist shelves or tagged playlist pages. For example, your CMS team may tag several playlists with chill , workout , kids , or new releases . Your app can retrieve those playlists and display them without hardcoding playlist IDs in the front end. The API spreadsheet also lists Get Playlists by Tags using the same endpoint: 👉 Endpoint: GET /api/v2.4/tags/playlists Use the API Reference to confirm whether your implementation should pass a single tag, multiple tags, or other query parameters. Retrieve audiobooks or podcast channels by tag If your service includes audiobooks or podcasts, tags can also be used to organise and surface that content. Use the relevant browse-by-tag endpoints: 👉 Endpoint: GET /api/v2.4/tags/audiobooks 👉 Endpoint: GET /api/v2.4/tags/podcasts Use these endpoints when building themed audiobook or podcast collections, such as wellbeing, children’s stories, education, or local content. Retrieve content by tag groups The API Reference also includes tag group endpoints for albums and artists. 👉 Endpoint: GET /api/v2.4/tags/groups/albums 👉 Endpoint: GET /api/v2.4/tags/groups/artists Use tag groups when your app needs to retrieve content using a grouped tag structure, rather than a single tag. For example, your CMS team may organise tags into broader groups such as genres, moods, regions, or campaigns. Your app can use the tag group endpoint to retrieve content associated with that grouped structure. Display tagged content in your app The API response should be used to render the tagged content in your app. Your front end should use the returned data to display the correct title, image, content type, and destination. Depending on the endpoint used, the returned content may represent different item types: Title Description Content type Recommended app behaviour Playlist Render a playlist card and open the playlist detail page when selected. Station Render a station card and open or start the radio experience. Album Render an album card and open the album detail page. Artist Render an artist card and open the artist page. Audiobook Render an audiobook card and open the audiobook detail page. Podcast channel Render a podcast card and open the podcast channel page. Your app should not hardcode which items appear under a tag. The CMS should control the tag assignments, while the app renders the content returned by the API. Use tagged content on a homepage Tagged content is often used to power homepage shelves. For example, a CMS team could create a homepage row called “Workout” and use a workout tag to control which playlists, albums, stations, or artists appear in that section. Your app can: retrieve the homepage configuration; identify that a section is powered by a tag; call the relevant tag endpoint for the content type; render the returned items in the homepage shelf. This makes homepage content easier to maintain because the CMS team can update the shelf by changing tag assignments rather than asking developers to update IDs in the app. Route users from tagged content When a user selects a tagged content item, your app should route them based on the content type returned by the API. For example: if the item is a playlist, open the playlist detail page; if the item is a radio station, open or start the station experience; if the item is an album, open the album detail page; if the item is an artist, open the artist page; if the item is an audiobook, open the audiobook detail page; if the item is a podcast channel, open the podcast channel page. Where additional data is required, call the relevant API endpoint for that content type after the user selects the item. Recommended implementation pattern Confirm the tag is configured in the CMS The tag should be created, enabled, and assigned to the relevant content by a CMS user. Decide what content type to display Choose whether the app should display playlists, artists, albums, stations, audiobooks, podcast channels, or another supported content type. Call the relevant tag endpoint Use the endpoint for the selected content type, such as GET /api/v2.4/tags/playlists , GET /api/v2.4/tags/albums , GET /api/v2.4/tags/artists , or GET /api/v2.4/tags/stations . Render the returned content Display the title, image, content type, and metadata returned by the API. Route users based on item type When a user selects an item, open the relevant detail page or playback experience. Respect visibility and catalogue rules Your app should respect any content tier, language, country, territory, rights, access, or availability rules returned or enforced by the API. Handle empty or unavailable results If a tag has no available content for the user, territory, or service, your app should hide the shelf, show a fallback, or display an empty state. Handle updates and caching If tag assignments are updated in the CMS, the change may not appear instantly in the app because caching may be used for performance. If an immediate update is required, the relevant tag cache may need to be cleared or refreshed. Related API Reference sections Developers should refer to the API Reference for endpoint-level details: Title Description API Reference section When to use it Tags Retrieve tags and content grouped by tag. Search Search for tags or tagged content. Playlists Retrieve playlist details and tracks when tagged content links to playlists. Stations & Radio Retrieve station details when tagged content links to radio stations. Albums & Releases Retrieve album or release details when tagged content links to albums. Artists Retrieve artist details when tagged content links to artists. Podcasts, Audiobooks & Authors Retrieve podcast or audiobook details when tagged content links to those content types. Content Pages & CMS Content Display tagged content as part of CMS-managed pages, shelves, or homepage sections. Important notes Tags are managed in the CMS and consumed through the APIs. Developers should avoid hardcoding tagged content if the section is intended to be managed by editorial, content, or operations teams. The app should render tagged content based on the items returned by the API, including their order, images, content type, and destination. If the tag has language-specific labels or images, make sure the app displays the correct localisation where available. If a tag assignment, tag image, or tagged content collection is updated in the CMS, the change may not appear instantly in the app because caching may be used for performance. If the app needs the update to appear immediately, clear or refresh the relevant tag cache from the CMS, then refresh the app content.
• [Postman](https://guide.tunedglobal.com/tools/postman.md): Music Streaming Service (DSP) - Quick start Please click this link to try our APIs in Postman