@stim-cli/server 1.14.0 → 1.15.0

package/dist/stim-frames/main.swift

@@ -1,17 +1,30 @@
 import CoreImage
 import CoreVideo
 import Foundation
-import ImageIO
 import IOSurface
+import ImageIO
 
 // stim-frames streams one device's screen as JPEG frames for stim-server.
 //
 //   stim-frames ios <udid>
-//   stim-frames android <serial>
+//   stim-frames android <serial> [owned-avd-name]
+//   stim-frames android-device <serial> <adb> <scrcpy-server>
+//   stim-frames web <cdpEndpoint> <chromePid> <targetId>
+//   stim-frames macos <owned-app-json>
+//   stim-frames iphone <udid> [name]
 //
+// android-device streams any adb device through the scrcpy server jar at <scrcpy-server>,
+// decoding its H.264 to re-encode it here; stim-server uses it for physical devices.
+// It takes touch, text and the home, back, app-switch and lock buttons, and does not
+// rotate or fold. It cleans up the device before any exit.
+// A web page streams Chrome's screencast of the owned page: its JPEGs pass through as
+// frames and are decoded for video. Input on a page takes touch, text and the "back"
+// button, as DevTools input events. A USB-cabled iPhone streams its screen and takes no input.
 // stdin takes one JSON object per line: {"fps": n, "maxEdge": px, "quality": 0-1,
-// "jpeg": bool, "jpegFps": n, "video": bool, "bitrate": bits per second}, where fps 0
-// pauses frames; {"keyframe": true} to make the next video frame a keyframe; or an input:
+// "jpeg": bool, "jpegFps": n, "video": bool, "bitrate": bits per second, "record":
+// {"maxEdge": px, "fps": n, "bitrate": bits per second}}, where fps 0 pauses frames and
+// "record", present only while stim-server records the device, runs a second encoder for it
+// at no more than its own fps; {"recordKeyframe": true} makes that encoder's next frame a keyframe; {"keyframe": true} to make the next video frame a keyframe; or an input:
 // {"input": "touch", "phase": "down|move|up", "x": 0-1, "y": 0-1, "display": n} with x
 // and y on the upright screen; {"input": "text", "text": s}, printable ASCII where "\n"
 // is Return, "\t" is Tab and "\u{8}" is Delete; and {"input": "button", "button":
@@ -23,9 +36,13 @@ import IOSurface
 // 1 is a frame (2-byte width, 2-byte height, JPEG bytes), 2 is a JSON notice
 // ({"error": message} before a failed exit, {"inputError": message}, on a simulator
 // with several displays {"display": n} when display n is the one lit and streamed, or
-// on an emulator {"keyboard": "yes|no"} once it reports its hardware), 3 is an H.264 access unit (1-byte
+// on an emulator {"keyboard": "yes|no"} once it reports its hardware, or on an iPhone
+// {"stalled": message} while frames cannot arrive and {"stalled": null} once they can), 3 is an H.264 access unit (1-byte
 // flags with bit 0 set on a keyframe, 8-byte big-endian float capture time in
-// milliseconds since the epoch, 2-byte width, 2-byte height, Annex-B bytes).
+// milliseconds since the epoch, 2-byte width, 2-byte height, Annex-B bytes), and 4 is an
+// access unit of the recording encoder, laid out like 3. Kind 5 adds a clockwise artwork
+// quarter-turn byte after the frame dimensions. Live video bit 5 marks that rotation
+// in bits 3-4; recordings omit it. The deviceFrame config requests PNG artwork notices.
 // The helper exits when stdin closes.
 
 struct Config: Equatable {
@@ -35,25 +52,43 @@ struct Config: Equatable {
   var jpeg = true
   var jpegFps: Double?
   var video = false
+  var deviceFrame = false
+  var duoFrame: DuoCapture?
   var bitrate = 3_000_000
+  var record: Recording?
+}
+
+struct Recording: Equatable {
+  var maxEdge: Int
+  var fps: Double
+  var bitrate: Int
+}
+
+struct DuoCapture: Equatable {
+  var maxEdge: Int
+  var fps: Double
 }
 
 enum Output {
   private static let writer = DispatchQueue(label: "stim.frames.output")
   private static let lock = NSLock()
   private static var writing = false
+  private static var writingDuo = false
   private static var pendingVideo = 0
   private static var videoNeedsKeyframe = false
   private static var keyframeRequested = false
   private static let maxPendingVideo = 30
   static var requestKeyframe: () -> Void = {}
 
-  static func frame(jpeg: Data, width: Int, height: Int) {
+  static func frame(jpeg: Data, width: Int, height: Int, artworkTurns: Int? = nil) {
     lock.lock()
     defer { lock.unlock() }
     guard !writing else { return }
     writing = true
-    var body = Data([1, UInt8(width >> 8), UInt8(width & 0xff), UInt8(height >> 8), UInt8(height & 0xff)])
+    var body = Data([
+      artworkTurns == nil ? 1 : 5, UInt8(width >> 8), UInt8(width & 0xff), UInt8(height >> 8), UInt8(height & 0xff),
+    ])
+    if let artworkTurns { body.append(UInt8(artworkTurns)) }
     body += jpeg
     writer.async {
       write(body)
@@ -63,6 +98,28 @@ enum Output {
     }
   }
 
+  static func duoFrame(_ frame: DuoFrameRenderer.Frame) {
+    guard
+      let metadata = try? JSONSerialization.data(withJSONObject: [
+        "width": frame.width, "height": frame.height, "revision": frame.revision,
+        "screenID": frame.screenID, "angle": frame.angle, "orientation": frame.orientation,
+      ]), metadata.count <= 65535
+    else { return }
+    lock.lock()
+    defer { lock.unlock() }
+    guard !writingDuo else { return }
+    writingDuo = true
+    var body = Data([6, UInt8(metadata.count >> 8), UInt8(metadata.count & 0xff)])
+    body += metadata
+    body += frame.jpeg
+    writer.async {
+      write(body)
+      lock.lock()
+      writingDuo = false
+      lock.unlock()
+    }
+  }
+
   static func video(_ unit: AccessUnit) {
     lock.lock()
     defer { lock.unlock() }
@@ -74,7 +131,8 @@ enum Output {
     videoNeedsKeyframe = false
     keyframeRequested = false
     pendingVideo += 1
-    var body = Data([3, unit.keyframe ? 1 : 0])
+    let artwork = unit.artworkTurns.map { UInt8(32 | ($0 << 3)) } ?? 0
+    var body = Data([3, (unit.keyframe ? 1 : 0) | artwork])
     withUnsafeBytes(of: unit.capturedAt.bitPattern.bigEndian) { body.append(contentsOf: $0) }
     body += Data([UInt8(unit.width >> 8), UInt8(unit.width & 0xff), UInt8(unit.height >> 8), UInt8(unit.height & 0xff)])
     body += unit.data
@@ -89,6 +147,15 @@ enum Output {
     }
   }
 
+  /// Recording units are never dropped: a gap would leave the rest of the segment undecodable.
+  static func record(_ unit: AccessUnit) {
+    var body = Data([4, unit.keyframe ? 1 : 0])
+    withUnsafeBytes(of: unit.capturedAt.bitPattern.bigEndian) { body.append(contentsOf: $0) }
+    body += Data([UInt8(unit.width >> 8), UInt8(unit.width & 0xff), UInt8(unit.height >> 8), UInt8(unit.height & 0xff)])
+    body += unit.data
+    writer.async { write(body) }
+  }
+
   static func notice(_ object: [String: Any]) {
     guard let json = try? JSONSerialization.data(withJSONObject: object) else { return }
     writer.sync { write(Data([2]) + json) }
@@ -102,8 +169,12 @@ enum Output {
   }
 }
 
+/// Runs before every exit, so a source can undo what it did on a device.
+var beforeExit: () -> Void = {}
+
 func fail(_ message: String) -> Never {
   Output.notice(["error": message])
+  beforeExit()
   exit(1)
 }
 
@@ -161,6 +232,30 @@ func videoEncoder() -> VideoEncoder {
   VideoEncoder(maxEdge: Config().maxEdge, fps: Int(Config().fps), bitrate: Config().bitrate, output: Output.video)
 }
 
+func recordEncoder() -> VideoEncoder {
+  VideoEncoder(maxEdge: Config().maxEdge, fps: Int(Config().fps), bitrate: Config().bitrate, output: Output.record)
+}
+
+extension VideoEncoder {
+  func configure(record config: Config) {
+    configure(
+      enabled: config.record != nil, maxEdge: config.record?.maxEdge ?? config.maxEdge,
+      fps: Int(config.record?.fps ?? config.fps), bitrate: config.record?.bitrate ?? config.bitrate)
+  }
+}
+
+/// Keeps the recording encoder at its own fps while live video renders faster, the way JpegGate paces JPEG.
+final class RecordGate {
+  private let gate = JpegGate()
+
+  func admit(_ config: Config, pacer: Pacer) -> Bool {
+    guard let record = config.record else { return false }
+    var paced = config
+    paced.jpegFps = record.fps
+    return gate.admit(paced, pacer: pacer)
+  }
+}
+
 /// Keeps JPEG at `jpegFps` while video renders faster. A frame it skips is rendered again once the
 /// interval passes, so the last frame of a burst still reaches JPEG subscribers. Used on the pacer queue.
 final class JpegGate {
@@ -197,7 +292,16 @@ final class SimulatorSource {
   private var reportedDisplay: Int?
   private let callbackID = NSUUID()
   private let video = videoEncoder()
+  private let recorder = recordEncoder()
+  private let recordGate = RecordGate()
   private let jpegGate = JpegGate()
+  private let duoGate = JpegGate()
+  private var duo: DuoCaptureSource?
+  private var duoRendering = false
+  private var duoMissed = false
+  private let stopLock = NSLock()
+  private var frameTurns: Int?
+  private lazy var artwork = FrameArtworkPublisher { SimulatorFrameArtwork.load(udid: self.udid) }
 
   init(udid: String) {
     self.udid = udid
@@ -208,6 +312,14 @@ final class SimulatorSource {
 
   var queue: DispatchQueue { pacer.queue }
 
+  func stop() {
+    stopLock.lock()
+    defer { stopLock.unlock() }
+    let touch = DispatchQueue.main.sync { MainActor.assumeIsolated { duo?.configure(nil) } }
+    guard let touch else { return }
+    inputQueue.sync { hid?.touch(.up, at: touch.point, screenID: touch.screenID) }
+  }
+
   func start(deadline: Date = Date().addingTimeInterval(30)) {
     let found = CoreSimulator.displays(udid: udid)
     guard !found.isEmpty else {
@@ -243,6 +355,12 @@ final class SimulatorSource {
       }
       self.displays = []
       self.reportedDisplay = nil
+      DispatchQueue.main.async {
+        MainActor.assumeIsolated {
+          self.releaseDuo(self.duo?.configure(nil))
+          self.duo = nil
+        }
+      }
       self.inputQueue.async { self.hid = nil }
       self.start()
     }
@@ -268,8 +386,17 @@ final class SimulatorSource {
 
   func configure(_ config: Config) {
     video.configure(enabled: config.video, maxEdge: config.maxEdge, fps: Int(config.fps), bitrate: config.bitrate)
+    recorder.configure(record: config)
     queue.async {
       self.pacer.config = config
+      DispatchQueue.main.async {
+        MainActor.assumeIsolated {
+          if self.duo == nil, config.duoFrame != nil {
+            self.duo = DuoCaptureSource(udid: self.udid, changed: self.pacer.changed)
+          }
+          self.releaseDuo(self.duo?.configure(config.duoFrame))
+        }
+      }
       self.pacer.changed()
     }
   }
@@ -279,6 +406,11 @@ final class SimulatorSource {
     pacer.changed()
   }
 
+  func recordKeyframe() {
+    recorder.requestKeyframe()
+    pacer.changed()
+  }
+
   // uiOrientation is a UIInterfaceOrientation; the framebuffer stays in the
   // display's native portrait orientation, so the image is turned upright.
   private func render(_ config: Config) {
@@ -292,22 +424,64 @@ final class SimulatorSource {
     default: (orientation, quarterTurns) = (.up, 0)
     }
     let ioSurface = unsafeBitCast(surface, to: IOSurfaceRef.self)
-    if config.video {
+    let artworkTurns = (4 - quarterTurns) % 4
+    if config.duoFrame != nil, duoRendering { duoMissed = true }
+    if let requested = config.duoFrame, !duoRendering,
+      let properties = display.screenProperties
+    {
+      var paced = config
+      paced.jpegFps = requested.fps
+      if duoGate.admit(paced, pacer: pacer) {
+        duoRendering = true
+        let surfaces = displays.compactMap { display -> (screenID: UInt32, surface: IOSurface?)? in
+          guard let properties = display.screenProperties, properties.screenType == 0 else { return nil }
+          return (properties.screenID, display.framebufferSurface)
+        }
+        let viewport = CIImage(ioSurface: ioSurface).oriented(orientation).extent.size
+        DispatchQueue.main.async {
+          MainActor.assumeIsolated {
+            if self.duo == nil {
+              self.duo = DuoCaptureSource(udid: self.udid, changed: self.pacer.changed)
+              self.releaseDuo(self.duo?.configure(config.duoFrame))
+            }
+            self.duo?.render(
+              surfaces: surfaces, activeID: properties.screenID,
+              orientation: properties.uiOrientation, viewport: viewport, config: config)
+            self.queue.async {
+              self.duoRendering = false
+              if self.duoMissed {
+                self.duoMissed = false
+                self.pacer.changed()
+              }
+            }
+          }
+        }
+      }
+    }
+    if config.deviceFrame, frameTurns != artworkTurns {
+      frameTurns = artworkTurns
+      artwork.send(quarterTurns: artworkTurns)
+    }
+    let record = recordGate.admit(config, pacer: pacer)
+    if config.video || record {
       var buffer: Unmanaged<CVPixelBuffer>?
       CVPixelBufferCreateWithIOSurface(nil, ioSurface, nil, &buffer)
       if let pixels = buffer?.takeRetainedValue() {
-        video.encode(pixels, quarterTurns: quarterTurns, capturedAt: now())
+        let capturedAt = now()
+        if config.video { video.encode(pixels, quarterTurns: quarterTurns, capturedAt: capturedAt, artworkTurns: artworkTurns) }
+        if record { recorder.encode(pixels, quarterTurns: quarterTurns, capturedAt: capturedAt) }
       }
     }
     guard config.jpeg, jpegGate.admit(config, pacer: pacer) else { return }
     let image = CIImage(ioSurface: ioSurface).oriented(orientation)
     guard let (data, width, height) = jpeg(image, config: config) else { return }
-    Output.frame(jpeg: data, width: width, height: height)
+    Output.frame(jpeg: data, width: width, height: height, artworkTurns: artworkTurns)
   }
 }
 
 final class EmulatorSource {
   let serial: String
+  let avdName: String?
   let queue = DispatchQueue(label: "stim.frames.emulator")
   let inputQueue = DispatchQueue(label: "stim.frames.emulator-input")
   var input: EmulatorInput?
@@ -318,10 +492,15 @@ final class EmulatorSource {
   var latest: EmulatorFrame?
   private var pacer: Pacer!
   private let video = videoEncoder()
+  private let recorder = recordEncoder()
+  private let recordGate = RecordGate()
   private let jpegGate = JpegGate()
+  private var frameTurns: Int?
+  private lazy var artwork = FrameArtworkPublisher { self.avdName.flatMap { EmulatorFrameArtwork.load(avdName: $0) } }
 
-  init(serial: String) {
+  init(serial: String, avdName: String? = nil) {
     self.serial = serial
+    self.avdName = avdName
     pacer = Pacer { [unowned self] config in
       guard let frame = self.queue.sync(execute: { self.latest }) else { return }
       self.render(frame, config: config)
@@ -339,6 +518,7 @@ final class EmulatorSource {
 
   func configure(_ config: Config) {
     video.configure(enabled: config.video, maxEdge: config.maxEdge, fps: Int(config.fps), bitrate: config.bitrate)
+    recorder.configure(record: config)
     queue.async {
       let resized = config.maxEdge != self.config.maxEdge
       self.config = config
@@ -359,6 +539,11 @@ final class EmulatorSource {
     pacer.changed()
   }
 
+  func recordKeyframe() {
+    recorder.requestKeyframe()
+    pacer.changed()
+  }
+
   private func connect() {
     guard let endpoint = EmulatorDiscovery.endpoint(serial: serial) else {
       fail("\(serial) has no gRPC endpoint. Frames appear after Stim next boots this emulator.")
@@ -383,7 +568,18 @@ final class EmulatorSource {
   }
 
   private func render(_ frame: EmulatorFrame, config: Config) {
-    if config.video { video.encode(rgba: frame.rgba, width: frame.width, height: frame.height, capturedAt: now()) }
+    let capturedAt = now()
+    let artworkTurns = (-frame.rotation % 4 + 4) % 4
+    if config.deviceFrame, frameTurns != artworkTurns {
+      frameTurns = artworkTurns
+      artwork.send(quarterTurns: artworkTurns)
+    }
+    if config.video {
+      video.encode(rgba: frame.rgba, width: frame.width, height: frame.height, capturedAt: capturedAt, artworkTurns: artworkTurns)
+    }
+    if recordGate.admit(config, pacer: pacer) {
+      recorder.encode(rgba: frame.rgba, width: frame.width, height: frame.height, capturedAt: capturedAt)
+    }
     guard config.jpeg, jpegGate.admit(config, pacer: pacer), let provider = CGDataProvider(data: frame.rgba as CFData),
       let image = CGImage(
         width: frame.width, height: frame.height, bitsPerComponent: 8, bitsPerPixel: 32, bytesPerRow: frame.width * 4,
@@ -391,14 +587,283 @@ final class EmulatorSource {
         provider: provider, decode: nil, shouldInterpolate: false, intent: .defaultIntent),
       let (data, width, height) = jpeg(CIImage(cgImage: image), config: config)
     else { return }
+    Output.frame(jpeg: data, width: width, height: height, artworkTurns: artworkTurns)
+  }
+}
+
+final class AndroidDeviceSource {
+  let queue = DispatchQueue(label: "stim.frames.android-device")
+  let stream: AndroidDeviceStream
+  private var latest: CVPixelBuffer?
+  private var pacer: Pacer!
+  private let video = videoEncoder()
+  private let jpegGate = JpegGate()
+
+  init(serial: String, adb: String, serverJar: URL) {
+    stream = AndroidDeviceStream(serial: serial, adb: adb, serverJar: serverJar)
+    pacer = Pacer { [unowned self] config in
+      guard let frame = self.queue.sync(execute: { self.latest }) else { return }
+      self.render(frame, config: config)
+    }
+  }
+
+  func start() {
+    stream.onFrame = { [weak self] frame in
+      guard let self else { return }
+      self.queue.async { self.latest = frame }
+      self.pacer.changed()
+    }
+    stream.onEnd = { fail($0) }
+    stream.start()
+  }
+
+  func configure(_ config: Config) {
+    video.configure(enabled: config.video, maxEdge: config.maxEdge, fps: Int(config.fps), bitrate: config.bitrate)
+    pacer.queue.async {
+      self.pacer.config = config
+      self.pacer.changed()
+    }
+  }
+
+  /// A device whose screen does not change sends no frame, so a keyframe re-encodes the last one.
+  func keyframe() {
+    video.requestKeyframe()
+    pacer.changed()
+  }
+
+  /// stim-server does not record a physical device.
+  func recordKeyframe() {}
+
+  private func render(_ frame: CVPixelBuffer, config: Config) {
+    if config.video { video.encode(frame, quarterTurns: 0, capturedAt: now()) }
+    guard config.jpeg, jpegGate.admit(config, pacer: pacer),
+      let (data, width, height) = jpeg(CIImage(cvPixelBuffer: frame), config: config)
+    else { return }
     Output.frame(jpeg: data, width: width, height: height)
   }
 }
 
-enum Command {
+extension AndroidDeviceSource: Source {
+  func input(_ command: Command) {
+    switch command {
+    case .touch(let phase, let point, let display):
+      guard display == 0 else { return Output.notice(["inputError": "Input goes to the device's main display only."]) }
+      guard let size = stream.size else { return Output.notice(["inputError": "The device has sent no frame yet."]) }
+      let action: Scrcpy.TouchAction = phase == .down ? .down : phase == .up ? .up : .move
+      stream.send(
+        Scrcpy.touch(
+          action, x: Int32((point.x * Double(size.width - 1)).rounded()),
+          y: Int32((point.y * Double(size.height - 1)).rounded()), width: UInt16(size.width),
+          height: UInt16(size.height)))
+    case .text(let text):
+      var run = ""
+      let flush = {
+        if !run.isEmpty { self.stream.send(Scrcpy.text(run)) }
+        run = ""
+      }
+      for character in text {
+        if let key = Scrcpy.keycodes[String(character)] {
+          flush()
+          stream.send(Scrcpy.keycode(.down, key))
+          stream.send(Scrcpy.keycode(.up, key))
+        } else {
+          run.append(character)
+        }
+      }
+      flush()
+    case .button(let name):
+      guard ["home", "back", "app-switch", "lock"].contains(name), let key = Scrcpy.keycodes[name] else {
+        return Output.notice(["inputError": "Android has no \(name) button."])
+      }
+      stream.send(Scrcpy.keycode(.down, key))
+      stream.send(Scrcpy.keycode(.up, key))
+    case .rotate, .posture:
+      Output.notice(["inputError": "A physical device rotates and folds only in hand."])
+    case .config, .keyframe, .recordKeyframe, .control, .scoped, .scroll, .key, .window, .duoTouch, .duoRelease:
+      break
+    }
+  }
+}
+
+final class WebSource {
+  let queue = DispatchQueue(label: "stim.frames.web")
+  private let endpoint: URL
+  private let chromePid: Int32
+  private let targetId: String
+  private var page: WebPage?
+  private var latest: ScreencastFrame?
+  private var screencast: (maxEdge: Int, quality: Int)?
+  private var config = Config()
+  private var pacer: Pacer!
+  private let video = videoEncoder()
+  private let recorder = recordEncoder()
+  private let recordGate = RecordGate()
+  private let jpegGate = JpegGate()
+  private var pixels: CVPixelBufferPool?
+  private var pixelSize = (width: 0, height: 0)
+  private var encodedAt: Double?
+  private var waiting: [Command] = []
+
+  init(endpoint: URL, chromePid: Int32, targetId: String) {
+    self.endpoint = endpoint
+    self.chromePid = chromePid
+    self.targetId = targetId
+    pacer = Pacer { [unowned self] config in
+      guard let frame = self.queue.sync(execute: { self.latest }) else { return }
+      self.render(frame, config: config)
+    }
+  }
+
+  func start() {
+    WebPage.open(endpoint: endpoint, chromePid: chromePid, targetId: targetId) { result in
+      switch result {
+      case .failure(let failure):
+        fail(failure.description)
+      case .success(let page):
+        page.onEnd { fail($0) }
+        page.onFrame { frame in
+          self.queue.async { self.latest = frame }
+          self.pacer.changed()
+        }
+        self.queue.async {
+          self.page = page
+          self.updateScreencast()
+          let waiting = self.waiting
+          self.waiting = []
+          for command in waiting { self.apply(command, on: page) }
+        }
+      }
+    }
+  }
+
+  func configure(_ config: Config) {
+    video.configure(enabled: config.video, maxEdge: config.maxEdge, fps: Int(config.fps), bitrate: config.bitrate)
+    recorder.configure(record: config)
+    queue.async {
+      self.config = config
+      self.updateScreencast()
+      self.pacer.queue.async {
+        self.pacer.config = config
+        self.pacer.changed()
+      }
+    }
+  }
+
+  /// A page that does not change sends no frame, so a keyframe re-encodes the last one.
+  func keyframe() {
+    video.requestKeyframe()
+    pacer.changed()
+  }
+
+  func recordKeyframe() {
+    recorder.requestKeyframe()
+    pacer.changed()
+  }
+
+  private func updateScreencast() {
+    guard let page else { return }
+    guard config.fps > 0 else {
+      if screencast != nil { page.stopScreencast() }
+      screencast = nil
+      return
+    }
+    let wanted = (maxEdge: config.maxEdge, quality: config.video ? 85 : Int(config.quality * 100))
+    guard screencast.map({ $0 != wanted }) ?? true else { return }
+    screencast = wanted
+    page.startScreencast(maxEdge: wanted.maxEdge, quality: wanted.quality)
+  }
+
+  private func render(_ frame: ScreencastFrame, config: Config) {
+    guard let source = CGImageSourceCreateWithData(frame.jpeg as CFData, nil) else { return }
+    let record = recordGate.admit(config, pacer: pacer)
+    if config.video || record, let image = CGImageSourceCreateImageAtIndex(source, 0, nil),
+      let buffer = pixelBuffer(image)
+    {
+      let repeated = frame.capturedAt == encodedAt
+      encodedAt = frame.capturedAt
+      let capturedAt = repeated ? now() : frame.capturedAt
+      if config.video { video.encode(buffer, quarterTurns: 0, capturedAt: capturedAt) }
+      if record { recorder.encode(buffer, quarterTurns: 0, capturedAt: capturedAt) }
+    }
+    guard config.jpeg, jpegGate.admit(config, pacer: pacer),
+      let properties = CGImageSourceCopyPropertiesAtIndex(source, 0, nil) as? [CFString: Any],
+      let width = properties[kCGImagePropertyPixelWidth] as? Int,
+      let height = properties[kCGImagePropertyPixelHeight] as? Int
+    else { return }
+    Output.frame(jpeg: frame.jpeg, width: width, height: height)
+  }
+
+  private func pixelBuffer(_ image: CGImage) -> CVPixelBuffer? {
+    let size = (width: image.width, height: image.height)
+    if pixels == nil || pixelSize != size {
+      let attributes: [CFString: Any] = [
+        kCVPixelBufferPixelFormatTypeKey: kCVPixelFormatType_32BGRA,
+        kCVPixelBufferWidthKey: size.width,
+        kCVPixelBufferHeightKey: size.height,
+        kCVPixelBufferIOSurfacePropertiesKey: [:] as CFDictionary,
+      ]
+      pixels = nil
+      CVPixelBufferPoolCreate(nil, nil, attributes as CFDictionary, &pixels)
+      pixelSize = size
+    }
+    var buffer: CVPixelBuffer?
+    guard let pixels, CVPixelBufferPoolCreatePixelBuffer(nil, pixels, &buffer) == kCVReturnSuccess, let buffer else {
+      return nil
+    }
+    CVPixelBufferLockBaseAddress(buffer, [])
+    defer { CVPixelBufferUnlockBaseAddress(buffer, []) }
+    guard
+      let context = CGContext(
+        data: CVPixelBufferGetBaseAddress(buffer), width: size.width, height: size.height, bitsPerComponent: 8,
+        bytesPerRow: CVPixelBufferGetBytesPerRow(buffer), space: colorSpace,
+        bitmapInfo: CGImageAlphaInfo.noneSkipFirst.rawValue | CGBitmapInfo.byteOrder32Little.rawValue)
+    else { return nil }
+    context.draw(image, in: CGRect(x: 0, y: 0, width: size.width, height: size.height))
+    return buffer
+  }
+}
+
+extension WebSource: Source {
+  func input(_ command: Command) {
+    queue.async {
+      guard let page = self.page else { return self.waiting.append(command) }
+      self.apply(command, on: page)
+    }
+  }
+
+  private func apply(_ command: Command, on page: WebPage) {
+    switch command {
+    case .touch(let phase, let point, _):
+      switch phase {
+      case .down: page.touch(.down, x: point.x, y: point.y)
+      case .move: page.touch(.move, x: point.x, y: point.y)
+      case .up: page.touch(.up, x: point.x, y: point.y)
+      }
+    case .text(let text):
+      page.type(text)
+    case .button(let name):
+      guard name == "back" else { return Output.notice(["inputError": "A web page has no \(name) button."]) }
+      page.back()
+    case .rotate, .posture:
+      Output.notice(["inputError": "A web page does not rotate or fold."])
+    case .config, .keyframe, .recordKeyframe, .control, .scoped, .scroll, .key, .window, .duoTouch, .duoRelease:
+      break
+    }
+  }
+}
+
+indirect enum Command {
+  case control(String, enabled: Bool)
+  case scoped(String, Command)
+  case scroll(CGPoint, delta: CGPoint)
+  case key(String, modifiers: [String])
+  case window(UInt32?)
   case config(Config)
   case keyframe
+  case recordKeyframe
   case touch(TouchPhase, CGPoint, display: Int)
+  case duoTouch(TouchPhase, CGPoint, revision: String)
+  case duoRelease
   case text(String)
   case button(String)
   case rotate(clockwise: Bool)
@@ -407,14 +872,43 @@ enum Command {
 
 func parseCommand(_ line: String, base: Config) -> Command? {
   guard let object = try? JSONSerialization.jsonObject(with: Data(line.utf8)) as? [String: Any] else { return nil }
+  if let control = object["control"] as? [String: Any], let session = control["session"] as? String,
+    let enabled = control["enabled"] as? Bool { return .control(session, enabled: enabled) }
+  if let session = object["controlSession"] as? String {
+    var unscoped = object
+    unscoped.removeValue(forKey: "controlSession")
+    guard let data = try? JSONSerialization.data(withJSONObject: unscoped),
+      let command = parseCommand(String(decoding: data, as: UTF8.self), base: base)
+    else { return nil }
+    return .scoped(session, command)
+  }
   if object["keyframe"] as? Bool == true { return .keyframe }
+  if object["recordKeyframe"] as? Bool == true { return .recordKeyframe }
   switch object["input"] as? String {
+  case "duo-release":
+    return .duoRelease
   case "touch":
     let phases: [String: TouchPhase] = ["down": .down, "move": .move, "up": .up]
     guard let phase = (object["phase"] as? String).flatMap({ phases[$0] }),
       let x = object["x"] as? Double, let y = object["y"] as? Double, (0...1).contains(x), (0...1).contains(y)
     else { return nil }
+    if let revision = object["duoRevision"] as? String, UUID(uuidString: revision) != nil {
+      return .duoTouch(phase, CGPoint(x: x, y: y), revision: revision)
+    }
     return .touch(phase, CGPoint(x: x, y: y), display: object["display"] as? Int ?? 0)
+  case "scroll":
+    guard let x = object["x"] as? Double, let y = object["y"] as? Double,
+      let dx = object["deltaX"] as? Double, let dy = object["deltaY"] as? Double,
+      (0...1).contains(x), (0...1).contains(y), dx.isFinite, dy.isFinite, abs(dx) <= 1000, abs(dy) <= 1000
+    else { return nil }
+    return .scroll(CGPoint(x: x, y: y), delta: CGPoint(x: dx, y: dy))
+  case "key":
+    guard let key = object["key"] as? String, let modifiers = object["modifiers"] as? [String] else { return nil }
+    return .key(key, modifiers: modifiers)
+  case "window":
+    if object["window"] is NSNull { return .window(nil) }
+    guard let id = object["window"] as? Int, let window = UInt32(exactly: id) else { return nil }
+    return .window(window)
   case "text":
     return (object["text"] as? String).map { .text($0) }
   case "button":
@@ -433,7 +927,20 @@ func parseCommand(_ line: String, base: Config) -> Command? {
     if let jpeg = object["jpeg"] as? Bool { config.jpeg = jpeg }
     if let jpegFps = object["jpegFps"] as? Double, jpegFps > 0 { config.jpegFps = min(jpegFps, 60) }
     if let video = object["video"] as? Bool { config.video = video }
+    config.deviceFrame = object["deviceFrame"] as? Bool ?? false
+    config.duoFrame = (object["duoFrame"] as? [String: Any]).flatMap { duo in
+      guard let edge = duo["maxEdge"] as? Int, edge > 0,
+        let fps = duo["fps"] as? Double, fps > 0
+      else { return nil }
+      return DuoCapture(maxEdge: min(edge, 4096), fps: min(fps, 60))
+    }
     if let bitrate = object["bitrate"] as? Int, bitrate > 0 { config.bitrate = bitrate }
+    config.record = (object["record"] as? [String: Any]).flatMap { record in
+      guard let edge = record["maxEdge"] as? Int, edge > 0, let bitrate = record["bitrate"] as? Int, bitrate > 0,
+        let fps = record["fps"] as? Double, fps > 0
+      else { return nil }
+      return Recording(maxEdge: min(edge, 4096), fps: min(fps, 60), bitrate: bitrate)
+    }
     return .config(config)
   default:
     return nil
@@ -443,6 +950,7 @@ func parseCommand(_ line: String, base: Config) -> Command? {
 protocol Source: AnyObject {
   func configure(_ config: Config)
   func keyframe()
+  func recordKeyframe()
   func input(_ command: Command)
 }
 
@@ -452,7 +960,10 @@ func readCommands(_ source: Source) {
     var config = Config()
     while true {
       let chunk = FileHandle.standardInput.availableData
-      if chunk.isEmpty { exit(0) }
+      if chunk.isEmpty {
+        beforeExit()
+        exit(0)
+      }
       buffer += chunk
       while let newline = buffer.firstIndex(of: 0x0a) {
         let line = String(decoding: buffer[buffer.startIndex..<newline], as: UTF8.self)
@@ -463,6 +974,8 @@ func readCommands(_ source: Source) {
           source.configure(config)
         case .keyframe?:
           source.keyframe()
+        case .recordKeyframe?:
+          source.recordKeyframe()
         case let command?:
           source.input(command)
         case nil:
@@ -500,9 +1013,30 @@ let keyCodes: [Character: (code: UInt16, shift: Bool)] = {
 
 extension SimulatorSource: Source {
   func input(_ command: Command) {
+    if case .duoTouch(let phase, let point, let revision) = command {
+      DispatchQueue.main.async {
+        MainActor.assumeIsolated {
+          guard let touch = self.duo?.touch(phase, point: point, revision: revision) else { return }
+          self.inputQueue.async {
+            if self.hid?.isConnected != true { self.hid = SimulatorHID(udid: self.udid) }
+            self.hid?.touch(phase, at: touch.point, screenID: touch.screenID)
+          }
+        }
+      }
+      return
+    }
+    if case .duoRelease = command {
+      DispatchQueue.main.async { MainActor.assumeIsolated { self.releaseDuo(self.duo?.release()) } }
+      return
+    }
     inputQueue.async { self.apply(command) }
   }
 
+  private func releaseDuo(_ touch: DuoFrameRenderer.Touch?) {
+    guard let touch else { return }
+    inputQueue.async { self.hid?.touch(.up, at: touch.point, screenID: touch.screenID) }
+  }
+
   private func apply(_ command: Command) {
     if case .rotate(let clockwise) = command {
       if !SimulatorRotation.rotate(udid: udid, clockwise: clockwise) {
@@ -535,7 +1069,7 @@ extension SimulatorSource: Source {
       hid.button(button, down: true)
       usleep(100_000)
       hid.button(button, down: false)
-    case .config, .keyframe, .rotate, .posture:
+    case .config, .keyframe, .recordKeyframe, .rotate, .posture, .control, .scoped, .scroll, .key, .window, .duoTouch, .duoRelease:
       break
     }
   }
@@ -581,7 +1115,7 @@ extension EmulatorSource: Source {
       wait("rotation") { await EmulatorRotation.rotate(serial: self.serial, clockwise: clockwise) }
     case .posture(let posture):
       wait("posture") { await posture.apply(serial: self.serial) }
-    case .config, .keyframe:
+    case .config, .keyframe, .recordKeyframe, .control, .scoped, .scroll, .key, .window, .duoTouch, .duoRelease:
       break
     }
   }
@@ -632,21 +1166,116 @@ extension EmulatorSource: Source {
 setvbuf(stdout, nil, _IONBF, 0)
 signal(SIGPIPE, SIG_IGN)
 let arguments = CommandLine.arguments
-guard arguments.count == 3 else { fail("usage: stim-frames ios <udid> | android <serial>") }
+let usage =
+  "usage: stim-frames ios <udid> | android <serial> | android-device <serial> <adb> <scrcpy-server> | web <cdpEndpoint> <chromePid> <targetId> | iphone <udid> [name]"
+let terminated = DispatchSource.makeSignalSource(signal: SIGTERM, queue: .global())
+let counts = [
+  "simulator-options": [4, 5], "hinge-monitor": [3], "web": [5], "iphone": [3, 4], "android-device": [5], "android": [3, 4],
+]
+guard arguments.count > 1, (counts[arguments[1]] ?? [3]).contains(arguments.count) else { fail(usage) }
 switch arguments[1] {
+case "hinge-monitor":
+  guard let directory = ProcessInfo.processInfo.environment["DEVELOPER_DIR"] else { exit(1) }
+  CoreSimulator.developerDir = directory
+  DuoHingeMonitor.run(udid: arguments[2])
+case "simulator-options":
+  DispatchQueue.global().async {
+    _ = FileHandle.standardInput.readDataToEndOfFile()
+    exit(0)
+  }
+  CoreSimulator.developerDir = CoreSimulator.selectedDeveloperDir()
+  do {
+    let udid = arguments[2]
+    let settings: SimulatorDevelopmentOptions.Settings
+    switch arguments[3] {
+    case "read" where arguments.count == 4:
+      settings = try SimulatorDevelopmentOptions.read(udid: udid)
+    case "shake" where arguments.count == 4:
+      try SimulatorDevelopmentOptions.shake(udid: udid)
+      settings = try SimulatorDevelopmentOptions.read(udid: udid)
+    case "slow-animations" where arguments.count == 5 && ["on", "off"].contains(arguments[4]):
+      settings = try SimulatorDevelopmentOptions.setSlowAnimations(arguments[4] == "on", udid: udid)
+    default:
+      throw NSError(domain: "StimFrames", code: 1, userInfo: [NSLocalizedDescriptionKey: "Invalid simulator option."])
+    }
+    let result: [String: Any] = [
+      "canShake": settings.canShake,
+      "slowAnimations": settings.slowAnimations.map { $0 as Any } ?? NSNull(),
+    ]
+    let data = try JSONSerialization.data(withJSONObject: result, options: [.sortedKeys])
+    FileHandle.standardOutput.write(data)
+    exit(0)
+  } catch {
+    FileHandle.standardError.write(Data("\(error.localizedDescription)\n".utf8))
+    exit(1)
+  }
+case "macos":
+  guard let data = arguments[2].data(using: .utf8),
+    let app = try? JSONDecoder().decode(MacosSource.OwnedApp.self, from: data)
+  else { fail("Invalid owned macOS app target.") }
+  let source = MacosSource(app: app)
+  let stop = source.stop
+  beforeExit = stop
+  signal(SIGTERM, SIG_IGN)
+  terminated.setEventHandler {
+    stop()
+    exit(0)
+  }
+  terminated.resume()
+  Output.requestKeyframe = source.keyframe
+  readCommands(source)
+  source.start()
 case "ios":
   CoreSimulator.developerDir = CoreSimulator.selectedDeveloperDir()
   guard CoreSimulator.deviceSet != nil else { fail("CoreSimulator could not be loaded from \(CoreSimulator.developerDir).") }
   let source = SimulatorSource(udid: arguments[2])
+  beforeExit = source.stop
+  signal(SIGTERM, SIG_IGN)
+  terminated.setEventHandler {
+    source.stop()
+    exit(0)
+  }
+  terminated.resume()
   Output.requestKeyframe = source.keyframe
   readCommands(source)
   source.queue.async { source.start() }
 case "android":
-  let source = EmulatorSource(serial: arguments[2])
+  let source = EmulatorSource(serial: arguments[2], avdName: arguments.count == 4 ? arguments[3] : nil)
+  Output.requestKeyframe = source.keyframe
+  readCommands(source)
+  source.start()
+case "android-device":
+  let source = AndroidDeviceSource(
+    serial: arguments[2], adb: arguments[3], serverJar: URL(fileURLWithPath: arguments[4]))
+  let stop = source.stream.stop
+  beforeExit = stop
+  signal(SIGTERM, SIG_IGN)
+  terminated.setEventHandler {
+    stop()
+    exit(0)
+  }
+  terminated.resume()
+  Output.requestKeyframe = source.keyframe
+  readCommands(source)
+  source.start()
+case "web":
+  guard let endpoint = URL(string: arguments[2]), let pid = Int32(arguments[3]) else { fail(usage) }
+  let source = WebSource(endpoint: endpoint, chromePid: pid, targetId: arguments[4])
   Output.requestKeyframe = source.keyframe
   readCommands(source)
   source.start()
+case "iphone":
+  let source = PhoneSource(udid: arguments[2], name: arguments.count > 3 ? arguments[3] : nil)
+  Output.requestKeyframe = source.keyframe
+  readCommands(source)
+  source.queue.async { source.start() }
 default:
-  fail("usage: stim-frames ios <udid> | android <serial>")
+  fail(usage)
+}
+if arguments[1] == "macos" {
+  // AppKit refreshes NSRunningApplication activation during main run-loop turns.
+  RunLoop.main.add(Port(), forMode: .default)
+  CFRunLoopRun()
+} else {
+  dispatchMain()
 }
-dispatchMain()