PHPackages mrfeathers/acoustid - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. mrfeathers/acoustid ActiveLibrary[API Development](/categories/api) mrfeathers/acoustid =================== Object Oriented PHP Wrapper for acoustid.org API 1.0.2(8y ago)5753MITPHPPHP >=7.1 Since Jan 19Pushed 8y ago2 watchersCompare [ Source](https://github.com/mrfeathers/acoustid)[ Packagist](https://packagist.org/packages/mrfeathers/acoustid)[ RSS](/packages/mrfeathers-acoustid/feed)WikiDiscussions master Synced 2mo ago READMEChangelog (3)Dependencies (7)Versions (5)Used By (0) AcoustId API Wrapper ==================== [](#acoustid-api-wrapper) [![Build Status](https://camo.githubusercontent.com/ca55a191f3e3f75b998ff78f4f098dca1413129811851eb02781c06f7a7fef27/68747470733a2f2f7472617669732d63692e6f72672f6d7266656174686572732f61636f75737469642e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/mrfeathers/acoustid)[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE) This package is an object oriented PHP wrapper for [acoustid.org API](https://acoustid.org/webservice). Installation ------------ [](#installation) Just require this package using [Composer](https://getcomposer.org/): ``` composer require mrfeathers/acoustid ``` Usage ----- [](#usage) Create an instance of `AcoustIdClient`: ``` $apiKey = 'here is your api key'; $acoustidClient = AcoustidFactory::create($apiKey); ``` > Also, you can create client without api key. In this case, you are able to use `listByMBId` method, that doesn't need api key. All other methods throws an exception in this case. **Now you're ready!** So, acoustid.org has some available actions, that are represented in the package client: - **Lookup by fingerprint** If you have an audio fingerprint generated by [Chromaprint](https://acoustid.org/chromaprint), you can use this method to lookup the MusicBrainz metadata associated with this fingerprint. ``` $fingerPrintContent = 'fingerprint string generated by Chromaprint'; $fingerPrintDuration = 100; //meta can be empty, it's not required $meta = [ Meta::RECORDINGS, Meta::RELEASES, ]; $resultCollection = $acoustidClient->lookupByFingerPrint($fingerPrintContent, $fingerPrintDuration, $meta); ``` You will get an instance of class `ResultCollection`, contains several (or one) objects of `Result` class. `ResultCollection` is iterable, so you can just use it as array: ``` foreach($resultCollection as $result) { //do something } ``` - **Lookup by track id** You can also look up data connected to a track ID, witch is a cluster of fingerprints. ``` //track id is a simple uuid string $trackId = '08268577-90f3-4ed5-8154-5768e2091554'; //meta can be empty, it's not required $meta = [ Meta::RECORDINGS, Meta::RELEASES, ]; $resultCollection = $acoustidClient->lookupByTrackId($trackId, $meta); ``` The result also will be `ResultCollection`. - **Submit fingerprint** The AcoustID database depends on user-submitted content. This method can be used to submit new audio fingerprints and their corresponding metadata to the database. Multiple fingerprints can be submitted in one call. Submissions are processed asynchronously by a background job. However, this normally only takes a few seconds, so if your application needs to get the imported AcoustIDs back, you can use the wait parameter to `wait` until the submissions are imported. It is not guaranteed that the submissions will be imported on time, so your application must be able to handle the case when the submission is still in the "pending" status. You can look up the status of the pending submissions later (use method `getSubmissionStatus`). While you can submit a fingerprint without any metadata, it is not very useful to do so. If the file has embedded MusicBrainz tags, please send the MusicBrainz recording ID. Otherwise you can send the textual metadata. Use `FingerPrintCollection` instance as argument. This class is just a wrapper under array of [`FingerPrint`](/doc/Fingerprint.md) objects. ``` //create collection of fingerprints $fingerPrintCollection = new FingerPrintCollection([ new FingerPrint('fingerprint string generated by Chromaprint', 100), new FingerPrint('fingerprint string generated by Chromaprint', 121), ]); //also you can add FingerPrint later by addFingerPrint method $fingerPrint = new FingerPrint('....', 200); //FingerPrint object has a lot of additional fields, that you can set calling setters $fingerPrint->setArtist('artist name') ->setAlbum('album name'); $fingerPrintCollection->addFingerPrint($fingerPrint); $userApiKey = 'here is your personal user key'; //wait is not required and equls 1 by default. Use it if you need to wait until the submissions are imported $wait = 1; $submissionCollection = $acoustidClient->submit($fingerPrintCollection, $userApiKey, $wait); ``` You will get an instance of `SubmissionCollection` as a result. It's also iterable and contains one or more `Submission` objects. - **Get submission status** If you submitted an fingerprint and it was imported immediately, you can check the status of the submission by looking up the ID from the `submit` call. ``` //let's get submisstionCollection from the previous example $submission = array_shift($submissionCollection); $result = $acoustidClient->getSubmissionStatus($submission->getId()); ``` The result also will be an instance of `SubmissionCollection`. - **List AcoustIDs by MBID** This method will return you a list of AcoustId id that are corresponding to MusicBrainz id. > Api key is not required for this method, so you can use client without key to call it You can send one or more mbids. If you send one, than you'll get the result as instance of `TrackCollection`. If you send more than one - instance of `MBIdCollection`. Both are iterable. ``` $mbids = ['83b3d37d-8c3d-4a7b-ae9a-d635e4e3374f']; $trackCollection = $acoustidClient->listByMBId($mbids); //add one more mbid $mbids[] = 'b00db402-51d2-4125-912b-c0eab9c6edd1'; //and you'll get MBIdCollection, each MBId object for each sent mbid $mbidCollection = $acoustidClient->listByMBId($mbids); ``` Response models and Meta ------------------------ [](#response-models-and-meta) Response models contain all known fields acoustid.org API can return. Unfortunately, acoustid.org doesn't have a full documentation for all possible response structures. So if you get an `AcoustidSerializerException` exception, please [open an issue](https://github.com/MrFeathers/acoustid/issues/new) and provide method and parameters you used to call it. Here's the descriptions of all response models: - [Artist](doc/Artist.md) - [Date](doc/Date.md) - [MBId](doc/MBId.md) - [Medium](doc/Medium.md) - [Recording](doc/Recording.md) - [Release](doc/Release.md) - [ReleaseEvent](doc/ReleaseEvent.md) - [Result](doc/Result.md) - [Submission](doc/Submission.md) - [Track](doc/Track.md) Collection response models: - [MBIdCollection](doc/Collection/MBIdCollection.md) - [ResultCollection](doc/Collection/ResultCollection.md) - [SubmissionCollection](doc/Collection/SubmissionCollection.md) - [TrackCollection](doc/Collection/TrackCollection.md) > **NB!** Response models has a lot of fields, but some of them can be empty. It's because of scope of meta parameters you send to the method. Different scope of meta values can return different results. All available meta values you can find in the class `Meta`. It's highly recommended to use constants from `Meta` class for creating meta array. ### Health Score 30 — LowBetter than 64% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity16 Limited adoption so far Community10 Small or concentrated contributor base Maturity61 Established project with proven stability Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~24 days Total 3 Last Release 2989d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/bb267a69bf86562da9b3c347e61a4480284b8b9cc6adf402dd19a9fff48c4f77?d=identicon)[MrFeathers](/maintainers/MrFeathers) --- Top Contributors [![mrfeathers](https://avatars.githubusercontent.com/u/1404970?v=4)](https://github.com/mrfeathers "mrfeathers (27 commits)") --- Tags acoustidaudio-fingerprintsfingerprintlookupmetadataphpapilibrarymusicFingerprintacoustid ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/mrfeathers-acoustid/health.svg) ``` [![Health](https://phpackages.com/badges/mrfeathers-acoustid/health.svg)](https://phpackages.com/packages/mrfeathers-acoustid) ``` ### Alternatives [sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.4k5.6M651](/packages/sylius-sylius)[checkout/checkout-sdk-php Checkout.com SDK for PHP 553.3M7](/packages/checkout-checkout-sdk-php)[api-platform/symfony Symfony API Platform integration 323.2M67](/packages/api-platform-symfony)[api-platform/serializer API Platform core Serializer 223.4M31](/packages/api-platform-serializer)[getjump/vk Library for work with API Vk.com 19948.5k](/packages/getjump-vk)[fingerprint/fingerprint-pro-server-api-sdk Fingerprint Server API provides a way for validating visitors’ data issued by Fingerprint Pro. 30223.1k1](/packages/fingerprint-fingerprint-pro-server-api-sdk) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)