feat(macOS): Capture audio on macOS using Tap API

.github/workflows/ci-homebrew.yml

@@ -61,6 +61,47 @@ jobs:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
 
+      - name: Seed additional macOS TCC permissions
+        if: runner.os == 'macOS'
+        run: |
+          set -euo pipefail
+
+          configure_system_tccdb() {
+            local values=$1
+            local dbPath="/Library/Application Support/com.apple.TCC/TCC.db"
+            local sqlQuery="INSERT OR IGNORE INTO access VALUES($values);"
+            sudo sqlite3 "$dbPath" "$sqlQuery"
+          }
+
+          configure_user_tccdb() {
+            local values=$1
+            local dbPath="$HOME/Library/Application Support/com.apple.TCC/TCC.db"
+            local sqlQuery="INSERT OR IGNORE INTO access VALUES($values);"
+            sqlite3 "$dbPath" "$sqlQuery"
+          }
+
+          systemValuesArray=(
+            "'kTCCServiceAudioCapture','/opt/hca/hosted-compute-agent',1,2,4,1,NULL,NULL,NULL,'UNUSED',NULL,0,1736467200"
+            "'kTCCServiceAudioCapture','/opt/hca/start_hca.sh',1,2,0,1,NULL,NULL,NULL,'UNUSED',NULL,0,1576661342"
+            "'kTCCServiceAudioCapture','/usr/local/opt/runner/provisioner/provisioner',1,2,4,1,NULL,NULL,NULL,'UNUSED',NULL,0,1736467200"
+            "'kTCCServiceAudioCapture','/usr/local/opt/runner/runprovisioner.sh',1,2,0,1,NULL,NULL,NULL,'UNUSED',NULL,0,1576661342"
+          )
+          for values in "${systemValuesArray[@]}"; do
+            configure_system_tccdb "$values,NULL,NULL,'UNUSED',${values##*,}"
+          done
+
+          userValuesArray=(
+            "'kTCCServiceAudioCapture','/opt/hca/hosted-compute-agent',1,2,4,1,NULL,NULL,NULL,'UNUSED',NULL,0,1736467200"
+            "'kTCCServiceAudioCapture','/opt/hca/start_hca.sh',1,2,0,1,NULL,NULL,NULL,'UNUSED',NULL,0,1576661342"
+            "'kTCCServiceAudioCapture','/usr/local/opt/runner/provisioner/provisioner',1,2,4,1,NULL,NULL,NULL,'UNUSED',NULL,0,1736467200"
+            "'kTCCServiceAudioCapture','/usr/local/opt/runner/runprovisioner.sh',1,2,0,1,NULL,NULL,NULL,'UNUSED',NULL,0,1576661342"
+          )
+          for values in "${userValuesArray[@]}"; do
+            configure_user_tccdb "$values,NULL,NULL,'UNUSED',${values##*,}"
+          done
+
+          echo "macOS TCC permissions configured."
+
       - name: Configure formula
         env:
           INPUT_RELEASE_VERSION: ${{ inputs.release_version }}

.github/workflows/ci-macos.yml

@@ -39,6 +39,7 @@ env:
   BRANCH: ${{ github.head_ref || github.ref_name }}
   BUILD_VERSION: ${{ inputs.release_version }}
   COMMIT: ${{ inputs.release_commit }}
+  MACOSX_DEPLOYMENT_TARGET: 14.2
 
 jobs:
   build_dmg:

README.md

@@ -242,7 +242,7 @@ LizardByte has the full documentation hosted on [Read the Docs](https://docs.liz
         <td>Linux/Ubuntu: 22.04+ (jammy)</td>
     </tr>
     <tr>
-        <td>macOS: 14+</td>
+        <td>macOS: 14.2+</td>
     </tr>
     <tr>
         <td>Windows: 11+ (Windows Server does not support virtual gamepads)</td>

cmake/compile_definitions/macos.cmake

@@ -28,7 +28,10 @@ endif()
 list(APPEND SUNSHINE_EXTERNAL_LIBRARIES
         ${APP_KIT_LIBRARY}
         ${APP_SERVICES_LIBRARY}
+        ${AUDIO_TOOLBOX_LIBRARY}
+        ${AUDIO_UNIT_LIBRARY}
         ${AV_FOUNDATION_LIBRARY}
+        ${CORE_AUDIO_LIBRARY}
         ${CORE_MEDIA_LIBRARY}
         ${CORE_VIDEO_LIBRARY}
         ${FOUNDATION_LIBRARY}
@@ -40,7 +43,7 @@ configure_file("${APPLE_PLIST_TEMPLATE}" "${APPLE_PLIST_FILE}" @ONLY)
 
 set(PLATFORM_TARGET_FILES
         "${CMAKE_SOURCE_DIR}/src/platform/macos/av_audio.h"
-        "${CMAKE_SOURCE_DIR}/src/platform/macos/av_audio.m"
+        "${CMAKE_SOURCE_DIR}/src/platform/macos/av_audio.mm"
         "${CMAKE_SOURCE_DIR}/src/platform/macos/av_img_t.h"
         "${CMAKE_SOURCE_DIR}/src/platform/macos/av_video.h"
         "${CMAKE_SOURCE_DIR}/src/platform/macos/av_video.m"

cmake/dependencies/macos.cmake

@@ -2,7 +2,10 @@
 
 FIND_LIBRARY(APP_KIT_LIBRARY AppKit)
 FIND_LIBRARY(APP_SERVICES_LIBRARY ApplicationServices)
+FIND_LIBRARY(AUDIO_TOOLBOX_LIBRARY AudioToolbox)
+FIND_LIBRARY(AUDIO_UNIT_LIBRARY AudioUnit)
 FIND_LIBRARY(AV_FOUNDATION_LIBRARY AVFoundation)
+FIND_LIBRARY(CORE_AUDIO_LIBRARY CoreAudio)
 FIND_LIBRARY(CORE_MEDIA_LIBRARY CoreMedia)
 FIND_LIBRARY(CORE_VIDEO_LIBRARY CoreVideo)
 FIND_LIBRARY(FOUNDATION_LIBRARY Foundation)

docs/getting_started.md

@@ -464,9 +464,13 @@ systemctl --user --now enable app-dev.lizardbyte.app.Sunshine
 ### macOS
 The first time you start Sunshine, you will be asked to grant access to screen recording and your microphone.
 
-Sunshine can only access microphones on macOS due to system limitations. To stream system audio use
+Sunshine supports native system audio capture on macOS 14.0 (Sonoma) and newer via Apple’s Audio Tap API.
+To use it, simply leave the **Audio Sink** setting blank.
+
+If you prefer to manage your own loopback device, you can still use
 [Soundflower](https://github.com/mattingalls/Soundflower) or
-[BlackHole](https://github.com/ExistentialAudio/BlackHole).
+[BlackHole](https://github.com/ExistentialAudio/BlackHole)
+and enter its device name in the [audio_sink](configuration.md#audio_sink) field.
 
 > [!NOTE]
 > Command Keys are not forwarded by Moonlight. Right Option-Key is mapped to CMD-Key.

packaging/sunshine.rb

@@ -296,9 +296,6 @@ def post_install
 
     if OS.mac?
       opoo <<~EOS
-        Sunshine can only access microphones on macOS due to system limitations.
-        To stream system audio use "Soundflower" or "BlackHole".
-
         Gamepads are not currently supported on macOS.
       EOS
     end

src/audio.cpp

@@ -194,8 +194,9 @@ namespace audio {
     }
 
     auto frame_size = config.packetDuration * stream.sampleRate / 1000;
+    bool host_audio = config.flags[config_t::HOST_AUDIO];
     bool continuous_audio = config.flags[config_t::CONTINUOUS_AUDIO];
-    auto mic = control->microphone(stream.mapping, stream.channelCount, stream.sampleRate, frame_size, continuous_audio);
+    auto mic = control->microphone(stream.mapping, stream.channelCount, stream.sampleRate, frame_size, continuous_audio, host_audio);
     if (!mic) {
       return;
     }
@@ -232,7 +233,7 @@ namespace audio {
           BOOST_LOG(info) << "Reinitializing audio capture"sv;
           mic.reset();
           do {
-            mic = control->microphone(stream.mapping, stream.channelCount, stream.sampleRate, frame_size, continuous_audio);
+            mic = control->microphone(stream.mapping, stream.channelCount, stream.sampleRate, frame_size, continuous_audio, host_audio);
             if (!mic) {
               BOOST_LOG(warning) << "Couldn't re-initialize audio input"sv;
             }

src/config.h

@@ -145,10 +145,10 @@ namespace config {
   };
 
   struct audio_t {
-    std::string sink;
-    std::string virtual_sink;
-    bool stream;
-    bool install_steam_drivers;
+    std::string sink;  ///< Audio output device/sink to use for audio capture
+    std::string virtual_sink;  ///< Virtual audio sink for audio routing
+    bool stream;  ///< Enable audio streaming to clients
+    bool install_steam_drivers;  ///< Install Steam audio drivers for enhanced compatibility
   };
 
   constexpr int ENCRYPTION_MODE_NEVER = 0;  // Never use video encryption, even if the client supports it

src/platform/common.h

@@ -568,7 +568,7 @@ namespace platf {
   public:
     virtual int set_sink(const std::string &sink) = 0;
 
-    virtual std::unique_ptr<mic_t> microphone(const std::uint8_t *mapping, int channels, std::uint32_t sample_rate, std::uint32_t frame_size, bool continuous) = 0;
+    virtual std::unique_ptr<mic_t> microphone(const std::uint8_t *mapping, int channels, std::uint32_t sample_rate, std::uint32_t frame_size, bool continuous, [[maybe_unused]] bool host_audio_enabled) = 0;
 
     /**
      * @brief Check if the audio sink is available in the system.

src/platform/linux/audio.cpp

@@ -441,7 +441,7 @@ namespace platf {
         return monitor_name;
       }
 
-      std::unique_ptr<mic_t> microphone(const std::uint8_t *mapping, int channels, std::uint32_t sample_rate, std::uint32_t frame_size, bool continuous_audio) override {
+      std::unique_ptr<mic_t> microphone(const std::uint8_t *mapping, int channels, std::uint32_t sample_rate, std::uint32_t frame_size, bool continuous_audio, [[maybe_unused]] bool host_audio_enabled) override {
         // Sink choice priority:
         // 1. Config sink
         // 2. Last sink swapped to (Usually virtual in this case)

src/platform/macos/av_audio.h

@@ -1,29 +1,168 @@
 /**
  * @file src/platform/macos/av_audio.h
- * @brief Declarations for audio capture on macOS.
+ * @brief Declarations for macOS audio capture with dual input paths.
+ *
+ * This header defines the AVAudio class which provides distinct audio capture methods:
+ * 1. **Microphone capture** - Uses AVFoundation framework to capture from specific microphone devices
+ * 2. **System-wide audio tap** - Uses Core Audio taps to capture all system audio output (macOS 14.0+)
+ *
+ * The system-wide audio tap allows capturing audio from all applications and system sounds,
+ * while microphone capture focuses on input from physical or virtual microphone devices.
  */
 #pragma once
 
 // platform includes
+#import <AudioToolbox/AudioToolbox.h>
 #import <AVFoundation/AVFoundation.h>
+#import <CoreAudio/AudioHardwareTapping.h>
+#import <CoreAudio/CoreAudio.h>
 
 // lib includes
 #include "third-party/TPCircularBuffer/TPCircularBuffer.h"
 
-static const int kBufferLength = 4096;
+NS_ASSUME_NONNULL_BEGIN
 
+// Forward declarations
+@class AVAudio;
+@class CATapDescription;
+
+namespace platf {
+  OSStatus audioConverterComplexInputProc(AudioConverterRef _Nullable inAudioConverter, UInt32 *_Nonnull ioNumberDataPackets, AudioBufferList *_Nonnull ioData, AudioStreamPacketDescription *_Nullable *_Nullable outDataPacketDescription, void *_Nonnull inUserData);
+  OSStatus systemAudioIOProc(AudioObjectID inDevice, const AudioTimeStamp *_Nullable inNow, const AudioBufferList *_Nullable inInputData, const AudioTimeStamp *_Nullable inInputTime, AudioBufferList *_Nullable outOutputData, const AudioTimeStamp *_Nullable inOutputTime, void *_Nullable inClientData);
+}  // namespace platf
+
+/**
+ * @brief Data structure for AudioConverter input callback.
+ * Contains audio data and metadata needed for format conversion during audio processing.
+ */
+struct AudioConverterInputData {
+  float *inputData;  ///< Pointer to input audio data
+  UInt32 inputFrames;  ///< Total number of input frames available
+  UInt32 framesProvided;  ///< Number of frames already provided to converter
+  UInt32 deviceChannels;  ///< Number of channels in the device audio
+  AVAudio *avAudio;  ///< Reference to the AVAudio instance
+};
+
+/**
+ * @brief IOProc client data structure for Core Audio system taps.
+ * Contains configuration and conversion data for real-time audio processing.
+ */
+typedef struct {
+  AVAudio *avAudio;  ///< Reference to AVAudio instance
+  UInt32 clientRequestedChannels;  ///< Number of channels requested by client
+  UInt32 clientRequestedSampleRate;  ///< Sample rate requested by client
+  UInt32 clientRequestedFrameSize;  ///< Frame size requested by client
+  UInt32 aggregateDeviceSampleRate;  ///< Sample rate of the aggregate device
+  UInt32 aggregateDeviceChannels;  ///< Number of channels in aggregate device
+  AudioConverterRef _Nullable audioConverter;  ///< Audio converter for format conversion
+  float *_Nullable conversionBuffer;  ///< Pre-allocated buffer for audio conversion
+  UInt32 conversionBufferSize;  ///< Size of the conversion buffer in bytes
+} AVAudioIOProcData;
+
+/**
+ * @brief Core Audio capture class for macOS audio input and system-wide audio tapping.
+ * Provides functionality for both microphone capture via AVFoundation and system-wide
+ * audio capture via Core Audio taps (requires macOS 14.0+).
+ */
 @interface AVAudio: NSObject <AVCaptureAudioDataOutputSampleBufferDelegate> {
 @public
-  TPCircularBuffer audioSampleBuffer;
+  TPCircularBuffer audioSampleBuffer;  ///< Shared circular buffer for both audio capture paths
+  dispatch_semaphore_t audioSemaphore;  ///< Real-time safe semaphore for signaling audio sample availability
+@private
+  // System-wide audio tap components (Core Audio)
+  AudioObjectID tapObjectID;  ///< Core Audio tap object identifier for system audio capture
+  AudioObjectID aggregateDeviceID;  ///< Aggregate device ID for system tap audio routing
+  AudioDeviceIOProcID ioProcID;  ///< IOProc identifier for real-time audio processing
+  AVAudioIOProcData *_Nullable ioProcData;  ///< Context data for IOProc callbacks and format conversion
 }
 
-@property (nonatomic, assign) AVCaptureSession *audioCaptureSession;
-@property (nonatomic, assign) AVCaptureConnection *audioConnection;
-@property (nonatomic, assign) NSCondition *samplesArrivedSignal;
+// AVFoundation microphone capture properties
+@property (nonatomic, assign, nullable) AVCaptureSession *audioCaptureSession;  ///< AVFoundation capture session for microphone input
+@property (nonatomic, assign, nullable) AVCaptureConnection *audioConnection;  ///< Audio connection within the capture session
+@property (nonatomic, assign) BOOL hostAudioEnabled;  ///< Whether host audio playback should be enabled (affects tap mute behavior)
+
+/**
+ * @brief Get all available microphone devices on the system.
+ * @return Array of AVCaptureDevice objects representing available microphones
+ */
++ (NSArray<AVCaptureDevice *> *)microphones;
+
+/**
+ * @brief Get names of all available microphone devices.
+ * @return Array of NSString objects with microphone device names
+ */
++ (NSArray<NSString *> *)microphoneNames;
+
+/**
+ * @brief Find a specific microphone device by name.
+ * @param name The name of the microphone to find (nullable - will return nil if name is nil)
+ * @return AVCaptureDevice object if found, nil otherwise
+ */
++ (nullable AVCaptureDevice *)findMicrophone:(nullable NSString *)name;
+
+/**
+ * @brief Sets up microphone capture using AVFoundation framework.
+ * @param device The AVCaptureDevice to use for audio input (nullable - will return error if nil)
+ * @param sampleRate Target sample rate in Hz
+ * @param frameSize Number of frames per buffer
+ * @param channels Number of audio channels (1=mono, 2=stereo)
+ * @return 0 on success, -1 on failure
+ */
+- (int)setupMicrophone:(nullable AVCaptureDevice *)device sampleRate:(UInt32)sampleRate frameSize:(UInt32)frameSize channels:(UInt8)channels;
+
+/**
+ * @brief Sets up system-wide audio tap for capturing all system audio.
+ * Requires macOS 14.0+ and appropriate permissions.
+ * @param sampleRate Target sample rate in Hz
+ * @param frameSize Number of frames per buffer
+ * @param channels Number of audio channels
+ * @return 0 on success, -1 on failure
+ */
+- (int)setupSystemTap:(UInt32)sampleRate frameSize:(UInt32)frameSize channels:(UInt8)channels;
 
-+ (NSArray *)microphoneNames;
-+ (AVCaptureDevice *)findMicrophone:(NSString *)name;
+// Buffer management methods for testing and internal use
+/**
+ * @brief Initializes the circular audio buffer for the specified number of channels.
+ * @param channels Number of audio channels to configure the buffer for
+ */
+- (void)initializeAudioBuffer:(UInt8)channels;
 
-- (int)setupMicrophone:(AVCaptureDevice *)device sampleRate:(UInt32)sampleRate frameSize:(UInt32)frameSize channels:(UInt8)channels;
+/**
+ * @brief Cleans up and deallocates the audio buffer resources.
+ */
+- (void)cleanupAudioBuffer;
+
+/**
+ * @brief Cleans up system tap resources in a safe, ordered manner.
+ * @param tapDescription Optional tap description object to release (can be nil)
+ */
+- (void)cleanupSystemTapContext:(nullable id)tapDescription;
+
+/**
+ * @brief Initializes the system tap context with specified audio parameters.
+ * @param sampleRate Target sample rate in Hz
+ * @param frameSize Number of frames per buffer
+ * @param channels Number of audio channels
+ * @return 0 on success, -1 on failure
+ */
+- (int)initializeSystemTapContext:(UInt32)sampleRate frameSize:(UInt32)frameSize channels:(UInt8)channels;
+
+/**
+ * @brief Creates a Core Audio tap description for system audio capture.
+ * @param channels Number of audio channels to configure the tap for
+ * @return CATapDescription object on success, nil on failure
+ */
+- (nullable CATapDescription *)createSystemTapDescriptionForChannels:(UInt8)channels;
+
+/**
+ * @brief Creates an aggregate device with the specified tap description and audio parameters.
+ * @param tapDescription Core Audio tap description for system audio capture
+ * @param sampleRate Target sample rate in Hz
+ * @param frameSize Number of frames per buffer
+ * @return OSStatus indicating success (noErr) or error code
+ */
+- (OSStatus)createAggregateDeviceWithTapDescription:(CATapDescription *)tapDescription sampleRate:(UInt32)sampleRate frameSize:(UInt32)frameSize;
 
 @end
+
+NS_ASSUME_NONNULL_END