Merge pull request #19 from orchetect/dev

Improved real time conversion & added additional unit test

Author: orchetect

Sources/TimecodeKit/Data Interchange/Timecode Real Time.swift

@@ -12,20 +12,14 @@ extension Timecode {
 
 	/// (Lossy) Returns the current timecode converted to a duration in real-time (wall-clock time), based on the frame rate.
 	///
-	/// Generally, `.realTimeValue` -> `.setTimecode(fromRealTimeValue:)` will produce equivalent results where 'from timecode' == 'out timecode'.
-	/// When setting, invalid values will cause the setter to fail silently. (Validation is based on the frame rate and `upperLimit` property.)
+	/// Generally, `.realTimeValue` -> `.setTimecode(fromRealTimeValue:)` will produce equivalent timecodes.
+	///
+	/// When setting, invalid values will cause the setter to fail silently.
+	/// (Validation is based on the frame rate and `upperLimit` property.)
 	public var realTimeValue: TimeInterval {
 
 		get {
-			var calc = Double(totalElapsedFrames) * (1.0 / frameRate.frameRateForRealTimeCalculation)
-			
-			// over-estimate so real time is just past the equivalent timecode
-			// so calculations of real time back into timecode work reliably
-			// otherwise, this math produces a real time value that can be a hair under the actual elapsed real time that would trigger the equivalent timecode
-			
-			calc += 0.00000001
-			
-			return calc
+			Double(totalElapsedFrames) * (1.0 / frameRate.frameRateForRealTimeCalculation)
 		}
 
 		set {
@@ -36,18 +30,19 @@ extension Timecode {
 	}
 
 	/// Sets the timecode to the nearest frame at the current frame rate from real-time (wall-clock time).
+	///
 	/// Returns false if it underflows or overflows valid timecode range.
+	/// (Validation is based on the frame rate and `upperLimit` property.)
 	@discardableResult
 	public mutating func setTimecode(fromRealTimeValue: TimeInterval) -> Bool {
 
 		// the basic calculation
 		var calc = fromRealTimeValue / (1.0 / frameRate.frameRateForRealTimeCalculation)
 
 		// over-estimate so real time is just past the equivalent timecode
-		// so calculations of real time back into timecode work reliably
-		// otherwise, this math produces a real time value that can be a hair under the actual elapsed real time that would trigger the equivalent timecode
+		// since raw time values in practise can be a hair under the actual elapsed real time that would trigger the equivalent timecode (due to precision and rounding behaviors that may not be in our control, depending on where the passed real time value originated)
 
-		calc += 0.0000006
+		calc += 0.000_010 // 10 microseconds
 
 		// final calculation
 

Tests/TimecodeKit-Unit-Tests/Unit Tests/Data Interchange/Timecode Real Time Tests.swift

@@ -161,6 +161,104 @@ class Timecode_UT_DI_Real_Time_Tests: XCTestCase {
 
 	}
 
+	func testTimecode_RealTimeValue_RealWorld_SubFrames() {
+		
+		// test against real-world values extracted from DAWs
+		
+		// Cubase 11 XML file output (high resolution floating-point times in seconds)
+		
+		// the timecodes in the constant variable names are the timecodes as seen in Cubase
+		// the float-point number constant values are extracted from a Track Archive XML file exported from the Cubase project which outputs very high precision float-point numbers in seconds to define many attributes such as the project start time, and event start times and lengths on tracks which are in absolute time mode (not musical bars/beats mode which gets stored as PPQ values in the XML file instead of float-point seconds)
+		
+		
+		// 23.976fps, 80 subframe divisor
+		
+		//  _HH_MM_SS_FF_SF
+		
+		// session start timecode
+		let _00_49_27_15_00 = 2970.5926250000002255546860396862030029296875
+		
+		// events: delta times from session start time
+		let _00_49_29_17_00_delta = 2.0854162836310767836778268247144296765327453613281
+		let _00_49_31_09_00_delta = 3.7537499627098442900319241744000464677810668945312
+		let _00_49_33_21_79_delta = 6.297436893962323978257700218819081783294677734375
+		let _00_49_38_01_79_delta = 10.468270548180987233877203834708780050277709960938
+		
+		// test timecode formation from real time
+		
+		let start = Timecode(realTimeValue: _00_49_27_15_00,
+							 at: ._23_976)!
+		XCTAssertEqual(start.components,
+					   TCC(h: 00, m: 49, s: 27, f: 15, sf: 00))
+		
+		let event1 = Timecode(realTimeValue: _00_49_27_15_00 + _00_49_29_17_00_delta,
+							  at: ._23_976)!
+		XCTAssertEqual(event1.components,
+					   TCC(h: 00, m: 49, s: 29, f: 17, sf: 00))
+		
+		let event2 = Timecode(realTimeValue: _00_49_27_15_00 + _00_49_31_09_00_delta,
+							  at: ._23_976)!
+		XCTAssertEqual(event2.components,
+					   TCC(h: 00, m: 49, s: 31, f: 09, sf: 00))
+		
+		let event3 = Timecode(realTimeValue: _00_49_27_15_00 + _00_49_33_21_79_delta,
+							  at: ._23_976)!
+		XCTAssertEqual(event3.components,
+					   TCC(h: 00, m: 49, s: 33, f: 21, sf: 79))
+		
+		let event4 = Timecode(realTimeValue: _00_49_27_15_00 + _00_49_38_01_79_delta,
+							  at: ._23_976)!
+		XCTAssertEqual(event4.components,
+					   TCC(h: 00, m: 49, s: 38, f: 01, sf: 79))
+		
+		// test real time matching the seconds constants
+		
+		// start
+		XCTAssertEqual(
+			TCC(h: 00, m: 49, s: 27, f: 15, sf: 00)
+				.toTimecode(at: ._23_976)!
+				.realTimeValue,
+			_00_49_27_15_00
+		)
+		
+		// event1
+		XCTAssertEqual(
+			TCC(h: 00, m: 49, s: 29, f: 17, sf: 00)
+				.toTimecode(at: ._23_976)!
+				.realTimeValue,
+			_00_49_27_15_00 + _00_49_29_17_00_delta,
+			accuracy: 0.0000005
+		)
+		
+		// event2
+		XCTAssertEqual(
+			TCC(h: 00, m: 49, s: 31, f: 09, sf: 00)
+				.toTimecode(at: ._23_976)!
+				.realTimeValue,
+			_00_49_27_15_00 + _00_49_31_09_00_delta,
+			accuracy: 0.0000005
+		)
+		
+		// event3
+		XCTAssertEqual(
+			TCC(h: 00, m: 49, s: 33, f: 21, sf: 79)
+				.toTimecode(at: ._23_976)!
+				.realTimeValue,
+			_00_49_27_15_00 + _00_49_33_21_79_delta,
+			accuracy: 0.0000005
+		)
+		
+		// event4
+		XCTAssertEqual(
+			TCC(h: 00, m: 49, s: 38, f: 01, sf: 79)
+				.toTimecode(at: ._23_976)!
+				.realTimeValue,
+			_00_49_27_15_00 + _00_49_38_01_79_delta,
+			accuracy: 0.0000005
+		)
+		
+	}
+	
 }
 
 #endif