Pairing To Sound Zone

To stream music, the SDK must first be paired with a specific sound zone within a Soundtrack location. This is done using a temporary pairing code, generated on demand by Soundtrack. Once paired, a unique Device ID will be returned that can be used when checking for SDK updates later.

For implementation details, please refer to splayer_auth_api-1.h reference. To try out the pairing process, you’ll first need a Soundtrack Test account provided by us, please contact us if you don’t have one.

Obtaining a Pairing Code

There are two primary methods for getting a pairing code, Redirect and Callback or Manual Entry which is then used to call one of the functions initiate_pair_with_code or pair_with_code_sync.

Redirect and Callback (Preferred):

This method provides the smoothest user experience by eliminating manual entry. Your companion application, initiates the pairing and the player gets paired automatically without the user typing a code. This is how it is implemented:

1. Your companion application initiates a redirect to the following URL: https://app.soundtrack.io/connect/generic?redirect={REDIRECT_URL}. Replace <REDIRECT_URL> with the URL of your companion application that will handle the callback. This URL must include a redirect parameter that points back to your companion app.
2. The user logs in to their Soundtrack account and selects the desired sound zone to pair the SDK with.
3. Soundtrack redirects the user back to your specified <REDIRECT_URL> with the pairing code appended as a query parameter: <REDIRECT_URL>?code=<CODE>
4. Your companion application can then extract the code parameter and programmatically provide it to the SDK to complete the pairing.

If you wish to simulate this pairing flow, you can run this following example locally:

#!/usr/bin/env python3
import http.server
import socketserver
import webbrowser
from urllib.parse import urlparse, parse_qs

# --- Configuration ---
PORT = 8080
REDIRECT_URL = f"http://localhost:{PORT}"
SOUNDTRACK_URL = f"https://app.soundtrack.io/connect/generic?redirect={REDIRECT_URL}"

# --- Simple HTTP Server ---
class PairingCodeCallbackHandler(http.server.SimpleHTTPRequestHandler):
    def do_GET(self):
        # Parse the request URL to find the 'code' parameter
        query_components = parse_qs(urlparse(self.path).query)
        code = query_components.get("code", [None])[0]
        print(f"Received code: {code}")
        self.send_response(200)
        self.send_header("Content-type", "text/html")
        self.end_headers()

        raise SystemExit

# --- Main execution ---
try:
    with socketserver.TCPServer(("", PORT), PairingCodeCallbackHandler) as httpd:
        print(f"Starting local server on port {PORT}...\n")
        print("1. A browser window will open.")
        print("2. Log in using your test account and select a zone to pair with.")
        print("3. Press return to app and the code will appear in the terminal.")
        print("4. Copy the code for use with your SDK.")

        webbrowser.open(SOUNDTRACK_URL)
        httpd.serve_forever()
except OSError as e:
    print(f"Could not start server on port {PORT}: {e}")

See example_auth.c in the SDK package for a proof-of-concept using this method.

Important Notes:

• The generic endpoint is provided strictly for your initial development/testing work only and will only allow redirects to a localhost address. Once you are finished with testing, we will provide a unique slug to your project with specific allowed redirects.
• When using the redirect method, ensure your application can handle URL redirects and retrieve parameters from the callback URL.
• Using this method, it is important to clearly communicate through your applications UI the redirect process to the user to avoid confusion.

Manual Entry:

1. The user logs in to their Soundtrack account through the Soundtrack web application using any device.
2. The user navigate to the desired sound zone they wish to stream music from and generate a pairing code by selecting Pair.
3. A pairing code will be generated and displayed on the page.
4. Your application interface (e.g., on the companion app or a screen on the player itself) must provide a place for the user to type in this code.
5. Once entered, your application passes the code to the SDK to complete the pairing.