ShazamKit Reference
An API reference for ShazamKit, which recognizes audio against Shazam's music catalog or against a custom catalog you build. It covers the iOS 17 SHManagedSession, which records for you, and the iOS 15 SHSession for buffer-level control, plus catalogs, signatures, the user's Shazam library, and the shazam command-line tool.
When to Use This Reference
Use this reference when:
- Looking up
SHManagedSessioninitializers, methods (prepare(),result(),results,cancel()), or state cases (.idle,.prerecording,.matching) - Working with
SHSessionfor buffer-level matching (iOS 15+, with your ownAVAudioEnginecapture) ormatchStreamingBuffer(_:at:)for streaming audio - Building a custom catalog (
SHCustomCatalog) fromSHMediaItemandSHSignaturepairs, loading a.shazamcatalogfile, or serializing a catalog withdataRepresentation - Generating signatures with
SHSignatureGenerator, fromAVAudioPCMBufferchunks finished withsignature()or from a wholeAVAsset - Defining custom
SHMediaItemPropertykeys for app-specific metadata on matched items - Reading match-specific properties (
matchOffset,predictedCurrentMatchOffset,frequencySkew,confidence) fromSHMatchedMediaItem - Managing the user's Shazam library with
SHLibrary(iOS 17+ — add, read, and delete) or the legacy write-onlySHMediaLibrary(add) - Looking up
SHErrorcodes and their meanings - Using the
shazamcommand-line tool to generate signatures and catalogs offline, at scale
Example Prompts
Questions you can ask your assistant that will draw from this reference:
- "What's the API signature for
SHManagedSession.result()and what does the return type look like?" - "How do I use
SHSession.matchStreamingBufferand what's theat:parameter for?" - "What properties does
SHMatchedMediaItemadd on top ofSHMediaItem?" - "How do I define a custom
SHMediaItemPropertyfor my podcast episode number?" - "What's the difference between
SHLibraryandSHMediaLibrary?" - "What does
SHError.Code.audioDiscontinuitymean, and how do I avoid it?" - "How do I generate signatures from audio files at scale with the CLI?"
- "Can I match against both the Shazam catalog and a custom catalog from one session?"
What's Covered
SHManagedSession(iOS 17+) – initializer overloads (Shazam catalog vs custom catalog), single-shotresult() async,resultsAsyncSequencefor continuous matching,prepare() asyncfor pre-recording,cancel()to stop,Observableconformance and thestateproperty with.idle/.prerecording/.matchingcases,SendableconformanceSHSession(iOS 15+) – initializer overloads,match(_:)for complete signatures,matchStreamingBuffer(_:at:)for streaming audio (with the contiguous-audio validation),delegatefor callback-based delivery,resultsAsyncSequence(iOS 16+), audio format support on iOS 15–16 (specific PCM formats) vs iOS 17+ (automatic conversion), multiple-match behavior on iOS 17+SHSession.Result(iOS 16+) –.match(SHMatch)/.noMatch(SHSignature)/.error(any Error, SHSignature)SHSessionDelegate–session(_:didFind:)andsession(_:didNotFindMatchFor:error:)optional methodsSHMatch–mediaItemsarray ofSHMatchedMediaItemandquerySignatureSHMediaItem– properties dictionary keyed bySHMediaItemProperty, predefined keys (.title,.subtitle,.artist,.artworkURL,.videoURL,.genres,.explicitContent,.ISRC,.appleMusicID,.appleMusicURL,.webURL,.shazamID,.creationDate), iOS 16+ timed content properties (.timeRanges,.frequencySkewRanges), custom property extension pattern,fetch(shazamID:)class method, subscript access,Identifiable(iOS 17+) /SendableconformancesSHMatchedMediaItem– match-only additions:.matchOffset,.predictedCurrentMatchOffset(auto-updating during streaming),.frequencySkew,.confidence(0.0 to 1.0, iOS 18.4+)SHMediaItemProperty–RawRepresentablestruct for predefined and custom property keys, complete list of predefined keys, custom extension patternSHSignature–duration,dataRepresentationfor storage/transmission,init(dataRepresentation:)throwing initializer,slices(from:duration:stride:)for segmenting (iOS 18+)SHSignatureGenerator–append(_:at:)forAVAudioPCMBufferchunks,signature()to finalize,signature(from:)for anAVAsset(iOS 16+)SHCatalogandSHCustomCatalog–minimumQuerySignatureDuration/maximumQuerySignatureDuration,addReferenceSignature(_:representing:),dataRepresentationandinit(dataRepresentation:)(iOS 18+),add(from:)for.shazamcatalogfiles,write(to:)(deprecated in iOS 18)SHLibrary(iOS 17+) and the legacySHMediaLibrary–SHLibraryadds, reads, and deletes the items your app added, syncing through iCloud;SHMediaLibraryis write-only and accepts only Shazam catalog itemsSHErrorcodes – matching, catalog, signature, media library, and session errors- Audio format requirements – what formats
SHSessionaccepts on iOS 15–16 vs iOS 17+, format conversion responsibilities shazamCLI (macOS 13+) –shazam signatureand theshazam custom-catalogsubcommands (create,update,display,remove,export) for offline signature generation and catalog construction- Quick reference – class hierarchy, common-task table,
.shazamsignatureand.shazamcatalogfile extensions, and Apple's two sample projects
Documentation Scope
This page documents the shazamkit-ref skill (in the axiom-media suite), the API lookup half of the ShazamKit pair. Choosing between the two session APIs, the setup checklist, the ShazamKit App Service that Shazam catalog matching needs, and common mistakes live in the shazamkit skill listed under Related.
Related
- ShazamKit – which session API to use, the setup checklist, and why Shazam catalog matching silently returns nothing without the ShazamKit App Service
- Privacy UX – asking for microphone access (
NSMicrophoneUsageDescription) at the right moment - Now Playing – Lock Screen metadata and MusicKit playback when your app plays a matched song
- AVFoundation Reference – the
AVAudioEnginecapture that feedsAVAudioPCMBuffers toSHSession
Resources
WWDC: 2021-10044, 2021-10045, 2022-10028, 2023-10051
Docs: /shazamkit, /shazamkit/shmanagedsession, /shazamkit/shsession, /shazamkit/shcustomcatalog, /shazamkit/shmediaitem, /shazamkit/shlibrary