README

此软件包是acoustid.org API的面向对象PHP包装器。

安装

使用Composer要求此软件包

composer require mrfeathers/acoustid

使用方法

创建一个AcoustIdClient实例

$apiKey = 'here is your api key';
$acoustidClient = AcoustidFactory::create($apiKey);

您还可以不使用API密钥创建客户端。在这种情况下，您可以使用不需要API密钥的listByMBId方法。在这种情况下，所有其他方法都会抛出异常。

现在您已经准备好了！

因此，acoustid.org有一些可用的操作，这些操作在软件包客户端中得到了表示

通过指纹查找

如果您有由Chromaprint生成的音频指纹，您可以使用此方法查找与该指纹关联的MusicBrainz元数据。

$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);

您将得到一个ResultCollection类的实例，其中包含几个（或一个）Result类的对象。ResultCollection是可迭代的，因此您可以将其用作数组

foreach($resultCollection as $result) {
   //do something
}

通过曲目ID查找

您还可以查找与曲目ID相关的数据，该ID是一组指纹。

 //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);

结果也将是ResultCollection。

提交指纹

AcoustID数据库依赖于用户提交的内容。此方法可用于将新的音频指纹及其对应的元数据提交到数据库。可以一次性提交多个指纹。

提交异步由后台作业处理。然而，这通常只需要几秒钟，因此如果您的应用程序需要获取导入的AcoustID，您可以使用wait参数来等待提交导入。无法保证提交会按时导入，因此您的应用程序必须能够处理提交仍然处于“待处理”状态的情况。您可以在以后查找待处理提交的状态（使用方法getSubmissionStatus）。

虽然您可以在没有任何元数据的情况下提交指纹，但这样做并不很有用。如果文件中嵌入有MusicBrainz标签，请发送MusicBrainz录制ID。否则，您可以发送文本元数据。

将FingerPrintCollection实例作为参数。此类只是FingerPrint对象数组的包装器。

//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);

您将得到一个包含一个或多个Submission对象的SubmissionCollection实例作为结果。它也是可迭代的。

获取提交状态

如果您提交了一个指纹并且它已被立即导入，您可以通过从submit调用中查找ID来检查提交的状态。

//let's get submisstionCollection from the previous example
$submission = array_shift($submissionCollection);

$result = $acoustidClient->getSubmissionStatus($submission->getId());

结果也将是一个SubmissionCollection实例。

通过MBID列出AcoustID

此方法将返回与MusicBrainz ID相对应的AcoustId ID列表。

此方法不需要API密钥，因此您可以使用带键的客户端调用它

您可以发送一个或多个mbid。如果您发送一个，则结果将作为TrackCollection实例。如果您发送多个，则结果将作为MBIdCollection实例。两者都是可迭代的。

$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);

响应模型和元数据

响应模型包含 acoustid.org API 可以返回的所有已知字段。不幸的是，acoustid.org 没有所有可能响应结构的完整文档。所以，如果您遇到 AcoustidSerializerException 异常，请创建一个新问题并提供调用该方法的方法和参数。

以下是所有响应模型的描述

集合响应模型

注意！ 响应模型包含许多字段，但其中一些可能为空。这是因为您发送给方法的元参数的范围。不同的元值范围可以返回不同的结果。您可以在 Meta 类中找到所有可用的元值。强烈建议使用 Meta 类的常量来创建元数组。

mrfeathers/ acoustid

维护者

详细信息

README

安装

使用方法

响应模型和元数据