Skip to content

Latest commit

 

History

History
161 lines (108 loc) · 5.25 KB

README.md

File metadata and controls

161 lines (108 loc) · 5.25 KB
Raw

ChromaSwift

Platform Swift SPM Unit Tests codecov

Swift wrapper for Chromaprint, the audio fingerprint library of the AcoustID project

Installation

Add https://github.com/wallisch/ChromaSwift as SwiftPM dependency and import ChromaSwift

Usage

Generating fingerprints

Generate fingerprint of a file containing an audio track by URL. This also works for video files (e.g. music videos)

let fileURL = URL(fileURLWithPath: "Test.mp3")
let testFingerprint = try AudioFingerprint(from: fileURL)

Optionally, specify the AudioFingerprintAlgorithm (Default: .test2)

You can remove leading silence with.test4

Warning: Only .test2 fingerprints can be looked up at the AcoustID service

let testFingerprint = try AudioFingerprint(from: fileURL, algorithm: .test4)

And / Or the maximum duration to sample in seconds (Default: 120). Pass nil to sample the entire file

let testFingerprint = try AudioFingerprint(from: fileURL, maxSampleDuration: 10.0)

Handling fingerprints

Get the algorithm that was used to generate the fingerprint

let algorithm = testFingerprint.algorithm // AudioFingerprint.Algorithm.test2

Get the duration of the entire file in seconds

let duration = testFingerprint.duration // 46.0

Get the fingerprint in its raw form as an array of unsigned 32 bit integers

let rawFingerprint = testFingerprint.raw // [4107342261, 4107276695, ... ]

Get the fingerprint as base64 representation

let base64FingerprintString = testFingerprint.base64 // "AQABYJGikFSmJBCPijt6Hq..."

Get the fingerprints hash as binary string

let binaryHashString = testFingerprint.hash // "01110100010011101010100110100100"

Instantiate a fingerprint object from its raw form, algorithm and and entire file duration

let newFingerprint = AudioFingerprint(from: rawFingerprint, algorithm: .test2, duration: duration)

Instantiate a fingerprint object from its base64 representation and entire file duration

let newFingerprint = try AudioFingerprint(from: base64FingerprintString, duration: duration)

Get similarity to other fingerprint object (0.0 to 1.0)

let similarity = try newFingerprint.similarity(to: testFingerprint) // 1.0

Optionally, ignore sample duration differences greater than 20% between fingerprints (Default: false)

This is useful if you want to e.g. check if a a longer mix contains a specific track

Warning: This can lead to wrong results when comparing with Fingerprints sampled for a very short duration

try newFingerprint.similarity(to: testFingerprint, ignoreSampleDuration: true) // 1.0

You can also get the similarity to a fingerprint hash

Warning: This is less accurate than comparing fingerprint objects, especially if the algorithms don't match

try newFingerprint.similarity(to: binaryHashString) // 1.0

Looking up fingerprints

Init the service with your AcoustID API key

let acoustID = AcoustID(apiKey: "zfkYWDrOqAk")

Optionally, specify a timeout in seconds (Default: 3.0)

let acoustID = AcoustID(apiKey: "zfkYWDrOqAk", timeout: 10.0)

Lookup an AudioFingerprint object

do {
    let results = try await acoustID.lookup(newFingerprint)
    // [AcoustID.APIResult]
    for result in results {
        // Matching score (0.0 to 1.0)
        let score = result.score
        for recording in result.recordings! {
            // Song title
            let title = recording.title
            // Song artists
            let artists = recording.artists
            // Song release groups (Albums, Singles, etc.)
            let releasegroups = recording.releasegroups
        }
    }
} catch {
    // AcoustID.Error
}

Handling errors

The AudioFingerprint class throws either AudioDecoder.Error or AudioFingerprint.Error errors, the AcoustID class throws AcoustID.Error errors.

Accessing Chromaprints C API

You can also import CChromaprint to directly interact with Chromaprints C interface. Please refer to the official documentation for further information.

Note: To avoid licensing issues, CChromaprint has internal input resampling disabled and thus requires that input audio for the fingerprinter is already at the configured fingerprint sample rate.

Licensing

This package is distributed under the MIT license, see the LICENSE file for details.

The chromaprint project by default includes resampling code from the ffmpeg library, which is licensed under LGPL 2.1. ChromaSwift however uses Apples AVFoundation for resampling and removes all ffmpeg code from the build, making the package fully MIT compliant.