CocoaLibSpotify 2.4.5

CocoaLibSpotify 2.4.5

×

测试已测试✗
Lang语言 Obj-CObjective C
许可证 BSD 3.0
发布最后发布2014年12月

由 未声明的 维护。

CocoaLibSpotify 2.4.5

  • 由
  • Spotify

CocoaLibSpotify 是围绕我们的 libspotify 库的 Objective-C 包装器。它通过友好、KVC/O 符合的 Objective-C 包装器轻松访问 libspotify 的功能。

CocoaLibSpotify 需要 libspotify.framework，它不包括在存储库中。Mac 框架和 iOS 库 Xcode 项目包括一个构建步骤，用于自动从 developer.spotify.com 下载并解压它。如果由于某些原因失败，请从 developer.spotify.com 手动下载并解压到项目文件夹中。

发布说明

您可以在 CHANGELOG.markdown 文件中找到最新的发布说明。

线程

从 CocoaLibSpotify 2.0 开始，框架使用内部线程模型在后台线程上运行 libSpotify 库，允许您的应用程序在 libSpotify 经历大量负载时保持响应。

但是，libSpotify 是 非线程安全 的，CocoaLibSpotify 中所有提供对 libSpotify 类型访问的方法都被保护起来，以防止从错误的线程访问。如果您必须直接访问 libSpotify 类型，首先提交一个问题，以便我们可以在 CocoaLibSpotify 中为您的用例创建一个线程感知的 API，然后确保您在正确的线程上调用相关的 API，SPSession 提供了各种辅助宏来实现这一点。

错误

sp_artist *artist = …; // An artist.
SPArtist *artistObj = [SPArtist artistWithArtistStruct:artist inSession:session];
// ^ The above line will throw an assertion for being called on the wrong queue.

相反，您应该在正确的线程上创建对象，并将其安全地传递回目标队列（如果您正在做 UI 工作，则是主队列）以供进一步使用

SPDispatchAsync(^{
    sp_artist *artist = …; // An artist.
    SPArtist *artistObj = [SPArtist artistWithArtistStruct:artist inSession:session];
    dispatch_async(dispatch_get_main_queue(), ^{ self.artist = artistObj; });
});

CocoaLibSpotify 提供了三个宏来帮助进行线程操作

  • SPDispatchAsync() 接收一个块并在 libSpotify 线程上异步执行它。它非常类似于 libdispatch 的 dispatch_async。

  • SPDispatchSyncIfNeeded() 接收一个块并在 libSpotify 线程上同步执行它，直到完成后才阻止当前的代码路径。由于 libSpotify 线程基于先来先服务的方式执行块，内部工作可能会延迟相当长的时间，因此始终建议使用 SPDispatchAsync()。

  • SPAssertOnLibSpotifyThread() 当从非 libSpotify 线程调用时会抛出断言。这可以用于调试使用 libSpotify 线程的代码。

有关 "加载" 的说明

CocoaLibSpotify有很多异步加载的功能 —— 歌曲列表、播放列表、艺术家、专辑等对象都可能在您获取对象后完成其元数据的加载。在用户播放列表和搜索的情况下，这可能需要几秒钟的时间。

不要轮询这些属性 - 当您进行轮询循环时，在许多情况下，您可能会阻止CocoaLibSpotify执行任何操作，导致元数据无法加载。

相反，CocoaLibSpotify对象模型中的大多数对象（包括诸如SPArtist、SPTrack、SPAlbum等元数据类以及诸如SPSearch等“操作”类）均符合SPAsyncLoading协议，您可以使用SPAsyncLoading辅助类在给定项加载时接收回调块。例如

    NSArray *someTracks = …; // Some tracks.

    [SPAsyncLoading waitUntilLoaded:someTracks timeout:10.0 then:^(NSArray *loadedTracks, NSArray *notLoadedTracks) {

        NSLog(@"The following tracks are loaded: %@", loadedTracks);
    }];

此外，CocoaLibSpotify的属性兼容键值观察（Key-Value Observing），最佳实践是为你感兴趣的属性添加观察者以接收元数据加载时的通知回调。

例如，如果您想了解搜索结果何时返回，可以添加如下观察者

[self addObserver:self forKeyPath:@"search.tracks" options:0 context:nil];
self.search = [SPSearch searchWithSearchQuery:@"Hello" inSession:[SPSession sharedSession]];

当搜索结果中的歌曲更新时，您将收到回调

- (void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context {

    if ([keyPath isEqualToString:@"search.tracks"])
        NSLog(@"Search found tracks: %@", self.search.tracks);
}

键值观察是Mac和iOS SDK的核心技术，Apple的开发者文档中有详尽的文档和示例。

编译 - Mac OS X

Xcode项目需要Xcode 4.5和Mac OS X 10.7来编译，因为它使用了自动引用计数（ARC）。但是，编译的二进制文件可以部署在运行Mac OS X 10.6或更高版本的64位系统上。

编译的CocoaLibSpotify.framework包含作为一个子框架的libspotify.framework。有时，Xcode可能会在报告中出现构建错误，表示找不到。如果您遇到这种情况，请手动将libspotify.framework所在的目录添加到项目的“框架搜索路径”构建设置中。例如，如果您将CocoaLibSpotify项目与应用程序一起作为嵌入的Xcode项目构建，然后将它复制到您的包中，则会有如下所示的内容

$CONFIGURATION_BUILD_DIR/CocoaLibSpotify.framework/Versions/Frameworks

否则，您需要手动指定下载的libspotify.framework的位置，如下所示

../../libspotify-12.1.45-Darwin-universal

编译 - iOS

由于使用ARC，Xcode项目需要Xcode 4.5和iOS SDK版本6.0+来编译。但是，编译的二进制文件可以部署在任何iOS版本（从4.0版本）上。

编译好的libCocoaLibSpotify内部包含libspotify作为静态库，同时在名为“include”的目录中包含所有必需的头文件。

此外，您必须将SPLoginResources.bundle作为应用程序的资源包含在内。

当将libCocoaLibSpotify包含到您的应用程序中时，您还必须链接以下框架

  • SystemConfiguration.framework
  • CFNetwork.framework
  • libstdc++
  • CoreAudio.framework
  • AudioToolbox.framework
  • AVFoundation.framework
  • Security.framework

此外，您必须将以下两项添加到“其他链接器标志”构建设置中

  • -all_load
  • -ObjC

如果您将CocoaLibSpotify项目与应用程序一起作为嵌入的Xcode项目来构建，然后在构建步骤中将它与您的应用程序链接，您可以通过向项目的“框架搜索路径”构建设置中添加以下设置来告诉Xcode头文件的位置

$CONFIGURATION_BUILD_DIR/include

否则，您可以将所有头文件手动添加到项目中。

一切设置完成后，只需导入以下头文件即可开始使用CocoaLibSpotify！

#import "CocoaLibSpotify.h"

文档

CocoaLibSpotify的头文件有很好的文档记载，我们提供了Xcode DocSet，以在Xcode中提供文档。结合这些和示例项目，您应该拥有开始所需的一切！

此外，还有一个FAQ页面在这里库中：常见使用问题覆盖。

分支管理

所有开发工作都是在dev分支上完成的。当它被认为稳定时，会带上新版本标签与master分支合并。

单元测试

CocoaLibSpotify现在包含了一些单元测试，这些测试在一个由项目构建的独立应用内部运行。如果您在CocoaLibSpotify中发现了一个bug，请分叉该项目，在dev分支上添加或修改一个单元测试，使其失败（演示bug），然后发起一个pull请求。我们可以修复底层bug，并保留您的测试。

要运行测试，根据需要打开"CocoaLibSpotify Mac框架"或"CocoaLibSpotify iOS库"项目，然后在Xcode中切换到"CocoaLSTests"方案。然后

  • 通过从developer.spotify.com下载二进制版本（而不是C文件）并运行以下命令来生成您appkey的Base64表示： openssl base64 -in spotify_appkey.key | tr -d '\n'。
  • 编辑方案，在启动时传递以下参数：-TestUserName <您的用户名> -TestPassword <您的密码> -AppKey <Base64 appkey>
  • 运行"CocoaLSTests"目标。

测试本身包含制作良好测试的例子。

联系

如果您有任何问题或发现了任何bug，请查看我们的GitHub页面以了解已知问题和讨论。对于使用问题，请在Stack Overflow上打开一个问题并使用spotify标签。否则，我们可能在irc://irc.freenode.net/spotify上。