@appium/coresim 1.5.0 → 1.6.0

package/src/native/sim_process.mm

@@ -6,6 +6,7 @@
 #include <sys/un.h>
 
 #include <cstring>
+#include <string>
 #include <vector>
 
 namespace coresim {
@@ -25,48 +26,96 @@ NSString* ExecutablePath(pid_t pid) {
   return size > 0 ? [NSString stringWithUTF8String:pathBuf] : nil;
 }
 
-// argv[1] via the unprivileged KERN_PROCARGS2 sysctl (same as `ps`/`lsof`) — for `launchd_sim`
-// that's its bootstrap plist path, which embeds the device's UDID.
-NSString* FirstArgument(pid_t pid) {
+// Layout: argc, exec path, NUL padding, then argv[0..argc-1], then envp[...], each NUL-terminated
+// (envp has no guaranteed empty-string sentinel within the buffer — just runs to `size`).
+std::vector<char> ProcArgs2(pid_t pid) {
   int mib[3] = {CTL_KERN, KERN_PROCARGS2, pid};
   size_t size = 0;
   if (sysctl(mib, 3, nullptr, &size, nullptr, 0) != 0 || size < sizeof(int)) {
-    return nil;
+    return {};
   }
   std::vector<char> buffer(size);
   if (sysctl(mib, 3, buffer.data(), &size, nullptr, 0) != 0) {
+    return {};
+  }
+  return buffer;
+}
+
+const char* SkipExecPathAndPadding(const char* cursor, const char* end) {
+  cursor += strnlen(cursor, static_cast<size_t>(end - cursor));  // skip the exec path
+  while (cursor < end && *cursor == '\0') cursor++;              // skip the NUL padding
+  return cursor;
+}
+
+// Advances past `count` further NUL-terminated entries (e.g. argv), landing just after the last
+// one's terminator — or at `end` if there weren't that many.
+const char* SkipEntries(const char* cursor, const char* end, int count) {
+  for (int i = 0; i < count && cursor < end; i++) {
+    cursor += strnlen(cursor, static_cast<size_t>(end - cursor));
+    if (cursor < end) cursor++;
+  }
+  return cursor;
+}
+
+// argv[1] via the unprivileged KERN_PROCARGS2 sysctl (same as `ps`/`lsof`) — for `launchd_sim`
+// that's its bootstrap plist path, which embeds the device's UDID.
+NSString* FirstArgument(pid_t pid) {
+  std::vector<char> buffer = ProcArgs2(pid);
+  if (buffer.empty()) {
     return nil;
   }
-  // Layout: argc, exec path, NUL padding, then argv[0], argv[1], ..., each NUL-terminated.
   int argc = 0;
   std::memcpy(&argc, buffer.data(), sizeof(argc));
-  const char* cursor = buffer.data() + sizeof(argc);
-  const char* end = buffer.data() + size;
-  cursor += strnlen(cursor, static_cast<size_t>(end - cursor));  // skip the exec path
-  while (cursor < end && *cursor == '\0') cursor++;              // skip the NUL padding
-  cursor += strnlen(cursor, static_cast<size_t>(end - cursor));  // skip argv[0]
-  if (cursor < end) cursor++;                                    // skip its NUL terminator
+  const char* end = buffer.data() + buffer.size();
+  const char* cursor = SkipEntries(SkipExecPathAndPadding(buffer.data() + sizeof(argc), end), end, 1);
   if (argc < 2 || cursor >= end) {
     return nil;
   }
   return [NSString stringWithUTF8String:cursor];
 }
 
-// Each booted simulator has its own `launchd_sim`; finds the one owning `udid`.
-pid_t FindLaunchdSimPid(NSString* udid) {
+// The value of `key=...` in `pid`'s environment, past the end of its argv — same sysctl as
+// FirstArgument, walked further.
+NSString* FindEnvValue(pid_t pid, NSString* key) {
+  std::vector<char> buffer = ProcArgs2(pid);
+  if (buffer.empty()) {
+    return nil;
+  }
+  int argc = 0;
+  std::memcpy(&argc, buffer.data(), sizeof(argc));
+  const char* end = buffer.data() + buffer.size();
+  const char* cursor = SkipEntries(SkipExecPathAndPadding(buffer.data() + sizeof(argc), end), end, argc);
+  std::string prefix = std::string(key.UTF8String) + "=";
+  while (cursor < end && *cursor != '\0') {
+    size_t entryLen = strnlen(cursor, static_cast<size_t>(end - cursor));
+    if (entryLen > prefix.size() && std::memcmp(cursor, prefix.data(), prefix.size()) == 0) {
+      return [NSString stringWithUTF8String:cursor + prefix.size()];
+    }
+    cursor += entryLen;
+    if (cursor < end) cursor++;
+  }
+  return nil;
+}
+
+// Every live pid on the system, via the unprivileged proc_listpids sysctl.
+std::vector<pid_t> AllPids() {
   int neededBytes = proc_listpids(PROC_ALL_PIDS, 0, nullptr, 0);
   if (neededBytes <= 0) {
-    return -1;
+    return {};
   }
   // Headroom for processes started between the sizing call above and the listing call below.
   std::vector<pid_t> pids(neededBytes / sizeof(pid_t) + 64);
   int bytes = proc_listpids(PROC_ALL_PIDS, 0, pids.data(), static_cast<int>(pids.size() * sizeof(pid_t)));
   if (bytes <= 0) {
-    return -1;
+    return {};
   }
-  int count = bytes / static_cast<int>(sizeof(pid_t));
-  for (int i = 0; i < count; i++) {
-    pid_t pid = pids[i];
+  pids.resize(static_cast<size_t>(bytes) / sizeof(pid_t));
+  return pids;
+}
+
+// Each booted simulator has its own `launchd_sim`; finds the one owning `udid`.
+pid_t FindLaunchdSimPid(NSString* udid) {
+  for (pid_t pid : AllPids()) {
     if (pid <= 0) {
       continue;
     }
@@ -136,4 +185,18 @@ NSString* FindWebInspectorSocket(NSString* udid, NSError** error) {
   return socketPath;
 }
 
+std::vector<pid_t> FindGuestProcessPids(NSString* udid) {
+  std::vector<pid_t> result;
+  for (pid_t pid : AllPids()) {
+    if (pid <= 0) {
+      continue;
+    }
+    NSString* value = FindEnvValue(pid, @"SIMULATOR_UDID");
+    if (value != nil && [value caseInsensitiveCompare:udid] == NSOrderedSame) {
+      result.push_back(pid);
+    }
+  }
+  return result;
+}
+
 }  // namespace coresim

package/src/native/sim_video_stream.h

@@ -7,9 +7,9 @@
 #include <memory>
 #include <vector>
 
-namespace coresim {
+#include "video_encoder.h"
 
-enum class VideoStreamCodec { kH264, kHEVC };
+namespace coresim {
 
 // One encoded frame — Annex-B NAL units, concatenated. A keyframe's `data` has parameter sets
 // (SPS/PPS, or VPS/SPS/PPS for HEVC) prepended, so every keyframe is self-decodable alone.
@@ -21,20 +21,16 @@ struct VideoAccessUnit {
   int64_t timestampMicros = 0;
 };
 
-struct VideoStreamOptions {
-  VideoStreamCodec codec = VideoStreamCodec::kH264;
-  NSString* displayId = nil;
-  double fps = 15.0;
-  int bitrate = 2000000;
-};
-
 // Polls the live display IOSurface (sim_screenshot.h) on a serial queue and encodes changed
 // frames via the public VideoToolbox API — unlike StartVideoRecording's private, file-only
 // recorder, this delivers access units live. Full thread-safety contract: see CLAUDE.md.
 class VideoStreamSession {
  public:
-  VideoStreamSession(id device, VideoStreamOptions options, std::function<void(VideoAccessUnit)> onAccessUnit,
-                     std::function<void(NSError*)> onError, std::function<void()> onEnd);
+  // `onAbortDelivery`, if set, is invoked by AbortDelivery() below — not called by this class on
+  // its own.
+  VideoStreamSession(id device, VideoEncoderOptions options, std::function<void(VideoAccessUnit)> onAccessUnit,
+                     std::function<void(NSError*)> onError, std::function<void()> onEnd,
+                     std::function<void()> onAbortDelivery = nullptr);
   ~VideoStreamSession();
 
   VideoStreamSession(const VideoStreamSession&) = delete;
@@ -48,6 +44,13 @@ class VideoStreamSession {
   // onError/onEnd — same queue this blocks on, so it would deadlock.
   void Stop();
 
+  // Runs the constructor's `onAbortDelivery` (if any) — e.g. aborting a bounded delivery queue so
+  // a producer thread blocked pushing into it unblocks. Call before Stop() when the caller can't
+  // rely on anything else draining that queue concurrently (e.g. process-exit cleanup running
+  // synchronously on the same thread `Stop()` would otherwise wait on) — a normal Stop() doesn't
+  // need this. Safe from any thread; a no-op if unset.
+  void AbortDelivery();
+
   // Forces the next encoded frame to be a keyframe (self-decodable, parameter sets included) —
   // e.g. so a consumer that just resynced after dropping frames can resume cleanly instead of
   // waiting for the next periodic one. Safe from any thread; just sets a flag.

package/src/native/sim_video_stream.mm

@@ -1,372 +1,34 @@
 #include "sim_video_stream.h"
 
-#import <CoreMedia/CoreMedia.h>
-#import <CoreVideo/CoreVideo.h>
-#import <IOSurface/IOSurface.h>
-#import <VideoToolbox/VideoToolbox.h>
-
-#include <algorithm>
 #include <atomic>
-#include <ctime>
 
-#include "nserror_bridge.h"
-#include "safe_dispatch.h"
-#include "sim_screenshot.h"
+#include "video_encoder.h"
 
 namespace coresim {
 
-namespace {
-
-NSString* const kVideoStreamErrorDomain = @"com.appium.coresim.VideoStream";
-
-NSError* MakeError(NSInteger code, NSString* message) {
-  return [NSError errorWithDomain:kVideoStreamErrorDomain code:code userInfo:@{NSLocalizedDescriptionKey : message}];
-}
-
-NSError* MakeStatusError(NSInteger code, NSString* what, OSStatus status) {
-  return MakeError(code, [NSString stringWithFormat:@"%@ (OSStatus %d)", what, static_cast<int>(status)]);
-}
-
-// CFAbsoluteTimeGetCurrent() is wall time — subject to backward NTP/manual clock corrections,
-// which would violate VTCompressionSessionEncodeFrame's requirement of strictly increasing PTS.
-// CLOCK_MONOTONIC_RAW never goes backward and isn't adjusted by NTP.
-double MonotonicSeconds() {
-  struct timespec ts;
-  clock_gettime(CLOCK_MONOTONIC_RAW, &ts);
-  return static_cast<double>(ts.tv_sec) + static_cast<double>(ts.tv_nsec) / 1e9;
-}
-
-void AppendAnnexB(std::vector<uint8_t>& out, const uint8_t* nal, size_t length) {
-  static const uint8_t kStartCode[4] = {0, 0, 0, 1};
-  out.insert(out.end(), kStartCode, kStartCode + 4);
-  out.insert(out.end(), nal, nal + length);
-}
-
-// VideoToolbox's compressed output is AVCC-framed (a 4-byte big-endian length prefix per NAL,
-// no start codes) — rewrites it into Annex-B, matching VideoAccessUnit's documented wire format.
-void AppendSampleBufferNALs(std::vector<uint8_t>& out, CMSampleBufferRef sampleBuffer) {
-  CMBlockBufferRef block = CMSampleBufferGetDataBuffer(sampleBuffer);
-  if (block == nullptr) {
-    return;
-  }
-  size_t totalLength = CMBlockBufferGetDataLength(block);
-  if (totalLength == 0) {
-    return;
-  }
-  // CMBlockBufferGetDataPointer's pointer only covers the contiguous region starting at the given
-  // offset, which for a segmented buffer (multiple backing memory blocks — CoreMedia's documented
-  // contract, not just a VideoToolbox implementation detail) can be far shorter than totalLength;
-  // reading up to totalLength through it would run past that region. CopyDataBytes stitches
-  // segments together into a caller-owned, guaranteed-contiguous copy instead.
-  std::vector<uint8_t> data(totalLength);
-  if (CMBlockBufferCopyDataBytes(block, 0, totalLength, data.data()) != kCMBlockBufferNoErr) {
-    return;
-  }
-  const uint8_t* dataPointer = data.data();
-  size_t offset = 0;
-  while (offset + 4 <= totalLength) {
-    uint32_t nalLength = (static_cast<uint32_t>(dataPointer[offset]) << 24) |
-                         (static_cast<uint32_t>(dataPointer[offset + 1]) << 16) |
-                         (static_cast<uint32_t>(dataPointer[offset + 2]) << 8) | dataPointer[offset + 3];
-    offset += 4;
-    if (nalLength == 0 || offset + nalLength > totalLength) {
-      break;
-    }
-    AppendAnnexB(out, dataPointer + offset, nalLength);
-    offset += nalLength;
-  }
-}
-
-using ParameterSetAtIndexFn = OSStatus (*)(CMFormatDescriptionRef, size_t, const uint8_t**, size_t*, size_t*, int*);
-
-void AppendParameterSets(std::vector<uint8_t>& out, CMFormatDescriptionRef format, ParameterSetAtIndexFn getAtIndex) {
-  size_t count = 0;
-  if (getAtIndex(format, 0, nullptr, nullptr, &count, nullptr) != noErr) {
-    return;
-  }
-  for (size_t i = 0; i < count; i++) {
-    const uint8_t* bytes = nullptr;
-    size_t size = 0;
-    if (getAtIndex(format, i, &bytes, &size, nullptr, nullptr) == noErr) {
-      AppendAnnexB(out, bytes, size);
-    }
-  }
-}
-
-}  // namespace
-
 class VideoStreamSession::Impl {
  public:
-  Impl(id device, VideoStreamOptions options, std::function<void(VideoAccessUnit)> onAccessUnit,
-       std::function<void(NSError*)> onError, std::function<void()> onEnd)
-      : device_(device),
-        options_(options),
-        onAccessUnit_(std::move(onAccessUnit)),
-        onError_(std::move(onError)),
-        onEnd_(std::move(onEnd)) {
-    queue_ = dispatch_queue_create("com.appium.coresim.videoStream", DISPATCH_QUEUE_SERIAL);
-  }
-
-  ~Impl() { Stop(); }
-
-  void Start() {
-    NSError* error = nil;
-    id descriptor = ResolveCaptureDisplay(device_, options_.displayId, &error);
-    if (descriptor == nil) {
-      throw NSErrorException(error);
-    }
-    id surfaceObj = CurrentDisplaySurface(descriptor);
-    if (surfaceObj == nil) {
-      throw NSErrorException(MakeError(4, @"The device's display surface is not available yet"));
-    }
-    IOSurfaceRef surface = (__bridge IOSurfaceRef)surfaceObj;
-    // Set up synchronously (not lazily on the first Tick()) so a setup failure rejects Start()
-    // directly rather than only reaching onError, which the caller may not be listening for yet.
-    NSError* setupError = nil;
-    if (!SetUpSession(surface, &setupError)) {
-      throw NSErrorException(setupError);
-    }
-    // Must be set before EncodeSurface below — both it and HandleEncodedSample measure elapsed
-    // time from this.
-    startTime_ = MonotonicSeconds();
-    // Encode immediately rather than waiting for a *changed* seed on the first tick, or the
-    // stream would stay silent until the display changes again. running_ is set true before this
-    // call (not after), since VTCompressionSessionEncodeFrame's output callback can in principle
-    // fire on another thread before this one returns — HandleEncodedSample discards samples while
-    // running_ is false, which would otherwise silently drop the stream's very first (keyframe)
-    // access unit. A failure resets it and tears session_ down itself here, rather than going
-    // through Stop()/onEnd_ (see coresim.mm — onEnd_ firing this early would double-release its
-    // ThreadSafeFunctions).
-    running_ = true;
-    bool encoded = false;
-    try {
-      encoded = EncodeSurface(surface);
-    } catch (...) {
-      running_ = false;
-      VTCompressionSessionInvalidate(session_);
-      CFRelease(session_);
-      session_ = nullptr;
-      throw;
-    }
-    // Only commit the seed once a frame was actually submitted — a transient pixel-buffer
-    // creation failure (EncodeSurface returning false) otherwise leaves lastSeed_ at its default
-    // 0, so the first Tick() sees the real seed as "changed" and retries automatically instead of
-    // the stream going silent forever on a display that never changes again.
-    if (encoded) {
-      lastSeed_ = IOSurfaceGetSeed(surface);
-    }
-
-    double interval = 1.0 / std::max(options_.fps, 1.0);
-    dispatch_source_t timer = dispatch_source_create(DISPATCH_SOURCE_TYPE_TIMER, 0, 0, queue_);
-    dispatch_source_set_timer(timer, dispatch_time(DISPATCH_TIME_NOW, 0),
-                              static_cast<uint64_t>(interval * NSEC_PER_SEC),
-                              static_cast<uint64_t>(interval * NSEC_PER_SEC / 10));
-    // `this` outlives the timer: Stop()/StopFromQueue() always drain or outrun it before `this`
-    // can be destroyed (see their comments below).
-    dispatch_source_set_event_handler(timer, ^{
-      Tick();
-    });
-    timer_ = timer;
-    dispatch_resume(timer_);
+  Impl(id device, VideoEncoderOptions options, std::function<void(VideoAccessUnit)> onAccessUnit,
+       std::function<void(NSError*)> onError, std::function<void()> onEnd, std::function<void()> onAbortDelivery)
+      : options_(options), onAccessUnit_(std::move(onAccessUnit)), onAbortDelivery_(std::move(onAbortDelivery)) {
+    encoder_ = std::make_unique<VideoFrameEncoder>(
+        device, options, [this](CMSampleBufferRef sampleBuffer) { HandleEncodedSample(sampleBuffer); },
+        std::move(onError), std::move(onEnd));
   }
 
-  // Callable from any thread except `queue_` itself (would deadlock on the dispatch_sync below).
-  void Stop() {
-    if (!running_.exchange(false)) {
-      return;  // idempotent
-    }
-    if (timer_ != nullptr) {
-      dispatch_source_cancel(timer_);
-      // Blocks until any in-flight Tick() finishes — by then running_ is already false, so it
-      // won't touch session_ again.
-      dispatch_sync(queue_, ^{
-                    });
-      timer_ = nullptr;
+  void Start() { encoder_->Start(); }
+  void Stop() { encoder_->Stop(); }
+  void AbortDelivery() {
+    if (onAbortDelivery_) {
+      onAbortDelivery_();
     }
-    TearDownSessionAndFireEnd();
   }
-
-  void RequestKeyFrame() { forceKeyFrame_ = true; }
+  void RequestKeyFrame() { encoder_->RequestKeyFrame(); }
 
  private:
-  // Same as Stop() minus the dispatch_sync barrier — only safe from within Tick() itself, already
-  // serialized on `queue_`; would race a concurrent Tick() from any other thread.
-  void StopFromQueue() {
-    if (!running_.exchange(false)) {
-      return;  // idempotent — e.g. an external Stop() already won this race
-    }
-    if (timer_ != nullptr) {
-      dispatch_source_cancel(timer_);
-      timer_ = nullptr;
-    }
-    TearDownSessionAndFireEnd();
-  }
-
-  void TearDownSessionAndFireEnd() {
-    if (session_ != nullptr) {
-      // Flushes and blocks until every already-submitted frame's callback has returned — without
-      // this, a frame submitted just before Stop() could fire after onEnd_ releases the
-      // ThreadSafeFunctions below (a use-after-release; see CLAUDE.md).
-      VTCompressionSessionCompleteFrames(session_, kCMTimeInvalid);
-      VTCompressionSessionInvalidate(session_);
-      CFRelease(session_);
-      session_ = nullptr;
-    }
-    if (onEnd_) {
-      onEnd_();
-    }
-  }
-
-  void Tick() {
-    if (!running_) {
-      return;
-    }
-    if (pendingErrorTeardown_) {
-      // HandleEncodedSample (below) can run on VideoToolbox's own callback thread, where it's
-      // unsafe to tear down directly — StopFromQueue()/CompleteFrames() are only safe already
-      // serialized on `queue_` (here), and CompleteFrames specifically would deadlock waiting on
-      // its own still-executing callback. It sets this flag instead; picked up on the very next
-      // tick (queue_-serialized, safe) rather than via a raw cross-thread dispatch, since nothing
-      // here can outlive `this` the way a block captured on another thread otherwise could.
-      StopFromQueue();
-      return;
-    }
-    @autoreleasepool {
-      try {
-        // Re-resolved every tick (like CaptureScreenshot does), not cached once in Start(), so a
-        // deleted device or disconnected display surfaces a real error instead of Tick() quietly
-        // doing nothing forever.
-        NSError* resolveError = nil;
-        id descriptor = ResolveCaptureDisplay(device_, options_.displayId, &resolveError);
-        if (descriptor == nil) {
-          if (onError_) {
-            onError_(resolveError);
-          }
-          StopFromQueue();
-          return;
-        }
-        id surfaceObj = CurrentDisplaySurface(descriptor);
-        if (surfaceObj == nil) {
-          return;  // transient — the connection may not have a frame ready yet, try again next tick
-        }
-        IOSurfaceRef surface = (__bridge IOSurfaceRef)surfaceObj;
-        uint32_t seed = IOSurfaceGetSeed(surface);
-        if (seed == lastSeed_) {
-          return;  // unchanged since the last tick — mirrors CoreSimulator's own recorder, which
-                   // only encodes a frame when the display actually changes (see CLAUDE.md)
-        }
-        // Only commit the new seed once EncodeSurface actually submits it — a transient failure
-        // (pixel-buffer creation) must leave lastSeed_ stale so the next tick retries this same
-        // frame instead of silently going quiet until the display changes again.
-        if (EncodeSurface(surface)) {
-          lastSeed_ = seed;
-        }
-      } catch (const std::exception& e) {
-        // Without this, an exception here (e.g. a dropped display-proxy connection) would escape
-        // this bare GCD timer handler uncaught and crash the whole process (see CLAUDE.md).
-        if (onError_) {
-          onError_(MakeError(3, [NSString stringWithFormat:@"Video stream encoding failed: %s", e.what()]));
-        }
-        StopFromQueue();
-      }
-    }
-  }
-
-  bool SetUpSession(IOSurfaceRef surface, NSError** error) {
-    int32_t width = static_cast<int32_t>(IOSurfaceGetWidth(surface));
-    int32_t height = static_cast<int32_t>(IOSurfaceGetHeight(surface));
-    CMVideoCodecType codecType =
-        options_.codec == VideoStreamCodec::kHEVC ? kCMVideoCodecType_HEVC : kCMVideoCodecType_H264;
-    OSStatus status = VTCompressionSessionCreate(kCFAllocatorDefault, width, height, codecType, nullptr, nullptr,
-                                                 kCFAllocatorDefault, OutputCallback, this, &session_);
-    if (status != noErr) {
-      *error = MakeStatusError(1, @"Failed to create a VTCompressionSession", status);
-      return false;
-    }
-    // Clamped like Start()'s timer interval — an unvalidated 0 here would set MaxKeyFrameInterval
-    // to an out-of-spec value.
-    double fps = std::max(options_.fps, 1.0);
-    status = VTSessionSetProperty(session_, kVTCompressionPropertyKey_RealTime, kCFBooleanTrue);
-    if (status == noErr) {
-      status = VTSessionSetProperty(session_, kVTCompressionPropertyKey_AllowFrameReordering, kCFBooleanFalse);
-    }
-    if (status == noErr) {
-      status = VTSessionSetProperty(session_, kVTCompressionPropertyKey_AverageBitRate,
-                                    (__bridge CFNumberRef) @(options_.bitrate));
-    }
-    if (status == noErr) {
-      status =
-          VTSessionSetProperty(session_, kVTCompressionPropertyKey_ExpectedFrameRate, (__bridge CFNumberRef) @(fps));
-    }
-    if (status == noErr) {
-      status = VTSessionSetProperty(session_, kVTCompressionPropertyKey_MaxKeyFrameInterval,
-                                    (__bridge CFNumberRef) @(static_cast<int>(fps * 2)));
-    }
-    if (status != noErr) {
-      *error = MakeStatusError(2, @"Failed to configure the VTCompressionSession", status);
-      VTCompressionSessionInvalidate(session_);
-      CFRelease(session_);
-      session_ = nullptr;
-      return false;
-    }
-    VTCompressionSessionPrepareToEncodeFrames(session_);
-    return true;
-  }
-
-  // Returns whether a frame was actually submitted to the encoder — false for a transient
-  // pixel-buffer creation failure the caller should retry, as opposed to a real encode failure
-  // (thrown, not returned, since that tears down the whole stream).
-  bool EncodeSurface(IOSurfaceRef surface) {
-    CVPixelBufferRef pixelBuffer = nullptr;
-    CVReturn cvStatus = CVPixelBufferCreateWithIOSurface(kCFAllocatorDefault, surface, nullptr, &pixelBuffer);
-    if (cvStatus != kCVReturnSuccess || pixelBuffer == nullptr) {
-      return false;  // transient — try again next tick rather than tearing down the whole stream
-    }
-    CMTime pts = CMTimeMake(static_cast<int64_t>((MonotonicSeconds() - startTime_) * 1000000), 1000000);
-    NSDictionary* frameProperties = nil;
-    if (forceKeyFrame_.exchange(false)) {
-      frameProperties = @{(__bridge NSString*)kVTEncodeFrameOptionKey_ForceKeyFrame : @YES};
-    }
-    OSStatus status = VTCompressionSessionEncodeFrame(session_, pixelBuffer, pts, kCMTimeInvalid,
-                                                      (__bridge CFDictionaryRef)frameProperties, nullptr, nullptr);
-    CVPixelBufferRelease(pixelBuffer);
-    if (status != noErr) {
-      throw std::runtime_error([[NSString stringWithFormat:@"VTCompressionSessionEncodeFrame failed (OSStatus %d)",
-                                                           static_cast<int>(status)] UTF8String]);
-    }
-    return true;
-  }
-
-  static void OutputCallback(void* outputCallbackRefCon, void* /*sourceFrameRefCon*/, OSStatus status,
-                             VTEncodeInfoFlags /*infoFlags*/, CMSampleBufferRef sampleBuffer) {
-    static_cast<Impl*>(outputCallbackRefCon)->HandleEncodedSample(status, sampleBuffer);
-  }
-
-  void HandleEncodedSample(OSStatus status, CMSampleBufferRef sampleBuffer) {
-    if (!running_) {
-      return;
-    }
-    if (status != noErr) {
-      // Only the first failure is reported — pendingErrorTeardown_ doubles as the report-once
-      // gate, since Tick() (the only place that consumes it) only ever needs to see it once too.
-      if (!pendingErrorTeardown_.exchange(true)) {
-        if (onError_) {
-          onError_(MakeStatusError(3, @"VideoToolbox reported an encoding failure", status));
-        }
-      }
-      return;
-    }
-    if (sampleBuffer == nullptr) {
-      return;
-    }
-    bool isKeyFrame = true;
-    CFArrayRef attachments = CMSampleBufferGetSampleAttachmentsArray(sampleBuffer, false);
-    if (attachments != nullptr && CFArrayGetCount(attachments) > 0) {
-      CFDictionaryRef attachment = static_cast<CFDictionaryRef>(CFArrayGetValueAtIndex(attachments, 0));
-      isKeyFrame = !CFDictionaryContainsKey(attachment, kCMSampleAttachmentKey_NotSync);
-    }
-
-    // From the sample's own presentation timestamp (as submitted in EncodeSurface), not a fresh
+  void HandleEncodedSample(CMSampleBufferRef sampleBuffer) {
+    bool isKeyFrame = IsKeyFrame(sampleBuffer);
+    // From the sample's own presentation timestamp (as submitted to the encoder), not a fresh
     // wall-clock read here — this callback can fire well after encoding actually happened, and
     // resampling "now" would report a later, jittery timestamp than when the frame was captured.
     CMTime pts = CMSampleBufferGetPresentationTimeStamp(sampleBuffer);
@@ -374,47 +36,27 @@ class VideoStreamSession::Impl {
     unit.isKeyFrame = isKeyFrame;
     unit.sequence = sequence_++;
     unit.timestampMicros = pts.timescale != 0 ? (pts.value * 1000000 / pts.timescale) : 0;
-    if (isKeyFrame) {
-      CMFormatDescriptionRef format = CMSampleBufferGetFormatDescription(sampleBuffer);
-      if (format != nullptr) {
-        if (options_.codec == VideoStreamCodec::kHEVC) {
-          AppendParameterSets(unit.data, format, CMVideoFormatDescriptionGetHEVCParameterSetAtIndex);
-        } else {
-          AppendParameterSets(unit.data, format, CMVideoFormatDescriptionGetH264ParameterSetAtIndex);
-        }
-      }
-    }
-    AppendSampleBufferNALs(unit.data, sampleBuffer);
+    RepackAsAnnexB(unit.data, sampleBuffer, isKeyFrame, options_.codec);
     if (onAccessUnit_) {
       onAccessUnit_(std::move(unit));
     }
   }
 
-  id device_;
-  VideoStreamOptions options_;
+  VideoEncoderOptions options_;
   std::function<void(VideoAccessUnit)> onAccessUnit_;
-  std::function<void(NSError*)> onError_;
-  std::function<void()> onEnd_;
-
-  dispatch_queue_t queue_ = nullptr;
-  dispatch_source_t timer_ = nullptr;
-  VTCompressionSessionRef session_ = nullptr;
-  uint32_t lastSeed_ = 0;
+  std::function<void()> onAbortDelivery_;
+  std::unique_ptr<VideoFrameEncoder> encoder_;
   // VideoToolbox's output callback isn't documented as single-threaded, so this is read-modify-
   // written atomically rather than assuming HandleEncodedSample never runs concurrently.
   std::atomic<uint64_t> sequence_{0};
-  double startTime_ = 0;
-  std::atomic<bool> running_{false};
-  // Set by HandleEncodedSample (possibly off queue_) on an encoder failure, consumed by the next
-  // Tick() (on queue_) — see both for why teardown can't just happen inline there.
-  std::atomic<bool> pendingErrorTeardown_{false};
-  std::atomic<bool> forceKeyFrame_{false};
 };
 
-VideoStreamSession::VideoStreamSession(id device, VideoStreamOptions options,
+VideoStreamSession::VideoStreamSession(id device, VideoEncoderOptions options,
                                        std::function<void(VideoAccessUnit)> onAccessUnit,
-                                       std::function<void(NSError*)> onError, std::function<void()> onEnd)
-    : impl_(std::make_unique<Impl>(device, options, std::move(onAccessUnit), std::move(onError), std::move(onEnd))) {}
+                                       std::function<void(NSError*)> onError, std::function<void()> onEnd,
+                                       std::function<void()> onAbortDelivery)
+    : impl_(std::make_unique<Impl>(device, options, std::move(onAccessUnit), std::move(onError), std::move(onEnd),
+                                   std::move(onAbortDelivery))) {}
 
 VideoStreamSession::~VideoStreamSession() = default;
 
@@ -422,6 +64,8 @@ void VideoStreamSession::Start() { impl_->Start(); }
 
 void VideoStreamSession::Stop() { impl_->Stop(); }
 
+void VideoStreamSession::AbortDelivery() { impl_->AbortDelivery(); }
+
 void VideoStreamSession::RequestKeyFrame() { impl_->RequestKeyFrame(); }
 
 }  // namespace coresim