@@ -11,6 +11,13 @@ let minimumPinchVisibility: CFTimeInterval = 0.5
1111let swipeVisibilityTail : CFTimeInterval = 0.16
1212let trailOpacityKeyTimes : [ NSNumber ] = [ 0.0 , 0.08 , 0.62 , 1.0 ]
1313
14+ // A compositor that cannot render frames still completes with an empty track, so a whole frame at
15+ // or below this mean luma counts as black.
16+ let compositedBlackFrameLuma : Double = 1.0
17+ // Above this mean luma the raw capture is taken to hold visible content worth preserving. Below it
18+ // the recording itself is dark, so a dark composite is the content and not a compositor failure.
19+ let sourceVisibleFrameLuma : Double = 2.0
20+
1421struct GestureEnvelope : Decodable {
1522 let events : [ GestureEvent ]
1623}
@@ -126,10 +133,10 @@ func run() throws {
126133 in : parentLayer
127134 )
128135
129- // Overlay burn-in forces a full re-encode; medium quality keeps simulator videos readable
130- // while avoiding very slow highest-quality exports. Pass --quality high to opt into
131- // the slower highest-quality export .
132- let presetName = exportPresetName ( for : parsedArgs . exportQuality , compatibleWith : composition )
136+ // Overlay burn-in forces a full re-encode. The export has to keep the captured track's own
137+ // dimensions, so it uses the one preset that preserves arbitrary capture geometry; the hardware
138+ // encoder makes the full-resolution re-encode cheap (measured ~1-2s for a 90s 1206x2622 clip) .
139+ let presetName = try exportPresetName ( compatibleWith : composition )
133140 let exporter = try makeRecordingExporter (
134141 composition ,
135142 presetName : presetName ,
@@ -141,17 +148,19 @@ func run() throws {
141148 timeoutMessage : " Touch overlay export timed out. " ,
142149 failureMessage : " Touch overlay export failed. "
143150 )
151+ try verifyCompositedOverlay (
152+ input : inputURL ,
153+ output : outputURL ,
154+ expectedRenderSize : renderSize
155+ )
144156}
145157
146158func parseArguments (
147159 _ arguments : [ String ]
148- ) throws -> ( inputPath : String , outputPath : String , eventsPath : String , exportQuality : ExportQuality ) {
160+ ) throws -> ( inputPath : String , outputPath : String , eventsPath : String ) {
149161 var inputPath : String ?
150162 var outputPath : String ?
151163 var eventsPath : String ?
152- // Export quality defaults to medium so existing callers keep the fast, simulator-friendly
153- // export. Pass --quality high to opt into a slower highest-quality export.
154- var exportQuality : ExportQuality = . medium
155164 var index = 0
156165
157166 while index < arguments . count {
@@ -168,11 +177,13 @@ func parseArguments(
168177 eventsPath = try recordingOptionValue ( arguments , nextIndex , " --events " )
169178 index += 2
170179 case " --quality " :
180+ // Accepted for CLI parity with the other backends and still validated, but the composited
181+ // export always preserves the captured geometry (see `exportPresetName`), so the tier never
182+ // picks a resolution-capping preset and is not retained.
171183 let rawValue = try recordingOptionValue ( arguments , nextIndex , " --quality " )
172- guard let parsed = ExportQuality ( rawValue : rawValue ) else {
184+ guard ExportQuality ( rawValue : rawValue ) != nil else {
173185 throw RecordingScriptError . invalidArgs ( " --quality must be one of: medium, high " )
174186 }
175- exportQuality = parsed
176187 index += 2
177188 default :
178189 throw RecordingScriptError . invalidArgs ( " Unknown argument: \( argument ) " )
@@ -184,31 +195,140 @@ func parseArguments(
184195 " Usage: recording-overlay.swift --input <video> --output <video> --events <json> [--quality <medium|high>] "
185196 )
186197 }
187- return ( inputPath , outputPath , eventsPath , exportQuality )
198+ return ( inputPath , outputPath , eventsPath )
188199}
189200
190- func exportPresetName (
191- for exportQuality : ExportQuality ,
192- compatibleWith asset : AVAsset
193- ) -> String {
194- switch exportQuality {
195- case . high :
196- return AVAssetExportPresetHighestQuality
197- case . medium :
198- // Prefer the faster medium preset, falling back to highest quality only when medium is
199- // not available for this composition.
200- let compatible = AVAssetExportSession . exportPresets ( compatibleWith : asset )
201- return compatible . contains ( AVAssetExportPresetMediumQuality )
202- ? AVAssetExportPresetMediumQuality
203- : AVAssetExportPresetHighestQuality
201+ /// The composited overlay must keep the captured track's dimensions, so it can only use a preset
202+ /// that preserves source geometry. The fixed-canvas presets rescale the long edge —
203+ /// `AVAssetExportPresetMediumQuality` caps it at 480px, which is exactly what collapsed every
204+ /// touch-bearing recording to ~220x480 (#2707). Only `HighestQuality` preserves the capture, and it
205+ /// is the export for every quality tier, so `--quality` never trades capture resolution away. If a
206+ /// composition offers no geometry-preserving preset the export refuses rather than rescaling.
207+ func exportPresetName ( compatibleWith asset : AVAsset ) throws -> String {
208+ guard AVAssetExportSession . exportPresets ( compatibleWith : asset ) . contains ( AVAssetExportPresetHighestQuality ) else {
209+ throw RecordingScriptError . exportFailed (
210+ " No geometry-preserving export preset is available; refusing to rescale the capture. "
211+ )
204212 }
213+ return AVAssetExportPresetHighestQuality
205214}
206215
207216func resolvedRenderSize ( for track : AVAssetTrack ) -> CGSize {
208217 let transformed = track . naturalSize . applying ( track . preferredTransform )
209218 return CGSize ( width : abs ( transformed . width ) , height : abs ( transformed . height ) )
210219}
211220
221+ /// Guards the compositor's own contract before the caller adopts its output: the burn-in must keep
222+ /// the captured track's dimensions, must produce frames, and must not silently become an all-black
223+ /// track. Any failure throws, dropping the overlay and keeping the raw capture rather than
224+ /// publishing a broken file with a success exit.
225+ func verifyCompositedOverlay ( input : URL , output : URL , expectedRenderSize : CGSize ) throws {
226+ let composited = AVURLAsset ( url : output )
227+ guard let track = composited . tracks ( withMediaType : . video ) . first else {
228+ throw RecordingScriptError . exportFailed ( " Touch overlay export produced no video track. " )
229+ }
230+
231+ let producedSize = resolvedRenderSize ( for : track )
232+ if ! renderSizeMatches ( producedSize , expectedRenderSize ) {
233+ throw RecordingScriptError . exportFailed (
234+ " Touch overlay export changed the track geometry: \( Int ( producedSize . width ) ) x \( Int ( producedSize . height ) ) instead of \( Int ( expectedRenderSize . width ) ) x \( Int ( expectedRenderSize . height ) ) . "
235+ )
236+ }
237+
238+ // A compositor that produced no decodable frames is a failure, not an absence of evidence.
239+ guard let compositedLuma = meanFrameLuma ( of : composited ) else {
240+ throw RecordingScriptError . exportFailed ( " Touch overlay export produced no decodable frames. " )
241+ }
242+
243+ let source = AVURLAsset ( url : input )
244+ let sourceDuration = CMTimeGetSeconds ( source . duration )
245+ let producedDuration = CMTimeGetSeconds ( composited . duration )
246+ if sourceDuration . isFinite , sourceDuration > 1 , producedDuration . isFinite ,
247+ producedDuration < sourceDuration * 0.5
248+ {
249+ throw RecordingScriptError . exportFailed (
250+ " Touch overlay export truncated the track to \( Int ( producedDuration ) ) s of \( Int ( sourceDuration ) ) s. "
251+ )
252+ }
253+
254+ if compositedLuma <= compositedBlackFrameLuma ,
255+ let sourceLuma = meanFrameLuma ( of : source ) ,
256+ sourceLuma > sourceVisibleFrameLuma
257+ {
258+ throw RecordingScriptError . exportFailed (
259+ " Touch overlay export produced an all-black track while the raw capture had visible content. "
260+ )
261+ }
262+ }
263+
264+ func renderSizeMatches ( _ produced : CGSize , _ expected : CGSize ) -> Bool {
265+ // The encoder rounds the stored frame to its coding-block grid, so an honest match tolerates a
266+ // few pixels regardless of size. A geometry collapse (the #2707 failure) misses by hundreds.
267+ let tolerance : CGFloat = 32
268+ return abs ( produced . width - expected . width ) <= tolerance
269+ && abs ( produced . height - expected . height ) <= tolerance
270+ }
271+
272+ func meanFrameLuma ( of asset : AVURLAsset , sampleCount : Int = 5 ) -> Double ? {
273+ let duration = CMTimeGetSeconds ( asset . duration )
274+ guard duration . isFinite , duration > 0 else { return nil }
275+ let generator = AVAssetImageGenerator ( asset : asset )
276+ generator . appliesPreferredTrackTransform = true
277+ generator . requestedTimeToleranceBefore = . positiveInfinity
278+ generator . requestedTimeToleranceAfter = . positiveInfinity
279+ // Only the mean brightness is wanted, so decode a thumbnail rather than the full frame.
280+ generator . maximumSize = CGSize ( width : 64 , height : 64 )
281+
282+ var total = 0.0
283+ var sampled = 0
284+ for index in 0 ..< sampleCount {
285+ let fraction = ( Double ( index ) + 0.5 ) / Double ( sampleCount )
286+ let time = CMTime ( seconds : fraction * duration , preferredTimescale : 600 )
287+ guard let image = try? generator . copyCGImage ( at : time , actualTime : nil ) ,
288+ let luma = frameMeanLuma ( image )
289+ else { continue }
290+ total += luma
291+ sampled += 1
292+ }
293+ guard sampled > 0 else { return nil }
294+ return total / Double ( sampled )
295+ }
296+
297+ func frameMeanLuma ( _ image : CGImage ) -> Double ? {
298+ let width = image . width
299+ let height = image . height
300+ guard width > 0 , height > 0 else { return nil }
301+ let bytesPerRow = width * 4
302+ var pixels = [ UInt8 ] ( repeating : 0 , count : bytesPerRow * height )
303+ let drawn = pixels . withUnsafeMutableBytes { raw -> Bool in
304+ guard
305+ let context = CGContext (
306+ data : raw . baseAddress ,
307+ width : width ,
308+ height : height ,
309+ bitsPerComponent : 8 ,
310+ bytesPerRow : bytesPerRow ,
311+ space : CGColorSpaceCreateDeviceRGB ( ) ,
312+ bitmapInfo : CGImageAlphaInfo . premultipliedLast . rawValue
313+ )
314+ else { return false }
315+ context . draw ( image , in : CGRect ( x : 0 , y : 0 , width : width , height : height ) )
316+ return true
317+ }
318+ guard drawn else { return nil }
319+
320+ var total = 0.0
321+ var count = 0
322+ for offset in stride ( from : 0 , to : bytesPerRow * height , by : 4 ) {
323+ total += 0.299 * Double ( pixels [ offset ] )
324+ + 0.587 * Double ( pixels [ offset + 1 ] )
325+ + 0.114 * Double ( pixels [ offset + 2 ] )
326+ count += 1
327+ }
328+ guard count > 0 else { return nil }
329+ return total / Double ( count )
330+ }
331+
212332func resolvedFrameDuration ( for track : AVAssetTrack ) -> CMTime {
213333 let minFrameDuration = track . minFrameDuration
214334 if minFrameDuration . isValid && ! minFrameDuration . isIndefinite && minFrameDuration . seconds > 0 {
0 commit comments