feat(audio): apply audio processing options with a typed result

LocalAudioTrack.setAudioProcessingOptions returns an
AudioProcessingApplyResult (code + message + isSuccess) for operational
outcomes — applied/stored, and the device-capability rejections
platform-unavailable / apply-failed (inspect isSuccess). It throws
AudioProcessingException only for malformed requests (invalid mode
combination, or a non-local track).

The native plugin handlers return {result, code, message}; the Dart side
maps the code into the result or the exception accordingly.

Author: hiroshihorie

lib/src/support/native.dart

@@ -54,28 +54,24 @@ class Native {
   ///
   /// Resolved natively against the underlying WebRTC audio track owned by
   /// flutter_webrtc; [options] is the serialized [AudioProcessingOptions] map.
-  /// Returns whether the native layer applied/stored the request.
+  /// Returns the native result map (`result`/`code`/`message`) so the caller
+  /// can surface typed rejections. Channel errors propagate to the caller.
   @internal
-  static Future<bool> setAudioProcessingOptions(
+  static Future<Map<String, dynamic>> setAudioProcessingOptions(
     String trackId,
     Map<String, dynamic> options,
   ) async {
-    try {
-      final response = await channel.invokeMethod<dynamic>(
-        'setAudioProcessingOptions',
-        <String, dynamic>{
-          'trackId': trackId,
-          ...options,
-        },
-      );
-      if (response is Map) {
-        return response['result'] == true;
-      }
-      return response == true;
-    } catch (error) {
-      logger.warning('setAudioProcessingOptions did throw $error');
-      return false;
+    final response = await channel.invokeMethod<dynamic>(
+      'setAudioProcessingOptions',
+      <String, dynamic>{
+        'trackId': trackId,
+        ...options,
+      },
+    );
+    if (response is Map) {
+      return response.map((key, value) => MapEntry(key.toString(), value));
     }
+    return <String, dynamic>{};
   }
 
   @internal

lib/src/track/local/audio.dart

@@ -47,22 +47,36 @@ class LocalAudioTrack extends LocalTrack with AudioTrack, LocalAudioManagementMi
     }
   }
 
-  Future<bool> setAudioProcessingOptions(track_options.AudioProcessingOptions options) async {
+  Future<track_options.AudioProcessingApplyResult> setAudioProcessingOptions(
+      track_options.AudioProcessingOptions options) async {
     final nextOptions = currentOptions.copyWith(processing: options);
-    final success = await Native.setAudioProcessingOptions(
+    final response = await Native.setAudioProcessingOptions(
       mediaStreamTrack.id!,
       options.toMap(),
     );
 
-    if (success) {
+    final code = track_options.AudioProcessingOptionsResultCode.fromValue(response['code'] as String?);
+    final message = (response['message'] as String?) ?? '';
+
+    // Malformed requests (incompatible modes, or a non-local track) are caller
+    // bugs — surface them loudly rather than as a silently-unsuccessful result.
+    if (code == track_options.AudioProcessingOptionsResultCode.rejectedInvalidCombination ||
+        code == track_options.AudioProcessingOptionsResultCode.rejectedRemoteTrack) {
+      throw track_options.AudioProcessingException(
+        code,
+        message.isNotEmpty ? message : 'Unable to apply audio processing options',
+      );
+    }
+
+    final result = track_options.AudioProcessingApplyResult(code, message);
+    if (result.isSuccess) {
       currentOptions = nextOptions;
       events.emit(LocalTrackOptionsUpdatedEvent(
         track: this,
         options: currentOptions,
       ));
     }
-
-    return success;
+    return result;
   }
 
   num? _currentBitrate;

lib/src/track/options.dart

@@ -516,3 +516,56 @@ class AudioOutputOptions {
     );
   }
 }
+
+/// Result code from applying [AudioProcessingOptions], mirroring the native
+/// `AudioProcessingOptionsResult`. `applied`/`stored` are success; the rest are
+/// rejections.
+enum AudioProcessingOptionsResultCode {
+  applied('applied'),
+  stored('stored'),
+  rejectedRemoteTrack('rejectedRemoteTrack'),
+  rejectedInvalidCombination('rejectedInvalidCombination'),
+  rejectedPlatformUnavailable('rejectedPlatformUnavailable'),
+  applyFailed('applyFailed');
+
+  const AudioProcessingOptionsResultCode(this.value);
+
+  final String value;
+
+  static AudioProcessingOptionsResultCode fromValue(String? value) =>
+      AudioProcessingOptionsResultCode.values.firstWhere(
+        (e) => e.value == value,
+        orElse: () => AudioProcessingOptionsResultCode.applyFailed,
+      );
+
+  bool get isSuccess =>
+      this == AudioProcessingOptionsResultCode.applied || this == AudioProcessingOptionsResultCode.stored;
+}
+
+/// Thrown when the native layer rejects requested [AudioProcessingOptions]
+/// (e.g. an invalid platform/software combination, or platform processing that
+/// is unavailable on the device).
+class AudioProcessingException implements Exception {
+  AudioProcessingException(this.code, this.message);
+
+  final AudioProcessingOptionsResultCode code;
+  final String message;
+
+  @override
+  String toString() => 'AudioProcessingException(${code.value}): $message';
+}
+
+/// Outcome of applying [AudioProcessingOptions].
+///
+/// Returned for operational outcomes — `applied`/`stored` (success), and the
+/// device-capability rejections `rejectedPlatformUnavailable`/`applyFailed`
+/// (inspect [isSuccess]). A malformed request (incompatible modes, or a
+/// non-local track) throws [AudioProcessingException] instead.
+class AudioProcessingApplyResult {
+  AudioProcessingApplyResult(this.code, this.message);
+
+  final AudioProcessingOptionsResultCode code;
+  final String message;
+
+  bool get isSuccess => code.isSuccess;
+}