Extract the Start Timecode from a Quicktime Movie

Sun, 10 May 2026 18:55:19 -0700
This is a trifle but I was stuck on it for some time, even if you follow all of the documentation there’s a trick to it.
import AVFoundation
import CoreMedia

enum MovieTimecodeExtractionError: Error {
 case IntegrityError
}

enum MovieTimecodeExtractionResult {
 case Success(CMTime)
 case NoTimecodeTrack
 case NoTimecodeSamples
}

/// Get the first timecode value from a movie file.
///
/// This function uses AVFoundation and will attempt to load timecode tracks from the
/// given movie. This is appropriate for QuickTime `.mov` and `.mp4`-type files.
///
/// If the movie was succesfully read, the function will either return the time value as a
/// `CMTime` if timecode was found, or `nil` if
/// - The movie contained no timecode track, or
/// - The movie contains a timecode track but that track has no timecode samples
///
func extractStartTimecode(from url: URL) async throws
 -> MovieTimecodeExtractionResult
{
 let asset = AVURLAsset(url: url)

 // all of this is pretty straighforward...
 guard
 let timecodeTrack = try await asset.loadTracks(withMediaType: .timecode)
 .first
 else {
 return .NoTimecodeTrack
 }

 let reader = try AVAssetReader(asset: asset)
 let output = AVAssetReaderTrackOutput(
 track: timecodeTrack,
 outputSettings: nil
 )
 reader.add(output)
 guard reader.startReading() else {
 throw reader.error!
 }

 // This is where I got tripped-up...
 // What I didn't know was that the `output` here can (and does) return
 // valid sampleBuffers that, despite being valid, contain no data...
 while let sampleBuffer = output.copyNextSampleBuffer() {

 guard
 let formatDescription: CMFormatDescription =
 CMSampleBufferGetFormatDescription(sampleBuffer),
 let blockBuffer: CMBlockBuffer = CMSampleBufferGetDataBuffer(
 sampleBuffer
 )
 else {
 // ...so I'd get here, and when these two were nil, I initially assumed
 // that this meant the output was exhausted. Not the case!
 //
 // If these are nil, that just means this sampleBuffer was empty, but
 // there are more sampleBuffers and the output will return these from
 // copyNextSampleBuffer, and you should only stop iterating the output
 // when copyNextSampleBuffer returns nil.

 // If we're here, either of these were nil, and so the correct thing
 // to do now is to advance to the next sampleBuffer.
 continue
 }

 let frameQuanta = CMTimeCodeFormatDescriptionGetFrameQuanta(
 formatDescription
 )

 var rawData: UnsafeMutablePointer<Int8>? = nil
 var length: Int = 0
 var totalLength: Int = 0

 let error = CMBlockBufferGetDataPointer(
 blockBuffer,
 atOffset: 0,
 lengthAtOffsetOut: &length,
 totalLengthOut: &totalLength,
 dataPointerOut: &rawData
 )

 guard error == kCMBlockBufferNoErr else {
 throw NSError(domain: NSOSStatusErrorDomain, code: Int(error))
 }

 guard let tcData = rawData else {
 // I'm not sure how we would get here if error was noErr.
 throw MovieTimecodeExtractionError.IntegrityError
 }

 let type = CMFormatDescriptionGetMediaSubType(formatDescription)
 let frames: CMTimeValue?

 switch type {
 case kCMTimeCodeFormatType_TimeCode32:
 let fr0 = tcData.withMemoryRebound(
 to: UInt32.self,
 capacity: 1,
 { CFSwapInt32BigToHost($0.pointee) }
 )
 frames = CMTimeValue(fr0)

 case kCMTimeCodeFormatType_TimeCode64:
 let fr0 = tcData.withMemoryRebound(
 to: UInt64.self,
 capacity: 1,
 { CFSwapInt64BigToHost($0.pointee) }
 )
 frames = CMTimeValue(fr0)

 default:
 // IF we're here, `type` is probably one of the
 // kCMTimeCodeFormatType_Counter* values, which are not useable to
 // this function
 frames = nil
 }
 reader.cancelReading()

 return frames.flatMap {
 .Success(
 CMTime(
 value: $0,
 timescale: CMTimeScale(frameQuanta)
 )
 )
 } ?? .NoTimecodeSamples
 }

 // We're here if the `while` never found a timecode databuffer
 switch reader.status {
 case .completed:
 return .NoTimecodeSamples
 case .failed:
 throw reader.error!
 default:
 throw MovieTimecodeExtractionError.IntegrityError
 }
}
Swift on

Extract the Start Timecode from a Quicktime Movie
