Active Noise Cancellation

Read the current ANC settings from a connected device and update its mode, gains, or fade behavior.

Prerequisites

• The device is connected and ready.
• The device conforms to DeviceANCAPI.
• ancMode is not .unknown before enabling ANC controls.

Implement with AI Assistance

Build with AI

Implement this workflow with AI

Use the official Configure AIBuds Noise Control skill to adapt this workflow to your app.

Read and follow https://docs-aibuds.github.io/skills/configure-aibuds-anc. Use it to implement Configure AIBuds Noise Control in this iOS project and verify the result.

View official skill↗

API Reference

Framework

AIBuds.xcframework

Import

Swift

Swift

import AIBuds
import AIBudsFoundation

Objective-C

Objective-C

#import <AIBuds/AIBuds-Swift.h>
#import <AIBuds/AIBuds.h>

Protocol

The settings and commands are defined by DeviceANCAPI.

Swift

Swift

/// The protocol for device API that supports Active Noise Cancellation (ANC).
protocol DeviceANCAPI: DeviceAPI {
    /// The current Active Noise Cancellation (ANC) mode of the device.
    var ancMode: ANCMode { get }

    /// The current ANC gain value of the device.
    var ancGain: NSNumber? { get }

    /// The current transparency gain value of the device.
    var transparencyGain: NSNumber? { get }

    /// Indicates whether the ANC fade feature is currently enabled.
    var isAncFadeOn: Bool { get }

    /// Sets the Active Noise Cancellation (ANC) mode for the device.
    /// - Parameters:
    ///   - mode: The desired ANC mode to apply.
    ///   - completion: A closure that is called when the operation completes.
    ///     - success: Indicates whether the operation completed successfully.
    ///     - error: An optional error object that provides details if the operation failed; `nil` if the operation succeeded.
    func setAncMode(
        _ mode: ANCMode,
        completion: AIBudsCompletionHandler?
    )

    /// Sets the ANC gain value for the device.
    /// - Parameters:
    ///   - ancGain: The desired ANC gain value to apply.
    ///   - completion: A closure that is called when the operation completes.
    ///     - success: Indicates whether the operation completed successfully.
    ///     - error: An optional error object that provides details if the operation failed; `nil` if the operation succeeded.
    func setAncGain(
        _ ancGain: Int,
        completion: AIBudsCompletionHandler?
    )

    /// Sets the transparency gain value for the device.
    /// - Parameters:
    ///   - transparencyGain: The desired transparency gain value to apply.
    ///   - completion: A closure that is called when the operation completes.
    ///     - success: Indicates whether the operation completed successfully.
    ///     - error: An optional error object that provides details if the operation failed; `nil` if the operation succeeded.
    func setTransparencyGain(
        _ transparencyGain: Int,
        completion: AIBudsCompletionHandler?
    )

    /// Enables or disables the ANC fade feature for the device.
    /// - Parameters:
    ///   - isOn: A Boolean value indicating whether to enable (`true`) or disable (`false`) the ANC fade feature.
    ///   - completion: A closure that is called when the operation completes.
    ///     - success: Indicates whether the operation completed successfully.
    ///     - error: An optional error object that provides details if the operation failed; `nil` if the operation succeeded.
    func setAncFadeOn(
        _ isOn: Bool,
        completion: AIBudsCompletionHandler?
    )
}

Objective-C

Objective-C

/// The protocol for device API that supports Active Noise Cancellation (ANC).
@protocol AIBudsDeviceANCAPI <AIBudsDeviceAPI>
/// The current Active Noise Cancellation (ANC) mode of the device.
@property(nonatomic, readonly) enum AIBudsANCMode ancMode;

/// The current ANC gain value of the device.
@property(nonatomic, readonly, strong) NSNumber *_Nullable ancGain;

/// The current transparency gain value of the device.
@property(nonatomic, readonly, strong) NSNumber *_Nullable transparencyGain;

/// Indicates whether the ANC fade feature is currently enabled.
@property(nonatomic, readonly) BOOL isAncFadeOn;

/// Sets the Active Noise Cancellation (ANC) mode for the device.
/// - Parameters:
///   - mode: The desired ANC mode to apply.
///   - completion: A closure that is called when the operation completes.
///     - success: Indicates whether the operation completed successfully.
///     - error: An optional error object that provides details if the operation failed; `nil` if
///     the operation succeeded.
- (void)setAncMode:(enum AIBudsANCMode)mode
        completion:(AIBudsCompletionHandler _Nullable)completion;

/// Sets the ANC gain value for the device.
/// - Parameters:
///   - ancGain: The desired ANC gain value to apply.
///   - completion: A closure that is called when the operation completes.
///     - success: Indicates whether the operation completed successfully.
///     - error: An optional error object that provides details if the operation failed; `nil` if
///     the operation succeeded.
- (void)setAncGain:(NSInteger)ancGain completion:(AIBudsCompletionHandler _Nullable)completion;

/// Sets the transparency gain value for the device.
/// - Parameters:
///   - transparencyGain: The desired transparency gain value to apply.
///   - completion: A closure that is called when the operation completes.
///     - success: Indicates whether the operation completed successfully.
///     - error: An optional error object that provides details if the operation failed; `nil` if
///     the operation succeeded.
- (void)setTransparencyGain:(NSInteger)transparencyGain
                 completion:(AIBudsCompletionHandler _Nullable)completion;

/// Enables or disables the ANC fade feature for the device.
/// - Parameters:
///   - isOn: A Boolean value indicating whether to enable (`true`) or disable (`false`) the ANC
///   fade feature.
///   - completion: A closure that is called when the operation completes.
///     - success: Indicates whether the operation completed successfully.
///     - error: An optional error object that provides details if the operation failed; `nil` if
///     the operation succeeded.
- (void)setAncFadeOn:(BOOL)isOn completion:(AIBudsCompletionHandler _Nullable)completion;
@end

Properties

Property	Type	Description
ancMode	ANCMode	Current ANC mode.
ancGain	NSNumber?	Current ANC gain, or nil when unavailable.
transparencyGain	NSNumber?	Current transparency gain, or nil when unavailable.
isAncFadeOn	Bool / BOOL	Whether ANC fade is enabled.

Instance Methods

Method	Purpose
setAncMode	Change the ANC mode.
setAncGain	Change the ANC gain.
setTransparencyGain	Change the transparency gain.
setAncFadeOn	Enable or disable ANC fade.

Parameters

Parameter	Type	Description
mode	ANCMode / AIBudsANCMode	.normal, .anc, or .transparency. Do not set .unknown.
ancGain	Int / NSInteger	Desired ANC gain. The current Demo uses 0...100; the public SDK does not yet guarantee a universal range.
transparencyGain	Int / NSInteger	Desired transparency gain. The current Demo uses 0...100; the public SDK does not yet guarantee a universal range.
isOn	Bool / BOOL	Whether ANC fade should be enabled.
completion	AIBudsCompletionHandler?	Optional completion callback.

The methods return no value directly. Their completion callback receives success and an optional NSError.

Usage Examples

Read Current Settings

Swift

Swift

import AIBuds

guard let device = device as? DeviceANCAPI,
    device.ancMode != .unknown
else {
    print("Device does not support ANC")
    return
}

print("Mode: \(device.ancMode)")
print("ANC gain: \(device.ancGain?.intValue.description ?? "Unavailable")")
print("Transparency gain: \(device.transparencyGain?.intValue.description ?? "Unavailable")")
print("ANC fade: \(device.isAncFadeOn)")

Objective-C

Objective-C

#import <AIBuds/AIBuds-Swift.h>
#import <AIBuds/AIBuds.h>

id<AIBudsDeviceANCAPI> device = (id<AIBudsDeviceANCAPI>)self.device;
if (![device conformsToProtocol:@protocol(AIBudsDeviceANCAPI)] ||
    device.ancMode == AIBudsANCModeUnknown) {
    NSLog(@"Device does not support ANC");
    return;
}

NSLog(@"Mode: %ld", (long)device.ancMode);
NSLog(@"ANC gain: %@", device.ancGain ?: @"Unavailable");
NSLog(@"Transparency gain: %@", device.transparencyGain ?: @"Unavailable");
NSLog(@"ANC fade: %@", device.isAncFadeOn ? @"On" : @"Off");

Change ANC Mode

Swift

Swift

device.setAncMode(.anc) { success, error in
    guard success else {
        print("Failed to change ANC mode: \(error?.localizedDescription ?? "Unknown error")")
        return
    }
    print("ANC mode updated")
}

Objective-C

Objective-C

[device setAncMode:AIBudsANCModeAnc
        completion:^(BOOL success, NSError *_Nullable error) {
            if (!success) {
                NSLog(@"Failed to change ANC mode: %@", error.localizedDescription);
                return;
            }
            NSLog(@"ANC mode updated");
        }];

Change Gain and Fade

The following values follow the current SDK Demo. Revisit them when the SDK publishes device-specific gain limits.

Swift

Swift

device.setAncGain(60, completion: nil)
device.setTransparencyGain(40, completion: nil)
device.setAncFadeOn(true, completion: nil)

Objective-C

Objective-C

[device setAncGain:60 completion:nil];
[device setTransparencyGain:40 completion:nil];
[device setAncFadeOn:YES completion:nil];

Error Handling

If a command fails, restore the UI to the values currently exposed by the device and surface the callback error when available. The public API does not define ANC-specific error codes.