Skip to content

iOS: keep the interruption flag when the stop at interruption begin fails (m150) - #309

Closed
hiroshihorie wants to merge 2 commits into
m150_releasefrom
hiroshi/adm-keep-interruption-on-failed-stop-m150
Closed

hiroshihorie wants to merge 2 commits into
m150_releasefrom
hiroshi/adm-keep-interruption-on-failed-stop-m150

Conversation

@hiroshihorie

@hiroshihorie hiroshihorie commented Oct 13, 2026 •

Copy link
Copy Markdown
Member

Problem

ModifyEngineState commits engine state only when every step succeeds, and is_interrupted is part of that state. At an interruption begin, the stop step stops the engine and then calls OnEngineDidStop. When the observer returns an error there, the transition rolls back. The engine is already stopped, but is_interrupted stays false.

The interruption end then sees no change, so the start step never runs and the engine stays stopped until some unrelated transition restarts it. RTCAudioSession's synthetic ends (app activation, CallKit activation) do not help, since they also see no change.

Change

In the stop step, when OnEngineDidStop returns an error and the stop comes from an interruption begin, log the error instead of rolling back. The begin then commits normally with is_interrupted set, and the end restarts the engine as usual.

An app requested stop still rolls back on an OnEngineDidStop error, so the caller sees the error and can retry. The Swift SDK's observerFail audio test relies on that. A stop the system imposed for an interruption has no caller, the error was only ever logged, and nothing retries it.

The first commit set the flag from the interruption handler after the failure. The second commit moves the fix into the stop step, so ModifyEngineState stays the only place that commits engine state. Squash on merge.

Notes for review

Testing

  • clang -fsyntax-only of audio_engine_device.mm for macOS and iOS: no errors or warnings.
  • On device (iPhone 17 Pro Max, iOS 27) through apple-audio-lab. An engine observer at the head of the Swift SDK chain fails engineDidStop once, then the test posts a synthetic AVAudioSession.interruptionNotification began, then ended with shouldResume.
    • Swift SDK 2.15.3 with the released LiveKitWebRTC 144.7559.11: the engine never restarts after the end.
    • Local iOS debug build of m150_release: same, never restarts.
    • Local iOS debug build of this branch: the didStop error is logged, the begin commits, and the engine restarts 292 ms after the end (267 ms with the first commit alone).
  • The other lab SDK tests (synthetic interruption stop and restart, restart vs rebuild latency, processing seeds) pass on this build.

ModifyEngineState commits engine state only when every step succeeds,
and is_interrupted is part of that state. When an observer returns an
error from OnEngineDidStop at an interruption begin, the engine is
already stopped but the flag is dropped. The interruption end then sees
no change and never restarts the engine, so audio stays dead until some
other transition restarts it.

Set the flag after a failed begin so the end restarts the engine.
Move the fix into the stop step instead of writing engine_state_ from
the interruption handler. An app requested stop still rolls back on an
OnEngineDidStop error, so the caller sees it and can retry. A stop the
system imposed for an interruption has no caller to report to, so the
error is only logged and the begin commits normally with the flag set.

ModifyEngineState stays the only place that commits engine state.
@hiroshihorie

Copy link
Copy Markdown
Member Author

Superseded by #312. Its last commit stops rolling back on any teardown observer error (did-stop, did-disable and will-release), which covers the interruption begin case fixed here. The same device repro passes on #312. Closing in favor of #312.

hiroshihorie added a commit that referenced this pull request Nov 17, 2026
Supersedes #305, #306 and #309 (closed). #310 is a separate change.

## Problem

`ModifyEngineState` applies an engine transition step by step, rolls
back on any error, and commits the new state only when every step
succeeds. The engine observer hooks did not fit that model in two ways.

- Setup hooks could acquire without a release. When an enable failed
after a successful `OnEngineWillEnable`, or a create rolled back after a
successful `OnEngineDidCreate`, the observer was never told, so whatever
it acquired stayed held.
- Teardown hooks could roll back what cannot be undone.
`OnEngineDidStop`, `OnEngineDidDisable` and `OnEngineWillRelease` run
after `[engine stop]`, and the stop step registers no undo. An error
from them rolled the transition back with the engine already stopped, so
the committed state still said running. A later start saw no change and
never ran the engine, and an interruption end never restarted it.

## Change

The contract, documented in `api/audio/audio_device.h` and
`RTCAudioDeviceModule.h`:

1. Setup hooks (`OnEngineDidCreate`, `OnEngineWillEnable`,
`OnEngineWillStart` and the connect hooks) can fail the operation. A
non-zero result rolls it back and reaches the caller.
2. A setup hook that succeeded gets its release when the operation rolls
back. `OnEngineDidDisable` follows `OnEngineWillEnable`, and
`OnEngineWillRelease` follows `OnEngineDidCreate`.
3. Teardown hooks (`OnEngineDidStop`, `OnEngineDidDisable` and
`OnEngineWillRelease`) cannot fail the operation. A non-zero result is
logged and the operation completes.

One commit per rule:

- `68ac34a269` and `f92becad78`: will-enable compensation, port of #270
with its review follow-ups (previously #305).
- `9dc7a011fa`: did-create compensation (previously #306).
- `f300557860`: teardown errors are only logged, in the device and
manual rendering paths. Covers the interruption begin case of #309.

## Behavior change

A teardown hook error no longer reaches the caller. The Swift SDK's
`observerFail` audio test expects `stopLocalRecording()` to throw on a
failing `engineDidStop` and needs a matching update. React Native apps
whose JS did-stop handler throws get a log line instead of an error.

## Notes for review

- Not covered yet: an engine start failure after a successful
`OnEngineWillStart` still gets no `OnEngineDidStop`. The fault matrix
cannot inject a start failure, and current observers hold nothing from
will-start.
- #310 (double start at interruption end) and the interruption events
are separate changes and merge cleanly with this.

## Testing

- `clang -fsyntax-only` of `audio_engine_device.mm` and
`RTCAudioDeviceModule.mm` for macOS and iOS: no errors. The one iOS
warning is a pre-existing deprecation in `api/audio_options.h`.
- Fault injection matrix on device (iPhone 17 Pro Max, iOS 27),
apple-audio-lab `RollbackFaultMatrixTests`. A probe at the head of the
Swift SDK observer chain fails one of eight hooks once during one of
eight engine operations (capture start and stop, engine availability off
and on, interruption begin and end, mute and unmute in restart mute
mode). Each case then checks that bringing capture up runs the engine,
that taking it down stops it, and that every successful setup hook got
its release back at idle.
- Swift SDK 2.15.3 with the released LiveKitWebRTC 144.7559.11: 22 of 26
cases violate. 12 are setup failures that leak an acquire, 10 are
teardown failures that leave the engine stopped while the state says
running.
  - #306, which includes #305: 10 violations, all on the teardown path.
- Both numbers above predate the probe change below, which only affects
the three `willRelease` rows.
- A prototype of the teardown rule on top of #306 cleared the teardown
violations, except three that came from the probe itself (it failed
`willRelease` without forwarding it, which the probe now does).
  - This head: 0 of 26 cases violate.
- Other lab suites on this head, same device:
- Rolled back enable tests pass, including the did-disable order and the
release of the engine created for the failed enable.
- The #309 repro passes. A did-stop that fails at an interruption begin
no longer drops the interruption, and the end restarts the engine.
- A did-stop that fails on an app requested stop no longer throws, and
the next start runs the engine.
  - Interruption path and processing seed tests pass.
- The double start repros still hit `Check failed:
configuration_observer_ == nullptr` on this head, as expected without
#310.
hiroshihorie added a commit that referenced this pull request Nov 17, 2026
## Problem

Nothing keeps the engine from starting during an interruption. Any
transition from not running, a restart, or a recreate starts it while
`is_interrupted` is set, for example a capture start, or an engine
availability change while RTCAudioSession still considers the session
interrupted. The interruption end then runs the start step again through
`DidEndInterruption()`, although nothing stopped the engine:

- `OnEngineWillStart` fires a second time.
- A second `AVAudioEngineConfigurationChangeNotification` observer is
registered. Debug builds stop at `RTC_DCHECK(configuration_observer_ ==
nullptr)`. Release builds leak the first observer, so a later
configuration change runs `ReconfigureEngine` once per observer.

When RTCAudioSession's activation count is 0, which is always the case
under the Swift SDK, `updateAudioSessionAfterEvent` deactivates the
session at the interruption end. That stops the running engine without
the stop step, so the restart runs with the old observer still
registered.

## Change

- Start step: an interruption end starts the engine only when it is not
running.
- Stop step: at an interruption end, when the configuration observer is
still registered but the engine is not running, run the stop step first.
It removes the stale observer, and observers get `OnEngineDidStop`
before the restart.

## Notes for review

- Deactivating the session stops a running voice processing engine.
Measured on iOS 27: `setActive(false)` took 716 ms, `isRunning` was
false right after, and the engine posted one configuration change. That
is the activation count 0 path above.
- The normal path is unchanged. When the begin stopped the engine, the
observer is already removed and the engine is not running, so only the
start step runs at the end, as before.
- Independent of #305, #306 and #309, and merges cleanly with each. The
same code ships on `m144_release`, where React Native holds an
activation count above 0 and hits the double start.

## Testing

- `clang -fsyntax-only` of `audio_engine_device.mm` for macOS and iOS:
no errors.
- On device (iPhone 17 Pro Max, iOS 27) through apple-audio-lab. The
test posts a synthetic `AVAudioSession.interruptionNotification` began
while idle, starts local recording during the interruption, then posts a
synthetic ended with `shouldResume`.
- Activation count 1, raised through RTCAudioSession the way Flutter and
React Native hold it:
- Swift SDK 2.15.3 with the released LiveKitWebRTC 144.7559.11:
`OnEngineWillStart` fires twice with no stop in between.
- Local iOS debug build of `m150_release`: `Check failed:
configuration_observer_ == nullptr`.
- Local iOS debug build of this branch: `OnEngineWillStart` fires once
and the engine keeps running.
  - Activation count 0, the Swift SDK default:
- Swift SDK 2.15.3 with the released LiveKitWebRTC 144.7559.11: the
deactivation stops the engine, then `OnEngineWillStart` fires a second
time with the old observer still registered.
    - Local iOS debug build of `m150_release`: same check failure.
- Local iOS debug build of this branch: the ADM logs a stop, then a
start, and the engine runs.
- The other lab SDK tests (synthetic interruption stop and restart,
restart vs rebuild latency, processing seeds) pass on this build.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant