VideoExporter

@objcMembers
public class VideoExporter

The VideoExporter is responsible for exporting SessionVideo and SessionVideoSegment objects.

For example, you can export a video to an mp4 file with the following:

if let video = session.video {
    VideoExporter.shared.export(video: video, progress: { progress in
        print("Export progress: \(progress)")
    }, completion: { error in
        if let error = error {
            print("Unable to export video: \(error)")
            return
        }

        print("Finished video export at URL: \(video.exportedVideoURL)")
    })
}

After the export has completed, you should use, move or copy the file found at the exportedVideoURL. Once you are finished with the file, you should call destroy() on the session in order to remove the video from the users drafts and delete its associated files.

Frame rate can be customized by setting the frameDuration variable before exporting the video.

You can also change renderSize but we recommend you instead set the aspectRatio and aspectRatio. See the square content example. These properties allow you to preserve video quality by delaying any upscaling or downscaling until a later point in your video processing logic. If you plan on converting your video to HLS on a server that encoder should handle any upscaling or downscaling.

Default Encoding Settings

If you do not provide a fileType, videoEncodingSettings, or audioEncodingSettings the default settings will be an mp4 file with H.264 video encoding and stereo AAC audio encoding:

import AVFoundation
var acl = AudioChannelLayout()
memset(&acl, 0, MemoryLayout<AudioChannelLayout>.size)
acl.mChannelLayoutTag = kAudioChannelLayoutTag_Stereo

let audioEncodingSettings: [String: Any] = [
    AVFormatIDKey: kAudioFormatMPEG4AAC,
    AVNumberOfChannelsKey: 2,
    AVSampleRateKey: AVAudioSession.sharedInstance().sampleRate,
    AVChannelLayoutKey: NSData(bytes:&acl, length:MemoryLayout<AudioChannelLayout>.size),
    AVEncoderBitRateKey: 96000
]

let videoEncodingSettings: [String: Any] = [
    AVVideoCompressionPropertiesKey: [
        AVVideoProfileLevelKey: AVVideoProfileLevelH264HighAutoLevel,
        AVVideoH264EntropyModeKey: AVVideoH264EntropyModeCABAC],
    AVVideoCodecKey: AVVideoCodecType.h264
]

VideoExporter.shared.export(video: session.video!,
                            fileType: .mp4,
                            videoEncodingSettings: videoEncodingSettings,
                            audioEncodingSettings: audioEncodingSettings,
                            progress: nil,
                            completion: { error in

})

There are many combinations of encoding settings you can provide. They must conform to the specifications set forth in AVFoundations AVVideoSettings.h and AVAudioSettings.h headers. There is also a list of available codecs. Keep in mind each codec may have different requirements for the settings you provide.

HEVC Encoding Settings

Below is an example of HEVC encoding settings:

import AVFoundation
import VideoToolbox
let videoEncodingSettings: [String: Any] = [
    AVVideoCompressionPropertiesKey: [
        AVVideoProfileLevelKey: kVTProfileLevel_HEVC_Main_AutoLevel],
    AVVideoCodecKey: AVVideoCodecType.hevc
]

Pricing

The following pricing matrix applies to export functions in this class.

If you do not provide an API key or it is invalid, exported videos will include a watermark.

Getting the Shared VideoExporter

  • Use this to access the shared instance of the VideoExporter. For example to access the export status:

    print("Is exporting: \(VideoExporter.shared.isExporting)")
    

    Declaration

    Swift

    public static let shared: VideoExporter

Export Status

  • Indicates if the VideoExporter is currently exporting anything.

    Default value: false

    Declaration

    Swift

    public var isExporting: Bool { get }

Video Exports

  • Exports a SessionVideo object with the provided video and audio settings. If you do not provide any settings the defaults will be used. After the completion closure is called the exported video file will be available at the exportedVideoURL variable on the video. You can move, copy or delete this file at your own discretion.

    Attention

    When this is called, any other existing video export will be cancelled.

    Declaration

    Swift

    public func export(video: SessionVideo,
                       fileType: AVFileType = .mp4,
                       videoEncodingSettings: [String: Any]? = nil,
                       audioEncodingSettings: [String: Any]? = nil,
                       progress: ((Double) -> Void)?  = nil,
                       completion: @escaping (VideoExporterError?) -> Void)

    Parameters

    video

    The video to export.

    fileType

    The export file type.

    videoEncodingSettings

    The video encoding settings.

    audioEncodingSettings

    The audio encoding settings.

    progress

    This closure will be called each time the export progress is updated. The parameter will contain the progress of the export in a 0.0 to 1.0 range.

    completion

    This closure will be called when the export succeeds or fails. If the export failed there will be an error present.

  • Exports multiple SessionVideo objects with the provided video and audio settings. If you do not provide any settings the defaults will be used. After the completion closure is called the exported video files will be available at the exportedVideoURL variable for each respective video. You can move, copy or delete these files at your own discretion.

    Attention

    When this is called, any other existing video export will be cancelled.

    Declaration

    Swift

    public func export(videos: [SessionVideo],
                        fileType: AVFileType = .mp4,
                        videoEncodingSettings: [String: Any]? = nil,
                        audioEncodingSettings: [String: Any]? = nil,
                        progress: ((Double) -> Void)?  = nil,
                        completion: @escaping (VideoExporterError?) -> Void)

    Parameters

    videos

    The videos to export. You must provide at least one video.

    fileType

    The export file type.

    videoEncodingSettings

    The video encoding settings.

    audioEncodingSettings

    The audio encoding settings.

    progress

    This closure will be called each time the export progress is updated. The parameter will contain the progress of the export in a 0.0 to 1.0 range.

    completion

    This closure will be called when the export succeeds or fails. If the export failed there will be an error present.

Video Segment Exports

  • Exports a SessionVideoSegment object with the provided video and audio settings. If you do not provide any settings the defaults will be used. After the completion closure is called the exported video segment file will be available at the exportedVideoURL variable on the video segment. You can move, copy or delete this file at your own discretion.

    Attention

    When this is called, any other existing video export will be cancelled.

    Declaration

    Swift

    public func export(segment: SessionVideoSegment,
                       fileType: AVFileType = .mp4,
                       videoEncodingSettings: [String: Any]? = nil,
                       audioEncodingSettings: [String: Any]? = nil,
                       progress: ((Double) -> Void)?  = nil,
                       completion: @escaping (VideoExporterError?) -> Void)

    Parameters

    segment

    The video segment to export.

    fileType

    The export file type.

    videoEncodingSettings

    The video encoding settings.

    audioEncodingSettings

    The audio encoding settings.

    progress

    This closure will be called each time the export progress is updated. The parameter will contain the progress of the export in a 0.0 to 1.0 range.

    completion

    This closure will be called when the export succeeds or fails. If the export failed there will be an error present.

  • Exports multiple SessionVideoSegment objects with the provided video and audio settings. If you do not provide any settings the defaults will be used. After the completion closure is called the exported video segment files will be available at the exportedVideoURL variable for each respective video segment. You can move, copy or delete these files at your own discretion.

    Attention

    When this is called, any other existing video export will be cancelled.

    Declaration

    Swift

    public func export(segments: [SessionVideoSegment],
                       fileType: AVFileType = .mp4,
                       videoEncodingSettings: [String: Any]? = nil,
                       audioEncodingSettings: [String: Any]? = nil,
                       progress: ((Double) -> Void)?  = nil,
                       completion: @escaping (VideoExporterError?) -> Void)

    Parameters

    segments

    The video segments to export. You must provide at least one video segment.

    fileType

    The export file type.

    videoEncodingSettings

    The video encoding settings.

    audioEncodingSettings

    The audio encoding settings.

    progress

    This closure will be called each time the export progress is updated. The parameter will contain the progress of the export in a 0.0 to 1.0 range.

    completion

    This closure will be called when the export succeeds or fails. If the export failed there will be an error present.

Cancel Export

  • Cancels any existing video or video segment export.

    Declaration

    Swift

    public func cancelExport(completion: (() -> Void)? = nil)

    Parameters

    completion

    This closure will be called after the export has been cancelled. If there is no export, the closure will be called immediately.