主动降噪

读取已连接设备当前的 ANC 设置，并更新其模式、增益或淡入淡出行为。

前置条件

• 设备已连接且就绪。
• 设备符合 DeviceANCAPI。
• 启用 ANC 控件前，确认 ancMode 不为 .unknown。

使用 AI 辅助实现

使用 AI 开发

让 AI 帮助实现此工作流

使用官方“配置 AIBuds 主动降噪”技能，根据你的 App 完成实现。

请阅读并遵循 https://docs-aibuds.github.io/zh-Hans/skills/configure-aibuds-anc，使用该技能在当前 iOS 项目中完成“配置 AIBuds 主动降噪”，并验证结果。

查看官方技能↗

API 参考

框架

AIBuds.xcframework

导入

Swift

Swift

import AIBuds
import AIBudsFoundation

Objective-C

Objective-C

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

协议

设置和命令由 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

属性

属性	类型	描述
ancMode	ANCMode	当前 ANC 模式。
ancGain	NSNumber?	当前 ANC 增益；不可用时为 nil。
transparencyGain	NSNumber?	当前通透增益；不可用时为 nil。
isAncFadeOn	Bool / BOOL	是否启用 ANC 淡入淡出。

实例方法

方法	用途
setAncMode	更改 ANC 模式。
setAncGain	更改 ANC 增益。
setTransparencyGain	更改通透增益。
setAncFadeOn	启用或禁用 ANC 淡入淡出。

参数

参数	类型	描述
mode	ANCMode / AIBudsANCMode	.normal、.anc 或 .transparency。不要设置 .unknown。
ancGain	Int / NSInteger	目标 ANC 增益。当前 Demo 使用 0...100；公开 SDK 尚未保证统一范围。
transparencyGain	Int / NSInteger	目标通透增益。当前 Demo 使用 0...100；公开 SDK 尚未保证统一范围。
isOn	Bool / BOOL	是否启用 ANC 淡入淡出。
completion	AIBudsCompletionHandler?	可选完成回调。

这些方法不直接返回值。完成回调接收 success 和可选的 NSError。

使用示例

读取当前设置

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");

更改 ANC 模式

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");
        }];

更改增益与淡入淡出

以下值沿用当前 SDK Demo。SDK 发布设备特定的增益限制后，需要重新核对。

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];

错误处理

命令失败时，将 UI 恢复为设备当前公开的值，并在回调错误可用时向用户报告。公开 API 未定义 ANC 专用错误码。