Tuned Global Quickstart Guide

Overview

This quickstart demonstrates end-to-end music streaming API integration, covering authentication through playback logging in approximately 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:

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:

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:

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. Stream 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:

curl --location --request POST \
  'https://api-services-connect.tunedglobal.com/api/v3/plays/{trackId}/{device}/stream?streamType=Music&streamProvider=Tuned' \
  --header 'StoreID: XXYY' \
  --header 'Authorization: Bearer xxxyyyy'

6. Log Playback

Submit playback events for analytics and royalty reporting.

Example:

curl -X POST "https://api-services-connect.tunedglobal.com/api/v3/plays/222" \
  -H "Content-Type: application/json" \
  -d '{"TrackId": {trackId}, "LogPlayType": "Start", "Seconds": 30, "Source": "Album", "SourceId": {albumId}, "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