https://github.com/wallisch/chromaswift
Swift wrapper for Chromaprint, the audio fingerprint library of the AcoustID project
https://github.com/wallisch/chromaswift
acoustid audio audio-analysis audio-fingerprinting audio-processing chromaprint music spm swift
Last synced: 8 months ago
JSON representation
Swift wrapper for Chromaprint, the audio fingerprint library of the AcoustID project
- Host: GitHub
- URL: https://github.com/wallisch/chromaswift
- Owner: wallisch
- License: mit
- Created: 2021-06-11T23:53:47.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2025-09-18T21:08:34.000Z (9 months ago)
- Last Synced: 2025-10-21T07:53:58.294Z (8 months ago)
- Topics: acoustid, audio, audio-analysis, audio-fingerprinting, audio-processing, chromaprint, music, spm, swift
- Language: Swift
- Homepage:
- Size: 7 MB
- Stars: 20
- Watchers: 3
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ChromaSwift
[](https://swift.org/)
[](https://swift.org/package-manager/)
[](https://github.com/wallisch/ChromaSwift/actions/workflows/unit_tests.yml)
[](https://codecov.io/gh/wallisch/ChromaSwift)
Swift wrapper for [Chromaprint](https://github.com/acoustid/chromaprint), the audio fingerprint library of the [AcoustID](https://acoustid.org/) 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)
``` swift
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*
``` swift
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
``` swift
let testFingerprint = try AudioFingerprint(from: fileURL, maxSampleDuration: 10.0)
```
### Handling fingerprints
Get the algorithm that was used to generate the fingerprint
``` swift
let algorithm = testFingerprint.algorithm // AudioFingerprint.Algorithm.test2
```
Get the duration of the entire file in seconds
``` swift
let duration = testFingerprint.duration // 46.0
```
Get the fingerprint in its raw form as an array of unsigned 32 bit integers
``` swift
let rawFingerprint = testFingerprint.raw // [4107342261, 4107276695, ... ]
```
Get the fingerprint as base64 representation
``` swift
let base64FingerprintString = testFingerprint.base64 // "AQABYJGikFSmJBCPijt6Hq..."
```
Get the fingerprints hash as binary string
``` swift
let binaryHashString = testFingerprint.hash // "01110100010011101010100110100100"
```
Instantiate a fingerprint object from its raw form, algorithm and and entire file duration
``` swift
let newFingerprint = AudioFingerprint(from: rawFingerprint, algorithm: .test2, duration: duration)
```
Instantiate a fingerprint object from its base64 representation and entire file duration
``` swift
let newFingerprint = try AudioFingerprint(from: base64FingerprintString, duration: duration)
```
Get similarity to other fingerprint object (`0.0` to `1.0`)
``` swift
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*
``` swift
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*
``` swift
try newFingerprint.similarity(to: binaryHashString) // 1.0
```
### Looking up fingerprints
Init the service with your AcoustID API key
``` swift
let acoustID = AcoustID(apiKey: "zfkYWDrOqAk")
```
Optionally, specify a timeout in seconds (Default: `3.0`)
``` swift
let acoustID = AcoustID(apiKey: "zfkYWDrOqAk", timeout: 10.0)
```
Lookup an AudioFingerprint object
``` swift
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.