feat(recording): align quality and max-size controls (#816)

* feat(recording): make iOS export quality configurable

Wire the existing recording-export-quality enum through the record command
down to the Swift export preset. Adds a `--export-quality <medium|high>`
option for iOS recordings that controls the AVAssetExportSession preset used
when a recording is re-encoded.

`medium` stays the default and selects AVAssetExportPresetMediumQuality, which
preserves the fast simulator-friendly export. `high` opts into
AVAssetExportPresetHighestQuality for evidence-grade output. This is separate
from the existing integer `--quality <5-10>` capture flag that scales render
resolution.

Closes #568

* fix(recording): apply export quality to touch-overlay export path

The --export-quality flag was only wired into the resize export path. The
touch-overlay re-encode (finalizeRecordingOverlay -> overlayRecordingTouches ->
recording-overlay.swift) ignored it and always picked AVAssetExportPresetMediumQuality,
so record stop with --export-quality high had no effect when the stop path
re-encodes only to burn in touch overlays.

Thread the recording's exportQuality through finalizeRecordingOverlay and
overlayRecordingTouches, pass it as --export-quality to recording-overlay.swift,
and resolve the preset there via the same exportPresetName() helper used by
recording-resize.swift. Medium stays the default when the arg is absent, so
behavior is unchanged for callers that do not set it.

* feat: align recording quality and size flags

---------

Co-authored-by: Michał Pierzchała <thymikee@gmail.com>

Author: ryanda9910

ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift

@@ -420,24 +420,24 @@ extension RunnerTests {
       if let requestedFps = command.fps, (requestedFps < minRecordingFps || requestedFps > maxRecordingFps) {
         return Response(ok: false, error: ErrorPayload(message: "recordStart fps must be between \(minRecordingFps) and \(maxRecordingFps)"))
       }
-      if let requestedQuality = command.quality, (requestedQuality < minRecordingQuality || requestedQuality > maxRecordingQuality) {
-        return Response(ok: false, error: ErrorPayload(message: "recordStart quality must be between \(minRecordingQuality) and \(maxRecordingQuality)"))
+      if let requestedMaxSize = command.maxSize, requestedMaxSize < 1 {
+        return Response(ok: false, error: ErrorPayload(message: "recordStart maxSize must be a positive integer"))
       }
       do {
         let resolvedOutPath = resolveRecordingOutPath(requestedOutPath)
         let fpsLabel = command.fps.map(String.init) ?? String(RunnerTests.defaultRecordingFps)
-        let qualityLabel = command.quality.map(String.init) ?? "native"
+        let maxSizeLabel = command.maxSize.map(String.init) ?? "native"
         NSLog(
-          "AGENT_DEVICE_RUNNER_RECORD_START requestedOutPath=%@ resolvedOutPath=%@ fps=%@ quality=%@",
+          "AGENT_DEVICE_RUNNER_RECORD_START requestedOutPath=%@ resolvedOutPath=%@ fps=%@ maxSize=%@",
           requestedOutPath,
           resolvedOutPath,
           fpsLabel,
-          qualityLabel
+          maxSizeLabel
         )
         let recorder = ScreenRecorder(
           outputPath: resolvedOutPath,
           fps: command.fps.map { Int32($0) },
-          quality: command.quality
+          maxSize: command.maxSize
         )
         try recorder.start { [weak self] in
           return self?.captureRunnerFrame()

ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift

@@ -136,7 +136,7 @@ struct Command: Codable {
   let velocity: Double?
   let outPath: String?
   let fps: Int?
-  let quality: Int?
+  let maxSize: Int?
   let interactiveOnly: Bool?
   let depth: Int?
   let scope: String?

ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift

@@ -7,7 +7,7 @@ extension RunnerTests {
   final class ScreenRecorder {
     private let outputPath: String
     private let fps: Int32?
-    private let quality: Int?
+    private let maxSize: Int?
     private var effectiveFps: Int32 {
       max(1, fps ?? RunnerTests.defaultRecordingFps)
     }
@@ -26,10 +26,10 @@ extension RunnerTests {
     private var startedSession = false
     private var startError: Error?
 
-    init(outputPath: String, fps: Int32?, quality: Int?) {
+    init(outputPath: String, fps: Int32?, maxSize: Int?) {
       self.outputPath = outputPath
       self.fps = fps
-      self.quality = quality
+      self.maxSize = maxSize
     }
 
     func start(captureFrame: @escaping () -> RunnerImage?) throws {
@@ -262,10 +262,14 @@ extension RunnerTests {
     }
 
     private func scaledDimensions(width: Int, height: Int) -> CGSize {
-      guard let quality, quality < 10 else {
+      guard let maxSize, maxSize > 0 else {
         return CGSize(width: width, height: height)
       }
-      let scale = Double(quality) / 10.0
+      let longest = max(width, height)
+      guard longest > maxSize else {
+        return CGSize(width: width, height: height)
+      }
+      let scale = Double(maxSize) / Double(longest)
       return CGSize(
         width: scaledEvenDimension(width, scale: scale),
         height: scaledEvenDimension(height, scale: scale)

ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift

@@ -49,8 +49,6 @@ final class RunnerTests: XCTestCase {
   let xctestIdleKeepaliveInterval: TimeInterval = 5.0
   let minRecordingFps = 1
   let maxRecordingFps = 120
-  let minRecordingQuality = 5
-  let maxRecordingQuality = 10
   var needsPostSnapshotInteractionDelay = false
   var needsFirstInteractionDelay = false
   var activeRecording: ScreenRecorder?

ios-runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift

@@ -146,11 +146,9 @@ func run() throws {
   )
 
   // Overlay burn-in forces a full re-encode; medium quality keeps simulator videos readable
-  // while avoiding very slow highest-quality exports.
-  let presetName = AVAssetExportSession.exportPresets(compatibleWith: composition)
-    .contains(AVAssetExportPresetMediumQuality)
-    ? AVAssetExportPresetMediumQuality
-    : AVAssetExportPresetHighestQuality
+  // while avoiding very slow highest-quality exports. Pass --quality high to opt into
+  // the slower highest-quality export.
+  let presetName = exportPresetName(for: parsedArgs.exportQuality, compatibleWith: composition)
   guard let exporter = AVAssetExportSession(asset: composition, presetName: presetName) else {
     throw OverlayError.exportFailed("Failed to create export session.")
   }
@@ -174,10 +172,20 @@ func run() throws {
   }
 }
 
-func parseArguments(_ arguments: [String]) throws -> (inputPath: String, outputPath: String, eventsPath: String) {
+enum ExportQuality: String {
+  case medium
+  case high
+}
+
+func parseArguments(
+  _ arguments: [String]
+) throws -> (inputPath: String, outputPath: String, eventsPath: String, exportQuality: ExportQuality) {
   var inputPath: String?
   var outputPath: String?
   var eventsPath: String?
+  // Export quality defaults to medium so existing callers keep the fast, simulator-friendly
+  // export. Pass --quality high to opt into a slower highest-quality export.
+  var exportQuality: ExportQuality = .medium
   var index = 0
 
   while index < arguments.count {
@@ -196,15 +204,43 @@ func parseArguments(_ arguments: [String]) throws -> (inputPath: String, outputP
       guard nextIndex < arguments.count else { throw OverlayError.invalidArgs("--events requires a value") }
       eventsPath = arguments[nextIndex]
       index += 2
+    case "--quality":
+      guard nextIndex < arguments.count else {
+        throw OverlayError.invalidArgs("--quality requires a value")
+      }
+      guard let parsed = ExportQuality(rawValue: arguments[nextIndex]) else {
+        throw OverlayError.invalidArgs("--quality must be one of: medium, high")
+      }
+      exportQuality = parsed
+      index += 2
     default:
       throw OverlayError.invalidArgs("Unknown argument: \(argument)")
     }
   }
 
   guard let inputPath, let outputPath, let eventsPath else {
-    throw OverlayError.invalidArgs("Usage: recording-overlay.swift --input <video> --output <video> --events <json>")
+    throw OverlayError.invalidArgs(
+      "Usage: recording-overlay.swift --input <video> --output <video> --events <json> [--quality <medium|high>]"
+    )
+  }
+  return (inputPath, outputPath, eventsPath, exportQuality)
+}
+
+func exportPresetName(
+  for exportQuality: ExportQuality,
+  compatibleWith asset: AVAsset
+) -> String {
+  switch exportQuality {
+  case .high:
+    return AVAssetExportPresetHighestQuality
+  case .medium:
+    // Prefer the faster medium preset, falling back to highest quality only when medium is
+    // not available for this composition.
+    let compatible = AVAssetExportSession.exportPresets(compatibleWith: asset)
+    return compatible.contains(AVAssetExportPresetMediumQuality)
+      ? AVAssetExportPresetMediumQuality
+      : AVAssetExportPresetHighestQuality
   }
-  return (inputPath, outputPath, eventsPath)
 }
 
 func resolvedRenderSize(for track: AVAssetTrack) -> CGSize {

ios-runner/AgentDeviceRunner/RecordingScripts/recording-resize.swift

@@ -40,7 +40,13 @@ func run() throws {
     throw ResizeError.missingVideoTrack
   }
 
-  let renderSize = scaledRenderSize(for: sourceVideoTrack, quality: parsedArgs.quality)
+  let sourceRenderSize = resolvedRenderSize(for: sourceVideoTrack)
+  if max(sourceRenderSize.width, sourceRenderSize.height) <= CGFloat(parsedArgs.maxSize) {
+    try FileManager.default.copyItem(at: inputURL, to: outputURL)
+    return
+  }
+
+  let renderSize = scaledRenderSize(sourceRenderSize, maxSize: parsedArgs.maxSize)
   let composition = AVMutableComposition()
   let fullRange = CMTimeRange(start: .zero, duration: asset.duration)
 
@@ -60,7 +66,7 @@ func run() throws {
     try? compositionAudioTrack.insertTimeRange(fullRange, of: sourceAudioTrack, at: .zero)
   }
 
-  let scale = CGFloat(parsedArgs.quality) / 10.0
+  let scale = renderSize.width / sourceRenderSize.width
   let videoComposition = AVMutableVideoComposition()
   videoComposition.renderSize = renderSize
   videoComposition.frameDuration = resolvedFrameDuration(for: sourceVideoTrack)
@@ -74,7 +80,8 @@ func run() throws {
   instruction.layerInstructions = [layerInstruction]
   videoComposition.instructions = [instruction]
 
-  guard let exporter = AVAssetExportSession(asset: composition, presetName: AVAssetExportPresetHighestQuality) else {
+  let presetName = exportPresetName(for: parsedArgs.exportQuality, compatibleWith: composition)
+  guard let exporter = AVAssetExportSession(asset: composition, presetName: presetName) else {
     throw ResizeError.exportFailed("Failed to create export session.")
   }
 
@@ -97,10 +104,20 @@ func run() throws {
   }
 }
 
-func parseArguments(_ arguments: [String]) throws -> (inputPath: String, outputPath: String, quality: Int) {
+enum ExportQuality: String {
+  case medium
+  case high
+}
+
+func parseArguments(
+  _ arguments: [String]
+) throws -> (inputPath: String, outputPath: String, maxSize: Int, exportQuality: ExportQuality) {
   var inputPath: String?
   var outputPath: String?
-  var quality: Int?
+  var maxSize: Int?
+  // Export quality defaults to medium so re-encoded recordings stay fast by default.
+  // Pass --quality high to opt into a slower highest-quality export.
+  var exportQuality: ExportQuality = .medium
   var index = 0
 
   while index < arguments.count {
@@ -115,35 +132,61 @@ func parseArguments(_ arguments: [String]) throws -> (inputPath: String, outputP
       guard nextIndex < arguments.count else { throw ResizeError.invalidArgs("--output requires a value") }
       outputPath = arguments[nextIndex]
       index += 2
+    case "--max-size":
+      guard nextIndex < arguments.count else { throw ResizeError.invalidArgs("--max-size requires a value") }
+      guard let parsed = Int(arguments[nextIndex]), parsed >= 1 else {
+        throw ResizeError.invalidArgs("--max-size must be a positive integer")
+      }
+      maxSize = parsed
+      index += 2
     case "--quality":
-      guard nextIndex < arguments.count else { throw ResizeError.invalidArgs("--quality requires a value") }
-      guard let parsed = Int(arguments[nextIndex]), parsed >= 5, parsed <= 10 else {
-        throw ResizeError.invalidArgs("--quality must be an integer between 5 and 10")
+      guard nextIndex < arguments.count else {
+        throw ResizeError.invalidArgs("--quality requires a value")
+      }
+      guard let parsed = ExportQuality(rawValue: arguments[nextIndex]) else {
+        throw ResizeError.invalidArgs("--quality must be one of: medium, high")
       }
-      quality = parsed
+      exportQuality = parsed
       index += 2
     default:
       throw ResizeError.invalidArgs("Unknown argument: \(argument)")
     }
   }
 
-  guard let inputPath, let outputPath, let quality else {
+  guard let inputPath, let outputPath, let maxSize else {
     throw ResizeError.invalidArgs(
-      "Usage: recording-resize.swift --input <video> --output <video> --quality <5-10>"
+      "Usage: recording-resize.swift --input <video> --output <video> --max-size <px> [--quality <medium|high>]"
     )
   }
-  return (inputPath, outputPath, quality)
+  return (inputPath, outputPath, maxSize, exportQuality)
+}
+
+func exportPresetName(
+  for exportQuality: ExportQuality,
+  compatibleWith asset: AVAsset
+) -> String {
+  switch exportQuality {
+  case .high:
+    return AVAssetExportPresetHighestQuality
+  case .medium:
+    // Mirror the touch-overlay export: prefer the faster medium preset, falling back to
+    // highest quality only when medium is not available for this composition.
+    let compatible = AVAssetExportSession.exportPresets(compatibleWith: asset)
+    return compatible.contains(AVAssetExportPresetMediumQuality)
+      ? AVAssetExportPresetMediumQuality
+      : AVAssetExportPresetHighestQuality
+  }
 }
 
 func resolvedRenderSize(for track: AVAssetTrack) -> CGSize {
   let transformed = track.naturalSize.applying(track.preferredTransform)
   return CGSize(width: abs(transformed.width), height: abs(transformed.height))
 }
 
-func scaledRenderSize(for track: AVAssetTrack, quality: Int) -> CGSize {
-  let renderSize = resolvedRenderSize(for: track)
-  guard quality < 10 else { return renderSize }
-  let scale = CGFloat(quality) / 10.0
+func scaledRenderSize(_ renderSize: CGSize, maxSize: Int) -> CGSize {
+  let longest = max(renderSize.width, renderSize.height)
+  guard longest > CGFloat(maxSize) else { return renderSize }
+  let scale = CGFloat(maxSize) / longest
   return CGSize(
     width: scaledDimension(renderSize.width, scale: scale),
     height: scaledDimension(renderSize.height, scale: scale)

ios-runner/RUNNER_PROTOCOL.md

@@ -32,7 +32,7 @@ Examples:
 ```
 
 ```json
-{ "command": "recordStart", "outPath": "/tmp/demo.mp4", "fps": 30, "quality": 7 }
+{ "command": "recordStart", "outPath": "/tmp/demo.mp4", "fps": 30, "maxSize": 720 }
 ```
 
 ```json

src/backend.ts

@@ -15,6 +15,7 @@ import type { ClickButton } from './core/click-button.ts';
 import type { DeviceRotation } from './core/device-rotation.ts';
 import type { ScrollDirection } from './core/scroll-gesture.ts';
 import type { SessionSurface } from './core/session-surface.ts';
+import type { RecordingExportQuality } from './core/recording-export-quality.ts';
 import type { SnapshotDiagnosticsSummary } from './snapshot-diagnostics.ts';
 import type {
   SnapshotCaptureAnalysis,
@@ -282,7 +283,8 @@ export type BackendInstallResult = Record<string, unknown> & {
 export type BackendRecordingOptions = {
   outPath?: string;
   fps?: number;
-  quality?: number;
+  maxSize?: number;
+  quality?: RecordingExportQuality;
   showTouches?: boolean;
 };
 

src/client-normalizers.ts

@@ -304,6 +304,7 @@ export function buildFlags(options: InternalRequestOptions): CommandFlags {
     out: options.out,
     count: options.count,
     fps: options.fps,
+    screenshotMaxSize: options.maxSize,
     quality: options.quality,
     hideTouches: options.hideTouches,
     intervalMs: options.intervalMs,

src/client-types.ts

@@ -16,6 +16,7 @@ import type {
 import type { DeviceKind, DeviceTarget, Platform, PlatformSelector } from './utils/device.ts';
 import type { BackMode } from './core/back-mode.ts';
 import type { ClickButton } from './core/click-button.ts';
+import type { RecordingExportQuality } from './core/recording-export-quality.ts';
 import type { DeviceRotation } from './core/device-rotation.ts';
 import type {
   ScrollDirection,
@@ -768,13 +769,12 @@ export type NetworkOptions = AgentDeviceRequestOverrides & {
   include?: NetworkIncludeMode;
 };
 
-type RecordingQuality = 5 | 6 | 7 | 8 | 9 | 10;
-
 export type RecordOptions = AgentDeviceRequestOverrides & {
   action: 'start' | 'stop';
   path?: string;
   fps?: number;
-  quality?: RecordingQuality;
+  maxSize?: number;
+  quality?: RecordingExportQuality;
   hideTouches?: boolean;
 };
 
@@ -854,7 +854,8 @@ type CommandExecutionOptions = Partial<ScreenshotRequestFlags> & {
   forceFull?: boolean;
   count?: number;
   fps?: number;
-  quality?: RecordingQuality;
+  maxSize?: number;
+  quality?: RecordingExportQuality;
   hideTouches?: boolean;
   intervalMs?: number;
   delayMs?: number;