Migration from v10

Update dependencies#

VideoEditor SDK requires iOS 13+ and Xcode 13.3+ with Swift 5.6+. If you have to use older versions of Swift or support older versions of iOS, please have a look at previous versions.

Swift Package Manager#

Go to your Xcode project Package Dependencies section, make sure that the version policy for the vesdk-ios-build package includes v11:

Then select File > Packages > Update to Latest Package Versions.

For more details about using Swift Package Manager see the official guide.

CocoaPods#

Your Podfile should already contain the proper entry:

pod 'VideoEditorSDK'

To perform the actual update, run the following command:

pod update VideoEditorSDK --repo-update

During a successful update to v11, you should get a similar output:

Installing VideoEditorSDK 11.0.0 (was 10.30.0)
Installing imglyKit 11.0.0 (was 10.30.0)

For more details about using CocoaPods see the official guide.

Manually#

Download the latest version of the SDK here, then replace ImglyKit.framework as well as VideoEditorSDK.framework in the Frameworks, Libraries, and Embedded Content section of your target and make sure that the Embed & Sign option is selected for both of them:

For more details about manual integration see the getting started section.

UIKit#

CameraViewController#

The CameraViewController now returns its results within a single completionBlock:

- cameraViewController.completionBlock = { image, url in
-   // ...
- }
- cameraViewController.dataCompletionBlock = { data in
-   // ...
- }
+ cameraViewController.completionBlock = { result in
+   // ...
+ }

- [cameraViewController setCompletionBlock:^(UIImage * _Nullable image, NSURL * _Nullable url) {
-   // ...
- }];
- [cameraViewController setDataCompletionBlock:^(NSData * _Nullable imageData) {
-   // ...
- }];
+ [cameraViewController setCompletionBlock:^(PESDKCameraResult * _Nonnull result) {
+   // ...
+ }];

The new CameraResult parameter optionally contains either:

• JPEG data along with EXIF information or
• the url of the recorded video.

It also adds the model property to be able to pass, e.g., the filter state stored in PhotoEditModel between the camera and the editor.

To create a Video and pass it to the editor, use Video(url:) accordingly:

let cameraViewController = CameraViewController()
cameraViewController.completionBlock = { [unowned cameraViewController] result in
  guard let url = result.url else { return }

  let video = Video(url: url)
  let videoEditViewController = VideoEditViewController(videoAsset: video)
  videoEditViewController.delegate = self

  cameraViewController.present(videoEditViewController, animated: true, completion: nil)
}

present(cameraViewController, animated: true, completion: nil)

VideoEditViewControllerDelegate#

The VideoEditViewControllerDelegate uses extensible return types. See the examples below to integrate the improved result API with your existing code.

Getting the video#

- func videoEditViewController(_ videoEditViewController: VideoEditViewController, didFinishWithVideoAt url: URL?)
+ func videoEditViewControllerDidFinish(_ videoEditViewController: VideoEditViewController, result: VideoEditorResult)

The VideoEditorResult parameter has three inner properties:

• output - stores the url parameter with additional metadata (such as the type identifier),
• status - indicates which exact path was chosen by the user, whether the input video was processed by our rendering pipeline or just passed without changes. This extends the videoEditViewController.hasChanges property.
• task - encapsulates the input data (context) passed to the editor.

In most cases, you will work with your output video using its URL directly. Then, you will need to replace url with result.output.url inside your delegate methods.

Error handling#

- func videoEditViewControllerDidFailToGenerateVideo(_ videoEditViewController: VideoEditViewController)
+ func videoEditViewControllerDidFail(_ videoEditViewController: VideoEditViewController, error: VideoEditorError)

The VideoEditorError is passed to provide different fallback paths, as well as debugging possibilities. You can query the error object for its reason and optional underlyingError properties:

func videoEditViewControllerDidFail(_ videoEditViewController: VideoEditViewController, error: VideoEditorError) {
  // There was an error generating the video.
  print(error.localizedDescription)

  switch error.reason {
  case .videoTooShort:
    ()
  case .exportFailed:
    ()
  default:
    ()
  }

  // Dismissing the editor.
  presentingViewController?.dismiss(animated: true, completion: nil)
}

Starting the rendering (optional)#

There is also a new optional method that you can implement to perform additional validation of the input task and interrupt the rendering process if necessary:

func videoEditViewControllerShouldStart(_ videoEditViewController: VideoEditViewController, task: VideoEditorTask) -> Bool {
  true
}

SwiftUI#

Working with SwiftUI VideoEditor you are already familiar with VideoEditorResult as well as with the onDidSave and onDidFail modifiers. The new version provides a consistent API with its UIKit counterpart so that you can reuse the same straightforward patterns in your closures.

Camera#

- .onDidSaveData { data in

The onDidSaveData modifier was removed and results are returned with the single onDidSave modifier.

.onDidSave { result in
  // ...
}

The onDidSave modifier type did not change. The current CameraResult parameter optionally contains either JPEG data along with EXIF information or a URL of the recorded video.

VideoEditor#

Getting the video#

.onDidSave { result in
  // ...
}

The onDidSave modifier type did not change, but the VideoEditorResult itself is extended. In most cases, you will work with your output video using its URL directly. Then, you will need to replace result.url with result.output.url inside your closures.

For more details about consuming the results, see the getting the video section for UIKit.

Error handling#

- .onDidFail {
+ .onDidFail { error in

The onDidFail modifier passes the actual VideoEditorError that can be handled accordingly:

.onDidFail { error in
  // There was an error generating the video.
  print("Editor finished with error: \(error.localizedDescription)")

  switch error.reason {
  case .videoTooShort:
    ()
  case .exportFailed:
    ()
  default:
    ()
  }
}

Starting the rendering (optional)#

There is also a new optional modifier that you can implement to perform additional validation of the input task and interrupt the rendering process if necessary:

.onShouldStart { task in
  true
}

Explicit use of AssetCatalog#

We deprecated the static .all properties to configure the assets used in the editor, e.g., StickerCategory.all, Frame.all, Effect.all, and Overlay.all. With this gentle change, we are continuing the transition towards the adoption of the AssetCatalog API introduced in version 10.3.0. We encourage you to explicitly use the .assetCatalog property of your Configuration/ConfigurationBuilder object from now on to configure your assets. Future versions of the SDK will remove the old .all API and change the default of ConfigurationBuilder.assetCatalog from AssetCatalog.shared to AssetCatalog.defaultItems while also removing the now deprecated AssetCatalog.shared instance. This will avoid unexpected side effects and allow you to conveniently append assets to the catalog without explicitly creating a new one, or caring about one-time initialization code for global variables.

In the following, we highlight the required changes to modernize the asset configuration of your codebase for the overlay tool. The same concept translates to the other asset types.

Replace default asset items#

If you are completely replacing our predefined items with your custom assets you'll need to move the assignment to your configuration closure as shown in the example below.

  let customOverlays: [Overlay] = [ /* ...*/ ]
- Overlay.all = customOverlays
+ let configuration = Configuration { builder in
+   builder.assetCatalog.overlays = customOverlays
+ }

  NSArray<PESDKOverlay *> *customOverlays = @[ /* ... */ ];
- PESDKOverlay.all = customOverlays;
+ PESDKConfiguration *configuration = [[PESDKConfiguration alloc] initWithBuilder:^(PESDKConfigurationBuilder * _Nonnull builder) {
+   builder.assetCatalog.overlays = customOverlays;
+ }];

Extend default asset items#

If you mix and match your custom assets with our predefined items you'll also need to move the modifications to your configuration closure as demonstrated below for appending your assets to our predefined ones. Make sure to explicitly use the defaultItems if your code runs more than once so that you won't accumulate more and more assets for every editor invocation.

  let customOverlays: [Overlay] = [ /* ...*/ ]
- Overlay.all = Overlay.defaultItems
- Overlay.all.append(customOverlays)
+ let configuration = Configuration { builder in
+   builder.assetCatalog = AssetCatalog.defaultItems // This line won't be necessary in future versions as it will be the default.
+   builder.assetCatalog.overlays.append(contentsOf: overlays)
+ }

  NSArray<PESDKOverlay *> *customOverlays = @[ /* ... */ ];
- PESDKOverlay.all = PESDKOverlay.defaultItems;
- PESDKOverlay.all = [PESDKOverlay.all arrayByAddingObjectsFromArray:customOverlays];
+ PESDKConfiguration *configuration = [[PESDKConfiguration alloc] initWithBuilder:^(PESDKConfigurationBuilder * _Nonnull builder) {
+   builder.assetCatalog = PESDKAssetCatalog.defaultItems; // This line won't be necessary in future versions as it will be the default.
+   builder.assetCatalog.overlays = [builder.assetCatalog.overlays arrayByAddingObjectsFromArray:customOverlays];
+ }];

IMGLY extension namespace#

We've moved all public extensions of UIKit, Foundation, and other iOS SDK types to the .imgly namespace for Swift and changed the prefix from pesdk_ to imgly_ for Objective-C, and deprecated the old ones. The reason for deprecation is that ImglyKit is a framework used in a lot of different scenarios, where we can expect that the application is using other frameworks as well which can lead to method and property name collisions in public extensions. In the future, non-namespaced methods will be removed. Affected public extensions are UIImage, Bundle, and Notification.Name.

- let overlay = Overlay(identifier: "imgly_overlay_golden", displayName: "Golden", url: Bundle.imglyBundle.url(forResource: "imgly_overlay_golden", withExtension: "jpg"), thumbnailURL: Bundle.imglyBundle.url(forResource: "imgly_overlay_golden_thumb", withExtension: "jpg"), initialBlendMode: .lighten)
+ let overlay = Overlay(identifier: "imgly_overlay_golden", displayName: "Golden", url: Bundle.imgly.resourceBundle.url(forResource: "imgly_overlay_golden", withExtension: "jpg"), thumbnailURL: Bundle.imgly.resourceBundle.url(forResource: "imgly_overlay_golden_thumb", withExtension: "jpg"), initialBlendMode: .lighten)

  var sampleImage = UIImage(named: "sample_image")
- sampleImage = sampleImage?.image(withTint: .black)
+ sampleImage = sampleImage?.imgly.image(withTint: .black)

- PESDKOverlay *overlay = [[PESDKOverlay alloc] initWithIdentifier:@"imgly_overlay_golden" displayName:@"Golden" url:[NSBundle.imglyBundle URLForResource:@"imgly_overlay_golden" withExtension:@"jpg"] thumbnailURL:[NSBundle.imglyBundle URLForResource:@"imgly_overlay_golden_thumb" withExtension:@"jpg"] initialBlendMode:PESDKBlendModeLighten];
+ PESDKOverlay *overlay = [[PESDKOverlay alloc] initWithIdentifier:@"imgly_overlay_golden" displayName:@"Golden" url:[NSBundle.imgly_resourceBundle URLForResource:@"imgly_overlay_golden" withExtension:@"jpg"] thumbnailURL:[NSBundle.imgly_resourceBundle URLForResource:@"imgly_overlay_golden_thumb" withExtension:@"jpg"] initialBlendMode:PESDKBlendModeLighten];

  UIImage* sampleImage = [UIImage imageNamed:@"sample_image"];
- sampleImage = [sampleImage pesdk_imageWithTintColor:UIColor.blackColor];
+ sampleImage = [sampleImage imgly_imageWithTintColor:UIColor.blackColor];