Multi-Channel Audio playback

src/matoya.h

@@ -1453,29 +1453,47 @@ MTY_WaitPtr(int32_t *sync);
 
 //- #module Audio
 //- #mbrief Simple audio playback and resampling.
-//- #mdetails This is a very minimal interface that assumes 2-channel, 16-bit signed PCM
+//- #mdetails This is a very minimal interface that supports multi-channel PCM audio
 //-   submitted by pushing to a queue. This module also includes a straightforward
-//-   resampler.
+//-   resampler for 2-channel, 16-bit signed PCM audio.
 
 typedef struct MTY_Audio MTY_Audio;
 typedef struct MTY_Resampler MTY_Resampler;
 
+/// @brief Audio sample formats. Currently only PCM formats.
+typedef enum {
+	MTY_AUDIO_SAMPLE_FORMAT_FLOAT   = 1, ///< 32-bit floating point.
+	MTY_AUDIO_SAMPLE_FORMAT_INT16   = 2, ///< 16-bit signed integer.
+} MTY_AudioSampleFormat;
+
+/// @brief Format description for an audio device.
+typedef struct {
+	MTY_AudioSampleFormat sampleFormat; ///< Format of audio samples.
+	uint32_t sampleRate;                ///< Number of audio samples per second. Usually set to 48000.
+	uint32_t channels;                  ///< Number of audio channels.
+	uint32_t channelsMask;              ///< Opaque bitmask that defines which channels are present in the audio data.
+	                                    ///< Follows standard surround sound speaker ids (see
+	                                    ///<   https://en.wikipedia.org/wiki/Surround_sound#Standard_speaker_channels).
+	                                    ///<   For `channels` > 2, specify this value correctly in order
+	                                    ///<   to yield accurate audio playback.
+} MTY_AudioFormat;
+
 /// @brief Create an MTY_Audio context for playback.
-/// @param sampleRate Audio sample rate in KHz.
+/// @param format Format that the audio device will attempt to initialize. If the
+///   provided format is not supported, the function will fail and return NULL.
 /// @param minBuffer The minimum amount of audio in milliseconds that must be queued
 ///   before playback begins.
 /// @param maxBuffer The maximum amount of audio in milliseconds that can be queued
 ///   before audio begins getting dropped. The queue will flush to zero, then begin
 ///   building back towards `minBuffer` again before playback resumes.
-/// @param channels Number of audio channels.
 /// @param deviceID Specify a specific audio device for playback, or NULL for the default
 ///   device. Windows only.
 /// @param fallback If `deviceID` is not NULL, set to true to fallback to the default device, or
 ///   false to cause this function to fail and return NULL. Windows only.
 /// @returns On failure, NULL is returned. Call MTY_GetLog for details.\n\n
 ///   The returned MTY_Audio context must be destroyed with MTY_AudioDestroy.
 MTY_EXPORT MTY_Audio *
-MTY_AudioCreate(uint32_t sampleRate, uint32_t minBuffer, uint32_t maxBuffer, uint8_t channels,
+MTY_AudioCreate(MTY_AudioFormat format, uint32_t minBuffer, uint32_t maxBuffer,
 	const char *deviceID, bool fallback);
 
 /// @brief Destroy an MTY_Audio context.
@@ -1498,11 +1516,13 @@ MTY_AudioGetQueued(MTY_Audio *ctx);
 
 /// @brief Queue 16-bit signed PCM audio for playback.
 /// @param ctx An MTY_Audio context.
-/// @param frames Buffer containing 16-bit signed PCM audio frames. The number of audio channels
-///   is specified during MTY_AudioCreate. In the case of 2-channel PCM, one audio frame is two
-///   samples, each sample being one channel.
+/// @param frames Buffer containing PCM audio frames as per the format (channels, sample rate, etc)
+///   that was specified during MTY_AudioCreate. A frame is an interleaving of 1 sample per channel.
+///   For example, in the case of 2-channel/stereo audio, one audio frame is two samples, each
+///   sample being one channel.
 /// @param count The number of frames contained in `frames`. The number of frames would
-///   be the size of `frames` in bytes divided by 2 * `channels` specified during MTY_AudioCreate.
+///   be the size of `frames` in bytes divided by sample size * `channels` specified
+///   during MTY_AudioCreate.
 MTY_EXPORT void
 MTY_AudioQueue(MTY_Audio *ctx, const int16_t *frames, uint32_t count);
 

src/unix/apple/audio.c

@@ -4,22 +4,27 @@
 
 #include "matoya.h"
 
+#include <CoreAudio/CoreAudio.h>
 #include <AudioToolbox/AudioToolbox.h>
 
-#define AUDIO_SAMPLE_SIZE sizeof(int16_t)
+#define AUDIO_SAMPLE_SIZE(fmt) ((fmt) == MTY_AUDIO_SAMPLE_FORMAT_FLOAT ? sizeof(float) : sizeof(int16_t))
 #define AUDIO_BUFS        64
 
-#define AUDIO_BUF_SIZE(ctx) \
-	((ctx)->sample_rate * (ctx)->channels * AUDIO_SAMPLE_SIZE)
+#define AUDIO_HW_ERROR(e) ((e) != kAudioHardwareNoError)
+#define AUDIO_SV_ERROR(e) ((e) != kAudioServicesNoError)
 
 struct MTY_Audio {
 	AudioQueueRef q;
 	AudioQueueBufferRef audio_buf[AUDIO_BUFS];
 	MTY_Atomic32 in_use[AUDIO_BUFS];
+	MTY_AudioSampleFormat sample_format;
 	uint32_t sample_rate;
 	uint32_t min_buffer;
 	uint32_t max_buffer;
 	uint8_t channels;
+	uint32_t channels_mask;
+	uint32_t frame_size;
+	uint32_t buffer_size;
 	bool playing;
 };
 
@@ -31,46 +36,197 @@ static void audio_queue_callback(void *opaque, AudioQueueRef q, AudioQueueBuffer
 	buf->mAudioDataByteSize = 0;
 }
 
-MTY_Audio *MTY_AudioCreate(uint32_t sampleRate, uint32_t minBuffer, uint32_t maxBuffer, uint8_t channels,
-	const char *deviceID, bool fallback)
+static OSStatus audio_object_get_device_uid(AudioObjectID device, AudioObjectPropertyScope prop_scope,
+	AudioObjectPropertyElement prop_element, char **out_uid, CFStringRef *out_uid_cf)
 {
-	// TODO Should this use the current run loop rather than internal threading?
+	char *uid = NULL;
+	CFStringRef uid_cf = NULL;
+
+	UInt32 data_size = sizeof(CFStringRef);
+	AudioObjectPropertyAddress propAddr = {
+		.mSelector = kAudioDevicePropertyDeviceUID,
+		.mScope = prop_scope,
+		.mElement = prop_element,
+	};
+
+	OSStatus e = AudioObjectGetPropertyData(device, &propAddr, 0, NULL, &data_size, &uid_cf);
+	if (AUDIO_HW_ERROR(e))
+		goto except;
 
-	MTY_Audio *ctx = MTY_Alloc(1, sizeof(MTY_Audio));
-	ctx->sample_rate = sampleRate;
-	ctx->channels = channels;
+	UInt32 prop_size = CFStringGetMaximumSizeForEncoding(CFStringGetLength(uid_cf), kCFStringEncodingUTF8);
+	uid = calloc(1, prop_size + 1);
+	if (!CFStringGetCString(uid_cf, uid, prop_size + 1, kCFStringEncodingUTF8)) {
+		e = kAudioHardwareBadDeviceError;
+		goto except;
+	}
+
+	// OK
+	*out_uid = uid;
+	*out_uid_cf = uid_cf;
+
+	except:
+
+	if (AUDIO_HW_ERROR(e)) {
+		if (uid_cf)
+			CFRelease(uid_cf);
+		free(uid);
+	}
+
+	return e;
+}
+
+static OSStatus audio_device_create(MTY_Audio *ctx, const char *deviceID)
+{
+	AudioObjectID *selected_device = NULL;
+	CFStringRef selected_device_uid = NULL;
 
-	uint32_t frames_per_ms = lrint((float) sampleRate / 1000.0f);
-	ctx->min_buffer = minBuffer * frames_per_ms;
-	ctx->max_buffer = maxBuffer * frames_per_ms;
+	// Enumerate all output devices and identify the given device
+	AudioObjectID *device_ids = NULL;
+
+	bool default_dev = !deviceID || !deviceID[0];
+
+	AudioObjectPropertyAddress propAddr = {
+		.mSelector = default_dev ? kAudioHardwarePropertyDefaultOutputDevice : kAudioHardwarePropertyDevices,
+		.mScope = kAudioObjectPropertyScopeOutput,
+		.mElement = kAudioObjectPropertyElementWildcard,
+	};
+
+	UInt32 data_size = 0;
+	OSStatus e = AudioObjectGetPropertyDataSize(kAudioObjectSystemObject, &propAddr, 0, NULL, &data_size);
+	if (AUDIO_HW_ERROR(e))
+		goto except;
+
+	device_ids = calloc(1, data_size);
+	e = AudioObjectGetPropertyData(kAudioObjectSystemObject, &propAddr, 0, NULL, &data_size, device_ids);
+	if (AUDIO_HW_ERROR(e))
+		goto except;
+
+	uint32_t n = (uint32_t) (data_size / sizeof(AudioObjectID));
+
+	if (default_dev) {
+		if (n != 1) {
+			e = kAudioHardwareBadDeviceError;
+			goto except;
+		}
+
+		selected_device = device_ids;
+
+	} else {
+		// Goal: find the AudioObjectID of the device whose unique string ID matches the given `deviceID` parameter
+		for (uint32_t i = 0; !selected_device && i < n; i++) {
+			char *uid = NULL;
+			CFStringRef uid_cf = NULL;
+
+			if (AUDIO_HW_ERROR(audio_object_get_device_uid(device_ids[i],
+				propAddr.mScope, propAddr.mElement, &uid, &uid_cf)))
+				continue;
+
+			if (!strcmp(deviceID, uid)) {
+				selected_device = &device_ids[i];
+				selected_device_uid = uid_cf;
+				uid_cf = NULL;
+			}
+
+			if (uid_cf)
+				CFRelease(uid_cf);
+
+			free(uid);
+		}
+	}
+
+	if (!selected_device) {
+		e = kAudioHardwareBadDeviceError;
+		goto except;
+	}
+
+	// Initialize the selected device
 
 	AudioStreamBasicDescription format = {0};
-	format.mSampleRate = sampleRate;
+	format.mSampleRate = ctx->sample_rate;
 	format.mFormatID = kAudioFormatLinearPCM;
-	format.mFormatFlags = kAudioFormatFlagIsSignedInteger | kAudioFormatFlagIsPacked;
+	format.mFormatFlags = (ctx->sample_format == MTY_AUDIO_SAMPLE_FORMAT_FLOAT ?
+		kAudioFormatFlagIsFloat : kAudioFormatFlagIsSignedInteger) | kAudioFormatFlagIsPacked;
 	format.mFramesPerPacket = 1;
-	format.mChannelsPerFrame = channels;
-	format.mBitsPerChannel = AUDIO_SAMPLE_SIZE * 8;
-	format.mBytesPerPacket = AUDIO_SAMPLE_SIZE * format.mChannelsPerFrame;
+	format.mChannelsPerFrame = ctx->channels;
+	format.mBitsPerChannel = AUDIO_SAMPLE_SIZE(ctx->sample_format) * 8;
+	format.mBytesPerPacket = ctx->frame_size;
 	format.mBytesPerFrame = format.mBytesPerPacket;
 
-	OSStatus e = AudioQueueNewOutput(&format, audio_queue_callback, ctx, NULL, NULL, 0, &ctx->q);
-	if (e != kAudioServicesNoError) {
+	// Create a new audio queue, which by default chooses the device's default device
+	e = AudioQueueNewOutput(&format, audio_queue_callback, ctx, NULL, NULL, 0, &ctx->q);
+	if (AUDIO_SV_ERROR(e)) {
 		MTY_Log("'AudioQueueNewOutput' failed with error 0x%X", e);
 		goto except;
 	}
 
+	// Change the audio queue to be associated with the selected audio device
+	if (selected_device_uid) {
+		e = AudioQueueSetProperty(ctx->q, kAudioQueueProperty_CurrentDevice,
+			(const void *) &selected_device_uid, sizeof(CFStringRef));
+		if (AUDIO_SV_ERROR(e)) {
+			MTY_Log("'AudioQueueSetProperty(kAudioQueueProperty_CurrentDevice)' failed with error 0x%X", e);
+			goto except;
+		}
+	}
+
+	// Specify channel configuration
+	if (ctx->channels_mask) {
+		AudioChannelLayout channel_layout = {
+			.mChannelLayoutTag = kAudioChannelLayoutTag_UseChannelBitmap,
+			.mChannelBitmap = ctx->channels_mask, // Core Audio channel bitmap follows the spec that the WAVE format
+												  // follows, so we can simply pass in the mask as-is
+		};
+
+		e = AudioQueueSetProperty(ctx->q, kAudioQueueProperty_ChannelLayout,
+			(const void *) &channel_layout, sizeof(AudioChannelLayout));
+		if (AUDIO_SV_ERROR(e)) {
+			MTY_Log("'AudioQueueSetProperty(kAudioQueueProperty_ChannelLayout)' failed with error 0x%X", e);
+			goto except;
+		}
+	}
+
 	for (int32_t x = 0; x < AUDIO_BUFS; x++) {
-		e = AudioQueueAllocateBuffer(ctx->q, AUDIO_BUF_SIZE(ctx), &ctx->audio_buf[x]);
-		if (e != kAudioServicesNoError) {
+		e = AudioQueueAllocateBuffer(ctx->q, ctx->buffer_size, &ctx->audio_buf[x]);
+		if (AUDIO_SV_ERROR(e)) {
 			MTY_Log("'AudioQueueAllocateBuffer' failed with error 0x%X", e);
 			goto except;
 		}
 	}
 
 	except:
 
-	if (e != kAudioServicesNoError)
+	if (selected_device_uid)
+		CFRelease(selected_device_uid);
+
+	free(device_ids);
+
+	return e;
+}
+
+MTY_Audio *MTY_AudioCreate(MTY_AudioFormat format_in, uint32_t minBuffer, uint32_t maxBuffer,
+	const char *deviceID, bool fallback)
+{
+	// TODO Should this use the current run loop rather than internal threading?
+
+	MTY_Audio *ctx = MTY_Alloc(1, sizeof(MTY_Audio));
+	ctx->sample_format = format_in.sampleFormat;
+	ctx->sample_rate = format_in.sampleRate;
+	ctx->channels = format_in.channels;
+	ctx->channels_mask = format_in.channelsMask;
+	ctx->frame_size = format_in.channels * AUDIO_SAMPLE_SIZE(format_in.sampleFormat);
+	ctx->buffer_size = format_in.sampleRate * ctx->frame_size;
+
+	uint32_t samples_per_ms = lrint((float) format_in.sampleRate / 1000.0f);
+	ctx->min_buffer = minBuffer * samples_per_ms;
+	ctx->max_buffer = maxBuffer * samples_per_ms;
+
+	OSStatus e = audio_device_create(ctx, deviceID);
+
+	// Upon failure initializing the given device, try again with the system default device
+	if (AUDIO_SV_ERROR(e) && deviceID && deviceID[0])
+		e = audio_device_create(ctx, NULL);
+
+	if (AUDIO_SV_ERROR(e))
 		MTY_AudioDestroy(&ctx);
 
 	return ctx;
@@ -85,7 +241,7 @@ void MTY_AudioDestroy(MTY_Audio **audio)
 
 	if (ctx->q) {
 		OSStatus e = AudioQueueDispose(ctx->q, true);
-		if (e != kAudioServicesNoError)
+		if (AUDIO_SV_ERROR(e))
 			MTY_Log("'AudioQueueDispose' failed with error 0x%X", e);
 	}
 
@@ -104,15 +260,15 @@ static uint32_t audio_get_queued_frames(MTY_Audio *ctx)
 		}
 	}
 
-	return queued / (ctx->channels * AUDIO_SAMPLE_SIZE);
+	return queued / ctx->frame_size;
 }
 
 static void audio_play(MTY_Audio *ctx)
 {
 	if (ctx->playing)
 		return;
 
-	if (AudioQueueStart(ctx->q, NULL) == kAudioServicesNoError)
+	if (!AUDIO_SV_ERROR(AudioQueueStart(ctx->q, NULL)))
 		ctx->playing = true;
 }
 
@@ -121,7 +277,7 @@ void MTY_AudioReset(MTY_Audio *ctx)
 	if (!ctx->playing)
 		return;
 
-	if (AudioQueueStop(ctx->q, true) == kAudioServicesNoError)
+	if (!AUDIO_SV_ERROR(AudioQueueStop(ctx->q, true)))
 		ctx->playing = false;
 }
 
@@ -132,14 +288,14 @@ uint32_t MTY_AudioGetQueued(MTY_Audio *ctx)
 
 void MTY_AudioQueue(MTY_Audio *ctx, const int16_t *frames, uint32_t count)
 {
-	size_t size = count * ctx->channels * AUDIO_SAMPLE_SIZE;
+	size_t size = count * ctx->frame_size;
 	uint32_t queued = audio_get_queued_frames(ctx);
 
 	// Stop playing and flush if we've exceeded the maximum buffer or underrun
 	if (ctx->playing && (queued > ctx->max_buffer || queued == 0))
 		MTY_AudioReset(ctx);
 
-	if (size <= AUDIO_BUF_SIZE(ctx)) {
+	if (size <= ctx->buffer_size) {
 		for (uint8_t x = 0; x < AUDIO_BUFS; x++) {
 			if (MTY_Atomic32Get(&ctx->in_use[x]) == 0) {
 				AudioQueueBufferRef buf = ctx->audio_buf[x];
@@ -149,7 +305,7 @@ void MTY_AudioQueue(MTY_Audio *ctx, const int16_t *frames, uint32_t count)
 				buf->mUserData = (void *) (uintptr_t) x;
 
 				OSStatus e = AudioQueueEnqueueBuffer(ctx->q, buf, 0, NULL);
-				if (e == kAudioServicesNoError) {
+				if (!AUDIO_SV_ERROR(kAudioServicesNoError)) {
 					MTY_Atomic32Set(&ctx->in_use[x], 1);
 
 				} else {