Add audio engine availability control (#786)

**Audio Engine Availability Control:**

* Added `AudioEngineAvailability` struct and related conversion
extensions in `AudioEngineAvailability.swift` to represent and manage
input/output availability for the audio engine.
* Introduced `setEngineAvailability(_:)` and `engineAvailability` API to
`AudioManager`, providing high-priority control over the engine's
running state.
* Updated publishing logic in `LocalParticipant` to only wait for audio
frames if input is available, respecting the new availability controls.

**Testing and Documentation:**

* Added `AudioEngineAvailabilityTests` to verify that the audio engine
stops and resumes correctly when availability is toggled, ensuring
robust behavior.
* Added a helper sleep extension to `LKTestCase` to support async test
scenarios.

**Dependency Updates:**

* Updated `LiveKitWebRTC` dependency to version `137.7151.08` in
`LiveKitClient.podspec`, `Package.swift`, and `Package@swift-6.0.swift`
to support the new audio engine availability features.
[[1]](diffhunk://#diff-cd792874225249a1976737e2b629c17cc7c8bb8de175a12d6b93a4e49b33dedbL17-R17)
[[2]](diffhunk://#diff-f913940c58e8744a2af1c68b909bb6383e49007e6c5a12fb03104a9006ae677eL22-R22)
[[3]](diffhunk://#diff-8e7a2b05a09a07931d721896a66b6648bf9cc39fa80e2b4f65f3cdd6c8e553abL23-R23)

Other minor changes include internal test updates to use `ObjCBool` for
engine state properties.

Author: hiroshihorie

.changes/audio-engine-availability

@@ -0,0 +1 @@
+patch type="added" "audio engine availability control"

LiveKitClient.podspec

@@ -14,7 +14,7 @@ Pod::Spec.new do |spec|
 
   spec.source_files = "Sources/**/*"
 
-  spec.dependency("LiveKitWebRTC", "= 137.7151.04")
+  spec.dependency("LiveKitWebRTC", "= 137.7151.08")
   spec.dependency("SwiftProtobuf")
   spec.dependency("Logging", "= 1.5.4")
   spec.dependency("DequeModule", "= 1.1.4")

Package.swift

@@ -19,7 +19,7 @@ let package = Package(
     ],
     dependencies: [
         // LK-Prefixed Dynamic WebRTC XCFramework
-        .package(url: "https://github.com/livekit/webrtc-xcframework.git", exact: "137.7151.05"),
+        .package(url: "https://github.com/livekit/webrtc-xcframework.git", exact: "137.7151.08"),
         .package(url: "https://github.com/apple/swift-protobuf.git", from: "1.29.0"),
         .package(url: "https://github.com/apple/swift-log.git", from: "1.6.2"),
         .package(url: "https://github.com/apple/swift-collections.git", from: "1.1.0"),

Package@swift-6.0.swift

@@ -20,7 +20,7 @@ let package = Package(
     ],
     dependencies: [
         // LK-Prefixed Dynamic WebRTC XCFramework
-        .package(url: "https://github.com/livekit/webrtc-xcframework.git", exact: "137.7151.05"),
+        .package(url: "https://github.com/livekit/webrtc-xcframework.git", exact: "137.7151.08"),
         .package(url: "https://github.com/apple/swift-protobuf.git", from: "1.29.0"),
         .package(url: "https://github.com/apple/swift-log.git", from: "1.6.2"),
         .package(url: "https://github.com/apple/swift-collections.git", from: "1.1.0"),

Sources/LiveKit/Audio/Manager/AudioManager.swift

@@ -309,6 +309,30 @@ public class AudioManager: Loggable {
         try checkAdmResult(code: result)
     }
 
+    /// Sets whether the internal `AVAudioEngine` is allowed to run.
+    ///
+    /// This flag has the highest priority over any API that may start the engine
+    /// (e.g., enabling the mic, ``startLocalRecording()``, or starting playback).
+    ///
+    /// - Behavior:
+    ///   - When set to a disabled availability, the engine will stop if running,
+    ///     and it will not start, even if recording or playback is requested.
+    ///   - When set back to enabled, the engine will start as soon as possible
+    ///     if recording and/or playback had been previously requested while disabled
+    ///     (i.e., pending requests are honored once availability allows).
+    ///
+    /// This is useful when you need to set up connections without touching the audio
+    /// device yet (e.g., CallKit flows), or to guarantee the engine remains off
+    /// regardless of subscription/publication requests.
+    public func setEngineAvailability(_ availability: AudioEngineAvailability) throws {
+        let result = RTC.audioDeviceModule.setEngineAvailability(availability.toRTCType())
+        try checkAdmResult(code: result)
+    }
+
+    public var engineAvailability: AudioEngineAvailability {
+        RTC.audioDeviceModule.engineAvailability.toLKType()
+    }
+
     /// Set a chain of ``AudioEngineObserver``s.
     /// Defaults to having a single ``AudioSessionEngineObserver`` initially.
     ///

Sources/LiveKit/Participant/LocalParticipant.swift

@@ -693,8 +693,11 @@ extension LocalParticipant {
 
             // At this point at least 1 audio frame should be generated to continue
             if let track = track as? LocalAudioTrack {
-                log("[Publish] Waiting for audio frame...")
-                try await track.startWaitingForFrames()
+                // Only wait for frames if audio engine is allowed to start
+                if AudioManager.shared.engineAvailability.isInputAvailable {
+                    log("[Publish] Waiting for audio frame...")
+                    try await track.startWaitingForFrames()
+                }
             }
 
             if track is LocalVideoTrack {

Sources/LiveKit/Types/AudioEngineAvailability.swift

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+internal import LiveKitWebRTC
+
+public struct AudioEngineAvailability: Sendable {
+    public static let `default` = AudioEngineAvailability(isInputAvailable: true, isOutputAvailable: true)
+    public static let none = AudioEngineAvailability(isInputAvailable: false, isOutputAvailable: false)
+
+    public let isInputAvailable: Bool
+    public let isOutputAvailable: Bool
+
+    public init(isInputAvailable: Bool, isOutputAvailable: Bool) {
+        self.isInputAvailable = isInputAvailable
+        self.isOutputAvailable = isOutputAvailable
+    }
+}
+
+extension LKRTCAudioEngineAvailability {
+    func toLKType() -> AudioEngineAvailability {
+        AudioEngineAvailability(isInputAvailable: isInputAvailable.boolValue,
+                                isOutputAvailable: isOutputAvailable.boolValue)
+    }
+}
+
+extension AudioEngineAvailability {
+    func toRTCType() -> LKRTCAudioEngineAvailability {
+        LKRTCAudioEngineAvailability(isInputAvailable: ObjCBool(isInputAvailable),
+                                     isOutputAvailable: ObjCBool(isOutputAvailable))
+    }
+}

Tests/LiveKitTests/Audio/AudioEngineAvailability.swift

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+@preconcurrency import AVFoundation
+@testable import LiveKit
+import XCTest
+
+class AudioEngineAvailabilityTests: LKTestCase {
+    // Check if audio engine will stop when availability is set to .none,
+    // then resume (restart) when availability is set back to .default.
+    func testRecording() async throws {
+        // First check
+        XCTAssertFalse(AudioManager.shared.isEngineRunning)
+
+        // Start
+        try AudioManager.shared.startLocalRecording()
+        XCTAssertTrue(AudioManager.shared.isEngineRunning)
+
+        // Disable both input & output
+        try AudioManager.shared.setEngineAvailability(.none)
+        XCTAssertFalse(AudioManager.shared.isEngineRunning)
+
+        // Re-enable both input & output (default)
+        try AudioManager.shared.setEngineAvailability(.default)
+        XCTAssertTrue(AudioManager.shared.isEngineRunning)
+
+        // Stop
+        try AudioManager.shared.stopLocalRecording()
+        XCTAssertFalse(AudioManager.shared.isEngineRunning)
+    }
+}

Tests/LiveKitTests/LKTestCase.swift

@@ -32,3 +32,9 @@ class LKTestCase: XCTestCase {
         super.setUp()
     }
 }
+
+extension LKTestCase {
+    func sleep(forSeconds seconds: UInt) async {
+        try? await Task.sleep(nanoseconds: UInt64(seconds) * 1_000_000_000)
+    }
+}

Tests/LiveKitTests/MuteTests.swift

@@ -69,23 +69,23 @@ func applyEngineTransition(_ transition: TestEngineTransition) {
     var engineState = adm.engineState
 
     if case let .value(value) = transition.outputEnabled {
-        engineState.outputEnabled = value
+        engineState.outputEnabled = ObjCBool(value)
     }
 
     if case let .value(value) = transition.outputRunning {
-        engineState.outputRunning = value
+        engineState.outputRunning = ObjCBool(value)
     }
 
     if case let .value(value) = transition.inputEnabled {
-        engineState.inputEnabled = value
+        engineState.inputEnabled = ObjCBool(value)
     }
 
     if case let .value(value) = transition.inputRunning {
-        engineState.inputRunning = value
+        engineState.inputRunning = ObjCBool(value)
     }
 
     if case let .value(value) = transition.inputMuted {
-        engineState.inputMuted = value
+        engineState.inputMuted = ObjCBool(value)
     }
 
     if case let .value(value) = transition.legacyMuteMode {