skip to content

With AVFoundation, how do you join trimmed dance clips into one lesson video with AVMutableComposition and export it, and why might the result play sideways?

level: seniorimportance: should knowfreq 32%

answer

  1. load properties before you use them
  2. a running cursor along the timeline
  3. tracks get segments, not properties
  4. the transform a portrait clip carries
  5. the async export that throws

basics

~20 s

Load each AVURLAsset's duration and tracks asynchronously, insert each clip's time range into composition tracks at a running cursor, copy the source track's preferredTransform, then export with AVAssetExportSession's export(to:as:). A missing preferredTransform makes it play sideways.

solid answer

~30 s

I create an `AVMutableComposition` with one video and one audio track from `addMutableTrack(withMediaType:preferredTrackID:)`. For each clip I make an `AVURLAsset`, `try await asset.load(.duration)` and `loadTracks(withMediaType:)`, and call `insertTimeRange(_:of:at:)` on each composition track with the trimmed `CMTimeRange`, advancing a cursor. Inserting copies segments only, not track properties, so a portrait clip loses its rotation unless I set `preferredTransform` from the source track; that is the sideways video. Then `AVAssetExportSession(asset:presetName:)` with a preset such as `AVAssetExportPresetHighestQuality`, and `try await export(to:as:)`, which throws on failure and cancels with its task. Progress comes from `states(updateInterval:)` on iOS 18 and later. For frame-level control, `AVAssetWriter`.

code

swift · 29 lines
swift
import AVFoundation

func buildLesson(from clips: [URL], to output: URL) async throws {
    let composition = AVMutableComposition()
    guard let video = composition.addMutableTrack(withMediaType: .video,
                                                  preferredTrackID: kCMPersistentTrackID_Invalid),
          let audio = composition.addMutableTrack(withMediaType: .audio,
                                                  preferredTrackID: kCMPersistentTrackID_Invalid)
    else { return }
    var cursor = CMTime.zero
    for url in clips {
        let asset = AVURLAsset(url: url)
        let duration = try await asset.load(.duration)
        let range = CMTimeRange(start: .zero, duration: duration)
        if let sourceVideo = try await asset.loadTracks(withMediaType: .video).first {
            try video.insertTimeRange(range, of: sourceVideo, at: cursor)
            video.preferredTransform = try await sourceVideo.load(.preferredTransform)
        }
        if let sourceAudio = try await asset.loadTracks(withMediaType: .audio).first {
            try audio.insertTimeRange(range, of: sourceAudio, at: cursor)
        }
        cursor = cursor + duration
    }
    guard let export = AVAssetExportSession(asset: composition,
                                            presetName: AVAssetExportPresetHighestQuality)
    else { return }
    try? FileManager.default.removeItem(at: output)
    try await export.export(to: output, as: .mp4)
}

go deeper

for a junior

Recall that a composition is a timeline of references to clips, and that an export session renders it to a file.

for a middle

Explain async property loading, inserting time ranges at a cursor, and how presets differ, passthrough especially.

for a senior

Diagnose the sideways export from the missing preferredTransform, handle mixed orientations, and run export with cancellation and progress.

for a principal

Judge when presets stop serving the product and an AVAssetWriter pipeline is worth its cost, and who owns codec settings.

## The pieces of an edit AVFoundation edits without copying media. An **`AVAsset`** describes timed media; **`AVURLAsset`** is one backed by a file. An **`AVMutableComposition`** is itself an asset, assembled from **track segments** that point into other assets, so building one is cheap. Nothing is decoded until a player plays it or an **`AVAssetExportSession`** renders it to a file. The lesson builder therefore has three phases: load the clips, lay them out on a timeline, export. ## Load properties asynchronously An asset's properties, such as `duration`, `tracks` and a track's `preferredTransform`, may need I/O to read. Since **iOS 15**, Swift loads them with **`load(_:)`**: `try await asset.load(.duration)`, or several at once with `load(.duration, .tracks)`, plus `loadTracks(withMediaType:)`. The synchronous `duration` and `tracks` properties are deprecated for Swift from iOS 16, with "Use load(.duration) instead". The older callback API, `loadValuesAsynchronously(forKeys:completionHandler:)`, is deprecated for Swift from iOS 16 with "Use load(_:) instead". ## Lay the clips on the timeline 1. Create the composition and add one video and one audio track with `addMutableTrack(withMediaType:preferredTrackID:)`, passing `kCMPersistentTrackID_Invalid` to let AVFoundation pick IDs. 2. For each clip, build the trimmed `CMTimeRange`, here the whole clip from `.zero`, or a start and duration to trim. 3. Call `insertTimeRange(_:of:at:)` on each composition track with the source `AVAssetTrack` and the cursor time, then advance the cursor by the inserted duration. The composition also has an asset-level `insertTimeRange(_:of:at:)`, which inserts every track of a clip at once; in Swift it is `async` from iOS 16. The header notes that existing content at the insertion time is **pushed later** by the inserted duration, so the cursor approach appends cleanly. ## Why the lesson plays sideways The header for insertion is explicit: it **only inserts track segments and does not affect other track properties**. A clip filmed in portrait typically stores its rotation as the source track's **`preferredTransform`**, a transform applied on display, rather than in its pixels. Insertion does not copy that transform to the composition track, so the exported video shows the stored pixels unrotated and the lesson looks sideways. The fix is to load the source track's `preferredTransform` and assign it to the composition track. That works when every clip shares an orientation; mixing portrait and landscape needs a video composition with per-clip layer instructions, built in Swift with `AVVideoComposition.Configuration` from iOS 26, where `AVMutableVideoComposition` is deprecated for Swift. ## Export `AVAssetExportSession(asset:presetName:)` is failable and takes a preset: | Preset | Effect | |---|---| | `AVAssetExportPresetHighestQuality` | re-encodes at the best quality available | | `AVAssetExportPresetMediumQuality` | re-encodes smaller, for sharing | | `AVAssetExportPreset1920x1080` | re-encodes to a fixed size | | `AVAssetExportPresetPassthrough` | copies samples without re-encoding; ignores `videoComposition` and `audioMix` | In Swift, **`try await export(to:as:)`** is the call: it sets the URL and file type, runs the export, **throws** the session's error on failure and throws `CancellationError` when its task is cancelled. It is declared available from iOS 13 through back deployment, so it is not tied to one release. The SDK has deprecated the older Swift surface in two steps: - **iOS 18:** `exportAsynchronously(completionHandler:)`, `status` and `error`, with `states(updateInterval:)` as the progress stream. - **iOS 27:** `outputURL`, `outputFileType` and `progress`, plus `cancelExport()` in favour of `Task.cancel()`. Export a lesson to a fresh URL in a temporary directory, and clear any file left by an earlier attempt first. ## When presets are not enough `AVAssetWriter` writes media sample by sample with your own `AVAssetWriterInput` settings: exact bitrates, codecs or frames generated by the app. It costs far more code than an export session; reach for it only when no preset fits. ## Mistakes worth catching in review - Reading `duration` or `tracks` synchronously, which the Swift SDK has deprecated since iOS 16 and which can block on I/O. - Forgetting `preferredTransform`, the cause of the sideways lesson. - Copying one clip's transform onto a track that holds clips of different orientations. - Choosing passthrough and then wondering why a fade or a rotation fix did nothing. - Calling `exportAsynchronously(completionHandler:)` and checking `status` in new Swift code instead of `try await export(to:as:)`. - Running a long export without a way to cancel it when the instructor leaves the screen.

  • How do you show export progress on the iOS 27 SDK?
    Iterate `states(updateInterval:)`, available from iOS 18, in a child task while `export(to:as:)` runs; the `.exporting(progress:)` case carries a `Progress`. The `progress` property is deprecated for Swift in iOS 27; on iOS 17 the app still polls it, since it is not key-value observable.
  • When is AVAssetExportPresetPassthrough the right preset?
    When the clips already share a codec and you only cut and join them: it copies samples without re-encoding, so it is fast and lossless. It ignores a `videoComposition` and an `audioMix`, so it cannot fix mixed orientations or apply a fade.
  • How do you cancel a long export when the instructor leaves the screen?
    Cancel the Swift task running `export(to:as:)`. Its cancellation handler cancels the session, and the call throws `CancellationError`. `cancelExport()` is deprecated for Swift in iOS 27 in favour of `Task.cancel()`.

  • insertTimeRange copies the source track's rotation automatically
  • Reading asset.duration synchronously is fine on the main thread
  • The passthrough preset applies the attached video composition
  • exportAsynchronously(completionHandler:) is the current Swift export API
  • A composition duplicates the source media into memory

Assumes the iOS 27.1 SDK: async load(_:) is iOS 15, export(to:as:) back-deploys to iOS 13, and iOS 27 deprecates outputURL, progress and cancelExport() for Swift.