Skip to content
Newer
Older
100644 148 lines (86 sloc) 8.7 KB
84e3a70 @iKenndac Move README to markdown, because markdown is for winners.
iKenndac authored
1 # CocoaLibSpotify #
c2fc351 @iKenndac Initial release.
iKenndac authored
2
d3aac71 @iKenndac Updated readme.
iKenndac authored
3 CocoaLibSpotify is an Objective-C wrapper around our libspotify library. It provides easy access to libspotify's features in a friendly, KVC/O compliant Objective-C wrapper.
c2fc351 @iKenndac Initial release.
iKenndac authored
4
4a54260 @iKenndac Move and update readme files.
iKenndac authored
5 CocoaLibSpotify requires libspotify.framework, which isn't included in the repository. The Mac Framework and iOS Library Xcode projects include a build step to download and unpack it from developer.spotify.com automatically. If this fails for some reason, download it manually from developer.spotify.com and unpack it into the project folder.
6
a2afdbf @iKenndac Update README and add changelog.
iKenndac authored
7 ## Release Notes ##
4ed031a @iKenndac Update README and docs.
iKenndac authored
8
a2afdbf @iKenndac Update README and add changelog.
iKenndac authored
9 You can find the latest release notes in the [CHANGELOG.markdown](https://github.com/spotify/cocoalibspotify/blob/master/CHANGELOG.markdown) file.
4ed031a @iKenndac Update README and docs.
iKenndac authored
10
d4d79b3 @iKenndac Update README
iKenndac authored
11 ## Threading ##
12
13 As of CocoaLibSpotify 2.0, the framework uses an internal threading model to run the libSpotify library on a background thread, allowing your application to remain responsive when libSpotify is experiencing heavy load.
14
a3e9222 @iKenndac Fix mistake in README
iKenndac authored
15 However, libSpotify is **not** thread-safe, and all methods in CocoaLibSpotify that provide access to libSpotify types are guarded to prevent access from the wrong thread. If you must access libSpotify types directly, first file an issue so we can make a thread-aware API in CocoaLibSpotify for your use case, then make sure you call the relevant API on the correct thread, which `SPSession` provides various helper macros for.
d4d79b3 @iKenndac Update README
iKenndac authored
16
03297f6 @iKenndac Update readme (Fixes GitHub issue #116)
iKenndac authored
17 Bad:
d4d79b3 @iKenndac Update README
iKenndac authored
18
19 ```
20 sp_artist *artist = …; // An artist.
21 SPArtist *artistObj = [SPArtist artistWithArtistStruct:artist inSession:session];
22 // ^ The above line will throw an assertion for being called on the wrong queue.
23 ```
24
03297f6 @iKenndac Update readme (Fixes GitHub issue #116)
iKenndac authored
25 Instead, you should create the object on the correct thread and safely pass it back to the target queue (the main queue if you're doing UI work) for further use:
d4d79b3 @iKenndac Update README
iKenndac authored
26
27 ```
03297f6 @iKenndac Update readme (Fixes GitHub issue #116)
iKenndac authored
28 SPDispatchAsync(^{
d4d79b3 @iKenndac Update README
iKenndac authored
29 sp_artist *artist = …; // An artist.
30 SPArtist *artistObj = [SPArtist artistWithArtistStruct:artist inSession:session];
03297f6 @iKenndac Update readme (Fixes GitHub issue #116)
iKenndac authored
31 dispatch_async(dispatch_get_main_queue(), ^{ self.artist = artistObj; });
d4d79b3 @iKenndac Update README
iKenndac authored
32 });
33 ```
34
03297f6 @iKenndac Update readme (Fixes GitHub issue #116)
iKenndac authored
35 CocoaLibSpotify provides three macros to assist with threading:
36
37 - `SPDispatchAsync()` takes a block and executes it asynchronously on the libSpotify thread. It works very much like libdispatch's `dispatch_async`.
38
39 - `SPDispatchSyncIfNeeded()` takes a block and executes it synchronously on the libSpotify thread, blocking the current code path until completion. Since the libSpotify thread executes blocks on a first-come, first-served basis, internal work may delay execution for a significant amount of time, so using `SPDispatchAsync()` is always recommended.
40
41 - `SPAssertOnLibSpotifyThread()` will throw an assertion when called from anything but the libSpotify thread. This can be useful for debugging code using the libSpotify thread.
42
e266edf @iKenndac Add clarification on KVO to readme.
iKenndac authored
43 ## A Note On "Loading" ##
44
45 CocoaLibSpotify does a lot of asynchronous loading — tracks, playlists, artists, albums, etc can all finish loading their metadata after you get an object. In the case of user playlists and searching, this can be a number of seconds.
46
d4d79b3 @iKenndac Update README
iKenndac authored
47 Do *not* poll these properties - when you do a polling loop you can, in many cases, stop CocoaLibSpotify's ability to do any work, causing the metadata to never load.
e266edf @iKenndac Add clarification on KVO to readme.
iKenndac authored
48
d4d79b3 @iKenndac Update README
iKenndac authored
49 Instead, most objects in the CocoaLibSpotify object model (including metadata classes like `SPArtist`, `SPTrack`, `SPAlbum`, etc and "action" classes like `SPSearch` etc) conform to the `SPAsyncLoading` protocol, and you can use the `SPAsyncLoading` helper class to get a block callback when the given item(s) are loaded. For example:
50
51 ```
52 NSArray *someTracks = …; // Some tracks.
53
54 [SPAsyncLoading waitUntilLoaded:someTracks timeout:10.0 then:^(NSArray *loadedTracks, NSArray *notLoadedTracks) {
55
56 NSLog(@"The following tracks are loaded: %@", loadedTracks);
57 }];
58 ```
59
60 Additionally, CocoaLibSpotify's properties are Key-Value Observing compliant, and the best practice is to add an observer to the properties you're interested in to receive a notification callback when the metadata is loaded.
e266edf @iKenndac Add clarification on KVO to readme.
iKenndac authored
61
62 For example, if you want to know when search results come back, add an observer like this:
63
64 [self addObserver:self forKeyPath:@"search.tracks" options:0 context:nil];
65 self.search = [SPSearch searchWithSearchQuery:@"Hello" inSession:[SPSession sharedSession]];
66
67 When the tracks in the search are updated, you'll get a callback:
68
69
70 - (void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context {
71
72 if ([keyPath isEqualToString:@"search.tracks"])
73 NSLog(@"Search found tracks: %@", self.search.tracks);
74 }
75
76 Key-Value Observing is a core technology in the Mac and iOS SDKs, and extensive documentation and examples can be found in Apple's [developer documentation](http://developer.apple.com/library/ios/#documentation/General/Conceptual/DevPedia-CocoaCore/KVO.html).
77
84e3a70 @iKenndac Move README to markdown, because markdown is for winners.
iKenndac authored
78 ## Building - Mac OS X ##
c2fc351 @iKenndac Initial release.
iKenndac authored
79
03297f6 @iKenndac Update readme (Fixes GitHub issue #116)
iKenndac authored
80 The Xcode project requires Xcode 4.5 and Mac OS X 10.7 to build since it uses ARC. However, the built binary can be deployed on 64-bit systems running Mac OS X 10.6 or higher.
c2fc351 @iKenndac Initial release.
iKenndac authored
81
4a54260 @iKenndac Move and update readme files.
iKenndac authored
82 The built CocoaLibSpotify.framework contains libspotify.framework as a child framework. Sometimes, Xcode gives build errors complaining it can't find <libspotify/api.h>. If you get this, manually add the directory libspotify.framework is in to your project's "Framework Search Paths" build setting. For example, if you're building the CocoaLibSpotify project alongside your application as an embedded Xcode project then copying it into your bundle, you'd have this:
71a7cf5 @iKenndac Update readme.
iKenndac authored
83
84 `$CONFIGURATION_BUILD_DIR/CocoaLibSpotify.framework/Versions/Frameworks`
85
86 Otherwise, you'd point to the downloaded libspotify.framework manually, something like this:
87
3f30e5c @iKenndac Add new libspotify 12 features.
iKenndac authored
88 `../../libspotify-12.1.45-Darwin-universal`
c2fc351 @iKenndac Initial release.
iKenndac authored
89
84e3a70 @iKenndac Move README to markdown, because markdown is for winners.
iKenndac authored
90 ## Building - iOS ##
70b42a4 @iKenndac Update documentation. Remove iOS sample project since we don't have t…
iKenndac authored
91
03297f6 @iKenndac Update readme (Fixes GitHub issue #116)
iKenndac authored
92 The Xcode project requires Xcode 4.5 and iOS SDK version 6.0+ to build since it uses ARC. However, the built binary can be deployed on any iOS version from version 4.0.
0cd1d98 @iKenndac Update README with new requirements.
iKenndac authored
93
4a54260 @iKenndac Move and update readme files.
iKenndac authored
94 The built libCocoaLibSpotify contains libspotify internally as a static library, as well as all of the required header files in a directory called "include".
95
f8d151a @iKenndac Implement pretty login screen and new user signup flow.
iKenndac authored
96 In addition, you MUST include SPLoginResources.bundle as a resource of your application.
97
6c86f3d @iKenndac Update read me with linking instructions for iOS.
iKenndac authored
98 When including libCocoaLibSpotify in your application, you must also link to the following frameworks:
99
100 - SystemConfiguration.framework
101 - CFNetwork.framework
102 - libstdc++
5e46f17 @iKenndac Rewrite provided audio code (Fixes GitHub issue #50)
iKenndac authored
103 - CoreAudio.framework
104 - AudioToolbox.framework
105 - AVFoundation.framework
721df26 @iKenndac Link iOS projects to Security.framework for 12.1.62
iKenndac authored
106 - Security.framework
6c86f3d @iKenndac Update read me with linking instructions for iOS.
iKenndac authored
107
108 In addition, you must add the following two items to the "Other Linker Flags" build setting:
109
110 - -all_load
111 - -ObjC
112
4a54260 @iKenndac Move and update readme files.
iKenndac authored
113 If you're building the CocoaLibSpotify project alongside your application as an embedded Xcode project then linking it with your application in a build step, you can tell Xcode where the header files are by adding the following setting to the "Framework Search Paths" build setting of your project:
114
115 `$CONFIGURATION_BUILD_DIR/include`
116
03297f6 @iKenndac Update readme (Fixes GitHub issue #116)
iKenndac authored
117 Otherwise, you can simply add all of the header files to your project manually.
70b42a4 @iKenndac Update documentation. Remove iOS sample project since we don't have t…
iKenndac authored
118
4a54260 @iKenndac Move and update readme files.
iKenndac authored
119 Once everything is set up, simply import the following header to get started with CocoaLibSpotify!
70b42a4 @iKenndac Update documentation. Remove iOS sample project since we don't have t…
iKenndac authored
120
4a54260 @iKenndac Move and update readme files.
iKenndac authored
121 `#import "CocoaLibSpotify.h"`
0f88360 @iKenndac Update projects and readme for final 0.0.9 libspotify release.
iKenndac authored
122
84e3a70 @iKenndac Move README to markdown, because markdown is for winners.
iKenndac authored
123 ## Documentation ##
c2fc351 @iKenndac Initial release.
iKenndac authored
124
125 The headers of CocoaLibSpotify are well documented, and we've provided an Xcode DocSet to provide documentation right in Xcode. With these and the sample projects, you should have everything you need to dive right in!
126
03297f6 @iKenndac Update readme (Fixes GitHub issue #116)
iKenndac authored
127 Additionally, there's an FAQ [right here in the repo](https://github.com/spotify/cocoalibspotify/blob/master/FAQ.markdown) that covers common usage questions.
b8cc9fc @iKenndac Add FAQ
iKenndac authored
128
293a725 @iKenndac Add branch info to README.
iKenndac authored
129 ## Branching ##
130
03297f6 @iKenndac Update readme (Fixes GitHub issue #116)
iKenndac authored
131 All development work is done on the `dev` branch. When it's considered stable, it's merged to `master` with a new version tag.
293a725 @iKenndac Add branch info to README.
iKenndac authored
132
bc8520f @iKenndac Add section on Unit Tests to the README.
iKenndac authored
133 ## Unit Tests ##
134
5057d2b @iKenndac Update documentation.
iKenndac authored
135 CocoaLibSpotify now ships with a number of unit tests, which run inside a standalone application built by the project. If you find a bug in CocoaLibSpotify, please fork the project, add or modify a unit test *on the dev branch* so it fails (demonstrating the bug), then issue a pull request. We can then fix the underlying bug and keep your test so it stays that way.
bc8520f @iKenndac Add section on Unit Tests to the README.
iKenndac authored
136
137 To run the tests, open the "CocoaLibSpotify Mac Framework" or "CocoaLibSpotify iOS Library" project as needed, then switch to the "CocoaLSTests" scheme in Xcode. Then:
138
03297f6 @iKenndac Update readme (Fixes GitHub issue #116)
iKenndac authored
139 - Generate a Base64 representation of your appkey by downloading the binary version (not the C file) from `developer.spotify.com` and running the following command on it: `openssl base64 -in spotify_appkey.key | tr -d '\n'`.
140 - Edit the scheme to pass the following arguments on launch: `-TestUserName <Your username> -TestPassword <Your password> -AppKey <Base64 appkey>`
bc8520f @iKenndac Add section on Unit Tests to the README.
iKenndac authored
141 - Run the "CocoaLSTests" target.
142
143 You'll find examples on how to make a good test in the tests themselves.
144
84e3a70 @iKenndac Move README to markdown, because markdown is for winners.
iKenndac authored
145 ## Contact ##
0f88360 @iKenndac Update projects and readme for final 0.0.9 libspotify release.
iKenndac authored
146
03297f6 @iKenndac Update readme (Fixes GitHub issue #116)
iKenndac authored
147 If you have any problems or find any bugs, see our GitHub page for known issues and discussion. For usage questions, please open a question on Stack Overflow with the `spotify` tag. Otherwise, we may be available in irc://irc.freenode.net/spotify.
Something went wrong with that request. Please try again.