mac-capture: Show warning for macOS system effect on audio devices

[jcm93]

Description

Show a warning in the OBS properties window for audio devices that have macOS system effects such as Voice Isolation active.

The audio system effect status is given as an Objective-C class property on AVCaptureDevice. The macOS audio handling was previously pure C, but it has been converted here to Objective-C to facilitate easier access of this class property. The first two commits of this PR constitute the rename and subsequent formatting pass, so that the commit adding the functionality stands alone (the third commit).

Motivation and Context

macOS system effects operate on a "per-application" basis rather than "per-device". If the user has enabled Voice Isolation with a microphone attached, and later on adds a capture card source, they are often confused about distorted audio for their capture card device source, not realizing that the Voice Isolation effect has been applied to all subsequent audio devices added in OBS.

This makes macOS system effects borderline useless in OBS, since capturing multiple audio devices that carry different types of audio (microphone; capture card) is an incredibly common use case. We cannot disable these effects entirely, but we can at least provide a warning that makes the system effect status more apparent to the user.

Discussion

One element meriting discussion here is the underlying effect functionality. It's unclear exactly what each "microphone mode" actually does to the incoming signal. For example, the enum case describing the default status says that the standard mode, which is used by all applications in macOS for all audio devices by default, "processes microphone audio with standard voice DSP." It's entirely unclear what this means.

Since this is the mode used by DAWs on the system (including, for example, Logic Pro), it seems like we ought should expect that this mode is entirely absent DSP beyond basic gain limiting. If this actually constitutes a significant amount of "voice DSP," that would ordinarily be something we would want to actually warn about as well, despite it being the default and recommended for use in recording by Apple documentation.

The enum case for "Wide Spectrum", meanwhile, says it "minimizes microphone audio processing to capture all sounds in the room." It is also unclear what this means and whether the statement that it "minimizes processing" is accurate. It also seems unavailable in OBS for any audio devices in my testing, even those that constitute multi-mic arrays on recent Apple Silicon devices.

This PR currently warns for both "Voice Isolation" and "Wide Spectrum", since they both would seem to constitute more processing than the "Standard" mode; but clarity on these points from Apple would be appreciated.

How Has This Been Tested?

Tested on Apple Silicon, macOS 15.3.1. Verified that the warning is shown in the properties window when the effect is active, and that it does not appear if there are no system effects active.

Types of changes

• New feature (non-breaking change which adds functionality)
• Tweak (non-breaking change to improve existing functionality)

Checklist:

• My code has been run through clang-format.
• I have read the contributing document.
• My code is not on the master branch.
• The code has been tested.
• All commit messages are properly formatted and commits squashed where appropriate.
• I have included updates to all appropriate documentation.

[WizardCM]

I believe the wording could be improved, I don't know if users will know where to go to turn it off.

Additionally, if the device has both filters enabled, only one warning will show at a time. I'd prefer showing both warnings so the user can fix both at once, rather than fix, check, fix, check again.

[jcm93]

Additionally, if the device has both filters enabled, only one warning will show at a time. I'd prefer showing both warnings so the user can fix both at once, rather than fix, check, fix, check again.

A device can only be in one of the three modes at once (standard, voice isolation, or wide spectrum). They are mutually exclusive.

I believe the wording could be improved, I don't know if users will know where to go to turn it off.

The location of the controls for these effects is different in every major macOS release that OBS supports, and even varies between some point releases. Moreover, their location is not always consistent, and depends on the types of connections the user has active at any given time. I honestly don't think it's feasible to provide more specific guidance beyond telling the user that there is an active effect on their device, that the effect comes from macOS, and what the effect is called.

FWIW, I chose the wording to be consistent with #10895 as well.

(I don't mean to dismiss that the wording could be improved, just wanted to add context).

[jcm93]

I adjusted the wording a bit to hopefully make it more apparent that the effect comes from macOS and that the effect name is a proper noun. Updated the screenshot in the OP.

[PatTheMav]

Is there an observer for this change (maybe a NotificationCenter event)? Because I can have the dialog open, change the microphone mode, and the warning obviously only appears the next time I open the dialog.

EDIT: There is no notification, but good old KVO works:

• Add an ObjC object as a Key-Value-Observer to the coreaudio_data struct
• Call the register function in the plugin's create function
• Call the unregistered function in the plugin's destroy function

This object seems sufficient as a starting point:

@interface OBSKvoObject: NSObject

-(void)registerAsObserver;

-(void)unregisterAsObserver;

- (void)observeValueForKeyPath:(NSString *)keyPath
		      ofObject:(id)object
			change:(NSDictionary *)change
		       context:(void *)context;

@end

@implementation OBSKvoObject

-(void)registerAsObserver
{
	[AVCaptureDevice addObserver:self forKeyPath:@"activeMicrophoneMode" options:(NSKeyValueObservingOptionNew | NSKeyValueObservingOptionOld) context:nil];
}

-(void)unregisterAsObserver
{
	[AVCaptureDevice removeObserver:self forKeyPath:@"activeMicrophoneMode"];
}

-(void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context
{
	blog(LOG_INFO, "Observed value change for %s", keyPath.UTF8String);
}

@end

In that case change[NSKeyValueChangeOldKey] gives you the prior value, change[NSKeyValueChangeNewKey] the new one. Whether you can use that to get OBS to re-render the dialog in an elegant way is another question of course.

[jcm93]

Is there an observer for this change (maybe a NotificationCenter event)? Because I can have the dialog open, change the microphone mode, and the warning obviously only appears the next time I open the dialog.

Hmm, the property is listed as being key-value-observable, so it might be possible to subscribe to changes and update "live." I haven't tried to set up a property like that before, but I can take a look.

[PatTheMav]

Is there an observer for this change (maybe a NotificationCenter event)? Because I can have the dialog open, change the microphone mode, and the warning obviously only appears the next time I open the dialog.

Hmm, the property is listed as being key-value-observable, so it might be possible to subscribe to changes and update "live." I haven't tried to set up a property like that before, but I can take a look.

See above, I just implemented KVO to test this, and yes it works.. :D One might even provide the coreaudio_data pointer as context for the callback.

[jcm93]

Yeah, I'm more uncertain about the proper method for trying to re-render/update the property window in-place.

[PatTheMav]

The message is incorrect, because the settings are active for the application, not the device. There is no way to disable it for one device and have it enabled for another.

Saying "on the selected device" would imply that I can switch to another device and it could have a different state, but that ain't so - voice isolation (the most common setting that might be encountered) will be enabled for all input devices.

[jcm93]

It is indeed not representative of the underlying state, but I did write it this way on purpose.

I was figuring optimistically that the current behavior is in fact considered a "bug" in some respect on the Apple end, and that eventually we would in fact get per-device effects inside an application, because the current behavior seems so objectively dumb and bad to me. This could be naive / overly optimistic on my part, but I imagined that if that update ever happens, we could adjust the internals of how this message works rather than need to adjust the message itself inside this source properties window.

I also figured that, contextually, it just made more sense to only talk about the device the user has selected in that particular source's properties window. If we wanted to show a warning that "ALL your devices are going to sound like crap," that might be a good idea, but then the appropriate place to put that particular warning would be somewhere on a more general application level (though I don't know specifically where).

[PatTheMav]

I disagree, this setting is "per application" for a reason - namely that the vast majority of consumer applications is not a compositing/editing application but single-input voice conference or audio/video call applications, and the system-wide voice isolation feature was designed with that use case in mind.

We should not communicate something to our users that is factually wrong (it is not enabled for the device, it is enabled for the application), because then it is us who confuse the users ("but OBS told me it was enabled for the device, where can I disable it for the device?").

The warning should simply state "Voice Isolation is enabled for OBS Studio. Disable if unfiltered audio input is desired".

No opinions. No value statements. Just the facts.

EDIT: Which is not a comment on your assessment, but particularly for situations like these it's easier in my experience to just state the situation as-is and not add yet another layer of interpretation/communication.