Your first request

This page walks through the canonical SwiftSonic snippet line by line. By the end you should have a working client connected to a Subsonic-compatible server.

The full example

import SwiftSonic

let client = SwiftSonicClient(
    config: ServerConfiguration(
        host: "music.example.com",
        username: "user",
        password: "pass"
    )
)

let albums = try await client.getAlbumList2(type: .recent)

That’s the whole API surface for a basic call: import, configure, call.

Step by step

1. Import SwiftSonic

import SwiftSonic

The module exposes everything you need: SwiftSonicClient, ServerConfiguration, the API methods, the response models, and SwiftSonicError.

2. Build a server configuration

let config = ServerConfiguration(
    host: "music.example.com",
    username: "user",
    password: "pass"
)

ServerConfiguration collects the connection details: host, credentials, and any optional transport tweaks (custom headers, retry policy, logging). Defaults are sensible — no logging, token-based auth, no retries.

TODO: confirm the exact initializer signature and default values for ServerConfiguration in Sources/SwiftSonic/ServerConfiguration.swift. List the optional parameters here once verified.

3. Instantiate the client

let client = SwiftSonicClient(config: config)

SwiftSonicClient is an actor. All API methods are async and isolated to the actor, so you can share a single instance across your app safely.

4. Make a call

let albums = try await client.getAlbumList2(type: .recent)

getAlbumList2 is the OpenSubsonic-flavoured album-listing endpoint. The type parameter selects the listing mode: .recent, .newest, .frequent, etc.

TODO: confirm the full enum of AlbumListType cases and the exact return type from the SwiftSonicClient implementation.

Where to go from here

• Authentication — switch between password and token-based auth, add Cloudflare Access headers.
• Configuring the client — full ServerConfiguration reference.
• Error handling — recover from transient failures and surface auth errors.