Migrate from ShazamKit to AudD

This page is for developers using Apple’s ShazamKit who want recognition that runs the same way across platforms and servers, or who need to match against AudD’s managed database rather than only a catalog they build. ShazamKit is an Apple framework that matches audio on-device on Apple platforms, against Apple’s Shazam catalog or a custom catalog you assemble from your own reference recordings. AudD is a cross-platform HTTP API: you send audio (or a URL) over the network and get back the recognized track, matched against AudD’s 160-million-song database or your own uploaded custom catalog. This guide maps the concepts and shows iOS (Swift) before/after using the official AudD Swift SDK.

Concept mapping

ShazamKit concept	AudD equivalent
`SHManagedSession` / `SHSession`	An `AudD` client instance you construct once with your `api_token`.
`SHSignatureGenerator` (build a signature from audio)	No client-side signature step — you send the audio (URL, file, or bytes) and AudD fingerprints it server-side.
`SHSession.match(_:)` / delegate `didFind`	`try await audd.recognize(...)` returning `RecognitionResult?`.
`SHMatchedMediaItem` (title, artist, artworkURL, appleMusicID)	`RecognitionResult` fields: `artist`, `title`, `album`, `releaseDate`, `label`, `songLink`, `thumbnailURL`, plus provider blocks via `return`.
Custom catalog (`SHCustomCatalog` from your reference signatures)	AudD custom catalog uploaded via `POST api.audd.io/upload/`.
Apple’s Shazam catalog	AudD’s public database of 160 million songs.
On-device matching	An HTTP recognition call (from any platform, server-side or from your backend).

The equivalent call

Before — ShazamKit on iOS

With ShazamKit you capture audio, feed buffers to a signature generator, run the match in a session, and read the result from the matched media item:

// Before — ShazamKit: on-device match
import ShazamKit
import AVFoundation

let session = SHManagedSession()

func identify() async {
    for await result in session.results {
        switch result {
        case .match(let match):
            if let item = match.mediaItems.first {
                print("\(item.artist ?? "?") — \(item.title ?? "?")")
                print("Apple Music ID:", item.appleMusicID ?? "-")
            }
        case .noMatch:
            print("no match")
        case .error(let error, _):
            print("error:", error)
        }
    }
}

// elsewhere: await session.prepare(); session.start()  to begin listening

After — AudD with the Swift SDK

With AudD you record a short clip with AVAudioRecorder (or capture buffers and write a file), then hand the bytes — or a file URL — to recognize. The fingerprinting happens server-side. Install via Swift Package Manager from https://github.com/AudDMusic/audd-swift.

// After — AudD: send a clip, get the match back over HTTP
import AudD
import Foundation

let audd = try AudD(apiToken: "your-api-token")  // get a token at dashboard.audd.io

func identify(clip: URL) async throws {
    // Ask for the provider blocks you actually render.
    let result = try await audd.recognize(
        .file(clip),
        returnMetadata: ["apple_music", "spotify"]
    )

    if let r = result {
        print("\(r.artist ?? "?") — \(r.title ?? "?")")
        print("Apple Music:", r.streamingUrl(.appleMusic) ?? "-")
        print("Universal link:", r.songLink ?? "-")
        print("Cover art:", r.thumbnailURL ?? "-")
    } else {
        print("no match")  // a clean no-match, distinct from an error
    }
}

recognize returns RecognitionResult? — nil when the clip processed but matched nothing, which the API sends as result: null. The standard endpoint responds in under 2 seconds, accepts a short clip up to 10 MB, and matches against AudD’s 160-million-song database. A 5–15 second clip is plenty.

Hold the token on your backend for shipping apps. A bundled iOS app can call api.audd.io directly, but the api_token would then live in the app binary where it can be extracted. For production, route recognition through your own backend and keep the token server-side; the device uploads the clip to you, and you call AudD.

Custom catalog

ShazamKit’s SHCustomCatalog lets you match against reference signatures you generate from your own recordings on-device. AudD’s equivalent is a custom catalog you upload to your account; later recognize calls on that account match against your tracks in addition to (or instead of) the public database. A custom-catalog match carries audio_id (your reference to the uploaded track), and artist/title may be null if you didn’t supply them at upload time. Fields the SDK doesn’t model as typed properties are available via result.extras or the full result.rawResponse.

Custom-catalog access is gated — email [email protected] to enable it for your account, then upload via POST api.audd.io/upload/.

What’s different

Where matching runs. ShazamKit matches on-device. AudD matches server-side over an HTTP call. On-device matching works offline and keeps audio on the device; a server API requires a network round trip but runs identically from any platform and centralizes the catalog.
Platform reach. ShazamKit is an Apple framework for Apple platforms (iOS, macOS, watchOS, tvOS, visionOS) plus an Android variant. AudD is a language-agnostic HTTP API with 11 official SDKs (Python, Node, Go, Rust, PHP, Swift, Kotlin, .NET, Java, C, C++), so the same recognition contract is callable from your iOS app, your Android app, and your server.
What you match against. ShazamKit matches against Apple’s Shazam catalog or a custom catalog you build from reference signatures. AudD matches against its 160-million-song managed database, a custom catalog you upload, or both.
No client-side signature step. ShazamKit asks you to generate a signature from captured audio before matching. With AudD you send the audio (URL, file path, or bytes) and the fingerprinting is done server-side.
Long audio and live streams. ShazamKit is oriented around matching a captured sample. AudD additionally offers an enterprise endpoint that chunks long files (full songs, podcasts, DJ sets, broadcasts) and returns every match, and streams endpoints that recognize live broadcasts and POST matches to a callback.
Metadata fields. AudD returns artist, title, album, releaseDate, label, timecode, songLink, and — on enterprise calls or Startup-plan-and-above accounts — isrc and upc. Provider blocks (apple_music, spotify, deezer, musicbrainz) are returned only when requested via return.
Pricing. AudD’s per-request pricing is public: 300 free requests on signup (no card), then $5 per 1,000 requests pay-as-you-go, with volume plans on the dashboard.

Migration steps

Decide where the call runs. For a shipping app, plan to route recognition through your backend so the api_token stays server-side. For a prototype, the SDK can call api.audd.io directly with the test token (10 requests/day, standard endpoint only).
Get an AudD token. Sign up at dashboard.audd.io and copy the api_token.
Add the SDK. In Xcode, File → Add Package Dependencies… and paste https://github.com/AudDMusic/audd-swift. Add the AudD product to your target.
Replace the capture-and-match flow. Swap the SHSignatureGenerator / SHSession path for recording a short clip (e.g. with AVAudioRecorder) and calling try await audd.recognize(.file(clip)).
Re-map the result. Point UI code at RecognitionResult fields (artist, title, album, songLink, thumbnailURL, provider links via streamingUrl(_:)). Add an explicit nil (no-match) branch.
Move your custom catalog, if any. If you matched against an SHCustomCatalog, request custom-catalog access (email [email protected]) and upload your reference tracks via POST api.audd.io/upload/.
Verify with a fixed input. Run https://audd.tech/example.mp3 through the migrated path and confirm the fields you render are present before switching real traffic over.

Related