ShazamKit (shazam_kit v0.2.0)

Copy Markdown View Source

Elixir client for the ShazamKit API.

ShazamKit allows you to match audio signatures against Shazam's vast music catalog. Use it to:

  • Identify songs from audio fingerprints
  • Build custom audio recognition features
  • Match user-generated audio against the Shazam database

Quick Start

# Match a pre-generated audio signature
ShazamKit.match_signature(signature_data)

# Search Shazam catalog by ISRC
ShazamKit.search_by_isrc("USUG12002836")

Configuration

config :shazam_kit,
  team_id: System.get_env("APPLE_TEAM_ID"),
  key_id: System.get_env("SHAZAM_KEY_ID"),
  private_key: System.get_env("SHAZAM_PRIVATE_KEY"),
  base_url: "https://api.shazam.com"

Audio Signatures

Audio signatures (fingerprints) must be generated on the client side using:

  • iOS: SHSignatureGenerator from ShazamKit framework
  • Android: Shazam SDK
  • Custom implementation following Shazam's signature format

The signature is a binary blob that ShazamKit uses to match against its catalog.

Summary

Types

opts()
response()

Functions

get_chart(opts \\ [])

Get the Shazam chart (most popular tracks).

get_track(track_id, opts \\ [])

Get detailed information about a track by its Shazam ID.

list_cities(opts \\ [])

List available chart cities.

match_signature(signature, opts \\ [])

Match an audio signature against the Shazam catalog.

search_by_isrc(isrc, opts \\ [])

Search the Shazam catalog by ISRC (International Standard Recording Code).

search_tracks(query, opts \\ [])

Search for tracks by artist and title.

token(opts \\ [])

Return a cached ShazamKit access token (after JWT generation).

valid_signature?(signature)

Validate if a signature format is valid (basic validation).

Types

opts()

@type opts() :: keyword()

response()

@type response() :: {:ok, map()} | {:error, term()}

Functions

get_chart(opts \\ [])

@spec get_chart(opts()) :: response()

Get the Shazam chart (most popular tracks).

Parameters

  • opts:
    • :city_id - City ID for local charts (optional)
    • :limit - Maximum results (default 10)

Examples

ShazamKit.get_chart()
ShazamKit.get_chart(city_id: "12345", limit: 20)

get_track(track_id, opts \\ [])

@spec get_track(String.t(), opts()) :: response()

Get detailed information about a track by its Shazam ID.

Parameters

  • track_id: Shazam track identifier

Examples

ShazamKit.get_track("548587123")

list_cities(opts \\ [])

@spec list_cities(opts()) :: response()

List available chart cities.

Examples

ShazamKit.list_cities()

match_signature(signature, opts \\ [])

@spec match_signature(String.t() | binary(), opts()) :: response()

Match an audio signature against the Shazam catalog.

Parameters

  • signature: Audio signature data (base64 encoded string or binary)
  • opts:
    • :raw_audio - Set to true if signature is raw audio data (signature will be generated server-side)
    • :limit - Maximum results (default 1)

Returns

  • {:ok, %{"matches" => [%{"track" => track_data}]}} - Match found
  • {:ok, %{"matches" => []}} - No match found
  • {:error, %ShazamKit.Error{}} - API error

Examples

signature = "AQAsFU4eASQ..."  # base64 encoded signature from iOS ShazamKit
ShazamKit.match_signature(signature)

Notes

Audio signatures should be generated using Apple's ShazamKit framework on iOS, or the Shazam SDK on other platforms. The signature format is proprietary to Shazam.

search_by_isrc(isrc, opts \\ [])

@spec search_by_isrc(String.t(), opts()) :: response()

Search the Shazam catalog by ISRC (International Standard Recording Code).

Parameters

  • isrc: ISRC code (e.g., "USUG12002836")

Examples

ShazamKit.search_by_isrc("USUG12002836")

search_tracks(query, opts \\ [])

@spec search_tracks(String.t(), opts()) :: response()

Search for tracks by artist and title.

Parameters

  • query: Search query (artist name, track title, or both)
  • opts:
    • :limit - Maximum results (1-50, default 10)
    • :offset - Pagination offset

Examples

ShazamKit.search_tracks("The Beatles Yesterday")
ShazamKit.search_tracks("Billie Eilish", limit: 5)

token(opts \\ [])

@spec token(opts()) :: {:ok, String.t()} | {:error, term()}

Return a cached ShazamKit access token (after JWT generation).

valid_signature?(signature)

@spec valid_signature?(String.t()) :: boolean()

Validate if a signature format is valid (basic validation).

Examples

ShazamKit.valid_signature?("AQAsFU4eASQ...")