SJSAssetExportSession is an alternative to AVAssetExportSession that lets you provide custom audio and video settings, without dropping down into the world of AVAssetReader and AVAssetWriter. It has similar capabilites to SDAVAssetExportSession but the API is completely different, the code is written in Swift, and it's ready for the world of strict concurrency.
You shouldn't have to read through audio settings and video settings just to set the bitrate, and setting the frame rate can be tricky, so there's a nicer API that builds these settings dictionaries with some commonly used settings.
The only way to install this package is with Swift Package Manager (SPM). Please file a new issue or submit a pull-request if you want to use something else.
This package is supported on iOS 17.0+, macOS Sonoma 14.0+, and visionOS 1.3+.
When you're integrating this into an app with Xcode then go to your project's Package Dependencies and enter the URL https://github.com/samsonjs/SJSAssetExportSession and then go through the usual flow for adding packages.
When you're integrating this using SPM on its own then add this to the list of dependencies your Package.swift file:
.package(url: "https://github.com/samsonjs/SJSAssetExportSession.git", .upToNextMajor(from: "0.6.0"))and then add "SJSAssetExportSession" to the list of dependencies in your target as well.
There are two ways of exporting assets: one using dictionaries for audio and video settings just like with SDAVAssetExportSession, and the other using a builder-like API with data structures for commonly used settings.
This should be fairly self-explanatory:
let sourceURL = URL.documentsDirectory.appending(component: "some-video.mov")
let sourceAsset = AVURLAsset(url: sourceURL, options: [
AVURLAssetPreferPreciseDurationAndTimingKey: true,
])
let destinationURL = URL.temporaryDirectory.appending(component: "shiny-new-video.mp4")
let exporter = ExportSession()
Task {
for await progress in exporter.progressStream {
print("Export progress: \(progress)")
}
}
try await exporter.export(
asset: sourceAsset,
video: .codec(.h264, width: 1280, height: 720),
to: destinationURL,
as: .mp4
)Most of the audio and video configuration is optional which is why there are no audio settings specified here. By default you get AAC with 2 channels at a 44.1 KHz sample rate.
Here are all of the parameters you can pass into the nice export method:
let sourceURL = URL.documentsDirectory.appending(component: "some-video.mov")
let sourceAsset = AVURLAsset(url: sourceURL, options: [
AVURLAssetPreferPreciseDurationAndTimingKey: true,
])
let destinationURL = URL.temporaryDirectory.appending(component: "shiny-new-video.mp4")
let exporter = ExportSession()
Task {
for await progress in exporter.progressStream {
print("Export progress: \(progress)")
}
}
let locationMetadata = AVMutableMetadataItem()
locationMetadata.key = AVMetadataKey.commonKeyLocation.rawValue as NSString
locationMetadata.keySpace = .common
locationMetadata.value = "+48.50176+123.34368/" as NSString
try await exporter.export(
asset: sourceAsset,
optimizeForNetworkUse: true,
metadata: [locationMetadata],
timeRange: CMTimeRange(start: .zero, duration: .seconds(1)),
audio: .format(.mp3).channels(1).sampleRate(22_050),
video: .codec(.h264, width: 1280, height: 720)
.fps(24)
.bitrate(1_000_000)
.color(.sdr),
to: destinationURL,
as: .mp4
)When you need all the control you can get down to the nitty gritty details. This code uses the same settings as the code above with one difference: a composition you pass in is used as is, so nothing scales it for you. renderSize only sets the size of the canvas, so a source larger than 1280×720 is cropped unless your layer instructions scale it too:
let sourceURL = URL.documentsDirectory.appending(component: "some-video.mov")
let sourceAsset = AVURLAsset(url: sourceURL, options: [
AVURLAssetPreferPreciseDurationAndTimingKey: true,
])
let destinationURL = URL.temporaryDirectory.appending(component: "shiny-new-video.mp4")
let exporter = ExportSession()
Task {
for await progress in exporter.progressStream {
print("Export progress: \(progress)")
}
}
let locationMetadata = AVMutableMetadataItem()
locationMetadata.key = AVMetadataKey.commonKeyLocation.rawValue as NSString
locationMetadata.keySpace = .common
locationMetadata.value = "+48.50176+123.34368/" as NSString
let videoComposition = try await AVMutableVideoComposition.videoComposition(withPropertiesOf: sourceAsset)
videoComposition.renderSize = CGSize(width: 1280, height: 720)
videoComposition.sourceTrackIDForFrameTiming = kCMPersistentTrackID_Invalid
videoComposition.frameDuration = CMTime(value: 600 / 24, timescale: 600) // 24 fps
videoComposition.colorPrimaries = AVVideoColorPrimaries_ITU_R_709_2
videoComposition.colorTransferFunction = AVVideoTransferFunction_ITU_R_709_2
videoComposition.colorYCbCrMatrix = AVVideoYCbCrMatrix_ITU_R_709_2
try await exporter.export(
asset: sourceAsset,
optimizeForNetworkUse: true,
metadata: [locationMetadata],
timeRange: CMTimeRange(start: .zero, duration: .seconds(1)),
audioOutputSettings: [
AVFormatIDKey: kAudioFormatMPEGLayer3,
AVNumberOfChannelsKey: NSNumber(value: 1),
AVSampleRateKey: NSNumber(value: 22_050),
],
videoOutputSettings: [
AVVideoCodecKey: AVVideoCodecType.h264.rawValue,
AVVideoCompressionPropertiesKey: [
AVVideoProfileLevelKey: AVVideoProfileLevelH264HighAutoLevel,
AVVideoAverageBitRateKey: NSNumber(value: 1_000_000),
] as [String: any Sendable],
AVVideoColorPropertiesKey: [
AVVideoColorPrimariesKey: AVVideoColorPrimaries_ITU_R_709_2,
AVVideoTransferFunctionKey: AVVideoTransferFunction_ITU_R_709_2,
AVVideoYCbCrMatrixKey: AVVideoYCbCrMatrix_ITU_R_709_2,
],
],
composition: videoComposition,
to: destinationURL,
as: .mp4
)It's an effective illustration of why the nicer API exists right? But when you need this flexibility then it's available for you.
AudioOutputSettings and VideoOutputSettings have a property named settingsDictionary and you can use that to bootstrap your own custom settings.
let sourceURL = URL.documentsDirectory.appending(component: "some-video.mov")
let sourceAsset = AVURLAsset(url: sourceURL, options: [
AVURLAssetPreferPreciseDurationAndTimingKey: true,
])
let destinationURL = URL.temporaryDirectory.appending(component: "shiny-new-video.mp4")
let exporter = ExportSession()
Task {
for await progress in exporter.progressStream {
print("Export progress: \(progress)")
}
}
var audioSettings = AudioOutputSettings.default.settingsDictionary
audioSettings[AVVideoAverageBitRateKey] = 65_536
let videoSettings = VideoOutputSettings
.codec(.hevc, width: 1280, height: 720)
.settingsDictionary
try await exporter.export(
asset: sourceAsset,
audioOutputSettings: audioSettings,
videoOutputSettings: videoSettings,
to: destinationURL,
as: .mp4
)When the output size differs from the source, the whole picture is scaled to fit inside it, keeping the aspect ratio, so a portrait video exported at 1280×720 is pillarboxed. Choose another way with scaleMode(_:): .fill covers the output and crops what overflows, and .stretch scales each axis to the output size, distorting the picture when the aspect ratio differs.
try await exporter.export(
asset: sourceAsset,
video: .codec(.h264, width: 1080, height: 1080).scaleMode(.fill),
to: destinationURL,
as: .mp4
)The raw settings method always fits. With your own composition, the scale mode isn't used; your layer instructions decide what goes where.
Exports keep the source's frame timing unless you ask for a rate, so each source frame is written as it comes. Ask for one with fps(_:) and every frame is written at exactly that rate: a sparse source like a 2 fps screen recording has frames repeated to fill it, a denser one has frames dropped, and the last frame fills to the end.
try await exporter.export(
asset: sourceAsset,
video: .codec(.h264, width: 1280, height: 720).fps(30),
to: destinationURL,
as: .mp4
)With your own composition, the same rule follows AVFoundation's: when sourceTrackIDForFrameTiming is kCMPersistentTrackID_Invalid, frames are written at the composition's frameDuration. A composition from AVMutableVideoComposition.videoComposition(withPropertiesOf:) times its frames from the source track, so it keeps the source's timing until you set those two properties. A new AVMutableVideoComposition() starts out with kCMPersistentTrackID_Invalid, so its frameDuration sets the rate.
Pass a drawFrame closure to draw into each video frame before it's encoded, for things like watermarks and overlays. It's handed a VideoFrame with a writable pixel buffer, the frame's presentation time, and the composition's colour properties. It works with both export methods.
let sourceURL = URL.documentsDirectory.appending(component: "some-video.mov")
let sourceAsset = AVURLAsset(url: sourceURL, options: [
AVURLAssetPreferPreciseDurationAndTimingKey: true,
])
let destinationURL = URL.temporaryDirectory.appending(component: "shiny-new-video.mp4")
let watermark = CIImage(contentsOf: URL.documentsDirectory.appending(component: "watermark.png"))!
let context = CIContext()
let exporter = ExportSession()
try await exporter.export(
asset: sourceAsset,
video: .codec(.h264, width: 1280, height: 720),
drawFrame: { frame in
let destination = CIRenderDestination(pixelBuffer: frame.pixelBuffer)
destination.blendKernel = .sourceOver
try context.startTask(toRender: watermark, to: destination).waitUntilCompleted()
},
to: destinationURL,
as: .mp4
)The pixel buffer is bi-planar YCbCr: 10-bit for HLG and PQ compositions and 8-bit otherwise, IOSurface-backed and Metal-compatible. drawFrame is called once per frame, one call at a time, and the frame is encoded as soon as it returns, so finish any GPU work first. Drawing a full frame with Core Image is slow at 4K, so for small overlays it's worth drawing just those pixels, for example with Metal. An error thrown from drawFrame stops the export and is rethrown from export.
The package in Benchmarks measures how much CPU time and memory exports take, on the test fixtures and on a bundle of real iPhone clips. See Benchmarks/Readme.md for running them and comparing a change.
Copyright © 2024-2025 Sami Samhuri sami@samhuri.net. Released under the terms of the MIT License.