This library is under active development. We're shooting for a v1.0 release soon. All comments, questions, pull requests, and issues are welcome. See below for details.
- Design Considerations * Old Upload, New Upload 👴👶 * Constraints * Goals * Anatomy * NSURLSession * AFNetworking * VimeoUpload
- Getting Started * Prerequisites * Example Projects * CocoaPods * Submodule * Initialization
- Uploading Videos
- Custom Workflows 🍪🎉
- Want to Contribute?
- Found an Issue?
- Questions
- License
The current (public) server-side Vimeo upload API is comprised of 4 separate requests that must be made in sequence. This is more complex than we'd like it to be, and this complexity is not ideal for native mobile clients. More requests means more failure points. More requests means a process that's challenging to communicate to the developer and in turn to the user. The 4 requests are:
- Create a video object
- Upload the video file
- Activate the video object
- Optionally set the video object's metadata (e.g. title, description, privacy, etc.)
We affectionately refer to this 4-step flow as Old Upload.
A simplified flow that eliminates steps 3 and 4 above is in private beta right now. It's being used in the current Vimeo iOS and Vimeo Android apps and it's slated to be made available to the public later this year.
We affectionately refer to this 2-step flow as New Upload.
VimeoUpload is designed to accommodate a variety of background task workflows including Old Upload and New Upload. The library currently contains support for both. However, New Upoad classes are currently marked as "private" and will not work for the general public until they are released from private beta.
The VimeoUpload APIs for New and Old Upload are very similar. The Old Upload API is documented below. Old upload will be deprecated as soon as possible and the README will be updated to reflec the New Upload API at that time.
- iOS 7 Support Required
Because the Vimeo iOS app supports iOS7, and because a bunch of other apps out there do too, we must support both the ALAsset and PHAsset APIs.
- No Direct Access to PHAsset or ALAsset Source Files
Because of how the Apple APIs are designed, we cannot upload directly from ALAsset and PHAsset source files. So we must export a copy of the asset using an AVAssetExportSession before starting the upload process. Asset export must happen when the app is in the foreground.
- iCloud Photos
If a PHAsset is in iCloud and not resident on device we need to download it to the device before asset export. Download must happen when the app is in the foreground.
- Background Sessions
Because an upload can take a significant amount of time, we must design for the user potentially backgrounding the application at any point in the process. Therefore all requests must be handled by an NSURLSession configured with a background NSURLSessionConfiguration. This means we must rely exclusively on the NSURLSessionDelegate, NSURLSessionTaskDelegate, and NSURLSessionDownloadDelegate protocols. We cannot rely on an NSURLSessionTask subclasses' completion blocks.
- Resumable Uploads
The NSURLSession API does not support resuming an interrupted background upload from an offset. The initial release of this library will use these APIs exclusively and therefore will also not support resuming an upload from an offset.
- Fault Tolerance
The app process could be backgrounded, terminated, or crash at any time. This means that we need to persist the state of the upload system to disk so that it can be reconstructed as needed. Crashes should not adversely impact uploads or the upload system.
- Concurrent File Uploads
We want to be able to conduct concurrent uploads.
- State Introspection
We want to be able to communicate upload progress and state to the user in a variety of locations. Including communicating state for uploads initiated on other devices and other platforms.
- Reachability Awareness
The app could lose connectivity at any time. We want to be able to pause and resume the upload system when we lose connectivity. And we want to be able to allow the user to restrict uploads to wifi.
- Upload Quotas
We need to be able to communicate information to users about their upload quota.
- iOS SDK Quirks
NSURLSessionTask's suspend method doesn't quite do what we want it to TODO: Provide details
NSURLRequest's and NSURLSessionConfiguration's allowsCellularAccess properties don't quite do what we want them to TODO: provide details
AFURLSessionManager's tasks property behaves differently on iOS7 vs. iOS8+ TODO: provide details
And more...
-
A simplified server-side upload API
-
An upload system that addresses each constraint listed above
-
Clear and concise upload system initialization, management, and introspection
-
An upload system that accommodates as many UX futures as possible
TODO
TODO
TODO
- Ensure that you've verified your Vimeo account. When you create an account, you'll receive an email asking that you verify your account. Until you verify your account you will not be able to upload videos using the API.
- Ensure you have been granted permission to use the "upload" scope. This permission must explicitly be granted by Vimeo API admins. You can request this permission on your app page under "Request upload access". Visit developer.vimeo.com.
- Ensure that the OAuth token that you're using to make your requests has the "upload" scope included.
There's an example project for New Upload and one for Old Upload. In order to run them you'll have to drop a valid OAuth token into the example project's VimeoUpload subclass' init method where it says "YOUR_OAUTH_TOKEN". You can obtain an OAuth token by visiting developer.vimeo.com and creating a new "app" and associated OAuth token.
TODO
TODO
Create an instance of VimeoUpload, or modify VimeoUpload to act as a singleton:
let backgroundSessionIdentifier = "YOUR_BACKGROUND_SESSION_ID"
let authToken = "YOUR_OAUTH_TOKEN"
let vimeoUpload = VimeoUpload<OldUploadDescriptor>(backgroundSessionIdentifier: backgroundSessionIdentifier, authToken: authToken)If your OAuth token can change during the course of a session, use the constructor whose second argument is an authTokenBlock:
let backgroundSessionIdentifier = "YOUR_BACKGROUND_SESSION_ID"
var authToken = "YOUR_OAUTH_TOKEN"
let vimeoUpload = VimeoUpload<OldUploadDescriptor>(backgroundSessionIdentifier: backgroundSessionIdentifier, authTokenBlock: { () -> String? in
return authToken
})You can obtain an OAuth token by using the authentication methods provided by VIMNetworking or by visiting developer.vimeo.com and creating a new "app" and associated OAuth token.
In order to start an upload, you need a file URL pointing to the video file on disk that you would like to upload.
The steps required to obtain the file URL will vary depending on whether you are uploading a PHAsset, an ALAsset, or an asset that you manage outside of the device Photos environment. Once you have a valid file URL, you will use it to start your upload.
Unfortunately, because of how Apple's PHAsset and ALAsset APIs are designed uploading directly from a PHAsset or ALAsset resource URL is not possible. In order to upload PHAssets and ALAssets you will need to first create a copy of the asset itself and upload from that copy. See below for instructions on how to do this.
Use VimeoUpload's PHAssetExportSessionOperation to request an instance of AVAssetExportSession configured for the PHAsset that you intend to upload. If the PHAsset is in iCloud (i.e. not resident on the device) this will download the PHAsset from iCloud.
let phAsset = ... // The PHAsset you intend to upload
let operation = PHAssetExportSessionOperation(phAsset: phAsset)
// Optionally set a progress block
operation.progressBlock = { (progress: Double) -> Void in
// Do something with progress
}
operation.completionBlock = {
guard operation.cancelled == false else
{
return
}
if let error = operation.error
{
// Do something with the error
}
else if let exportSession = operation.result
{
// Use the export session to export a copy of the asset (see below)
}
else
{
assertionFailure("error and exportSession are mutually exclusive. This should never happen.")
}
}
operation.start()Next, use VimeoUpload's ExportOperation to export a copy of the PHAsset. You can then use the resulting url to start your upload.
let exportSession = ... // The export session you just generated (see above)
let operation = ExportOperation(exportSession: exportSession)
// Optionally set a progress block
operation.progressBlock = { (progress: Double) -> Void in
// Do something with progress
}
operation.completionBlock = {
guard operation.cancelled == false else
{
return
}
if let error = operation.error
{
// Do something with the error
}
else if let url = operation.outputURL
{
// Use the url to start your upload (see below)
}
else
{
assertionFailure("error and outputURL are mutually exclusive, this should never happen.")
}
}
operation.start()Use VimeoUpload's ExportOperation to export a copy of the ALAsset you intend to upload. You can then use the resulting url to start your upload.
let alAsset = ... // The ALAsset you intend to upload
let url = alAsset.defaultRepresentation().url() // For example
let avAsset = AVURLAsset(URL: url)
let operation = ExportOperation(asset: avAsset)
// Optionally set a progress block
operation.progressBlock = { (progress: Double) -> Void in
// Do something with progress
}
operation.completionBlock = {
guard operation.cancelled == false else
{
return
}
if let error = operation.error
{
// Do something with the error
}
else if let url = operation.outputURL
{
// Use the url to start your upload (see below)
}
else
{
assertionFailure("error and outputURL are mutually exclusive, this should never happen.")
}
}
operation.start()This is quite a bit simpler:
let path = "PATH_TO_VIDEO_FILE_ON_DISK"
let url = NSURL.fileURLWithPath(path)Use the url to start your upload:
let vimeoUpload = ... // Your instance of VimeoUpload (see above)
let url = ... // Your url (see above)
let descriptor = OldUploadDescriptor(url: url)
vimeoUpload.uploadVideo(descriptor: descriptor)You can also pass in a VideoSettings object if you'd like. This will set your video's metadata after the upload completes:
let vimeoUpload = ... // Your instance of VimeoUpload (see above)
let url = ... // Your url (see above)
let title = "Untitled"
let description = "A really cool video"
let privacy = "nobody"
let videoSettings = VideoSettings(title: title, description: description, privacy: privacy, users: nil, password: nil)
let descriptor = OldUploadDescriptor(url: url, videoSettings: videoSettings)
vimeoUpload.uploadVideo(descriptor: descriptor)You can use the descriptor you create to inspect state and progress, or to cancel the upload.
You can examine upload state and progress by inspecting the stateObservable and progressObservable properties of an OldUploadDescriptor.
You can obtain a reference to a specific OldUploadDescriptor by holding onto the OldUploadDescriptor that you used to initiate the upload, or by asking VimeoUpload for a specific OldUploadDescriptor like so:
let identifier = ... // The identifier you set on the descriptor when you created it (see above)
let vimeoUpload = ... // Your instance of VimeoUpload (see above)
let descriptor = vimeoUpload.descriptorForIdentifier(identifier: identifier)You can also ask VimeoUpload for an OldUploadDescriptor that passes a test that you construct. You can construct any test you'd like. In the case where we want a descriptor with a certain identifier, the convenience method descriptorForIdentifier leverages descriptorPassingTest under the hood:
let phAsset = ... // The PHAsset whose upload you'd like to inspect
let vimeoUpload = ... // Your instance of VimeoUpload (see above)
let descriptor = vimeoUpload.descriptorManager.descriptorPassingTest({ (descriptor) -> Bool in
return descriptor.identifier == phAsset.localIdentifier
})Once you have a reference to the OldUploadDescriptor you're interested in you can inspect its state directly:
print(descriptor.state)
print(descriptor.error?.localizedDescription)Or use KVO to observe changes to its state and progress:
private static let ProgressKeyPath = "progressObservable"
private static let StateKeyPath = "stateObservable"
private var progressKVOContext = UInt8()
private var stateKVOContext = UInt8()
...
descriptor.addObserver(self, forKeyPath: self.dynamicType.StateKeyPath, options: .New, context: &self.stateKVOContext)
descriptor.addObserver(self, forKeyPath: self.dynamicType.ProgressKeyPath, options: .New, context: &self.progressKVOContext)
...
descriptor.removeObserver(self, forKeyPath: self.dynamicType.StateKeyPath, context: &self.stateKVOContext)
descriptor.removeObserver(self, forKeyPath: self.dynamicType.ProgressKeyPath, context: &self.progressKVOContext)
...
// MARK: KVO
override func observeValueForKeyPath(keyPath: String?, ofObject object: AnyObject?, change: [String : AnyObject]?, context: UnsafeMutablePointer<Void>)
{
if let keyPath = keyPath
{
switch (keyPath, context)
{
case(self.dynamicType.ProgressKeyPath, &self.progressKVOContext):
let progress = change?[NSKeyValueChangeNewKey]?.doubleValue ?? 0
// Do something with progress
case(self.dynamicType.StateKeyPath, &self.stateKVOContext):
let stateRaw = (change?[NSKeyValueChangeNewKey] as? String) ?? DescriptorState.Ready.rawValue;
let state = DescriptorState(rawValue: stateRaw)!
// Do something with state
default:
super.observeValueForKeyPath(keyPath, ofObject: object, change: change, context: context)
}
}
else
{
super.observeValueForKeyPath(keyPath, ofObject: object, change: change, context: context)
}
}Canceling an upload will cancel the file upload itself as well as delete the video object from Vimeo servers. You can cancel an upload using the OldUploadDescriptor instance in question:
let vimeoUpload = ... // Your instance of VimeoUpload (see above)
let descriptor = ... // The descriptor you'd like to cancel
vimeoUpload.cancelUpload(descriptor: descriptor)Or by using the identifier of the OldUploadDescriptor in question:
let vimeoUpload = ... // Your instance of VimeoUpload (see above)
let identifier = phAsset.localIdentifier
vimeoUpload.cancelUpload(identifier: identifier)TODO
Please file it in the git issue tracker.
If you'd like to contribute, please follow our guidelines found in CONTRIBUTING.md.
VimeoUpload is available under the MIT license. See the LICENSE file for more info.
Tweet at us here: @vimeoapi.
Post on Stackoverflow with the tag vimeo-ios.
Get in touch here.
Interested in working at Vimeo? We're hiring!