Notice: MediaCrush has shut down. The API only exists if you are running your own instance, or using a third party instance.
MediaCrushKit is a Cocoa framework for interacting with the MediaCrush API. It's built atop AFNetworking, Mantle, and ReactiveCocoa.
As you evaluate the usage of MediaCrushKit and the MediaCrush service in your application, be aware of the following:
-
The MediaCrush service does not have user accounts. This is due to the creator's staunch support of end user privacy. MediaCrush aims to store as little uniquely identifying data as possible.
-
A hash of the uploader's IP address is used to determine ownership of media blobs (including albums). An edit or deletion operation will fail if the requester's IP address does not match the uploader's IP address. A revision to the API is in progress which will address this.
Finally, if your usage of the MediaCrush API will direct large amounts of traffic to the mediacru.sh servers, the creators of MediaCrush would appreciate a donation to offset the cost of running the service.
In order to begin interacting with the API, you must instantiate an
MCKClient. Instantiating an MCKClient requires you provide an MCKServer configured for the MediaCrush server you wish to communicate with. Call the +defaultServer
method to create an MCKServer
configured for communicating with mediacru.sh.
After we've got a client, we can start fetching data. Each request method on
MCKClient
returns
a ReactiveCocoa signal, which
is kind of like a future or
promise:
// Prepares a request that will load the files, represented by MCKFile
// objects, for the provided IDs.
//
// Note that the request is not actually _sent_ until you use one of the
// -subscribe… methods below.
RACSignal *request = [client fetchFilesWithIDs:@[@"SomeId"]];
However, you don't need a deep understanding of RAC to use MediaCrushKit. There are just a few basic operations to be aware of.
It often makes sense to handle each result object independently, so you can spread any processing out instead of doing it all at once:
// This method actually kicks off the request, handling any results using the
// blocks below.
[request subscribeNext:^(MCKFile *file) {
// This block is invoked for _each_ result received, so you can deal with
// them one-by-one as they arrive.
} error:^(NSError *error) {
// Invoked when an error occurs.
//
// Your `next` and `completed` blocks won't be invoked after this point.
} completed:^{
// Invoked when the request completes and we've received/processed all the
// results.
//
// Your `next` and `error` blocks won't be invoked after this point.
}];
If you can't do anything until you have all of the results, you can "collect" them into a single array:
[[request collect] subscribeNext:^(NSArray *files) {
// Thanks to -collect, this block is invoked after the request completes,
// with _all_ the results that were received.
} error:^(NSError *error) {
// Invoked when an error occurs. You won't receive any results if this
// happens.
}];
The blocks in the above examples will be invoked in the background, to avoid slowing down the main thread. However, if you want to run UI code, you shouldn't do it in the background, so you must "deliver" results to the main thread instead:
[[request deliverOn:RACScheduler.mainThreadScheduler] subscribeNext:^(MCKFile *file) {
// ...
} error:^(NSError *error) {
UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"Whoops!"
message:@"Something went wrong."
delegate:nil
cancelButtonTitle:nil
otherButtonTitles:nil];
[alert show];
} completed:^{
[self.tableView reloadData];
}];
All of the -subscribe…
methods actually return
a RACDisposable
object. Most of the time, you don't need it, but you can hold onto it if you
want to cancel requests:
- (void)viewWillAppear:(BOOL)animated {
[super viewWillAppear:animated];
RACDisposable *disposable = [[[[self.client
fetchFilesWithIDs:@[@"SomeId"]]
collect]
deliverOn:RACScheduler.mainThreadScheduler]
subscribeNext:^(NSArray *files) {
[self addTableViewRowsForRepositories:files];
} error:^(NSError *error) {
UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"Whoops!"
message:@"Something went wrong."
delegate:nil
cancelButtonTitle:nil
otherButtonTitles:nil];
[alert show];
}];
// Save the disposable into a `strong` property, so we can access it later.
self.filesDisposable = disposable;
}
- (void)viewWillDisappear:(BOOL)animated {
[super viewWillDisappear:animated];
// Cancels the request for the files if it's still in progress. If the
// request already terminated, nothing happens.
[self.filesDisposable dispose];
}
MediaCrushKit is released under the MIT license. See LICENSE.md.