AVAssetTrack: Added durationTimecode() method

Author: orchetect

Sources/TimecodeKit/AVFoundation Extensions/AVAssetTrack Timecode Read.swift

@@ -13,6 +13,68 @@ import AVFoundation
 // MARK: - Helper methods
 
 extension AVAssetTrack {
+    /// Returns the track duration expressed as timecode.
+    ///
+    /// Passing a value to `frameRate` will override frame rate detection.
+    /// Passing `nil` will detect frame rate from the asset's contents if possible.
+    ///
+    /// - Throws: ``Timecode/MediaParseError`` or ``Timecode/ValidationError``
+    @_disfavoredOverload
+    public func durationTimecode(
+        at frameRate: TimecodeFrameRate? = nil,
+        limit: Timecode.UpperLimit = ._24hours,
+        base: Timecode.SubFramesBase = .default(),
+        format: Timecode.StringFormat = .default()
+    ) throws -> Timecode {
+        guard let frameRate = try frameRate ?? self.asset?.timecodeFrameRate()
+        else {
+            throw Timecode.MediaParseError.missingOrNonStandardFrameRate
+        }
+        
+        let range = try timecodeRange(
+            at: frameRate,
+            limit: limit,
+            base: base,
+            format: format
+        )
+        
+        return range.upperBound - range.lowerBound
+    }
+    
+    // MARK: - Helpers
+    
+    // Note:
+    // This shouldn't be public because it's not terribly useful and might be misleading.
+    // For example, if used on a timecode track ("tmcd"), this will often return a range
+    // that starts from 0 and ends with the duration, instead of providing the actual timecode track's
+    // start and end timecode. This is because it references the `timeRange` property.
+    //
+    /// Returns the track `timeRange` as a range of timecode.
+    ///
+    /// Passing a value to `frameRate` will override frame rate detection.
+    /// Passing `nil` will detect frame rate from the asset's contents if possible.
+    ///
+    /// - Throws: ``Timecode/MediaParseError``
+    @_disfavoredOverload
+    internal func timecodeRange(
+        at frameRate: TimecodeFrameRate? = nil,
+        limit: Timecode.UpperLimit = ._24hours,
+        base: Timecode.SubFramesBase = .default(),
+        format: Timecode.StringFormat = .default()
+    ) throws -> ClosedRange<Timecode> {
+        guard let frameRate = try frameRate ?? self.asset?.timecodeFrameRate()
+        else {
+            throw Timecode.MediaParseError.missingOrNonStandardFrameRate
+        }
+        
+        return try timeRange.timecodeRange(
+            at: frameRate,
+            limit: limit,
+            base: base,
+            format: format
+        )
+    }
+    
     /// Returns the start frame number from a timecode track.
     /// Returns `nil` if the track is not a timecode track.
     internal func readTimecodeSamples(

Tests/TimecodeKit-Unit-Tests/Unit Tests/AVFoundation Extensions/AVAssetTrack Timecode Read Tests.swift

@@ -0,0 +1,68 @@
+//
+//  AVAssetTrack Timecode Read Tests.swift
+//  TimecodeKit • https://github.com/orchetect/TimecodeKit
+//  © 2022 Steffan Andrews • Licensed under MIT License
+//
+
+// AVAssetReader is unavailable on watchOS so we can't support any AVAsset operations
+#if shouldTestCurrentPlatform && canImport(AVFoundation) && !os(watchOS)
+
+import XCTest
+@testable import TimecodeKit
+import AVFoundation
+
+class AVAssetTrack_TimecodeRead_Tests: XCTestCase {
+    override func setUp() { }
+    override func tearDown() { }
+    
+    // MARK: - Start/Duration/End Timecode
+    
+    func testReadTimecodeRange_23_976fps() throws {
+        let frameRate: TimecodeFrameRate = ._23_976
+        let url = try TestResource.timecodeTrack_23_976_Start_00_58_40_00.url()
+        let asset = AVAsset(url: url)
+        let track = try XCTUnwrap(asset.tracks.first)
+        
+        let correctStart = try TCC().toTimecode(at: frameRate)
+        let correctEnd = try TCC(m: 24, s: 10, f: 19, sf: 03)
+            .toTimecode(at: frameRate, format: [.showSubFrames])
+        
+        // even though it's a timecode track, its timeRange property relates to overall timeline of the asset,
+        // so its start is 0.
+        // print(track.timeRange)
+        //   start: CMTime(value: 0, timescale: 1000, flags: __C.CMTimeFlags(rawValue: 1), epoch: 0)
+        //   duration: CMTime(value: 1452244, timescale: 1000, flags: __C.CMTimeFlags(rawValue: 1), epoch: 0)
+        
+        // auto-detect frame rate
+        do {
+            let tcRange = try track.timecodeRange()
+            XCTAssertEqual(tcRange.lowerBound, correctStart)
+            XCTAssertEqual(tcRange.upperBound, correctEnd)
+        }
+        
+        // manually supply frame rate
+        do {
+            let tcRange = try track.timecodeRange(at: frameRate)
+            XCTAssertEqual(tcRange.lowerBound, correctStart)
+            XCTAssertEqual(tcRange.upperBound, correctEnd)
+        }
+    }
+    
+    func testReadDurationTimecode_23_976fps() throws {
+        let frameRate: TimecodeFrameRate = ._23_976
+        let url = try TestResource.timecodeTrack_23_976_Start_00_58_40_00.url()
+        let asset = AVAsset(url: url)
+        let track = try XCTUnwrap(asset.tracks.first)
+        
+        // duration
+        let correctDur = try TCC(m: 24, s: 10, f: 19, sf: 03)
+            .toTimecode(at: frameRate, format: [.showSubFrames])
+        
+        // auto-detect frame rate
+        XCTAssertEqual(try track.durationTimecode(), correctDur)
+        // manually supply frame rate
+        XCTAssertEqual(try track.durationTimecode(at: frameRate), correctDur)
+    }
+}
+
+#endif