Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/hitenpatel/songprint/llms.txt

Use this file to discover all available pages before exploring further.

By the end of this guide you will have songprint added to your project, a raw PCM buffer converted to the format the library expects, a binary Shazam-compatible signature generated entirely on-device, and an identification result returned from the public discovery endpoint — all without an API key or any native code.
10–12 seconds of audio produces the most reliable matches. Shorter clips do work, but the probability of a correct identification drops with less audio. Aim for at least 10 seconds when you can control the capture window.
1

Add the JitPack repository

songprint is distributed via JitPack. Add the JitPack Maven repository to your build.gradle.kts:
repositories {
    maven("https://jitpack.io")
}
2

Add the dependency

Declare the songprint dependency in your dependencies block:
dependencies {
    implementation("com.github.hitenpatel:songprint:0.1.0")
}
Sync your project and the library is ready to use. There are no transitive runtime dependencies to resolve.
3

Import the classes

songprint exposes three public types. Import all three at the top of your file:
import io.github.hitenpatel.songprint.Pcm
import io.github.hitenpatel.songprint.SignatureGenerator
import io.github.hitenpatel.songprint.RecognitionClient
  • Pcm — static utilities for decoding and resampling raw PCM audio
  • SignatureGenerator — produces the binary fingerprint from 16 kHz mono samples
  • RecognitionClient — posts the fingerprint to the Shazam discovery endpoint
4

Prepare your PCM audio

SignatureGenerator requires 16 kHz mono 16-bit PCM as a ShortArray. Use the two Pcm helpers to get there from any common source format.
// Decode raw 16-bit little-endian PCM bytes into a ShortArray
val samples = Pcm.bytesToShorts(pcmBytes)

// Resample and downmix: here from 44.1 kHz stereo to 16 kHz mono
val mono16k = Pcm.resampleToMono16k(samples, 44100, 2)
bytesToShorts interprets every two bytes as one little-endian signed 16-bit sample. resampleToMono16k averages all channels to produce mono, then applies linear-interpolation resampling to reach 16 000 Hz. Pass the actual sample rate and channel count of your source audio as the second and third arguments.
5

Generate the signature

Pass the prepared ShortArray to SignatureGenerator.generateSignature. It returns a ByteArray containing the complete binary signature — header, CRC32, and delta-encoded peak data included.
val signature = SignatureGenerator().generateSignature(mono16k)
Generation is pure Kotlin and completes in a few milliseconds for a typical 10–12 second clip. generateSignature resets all internal state at the start of each call, so the same SignatureGenerator instance can be reused across multiple clips. Note that SignatureGenerator is not thread-safe — use one instance per thread.
6

Identify the song

Pass the signature and the number of 16 kHz mono samples to RecognitionClient.recognise. It returns the raw JSON response body as a String, or null if the endpoint returned a non-200 status.
val json = RecognitionClient().recognise(signature, mono16k.size)
Parse json with whichever JSON library you already use. The response contains a track object with the following fields of interest:
FieldContent
track.titleSong title
track.subtitleArtist name
track.images.coverartCover art image URL
track.share.hrefShazam link for the track
A null return value means either no match was found or the request failed. Check track for existence before reading its fields — a successful HTTP response may still carry an empty match.
RecognitionClient uses the unofficial, undocumented Shazam discovery endpoint at https://amp.shazam.com/discovery/v5/en/GB/android/-/tag. This endpoint has been stable for years and is used by projects such as SongRec, but it is not a public API and may change or become unavailable without notice. Do not rely on it for production workloads, high request volumes, or any context where an unexpected outage would cause a problem.

​
Next Steps

PCM Preparation

Capture audio from the microphone or a media file and feed it to songprint correctly.

Recognition

Handle match results, parse the full JSON response, and deal with no-match cases.

SignatureGenerator API

Full reference for SignatureGenerator, Pcm, and RecognitionClient.

Algorithm

Understand the spectrogram, peak-spreading, banding, and binary encoding pipeline.

Build docs developers (and LLMs) love

Get started for freeTalk to us