@appium/coresim 1.5.0 → 1.7.0

package/src/native/av_stream.mm

@@ -0,0 +1,217 @@
+#include "av_stream.h"
+
+#include <atomic>
+#include <mutex>
+
+#include "audio_encoder.h"
+#include "monotonic_clock.h"
+#include "sim_audio_tap.h"
+
+namespace coresim {
+
+class AVStreamSession::Impl {
+ public:
+  Impl(id device, NSString* udid, VideoEncoderOptions videoOptions, std::function<void(AVAccessUnit)> onAccessUnit,
+       std::function<void(NSError*)> onError, std::function<void()> onEnd, std::function<void()> onAbortDelivery)
+      : device_(device),
+        udid_(udid),
+        videoOptions_(videoOptions),
+        onAccessUnit_(std::move(onAccessUnit)),
+        onError_(std::move(onError)),
+        onEnd_(std::move(onEnd)),
+        onAbortDelivery_(std::move(onAbortDelivery)) {}
+
+  ~Impl() { StopInternal(); }
+
+  void Start() {
+    clockOrigin_ = MonotonicSeconds();
+    running_ = true;
+    try {
+      audioTap_ = std::make_unique<AudioTapSession>(
+          udid_, [this](const AudioBufferList* data, const AudioTimeStamp* time) { HandleAudioPCM(data, time); },
+          [this](NSError* error) {
+            // A failed process-list refresh (kAudioTapNonFatalProcessListRefreshErrorCode) isn't
+            // fatal — the tap keeps running. Everything else is.
+            if ([error.domain isEqualToString:kAudioTapErrorDomain] &&
+                error.code == kAudioTapNonFatalProcessListRefreshErrorCode) {
+              return;
+            }
+            Fail(error, /*fromVideo=*/false);
+          },
+          [] {});
+      audioTap_->Start();
+
+      // Start() can invoke HandleAudioPCM before returning, so audioEncoder_ is written under
+      // audioEncoderMutex_ (same lock HandleAudioPCM reads it under) to avoid a torn/racy read.
+      auto encoder = std::make_unique<AudioEncoder>(
+          audioTap_->Format(), [this](CMSampleBufferRef sampleBuffer) { HandleAudioSample(sampleBuffer); },
+          &clockOrigin_);
+      {
+        std::lock_guard<std::mutex> lock(audioEncoderMutex_);
+        audioEncoder_ = std::move(encoder);
+      }
+
+      videoEncoder_ = std::make_unique<VideoFrameEncoder>(
+          device_, videoOptions_, [this](CMSampleBufferRef sampleBuffer) { HandleVideoSample(sampleBuffer); },
+          [this](NSError* error) { Fail(error, /*fromVideo=*/true); }, [] {}, &clockOrigin_);
+      videoEncoder_->Start();
+    } catch (...) {
+      running_ = false;
+      StopInternal();
+      throw;
+    }
+  }
+
+  void Stop() { StopInternal(); }
+
+  void AbortDelivery() {
+    if (onAbortDelivery_) {
+      onAbortDelivery_();
+    }
+  }
+
+  void RequestKeyFrame() {
+    if (videoEncoder_) {
+      videoEncoder_->RequestKeyFrame();
+    }
+  }
+
+ private:
+  // Runs on AudioTapSession's own queue; audioEncoder_ is guarded by audioEncoderMutex_ (see
+  // Start()). A throw from EncodePCM is left to propagate — AudioTapSession::HandleBuffer catches
+  // it and self-stops (see sim_audio_tap.h's onBuffer doc) — never call audioTap_->Stop() here.
+  void HandleAudioPCM(const AudioBufferList* data, const AudioTimeStamp* time) {
+    AudioEncoder* encoder;
+    {
+      std::lock_guard<std::mutex> lock(audioEncoderMutex_);
+      if (!running_) {
+        return;
+      }
+      encoder = audioEncoder_.get();
+    }
+    if (encoder != nullptr) {
+      encoder->EncodePCM(data, time);
+    }
+  }
+
+  void HandleVideoSample(CMSampleBufferRef sampleBuffer) {
+    if (!running_) {
+      return;
+    }
+    bool isKeyFrame = IsKeyFrame(sampleBuffer);
+    CMTime pts = CMSampleBufferGetPresentationTimeStamp(sampleBuffer);
+    AVAccessUnit unit;
+    unit.track = AVTrack::kVideo;
+    unit.isKeyFrame = isKeyFrame;
+    unit.sequence = videoSequence_++;
+    unit.timestampMicros = pts.timescale != 0 ? (pts.value * 1000000 / pts.timescale) : 0;
+    RepackAsAnnexB(unit.data, sampleBuffer, isKeyFrame, videoOptions_.codec);
+    if (onAccessUnit_) {
+      onAccessUnit_(std::move(unit));
+    }
+  }
+
+  void HandleAudioSample(CMSampleBufferRef sampleBuffer) {
+    if (!running_) {
+      return;
+    }
+    CMBlockBufferRef block = CMSampleBufferGetDataBuffer(sampleBuffer);
+    if (block == nullptr) {
+      return;
+    }
+    size_t length = CMBlockBufferGetDataLength(block);
+    AVAccessUnit unit;
+    unit.track = AVTrack::kAudio;
+    unit.isKeyFrame = true;  // every AAC-LC packet is independently decodable
+    unit.sequence = audioSequence_++;
+    CMTime pts = CMSampleBufferGetPresentationTimeStamp(sampleBuffer);
+    unit.timestampMicros = pts.timescale != 0 ? (pts.value * 1000000 / pts.timescale) : 0;
+    // ADTS-framed (not bare AAC) so each packet self-describes its sample rate/channel count — a
+    // streaming consumer has no other way to learn those, unlike the muxed-file recording path
+    // (av_recording.h), which hands AVAssetWriter the format directly.
+    PrependADTSHeader(unit.data, length, audioTap_->Format());
+    size_t headerSize = unit.data.size();
+    unit.data.resize(headerSize + length);
+    if (CMBlockBufferCopyDataBytes(block, 0, length, unit.data.data() + headerSize) != kCMBlockBufferNoErr) {
+      return;
+    }
+    if (onAccessUnit_) {
+      onAccessUnit_(std::move(unit));
+    }
+  }
+
+  // Called from either encoder's onError. Stops only the OTHER (still-running) one — the failing
+  // one is already tearing itself down on its own error path, and calling its own blocking Stop()
+  // from within its own callback would deadlock.
+  void Fail(NSError* error, bool fromVideo) {
+    if (!running_.exchange(false)) {
+      return;  // already stopping/stopped
+    }
+    if (fromVideo) {
+      if (audioTap_) {
+        audioTap_->Stop();
+      }
+    } else {
+      if (videoEncoder_) {
+        videoEncoder_->Stop();
+      }
+    }
+    if (onError_) {
+      onError_(error);
+    }
+    if (onEnd_) {
+      onEnd_();
+    }
+  }
+
+  void StopInternal() {
+    if (!running_.exchange(false)) {
+      return;  // idempotent
+    }
+    if (videoEncoder_) {
+      videoEncoder_->Stop();
+    }
+    if (audioTap_) {
+      audioTap_->Stop();
+    }
+    if (onEnd_) {
+      onEnd_();
+    }
+  }
+
+  id device_;
+  NSString* udid_;
+  VideoEncoderOptions videoOptions_;
+  std::function<void(AVAccessUnit)> onAccessUnit_;
+  std::function<void(NSError*)> onError_;
+  std::function<void()> onEnd_;
+  std::function<void()> onAbortDelivery_;
+
+  double clockOrigin_ = 0;
+  std::unique_ptr<VideoFrameEncoder> videoEncoder_;
+  std::unique_ptr<AudioTapSession> audioTap_;
+  std::mutex audioEncoderMutex_;  // guards audioEncoder_ — see HandleAudioPCM/Start()
+  std::unique_ptr<AudioEncoder> audioEncoder_;
+
+  std::atomic<uint64_t> videoSequence_{0};
+  std::atomic<uint64_t> audioSequence_{0};
+  std::atomic<bool> running_{false};
+};
+
+AVStreamSession::AVStreamSession(id device, NSString* udid, VideoEncoderOptions videoOptions,
+                                 std::function<void(AVAccessUnit)> onAccessUnit, std::function<void(NSError*)> onError,
+                                 std::function<void()> onEnd, std::function<void()> onAbortDelivery)
+    : impl_(std::make_unique<Impl>(device, udid, videoOptions, std::move(onAccessUnit), std::move(onError),
+                                   std::move(onEnd), std::move(onAbortDelivery))) {}
+
+AVStreamSession::~AVStreamSession() = default;
+
+void AVStreamSession::Start() { impl_->Start(); }
+
+void AVStreamSession::Stop() { impl_->Stop(); }
+
+void AVStreamSession::AbortDelivery() { impl_->AbortDelivery(); }
+
+void AVStreamSession::RequestKeyFrame() { impl_->RequestKeyFrame(); }
+
+}  // namespace coresim

package/src/native/monotonic_clock.h

@@ -0,0 +1,20 @@
+#pragma once
+
+#include <ctime>
+
+namespace coresim {
+
+// CFAbsoluteTimeGetCurrent()/gettimeofday() are wall time — subject to backward NTP/manual clock
+// corrections, which would violate encoders' requirement of strictly increasing presentation
+// timestamps. CLOCK_MONOTONIC_RAW never goes backward and isn't adjusted by NTP. Shared by
+// video_encoder.mm, audio_encoder.mm, and av_recording.mm/av_stream.mm — the latter two capture
+// one value from this up front and hand it to both encoders as their common PTS-zero reference,
+// so a combined recording/stream's video and audio tracks stay in sync instead of each measuring
+// elapsed time from its own, independently-timed setup completion.
+inline 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;
+}
+
+}  // namespace coresim

package/src/native/sim_audio_tap.h

@@ -0,0 +1,67 @@
+#pragma once
+
+#import <CoreAudio/CoreAudio.h>
+#import <Foundation/Foundation.h>
+
+#include <functional>
+#include <memory>
+
+namespace coresim {
+
+// Domain of every NSError AudioTapSession reports via its `onError` callback.
+extern NSString* const kAudioTapErrorDomain;
+
+// The one `onError` code that does NOT mean the session stopped itself: a failed attempt to
+// refresh the tapped process list — it keeps running on the stale set and retries next poll tick.
+// Every other code means the session already tore itself down. Callers that otherwise treat every
+// `onError` as fatal must special-case this one.
+constexpr NSInteger kAudioTapNonFatalProcessListRefreshErrorCode = 9;
+
+// Captures one simulator's audio via macOS's public Core Audio "process tap" API
+// (CATapDescription + AudioHardwareCreateProcessTap, macOS 14.2+), scoped to the live set of host
+// PIDs belonging to that device's guest process tree (SpringBoard + any launched app — see
+// sim_process.h's FindGuestProcessPids). CoreSimulator itself has no audio *capture* API at all
+// (see CLAUDE.md) — this taps the guest's own processes directly, isolating one simulator's audio
+// from other simulators and from unrelated Mac apps.
+//
+// IMPORTANT — host TCC permission required, not obtainable programmatically: creating a process
+// tap for another process's audio requires the host's "System Audio Recording Only" permission
+// (kTCCServiceAudioCapture), granted once via System Settings > Privacy & Security. Unlike every
+// other permission this addon handles, this one is keyed to the host Node process's code-signing
+// identity, lives in the host's SIP-protected system TCC database (no direct-write workaround like
+// tcc_privacy.mm's), and has no query API — a denial isn't a catchable error, it's silent
+// all-zero PCM. See CLAUDE.md for the full writeup; this is a documented limitation, not a bug.
+class AudioTapSession {
+ public:
+  // `onBuffer` delivers each IO cycle's tapped PCM, in the tap's own AudioStreamBasicDescription
+  // (query via Format() after Start()) — valid only for the duration of the call, copy out
+  // anything needed beyond it. If it throws, the session catches it, reports via `onError`, and
+  // stops itself — no try/catch needed in `onBuffer`, and it must never call this session's own
+  // Stop() (runs on the session's internal queue — would deadlock). `onError`/`onEnd` mirror
+  // VideoFrameEncoder's contract, except `onError` can also fire non-fatally — see
+  // kAudioTapNonFatalProcessListRefreshErrorCode.
+  AudioTapSession(NSString* udid, std::function<void(const AudioBufferList*, const AudioTimeStamp*)> onBuffer,
+                  std::function<void(NSError*)> onError, std::function<void()> onEnd);
+  ~AudioTapSession();
+
+  AudioTapSession(const AudioTapSession&) = delete;
+  AudioTapSession& operator=(const AudioTapSession&) = delete;
+
+  // Resolves the device's current guest process set, creates the tap + aggregate device, and
+  // starts IO. Throws synchronously on failure (`onEnd` never called then) — including
+  // NativeSimUnavailableError if this macOS predates process taps (< 14.2), and a plain
+  // NSErrorException if the guest process set is empty (device not really booted).
+  void Start();
+
+  // Idempotent; blocks until IO has fully stopped and the tap/aggregate device are destroyed.
+  void Stop();
+
+  // The tap's live PCM format — valid only after Start() returns.
+  const AudioStreamBasicDescription& Format() const;
+
+ private:
+  class Impl;
+  std::unique_ptr<Impl> impl_;
+};
+
+}  // namespace coresim

package/src/native/sim_audio_tap.mm

@@ -0,0 +1,350 @@
+#include "sim_audio_tap.h"
+
+#import <CoreAudio/AudioHardwareTapping.h>
+#import <CoreAudio/CATapDescription.h>
+
+#include <algorithm>
+#include <atomic>
+
+#include "nserror_bridge.h"
+#include "sim_process.h"
+
+namespace coresim {
+
+NSString* const kAudioTapErrorDomain = @"com.appium.coresim.AudioTap";
+
+namespace {
+
+NSError* MakeError(NSInteger code, NSString* message) {
+  return [NSError errorWithDomain:kAudioTapErrorDomain 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)]);
+}
+
+// AudioObjectID for `pid`'s Core Audio process object, or kAudioObjectUnknown (0) if it hasn't
+// registered with the audio HAL yet (e.g. a just-launched app that hasn't touched audio) — not an
+// error per kAudioHardwarePropertyTranslatePIDToProcessObject's own documented contract.
+AudioObjectID TranslatePidToProcessObject(pid_t pid) {
+  AudioObjectPropertyAddress address = {kAudioHardwarePropertyTranslatePIDToProcessObject,
+                                        kAudioObjectPropertyScopeGlobal, kAudioObjectPropertyElementMain};
+  AudioObjectID objectID = kAudioObjectUnknown;
+  UInt32 dataSize = sizeof(objectID);
+  pid_t qualifierPid = pid;
+  OSStatus status = AudioObjectGetPropertyData(kAudioObjectSystemObject, &address, sizeof(qualifierPid), &qualifierPid,
+                                               &dataSize, &objectID);
+  return status == noErr ? objectID : kAudioObjectUnknown;
+}
+
+// The live, audio-HAL-registered process set for `udid` — skips any guest pid that hasn't
+// touched the audio HAL yet. Sorted so two resolutions can be compared with plain `==`.
+std::vector<AudioObjectID> ResolveProcessObjects(NSString* udid) {
+  std::vector<AudioObjectID> result;
+  for (pid_t pid : FindGuestProcessPids(udid)) {
+    AudioObjectID objectID = TranslatePidToProcessObject(pid);
+    if (objectID != kAudioObjectUnknown) {
+      result.push_back(objectID);
+    }
+  }
+  std::sort(result.begin(), result.end());
+  return result;
+}
+
+NSArray<NSNumber*>* ToNumberArray(const std::vector<AudioObjectID>& objectIDs) {
+  NSMutableArray<NSNumber*>* array = [NSMutableArray arrayWithCapacity:objectIDs.size()];
+  for (AudioObjectID objectID : objectIDs) {
+    [array addObject:@(objectID)];
+  }
+  return array;
+}
+
+}  // namespace
+
+class AudioTapSession::Impl {
+ public:
+  Impl(NSString* udid, std::function<void(const AudioBufferList*, const AudioTimeStamp*)> onBuffer,
+       std::function<void(NSError*)> onError, std::function<void()> onEnd)
+      : udid_(udid), onBuffer_(std::move(onBuffer)), onError_(std::move(onError)), onEnd_(std::move(onEnd)) {
+    queue_ = dispatch_queue_create("com.appium.coresim.audioTap", DISPATCH_QUEUE_SERIAL);
+  }
+
+  ~Impl() { Stop(); }
+
+  void Start() {
+    if (@available(macOS 14.2, *)) {
+      StartTap();
+    } else {
+      throw NSErrorException(
+          MakeError(1, @"Core Audio process taps require macOS 14.2 or later — this host's macOS predates it"));
+    }
+  }
+
+  // Callable from any thread except `queue_` itself (would deadlock on the dispatch_sync below).
+  void Stop() {
+    if (!running_.exchange(false)) {
+      return;  // idempotent
+    }
+    if (pollTimer_ != nullptr) {
+      dispatch_source_cancel(pollTimer_);
+      // Blocks until any in-flight poll tick finishes — by then running_ is already false.
+      dispatch_sync(queue_, ^{
+                    });
+      pollTimer_ = nullptr;
+    }
+    TearDown();
+    if (onEnd_) {
+      onEnd_();
+    }
+  }
+
+  const AudioStreamBasicDescription& Format() const { return format_; }
+
+ private:
+  API_AVAILABLE(macos(14.2))
+  void StartTap() {
+    // A host with no default audio output device at all can't do any of this — checked up front
+    // so that case fails in milliseconds. Doesn't cover every slow-CI-host failure mode: some
+    // runners with a real default device still make AudioDeviceStart below block for ~180s before
+    // failing with MACH_RCV_TIMED_OUT (a Mach IPC timeout talking to coreaudiod) — see CLAUDE.md.
+    // That one isn't predictable/avoidable from here.
+    AudioObjectID defaultOutput = kAudioObjectUnknown;
+    UInt32 defaultOutputSize = sizeof(defaultOutput);
+    AudioObjectPropertyAddress defaultOutputAddress = {
+        kAudioHardwarePropertyDefaultOutputDevice, kAudioObjectPropertyScopeGlobal, kAudioObjectPropertyElementMain};
+    OSStatus defaultOutputStatus = AudioObjectGetPropertyData(kAudioObjectSystemObject, &defaultOutputAddress, 0,
+                                                              nullptr, &defaultOutputSize, &defaultOutput);
+    if (defaultOutputStatus != noErr || defaultOutput == kAudioObjectUnknown) {
+      throw NSErrorException(
+          MakeError(11, @"This host has no default audio output device — Core Audio process taps need one"));
+    }
+
+    lastProcessSet_ = ResolveProcessObjects(udid_);
+    if (lastProcessSet_.empty()) {
+      throw NSErrorException(MakeError(
+          2, [NSString stringWithFormat:@"No audio-capturable guest processes were found for device '%@' — is it "
+                                        @"booted, and has it produced any audio yet?",
+                                        udid_]));
+    }
+    NSUUID* uuid = [NSUUID UUID];
+    CATapDescription* description =
+        [[CATapDescription alloc] initStereoMixdownOfProcesses:ToNumberArray(lastProcessSet_)];
+    description.privateTap = YES;
+    description.UUID = uuid;
+    AudioObjectID tapID = kAudioObjectUnknown;
+    OSStatus status = AudioHardwareCreateProcessTap(description, &tapID);
+    if (status != noErr) {
+      throw NSErrorException(MakeStatusError(3, @"AudioHardwareCreateProcessTap failed", status));
+    }
+    tapID_ = tapID;
+    tapUUID_ = uuid;
+
+    UInt32 formatSize = sizeof(format_);
+    AudioObjectPropertyAddress formatAddress = {kAudioTapPropertyFormat, kAudioObjectPropertyScopeGlobal,
+                                                kAudioObjectPropertyElementMain};
+    status = AudioObjectGetPropertyData(tapID_, &formatAddress, 0, nullptr, &formatSize, &format_);
+    if (status != noErr) {
+      TearDown();
+      throw NSErrorException(MakeStatusError(4, @"Failed to read the tap's audio format", status));
+    }
+
+    // UID includes the tap's own per-session UUID, not just udid_ — concurrent sessions on the
+    // same device are supported, and a udid_-only UID would let two collide on the same
+    // persistent UID, which CoreAudio dedupes rather than erroring.
+    NSDictionary* aggregateDescription = @{
+      @(kAudioAggregateDeviceNameKey) : [NSString stringWithFormat:@"coresim-audio-%@", udid_],
+      @(kAudioAggregateDeviceUIDKey) :
+          [NSString stringWithFormat:@"com.appium.coresim.audio.%@.%@", udid_, uuid.UUIDString],
+      @(kAudioAggregateDeviceIsPrivateKey) : @YES,
+      @(kAudioAggregateDeviceTapAutoStartKey) : @NO,
+      @(kAudioAggregateDeviceTapListKey) : @[ @{
+        @(kAudioSubTapUIDKey) : uuid.UUIDString,
+        @(kAudioSubTapDriftCompensationKey) : @YES,
+      } ],
+    };
+    AudioObjectID aggregateID = kAudioObjectUnknown;
+    status = AudioHardwareCreateAggregateDevice((__bridge CFDictionaryRef)aggregateDescription, &aggregateID);
+    if (status != noErr) {
+      TearDown();
+      throw NSErrorException(MakeStatusError(5, @"AudioHardwareCreateAggregateDevice failed", status));
+    }
+    aggregateID_ = aggregateID;
+
+    running_ = true;  // before AudioDeviceStart — the IOProc block can fire before it returns
+    AudioDeviceIOProcID procID = nullptr;
+    status = AudioDeviceCreateIOProcIDWithBlock(
+        &procID, aggregateID_, queue_,
+        ^(const AudioTimeStamp*, const AudioBufferList* inInputData, const AudioTimeStamp* inInputTime,
+          AudioBufferList*, const AudioTimeStamp*) {
+          HandleBuffer(inInputData, inInputTime);
+        });
+    if (status != noErr || procID == nullptr) {
+      running_ = false;
+      TearDown();
+      throw NSErrorException(MakeStatusError(6, @"AudioDeviceCreateIOProcIDWithBlock failed", status));
+    }
+    procID_ = procID;
+
+    status = AudioDeviceStart(aggregateID_, procID_);
+    if (status != noErr) {
+      running_ = false;
+      TearDown();
+      throw NSErrorException(MakeStatusError(7, @"AudioDeviceStart failed", status));
+    }
+
+    StartPolling();
+  }
+
+  API_AVAILABLE(macos(14.2))
+  void StartPolling() {
+    dispatch_source_t timer = dispatch_source_create(DISPATCH_SOURCE_TYPE_TIMER, 0, 0, queue_);
+    dispatch_source_set_timer(
+        timer, dispatch_time(DISPATCH_TIME_NOW, static_cast<int64_t>(kPollIntervalSeconds * NSEC_PER_SEC)),
+        static_cast<uint64_t>(kPollIntervalSeconds * NSEC_PER_SEC),
+        static_cast<uint64_t>(kPollIntervalSeconds * NSEC_PER_SEC / 10));
+    // `this` outlives the timer: Stop() always drains or outruns it before `this` can be
+    // destroyed (see its comment).
+    dispatch_source_set_event_handler(timer, ^{
+      PollAndRefresh();
+    });
+    pollTimer_ = timer;
+    dispatch_resume(pollTimer_);
+  }
+
+  // Refreshes the tapped process set in place via kAudioTapPropertyDescription — no tap/aggregate
+  // recreation needed, confirmed by that property's own header comment ("can be used to modify
+  // and set the description of an existing tap").
+  API_AVAILABLE(macos(14.2))
+  void PollAndRefresh() {
+    if (!running_) {
+      return;
+    }
+    @autoreleasepool {
+      std::vector<AudioObjectID> current = ResolveProcessObjects(udid_);
+      if (current.empty()) {
+        // The device's guest process tree vanished entirely (shut down/erased mid-capture) — a
+        // real, reportable failure, not a transient empty tick.
+        if (onError_) {
+          onError_(MakeError(8, [NSString stringWithFormat:@"Device '%@' no longer has any audio-capturable guest "
+                                                           @"processes — was it shut down?",
+                                                           udid_]));
+        }
+        StopFromQueue();
+        return;
+      }
+      if (current == lastProcessSet_) {
+        return;
+      }
+      CATapDescription* description = [[CATapDescription alloc] initStereoMixdownOfProcesses:ToNumberArray(current)];
+      description.privateTap = YES;
+      description.UUID = tapUUID_;
+      AudioObjectPropertyAddress descAddress = {kAudioTapPropertyDescription, kAudioObjectPropertyScopeGlobal,
+                                                kAudioObjectPropertyElementMain};
+      // The property value is the CATapDescription* itself — inData must point to a variable
+      // holding that pointer, not be the pointer value cast to an address (which reads the
+      // object's own memory as if it were the property buffer).
+      void* descriptionPtr = (__bridge void*)description;
+      OSStatus status =
+          AudioObjectSetPropertyData(tapID_, &descAddress, 0, nullptr, sizeof(descriptionPtr), &descriptionPtr);
+      if (status != noErr) {
+        // Keep running with the stale set rather than tearing down the whole capture over one
+        // failed refresh — the next poll tick retries.
+        if (onError_) {
+          onError_(MakeStatusError(9, @"Failed to update the audio tap's process list", status));
+        }
+        return;
+      }
+      lastProcessSet_ = std::move(current);
+    }
+  }
+
+  void HandleBuffer(const AudioBufferList* data, const AudioTimeStamp* time) {
+    if (!running_ || !onBuffer_) {
+      return;
+    }
+    try {
+      onBuffer_(data, time);
+    } catch (const std::exception& e) {
+      // onBuffer_ (e.g. AudioEncoder::EncodePCM) can throw — uncaught, it'd crash the process.
+      // Routed through the same onError_/StopFromQueue() path PollAndRefresh's own errors use.
+      if (onError_) {
+        onError_(MakeError(10, [NSString stringWithFormat:@"Audio buffer consumer failed: %s", e.what()]));
+      }
+      StopFromQueue();
+    }
+  }
+
+  // Same as Stop() minus the dispatch_sync barrier — only safe from within a callback already
+  // serialized on `queue_` (PollAndRefresh); would deadlock waiting on itself otherwise.
+  void StopFromQueue() {
+    if (!running_.exchange(false)) {
+      return;  // idempotent — e.g. an external Stop() already won this race
+    }
+    if (pollTimer_ != nullptr) {
+      dispatch_source_cancel(pollTimer_);
+      pollTimer_ = nullptr;
+    }
+    TearDown();
+    if (onEnd_) {
+      onEnd_();
+    }
+  }
+
+  // Deliberately not API_AVAILABLE-annotated so Stop()/StopFromQueue()/~Impl() can call it
+  // unconditionally without themselves needing an availability guard — the guarded body below is
+  // a no-op whenever nothing was actually created (Start() never got past the macOS-version gate).
+  void TearDown() {
+    if (aggregateID_ == kAudioObjectUnknown && tapID_ == kAudioObjectUnknown) {
+      return;
+    }
+    if (@available(macOS 14.2, *)) {
+      if (aggregateID_ != kAudioObjectUnknown) {
+        if (procID_ != nullptr) {
+          AudioDeviceStop(aggregateID_, procID_);
+          AudioDeviceDestroyIOProcID(aggregateID_, procID_);
+          procID_ = nullptr;
+        }
+        // Destruction is documented as asynchronous — may complete after this call returns — so
+        // this UID isn't assumed immediately reusable.
+        AudioHardwareDestroyAggregateDevice(aggregateID_);
+        aggregateID_ = kAudioObjectUnknown;
+      }
+      if (tapID_ != kAudioObjectUnknown) {
+        AudioHardwareDestroyProcessTap(tapID_);
+        tapID_ = kAudioObjectUnknown;
+      }
+    }
+  }
+
+  static constexpr double kPollIntervalSeconds = 1.0;
+
+  NSString* udid_;
+  std::function<void(const AudioBufferList*, const AudioTimeStamp*)> onBuffer_;
+  std::function<void(NSError*)> onError_;
+  std::function<void()> onEnd_;
+
+  dispatch_queue_t queue_ = nullptr;
+  dispatch_source_t pollTimer_ = nullptr;
+  AudioObjectID tapID_ = kAudioObjectUnknown;
+  AudioObjectID aggregateID_ = kAudioObjectUnknown;
+  AudioDeviceIOProcID procID_ = nullptr;
+  NSUUID* tapUUID_ = nil;
+  AudioStreamBasicDescription format_ = {};
+  std::vector<AudioObjectID> lastProcessSet_;
+  std::atomic<bool> running_{false};
+};
+
+AudioTapSession::AudioTapSession(NSString* udid,
+                                 std::function<void(const AudioBufferList*, const AudioTimeStamp*)> onBuffer,
+                                 std::function<void(NSError*)> onError, std::function<void()> onEnd)
+    : impl_(std::make_unique<Impl>(udid, std::move(onBuffer), std::move(onError), std::move(onEnd))) {}
+
+AudioTapSession::~AudioTapSession() = default;
+
+void AudioTapSession::Start() { impl_->Start(); }
+
+void AudioTapSession::Stop() { impl_->Stop(); }
+
+const AudioStreamBasicDescription& AudioTapSession::Format() const { return impl_->Format(); }
+
+}  // namespace coresim

package/src/native/sim_process.h

@@ -2,6 +2,10 @@
 
 #import <Foundation/Foundation.h>
 
+#include <sys/types.h>
+
+#include <vector>
+
 namespace coresim {
 
 // Locates the Unix-domain socket the device's `com.apple.webinspectord_sim` launchd job listens
@@ -10,4 +14,10 @@ namespace coresim {
 // the same mechanism `lsof -aUc launchd_sim` uses.
 NSString* FindWebInspectorSocket(NSString* udid, NSError** error);
 
+// Every host process whose environment carries SIMULATOR_UDID=<udid> — that device's SpringBoard
+// plus any app currently launched inside it, all inherited from that device's own launchd_sim
+// (see CLAUDE.md). No CoreSimulator dispatch — same libproc/sysctl introspection as
+// FindWebInspectorSocket. Used to scope a Core Audio process tap to one simulator (sim_audio_tap.h).
+std::vector<pid_t> FindGuestProcessPids(NSString* udid);
+
 }  // namespace coresim