From f3378333a1d73b40185f4e8c0d3c04e900ae2c2d Mon Sep 17 00:00:00 2001 From: Ricardo Date: Mon, 31 Aug 2026 15:35:15 +0100 Subject: [PATCH 1/2] fix(ios): stabilize simulator audio startup Prime the Simulator audio route before AVAudioEngine realization, size and clear render buffers defensively, and serialize runtime replacement across route changes. --- ios/Elementary.mm | 152 ++++++++++++------ src/__tests__/iosOutputBufferSafety.test.ts | 92 +++++++++++ .../iosSimulatorRoutePriming.test.ts | 73 +++++++++ 3 files changed, 267 insertions(+), 50 deletions(-) create mode 100644 src/__tests__/iosOutputBufferSafety.test.ts create mode 100644 src/__tests__/iosSimulatorRoutePriming.test.ts diff --git a/ios/Elementary.mm b/ios/Elementary.mm index b41726f..4364e74 100644 --- a/ios/Elementary.mm +++ b/ios/Elementary.mm @@ -1,10 +1,22 @@ #import "Elementary.h" +#import #include "../cpp/AudioResourceLoader.h" #include "../cpp/vendor/elementary/runtime/elem/AudioBufferResource.h" static Elementary *_sharedInstance = nil; +#if TARGET_OS_SIMULATOR +// 100 ms of stereo 16-bit PCM silence avoids needlessly looping a one-frame +// asset at audio rate while the shared engine starts. +static const unsigned char kSimulatorRoutePrimerWav[17684] = { + 0x52, 0x49, 0x46, 0x46, 0x0c, 0x45, 0x00, 0x00, 0x57, 0x41, 0x56, 0x45, + 0x66, 0x6d, 0x74, 0x20, 0x10, 0x00, 0x00, 0x00, 0x01, 0x00, 0x02, 0x00, + 0x44, 0xac, 0x00, 0x00, 0x10, 0xb1, 0x02, 0x00, 0x04, 0x00, 0x10, 0x00, + 0x64, 0x61, 0x74, 0x61, 0xe8, 0x44, 0x00, 0x00, +}; +#endif + @implementation Elementary // Main-thread dispatch policy: @@ -68,6 +80,23 @@ - (void)dispatchMainWithEngineInit:(void (^)(void))block }); } +#if TARGET_OS_SIMULATOR +- (AVAudioPlayer *)startSimulatorAudioRoutePrimer { + NSData *silence = [NSData dataWithBytes:kSimulatorRoutePrimerWav + length:sizeof(kSimulatorRoutePrimerWav)]; + NSError *error = nil; + AVAudioPlayer *player = [[AVAudioPlayer alloc] initWithData:silence error:&error]; + player.numberOfLoops = -1; + player.volume = 0.0f; + if (!player || ![player play]) { + NSLog(@"[Elementary] Failed to prime Simulator audio route: %@", error.localizedDescription); + return nil; + } + NSLog(@"[Elementary] Simulator audio route primed"); + return player; +} +#endif + - (BOOL)initializeAudioEngineIfNeeded { if (self.audioEngineInitialized) { return YES; @@ -81,11 +110,19 @@ - (BOOL)initializeAudioEngineIfNeeded { // Configure and activate the audio session before creating AVAudioEngine. NSError *sessionError = nil; - [self setAudioSessionActive:YES error:&sessionError]; - if (sessionError) { + if (![self setAudioSessionActive:YES error:&sessionError]) { NSLog(@"[Elementary] Failed to activate audio session: %@", sessionError.localizedDescription); + return NO; } +#if TARGET_OS_SIMULATOR + // Simulator CoreAudio can abort if its host output starts while the first + // AURemoteIO is being reconfigured. Hold a silent client until the shared + // engine is running so that cleanup never races a cold device start. + AVAudioPlayer *routePrimer = [self startSimulatorAudioRoutePrimer]; + if (!routePrimer) return NO; +#endif + self.audioEngine = [[AVAudioEngine alloc] init]; AVAudioFormat *outputFormat = [self.audioEngine.outputNode outputFormatForBus:0]; @@ -105,34 +142,31 @@ - (BOOL)initializeAudioEngineIfNeeded { AVAudioFrameCount frameCount, AudioBufferList * _Nonnull audioBufferList) { - UInt32 actualChannels = audioBufferList->mNumberBuffers; + UInt32 suppliedBufferCount = audioBufferList->mNumberBuffers; + UInt32 actualChannels = MIN(suppliedBufferCount, (UInt32)numOutputChannels); - for (UInt32 channel = 0; channel < actualChannels; channel++) { + for (UInt32 channel = 0; channel < suppliedBufferCount; channel++) { memset(audioBufferList->mBuffers[channel].mData, 0, audioBufferList->mBuffers[channel].mDataByteSize); } - if (self.runtime == nullptr) { - return noErr; - } - // Try to acquire the lock without blocking. If applyInstructions // is in progress on the JS thread, output silence for this block // rather than risking heap corruption from concurrent access. std::unique_lock lock(self->_runtimeMutex, std::try_to_lock); - if (!lock.owns_lock()) { + if (!lock.owns_lock() || self.runtime == nullptr || actualChannels == 0) { return noErr; } - for (UInt8 channel = 0; channel < numOutputChannels; channel++) { + for (UInt32 channel = 0; channel < actualChannels; channel++) { outputBuffer[channel] = (float*)audioBufferList->mBuffers[channel].mData; } self.runtime->process( inputBuffer, - numOutputChannels, + actualChannels, outputBuffer, - numOutputChannels, + actualChannels, frameCount, nullptr ); @@ -143,16 +177,24 @@ - (BOOL)initializeAudioEngineIfNeeded { [self.audioEngine attachNode:sourceNode]; [self.audioEngine connect:sourceNode to:mixerNode format:outputFormat]; + int bufferSize = [self computeMaximumRenderFrames]; + NSLog(@"[Elementary] Runtime max block size: %d frames", bufferSize); + { + std::lock_guard lock(_runtimeMutex); + self.runtime = std::make_shared>(outputFormat.sampleRate, bufferSize); + } + NSError *error = nil; if (![self.audioEngine startAndReturnError:&error]) { +#if TARGET_OS_SIMULATOR + [routePrimer stop]; +#endif NSLog(@"Error starting audio engine: %@", error.localizedDescription); return NO; } - - // Use granted IOBufferDuration — iOS may not honor the preferred value exactly. - int bufferSize = [self computeBufferSizeFromSession]; - NSLog(@"[Elementary] Runtime block size: %d frames", bufferSize); - self.runtime = std::make_shared>(outputFormat.sampleRate, bufferSize); +#if TARGET_OS_SIMULATOR + [routePrimer stop]; +#endif [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(handleAudioInterruption:) @@ -190,9 +232,15 @@ - (void)startEventPolling { __weak Elementary *weakSelf = self; dispatch_source_set_event_handler(timer, ^{ Elementary *strongSelf = weakSelf; - if (!strongSelf || strongSelf.runtime == nullptr) return; + if (!strongSelf) return; - strongSelf.runtime->processQueuedEvents([strongSelf](std::string const& type, elem::js::Value data) { + std::shared_ptr> runtime; + { + std::lock_guard lock(strongSelf->_runtimeMutex); + runtime = strongSelf.runtime; + } + if (runtime == nullptr) return; + runtime->processQueuedEvents([strongSelf](std::string const& type, elem::js::Value data) { NSString *eventType = [NSString stringWithUTF8String:type.c_str()]; NSMutableDictionary *eventData = [NSMutableDictionary new]; eventData[@"type"] = eventType; @@ -273,21 +321,20 @@ - (void)handleEngineConfigChange:(NSNotification *)notification { NSLog(@"[Elementary] Failed to reactivate audio session after config change: %@", error.localizedDescription); error = nil; } + // Resize the runtime while the engine is stopped so no callback can observe + // the previous route's capacity after the new route starts rendering. + AVAudioFormat *newFormat = [strongSelf.audioEngine.outputNode outputFormatForBus:0]; + int newBufferSize = [strongSelf computeMaximumRenderFrames]; + NSLog(@"[Elementary] Recreating runtime: sampleRate=%.0f, maxBlockSize=%d", newFormat.sampleRate, newBufferSize); + { + std::lock_guard lock(strongSelf->_runtimeMutex); + strongSelf.runtime = std::make_shared>(newFormat.sampleRate, newBufferSize); + } + if (![strongSelf.audioEngine startAndReturnError:&error]) { NSLog(@"[Elementary] Failed to restart engine after config change: %@", error.localizedDescription); } else { NSLog(@"[Elementary] Engine restarted after config change"); - - // Recreate runtime with updated sample rate and block size. - // After a route change (e.g. Bluetooth/AirPlay), the session's - // IOBufferDuration and sample rate may differ from what we used at init. - AVAudioFormat *newFormat = [strongSelf.audioEngine.outputNode outputFormatForBus:0]; - int newBufferSize = [strongSelf computeBufferSizeFromSession]; - NSLog(@"[Elementary] Recreating runtime: sampleRate=%.0f, blockSize=%d", newFormat.sampleRate, newBufferSize); - { - std::lock_guard lock(strongSelf->_runtimeMutex); - strongSelf.runtime = std::make_shared>(newFormat.sampleRate, newBufferSize); - } } }); } @@ -421,12 +468,9 @@ - (AVAudioSessionCategoryOptions)audioSessionOptionsFromArray:(NSArray *)options return options; } -- (int)computeBufferSizeFromSession { - AVAudioSession *session = [AVAudioSession sharedInstance]; - AVAudioFormat *outputFormat = [self.audioEngine.outputNode outputFormatForBus:0]; - int bufferSize = (int)round(outputFormat.sampleRate * session.IOBufferDuration); - if (bufferSize <= 0 || bufferSize > 4096) bufferSize = 512; // safety fallback - return bufferSize; +- (int)computeMaximumRenderFrames { + int maximumFrames = (int)self.audioEngine.outputNode.AUAudioUnit.maximumFramesToRender; + return maximumFrames > 0 ? maximumFrames : 4096; } #ifdef RCT_NEW_ARCH_ENABLED @@ -502,11 +546,16 @@ - (void)disableAudioSessionManagement { [self dispatchMainWithEngineInit:^{ AVAudioFormat *format = [self.audioEngine.outputNode outputFormatForBus:0]; + BOOL runtimeReady; + { + std::lock_guard lock(_runtimeMutex); + runtimeReady = self.runtime != nullptr; + } resolve(@{ @"channels": @(format.channelCount), @"sampleRate": @(format.sampleRate), @"engineRunning": @(self.audioEngine.isRunning), - @"runtimeReady": @(self.runtime != nullptr), + @"runtimeReady": @(runtimeReady), }); } reject:reject]; } @@ -549,7 +598,7 @@ - (void)setProperty:(double)nodeHash key:(NSString *)key value:(double)value #endif { // Fast path: engine already initialized — update synchronously. - if (self.audioEngineInitialized && self.runtime != nullptr) { + if (self.audioEngineInitialized) { elem::js::Array instruction; instruction.push_back((double)3); instruction.push_back(nodeHash); @@ -561,7 +610,7 @@ - (void)setProperty:(double)nodeHash key:(NSString *)key value:(double)value { std::lock_guard lock(_runtimeMutex); - self.runtime->applyInstructions(batch); + if (self.runtime != nullptr) self.runtime->applyInstructions(batch); } return; } @@ -569,7 +618,7 @@ - (void)setProperty:(double)nodeHash key:(NSString *)key value:(double)value // Cold path: engine not yet initialized. Dispatch to main thread to // avoid AURemoteIO::Cleanup RPC timeout when accessing AVAudioEngine. dispatch_async(dispatch_get_main_queue(), ^{ - if (![self initializeAudioEngineIfNeeded] || self.runtime == nullptr) return; + if (![self initializeAudioEngineIfNeeded]) return; // Native integrations apply renderer instruction batches via Runtime::applyInstructions: // https://www.elementary.audio/docs/guides/Native_Integrations#applyinstructions @@ -585,7 +634,7 @@ - (void)setProperty:(double)nodeHash key:(NSString *)key value:(double)value { std::lock_guard lock(self->_runtimeMutex); - self.runtime->applyInstructions(batch); + if (self.runtime != nullptr) self.runtime->applyInstructions(batch); } }); } @@ -618,11 +667,6 @@ - (void)loadAudioResource:(NSString *)key { [self dispatchMainWithEngineInit:^{ dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{ - if (self.runtime == nullptr) { - reject(@"E_RUNTIME_NOT_INITIALIZED", @"Audio runtime not initialized", nil); - return; - } - std::string keyStr = [key UTF8String]; std::string filePathStr = [filePath UTF8String]; @@ -645,12 +689,20 @@ - (void)loadAudioResource:(NSString *)key numChannels, numSamples ); - bool added; + bool runtimeReady; + bool added = false; { std::lock_guard lock(self->_runtimeMutex); - added = self.runtime->addSharedResource(keyStr, std::move(resource)); + runtimeReady = self.runtime != nullptr; + if (runtimeReady) { + added = self.runtime->addSharedResource(keyStr, std::move(resource)); + } } + if (!runtimeReady) { + reject(@"E_RUNTIME_NOT_INITIALIZED", @"Audio runtime not initialized", nil); + return; + } if (!added) { reject(@"E_KEY_EXISTS", [NSString stringWithFormat:@"Resource with key '%@' already exists", key], nil); return; @@ -686,7 +738,7 @@ - (void)unloadAudioResource:(NSString *)key // unloadAudioResource does not require the audio engine to be running. // If the engine was never initialized, there are no resources to unload — // resolve immediately with NO without touching AVAudioEngine. - if (!self.audioEngineInitialized || self.runtime == nullptr) { + if (!self.audioEngineInitialized) { resolve(@(NO)); return; } @@ -706,7 +758,7 @@ - (void)unloadAudioResource:(NSString *)key if (found) { { std::lock_guard lock(self->_runtimeMutex); - self.runtime->pruneSharedResources(); + if (self.runtime != nullptr) self.runtime->pruneSharedResources(); } } diff --git a/src/__tests__/iosOutputBufferSafety.test.ts b/src/__tests__/iosOutputBufferSafety.test.ts new file mode 100644 index 0000000..9deb3ef --- /dev/null +++ b/src/__tests__/iosOutputBufferSafety.test.ts @@ -0,0 +1,92 @@ +import fs from 'node:fs'; +import path from 'node:path'; + +const source = fs.readFileSync( + path.resolve(__dirname, '../../ios/Elementary.mm'), + 'utf8' +); + +describe('iOS render buffer safety', () => { + it('only gives Elementary the output buffers supplied to the render callback', () => { + expect(source).not.toContain( + 'for (UInt8 channel = 0; channel < numOutputChannels; channel++)' + ); + expect(source).toMatch( + /self\.runtime->process\([\s\S]*?outputBuffer,[\s\S]*?actualChannels,\s*frameCount/ + ); + expect(source).toContain( + 'self.audioEngine.outputNode.AUAudioUnit.maximumFramesToRender' + ); + }); + + it('keeps every replaceable runtime pointer access behind the mutex', () => { + const method = (start: string, end: string) => + source.slice( + source.indexOf(start), + source.indexOf(end, source.indexOf(start)) + ); + const methods = [ + method( + 'RCT_EXPORT_METHOD(getAudioInfo:', + '#pragma mark - React Native Methods' + ), + method('- (void)setProperty:', '- (void)getSampleRate:'), + method('- (void)loadAudioResource:', '- (void)unloadAudioResource:'), + method('- (void)unloadAudioResource:', '- (void)getDocumentsDirectory:'), + ]; + + expect(source).not.toContain( + 'self.audioEngineInitialized && self.runtime != nullptr' + ); + expect(source).not.toContain( + 'initializeAudioEngineIfNeeded] || self.runtime == nullptr' + ); + for (const body of methods) { + expect( + body.indexOf('std::lock_guard') + ).toBeGreaterThanOrEqual(0); + expect(body.indexOf('self.runtime')).toBeGreaterThan( + body.indexOf('std::lock_guard') + ); + } + }); + + it('serializes runtime replacement before route callbacks resume', () => { + expect(source).toMatch( + /Runtime max block size[\s\S]*?lock\(_runtimeMutex\);[\s\S]*?self\.runtime =/ + ); + expect(source).toMatch( + /dispatch_source_set_event_handler[\s\S]*?lock\(strongSelf->_runtimeMutex\);[\s\S]*?runtime = strongSelf\.runtime;[\s\S]*?runtime->processQueuedEvents/ + ); + + const initializerStart = source.indexOf( + '- (BOOL)initializeAudioEngineIfNeeded' + ); + const initializerEnd = source.indexOf( + '- (void)startEventPolling', + initializerStart + ); + const initializer = source.slice(initializerStart, initializerEnd); + const initialRuntime = initializer.indexOf( + 'self.runtime = std::make_shared' + ); + const initialEngineStart = initializer.indexOf('startAndReturnError'); + expect(initialRuntime).toBeGreaterThanOrEqual(0); + expect(initialEngineStart).toBeGreaterThanOrEqual(0); + expect(initialRuntime).toBeLessThan(initialEngineStart); + + const handlerStart = source.indexOf('- (void)handleEngineConfigChange:'); + const handlerEnd = source.indexOf( + '+ (BOOL) requiresMainQueueSetup', + handlerStart + ); + const handler = source.slice(handlerStart, handlerEnd); + const replacementRuntime = handler.indexOf( + 'strongSelf.runtime = std::make_shared' + ); + const replacementEngineStart = handler.indexOf('startAndReturnError'); + expect(replacementRuntime).toBeGreaterThanOrEqual(0); + expect(replacementEngineStart).toBeGreaterThanOrEqual(0); + expect(replacementRuntime).toBeLessThan(replacementEngineStart); + }); +}); diff --git a/src/__tests__/iosSimulatorRoutePriming.test.ts b/src/__tests__/iosSimulatorRoutePriming.test.ts new file mode 100644 index 0000000..5a4204f --- /dev/null +++ b/src/__tests__/iosSimulatorRoutePriming.test.ts @@ -0,0 +1,73 @@ +import fs from 'node:fs'; +import path from 'node:path'; + +const source = fs.readFileSync( + path.resolve(__dirname, '../../ios/Elementary.mm'), + 'utf8' +); + +describe('iOS Simulator audio route priming', () => { + it('uses an explicitly muted, valid PCM silence buffer', () => { + const declaration = source.match( + /kSimulatorRoutePrimerWav\[(\d+)\]\s*=\s*\{([\s\S]*?)\};/ + ); + expect(declaration).not.toBeNull(); + if (!declaration?.[1] || !declaration[2]) throw new Error('Missing WAV'); + + const length = Number(declaration[1]); + const initializedBytes = Array.from( + declaration[2].matchAll(/0x([\da-f]{2})/gi), + (match) => Number.parseInt(match[1] ?? '', 16) + ); + const wav = Buffer.alloc(length); + initializedBytes.forEach((byte, index) => { + wav[index] = byte; + }); + + expect(wav.toString('ascii', 0, 4)).toBe('RIFF'); + expect(wav.readUInt32LE(4)).toBe(length - 8); + expect(wav.toString('ascii', 8, 12)).toBe('WAVE'); + expect(wav.readUInt16LE(20)).toBe(1); // PCM + expect(wav.readUInt16LE(22)).toBe(2); // stereo + expect(wav.readUInt32LE(24)).toBe(44_100); + expect(wav.readUInt16LE(34)).toBe(16); + expect(wav.readUInt32LE(40)).toBe(length - 44); + expect(wav.subarray(44).every((sample) => sample === 0)).toBe(true); + expect(source).toContain('player.volume = 0.0f'); + }); + + it('holds the muted route open while the shared AVAudioEngine initializes', () => { + const initializer = source.slice( + source.indexOf('- (BOOL)initializeAudioEngineIfNeeded'), + source.indexOf('- (void)startEventPolling') + ); + + expect(source).toContain('#if TARGET_OS_SIMULATOR'); + expect(source).toContain('AVAudioPlayer'); + expect(source).toContain('numberOfLoops = -1'); + expect(source).not.toContain( + 'if (!self.shouldManageAudioSession) return nil;' + ); + expect(initializer).toContain('if (!routePrimer) return NO;'); + expect(initializer).toMatch( + /if \(!\[self setAudioSessionActive:YES error:&sessionError\]\) \{[\s\S]*?return NO;/ + ); + + const primerStart = initializer.indexOf( + '[self startSimulatorAudioRoutePrimer]' + ); + const engineAllocation = initializer.indexOf( + '[[AVAudioEngine alloc] init]' + ); + const engineStart = initializer.indexOf('startAndReturnError'); + const primerStops = initializer.match(/\[routePrimer stop\]/g) ?? []; + const primerStop = initializer.indexOf('[routePrimer stop]'); + expect(primerStart).toBeGreaterThanOrEqual(0); + expect(engineAllocation).toBeGreaterThanOrEqual(0); + expect(engineStart).toBeGreaterThanOrEqual(0); + expect(primerStop).toBeGreaterThanOrEqual(0); + expect(primerStops).toHaveLength(2); + expect(primerStart).toBeLessThan(engineAllocation); + expect(primerStop).toBeGreaterThan(engineStart); + }); +}); From 973dcc44da91279887762c97294b7bf60f875b8f Mon Sep 17 00:00:00 2001 From: Ricardo Date: Mon, 16 Nov 2026 22:09:14 +0000 Subject: [PATCH 2/2] fix(ios): preserve fixed DSP blocks and serialize queued events --- .github/workflows/ci.yml | 7 ++ CHANGELOG.md | 9 ++ ios/Elementary.h | 3 + ios/Elementary.mm | 96 ++++++++++++------- ios/FixedBlockRenderer.h | 80 ++++++++++++++++ ios/QueuedEventPoller.h | 30 ++++++ ios/tests/AudioStabilityTests.cpp | 86 +++++++++++++++++ src/__tests__/iosAudioStability.test.ts | 34 +++++++ src/__tests__/iosOutputBufferSafety.test.ts | 14 ++- .../iosSimulatorRoutePriming.test.ts | 5 +- 10 files changed, 325 insertions(+), 39 deletions(-) create mode 100644 ios/FixedBlockRenderer.h create mode 100644 ios/QueuedEventPoller.h create mode 100644 ios/tests/AudioStabilityTests.cpp create mode 100644 src/__tests__/iosAudioStability.test.ts diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6681329..73ecad5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -29,6 +29,13 @@ jobs: steps: - name: Checkout uses: actions/checkout@v3 + with: + submodules: true + + - name: Native audio stability regressions + run: | + clang++ -std=c++17 -pthread -fsanitize=address,undefined -fno-omit-frame-pointer ios/tests/AudioStabilityTests.cpp -o /tmp/audio-stability-tests + /tmp/audio-stability-tests - name: Setup uses: ./.github/actions/setup diff --git a/CHANGELOG.md b/CHANGELOG.md index 8fb0f8a..07edf76 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## Unreleased + +### Bug Fixes + +- **ios:** Prime the Simulator audio route before cold engine startup and reject unusable output formats. +- **ios:** Adapt variable-size host callbacks to fixed DSP blocks, preserving feedback history and preventing buffer overruns. Carry-over can add up to one runtime block of latency. +- **ios:** Serialize runtime event collection with graph updates and route replacement; deliver events after unlocking so listeners can safely re-enter. +- **ios:** Keep `getAudioInfo` status-only: before initialization it returns zero channels/sample rate and false readiness/running flags without starting audio. + ## 0.4.1-beta.2 ### Features diff --git a/ios/Elementary.h b/ios/Elementary.h index 9e04543..cd10c05 100644 --- a/ios/Elementary.h +++ b/ios/Elementary.h @@ -2,6 +2,7 @@ #import "../cpp/vendor/elementary/runtime/elem/Runtime.h" #import #include +#include "FixedBlockRenderer.h" #ifdef RCT_NEW_ARCH_ENABLED #import @@ -12,6 +13,7 @@ /// and the JS thread (applyInstructions / setProperty). The audio callback /// uses try_lock — outputs silence on contention rather than blocking. std::mutex _runtimeMutex; + FixedBlockRenderer _fixedBlockRenderer; int _listenerCount; BOOL _hasEventListeners; } @@ -23,6 +25,7 @@ @interface Elementary : RCTEventEmitter { std::mutex _runtimeMutex; + FixedBlockRenderer _fixedBlockRenderer; int _listenerCount; BOOL _hasEventListeners; } diff --git a/ios/Elementary.mm b/ios/Elementary.mm index 4364e74..639746c 100644 --- a/ios/Elementary.mm +++ b/ios/Elementary.mm @@ -1,6 +1,8 @@ #import "Elementary.h" #import +#include +#include "QueuedEventPoller.h" #include "../cpp/AudioResourceLoader.h" #include "../cpp/vendor/elementary/runtime/elem/AudioBufferResource.h" @@ -97,6 +99,10 @@ - (AVAudioPlayer *)startSimulatorAudioRoutePrimer { } #endif +- (BOOL)hasUsableOutputFormat:(AVAudioFormat *)format { + return format.channelCount > 0 && std::isfinite(format.sampleRate) && format.sampleRate > 0; +} + - (BOOL)initializeAudioEngineIfNeeded { if (self.audioEngineInitialized) { return YES; @@ -126,12 +132,22 @@ - (BOOL)initializeAudioEngineIfNeeded { self.audioEngine = [[AVAudioEngine alloc] init]; AVAudioFormat *outputFormat = [self.audioEngine.outputNode outputFormatForBus:0]; - AVAudioMixerNode *mixerNode = self.audioEngine.mainMixerNode; - int numOutputChannels = outputFormat.channelCount; - const float **inputBuffer = (const float **)calloc(numOutputChannels, sizeof(float *)); - float **outputBuffer = (float **)malloc(numOutputChannels * sizeof(float *)); + if (![self hasUsableOutputFormat:outputFormat]) { + NSLog(@"[Elementary] Audio unavailable: invalid output format"); + self.audioEngine = nil; +#if TARGET_OS_SIMULATOR + [routePrimer stop]; +#endif + return NO; + } + + AVAudioMixerNode *mixerNode = self.audioEngine.mainMixerNode; + + // Captured owners release pointer storage when the source node is released. + auto inputBuffer = std::make_shared>(numOutputChannels, nullptr); + auto outputBuffer = std::make_shared>(numOutputChannels, nullptr); NSLog(@"[Elementary] Init: %d output channels, sampleRate=%.0f, IOBufferDuration=%.4fs", numOutputChannels, outputFormat.sampleRate, [AVAudioSession sharedInstance].IOBufferDuration); @@ -146,8 +162,10 @@ - (BOOL)initializeAudioEngineIfNeeded { UInt32 actualChannels = MIN(suppliedBufferCount, (UInt32)numOutputChannels); for (UInt32 channel = 0; channel < suppliedBufferCount; channel++) { - memset(audioBufferList->mBuffers[channel].mData, 0, - audioBufferList->mBuffers[channel].mDataByteSize); + if (audioBufferList->mBuffers[channel].mData != nullptr) { + memset(audioBufferList->mBuffers[channel].mData, 0, + audioBufferList->mBuffers[channel].mDataByteSize); + } } // Try to acquire the lock without blocking. If applyInstructions @@ -159,17 +177,22 @@ - (BOOL)initializeAudioEngineIfNeeded { } for (UInt32 channel = 0; channel < actualChannels; channel++) { - outputBuffer[channel] = (float*)audioBufferList->mBuffers[channel].mData; + const AudioBuffer& buffer = audioBufferList->mBuffers[channel]; + if (buffer.mData == nullptr || buffer.mNumberChannels != 1 || + frameCount > buffer.mDataByteSize / sizeof(float)) { + return noErr; + } + (*outputBuffer)[channel] = (float*)buffer.mData; } - self.runtime->process( - inputBuffer, - actualChannels, - outputBuffer, - actualChannels, - frameCount, - nullptr - ); + // Preserve feedback history: every DSP call must use the same block size, + // even when the host asks for a short remainder or an oversized callback. + self->_fixedBlockRenderer.render( + outputBuffer->data(), actualChannels, frameCount, + [&](float **blockOutput, std::size_t blockChannels, std::size_t blockSize) { + self.runtime->process(inputBuffer->data(), numOutputChannels, + blockOutput, blockChannels, blockSize, nullptr); + }); return noErr; }]; @@ -177,10 +200,11 @@ - (BOOL)initializeAudioEngineIfNeeded { [self.audioEngine attachNode:sourceNode]; [self.audioEngine connect:sourceNode to:mixerNode format:outputFormat]; - int bufferSize = [self computeMaximumRenderFrames]; - NSLog(@"[Elementary] Runtime max block size: %d frames", bufferSize); + int bufferSize = [self computeBufferSizeFromSession]; + NSLog(@"[Elementary] Runtime fixed block size: %d frames", bufferSize); { std::lock_guard lock(_runtimeMutex); + _fixedBlockRenderer.configure(numOutputChannels, bufferSize); self.runtime = std::make_shared>(outputFormat.sampleRate, bufferSize); } @@ -234,13 +258,9 @@ - (void)startEventPolling { Elementary *strongSelf = weakSelf; if (!strongSelf) return; - std::shared_ptr> runtime; - { - std::lock_guard lock(strongSelf->_runtimeMutex); - runtime = strongSelf.runtime; - } - if (runtime == nullptr) return; - runtime->processQueuedEvents([strongSelf](std::string const& type, elem::js::Value data) { + pollRuntimeEvents(strongSelf->_runtimeMutex, + [strongSelf] { return strongSelf.runtime; }, + [strongSelf](std::string const& type, elem::js::Value const& data) { NSString *eventType = [NSString stringWithUTF8String:type.c_str()]; NSMutableDictionary *eventData = [NSMutableDictionary new]; eventData[@"type"] = eventType; @@ -319,15 +339,20 @@ - (void)handleEngineConfigChange:(NSNotification *)notification { strongSelf.audioSessionActive = NO; if (![strongSelf setAudioSessionActive:YES error:&error]) { NSLog(@"[Elementary] Failed to reactivate audio session after config change: %@", error.localizedDescription); - error = nil; + return; } // Resize the runtime while the engine is stopped so no callback can observe // the previous route's capacity after the new route starts rendering. AVAudioFormat *newFormat = [strongSelf.audioEngine.outputNode outputFormatForBus:0]; - int newBufferSize = [strongSelf computeMaximumRenderFrames]; - NSLog(@"[Elementary] Recreating runtime: sampleRate=%.0f, maxBlockSize=%d", newFormat.sampleRate, newBufferSize); + if (![strongSelf hasUsableOutputFormat:newFormat]) { + NSLog(@"[Elementary] Audio unavailable after route change: invalid output format"); + return; + } + int newBufferSize = [strongSelf computeBufferSizeFromSession]; + NSLog(@"[Elementary] Recreating runtime: sampleRate=%.0f, blockSize=%d", newFormat.sampleRate, newBufferSize); { std::lock_guard lock(strongSelf->_runtimeMutex); + strongSelf->_fixedBlockRenderer.configure(newFormat.channelCount, newBufferSize); strongSelf.runtime = std::make_shared>(newFormat.sampleRate, newBufferSize); } @@ -468,9 +493,10 @@ - (AVAudioSessionCategoryOptions)audioSessionOptionsFromArray:(NSArray *)options return options; } -- (int)computeMaximumRenderFrames { - int maximumFrames = (int)self.audioEngine.outputNode.AUAudioUnit.maximumFramesToRender; - return maximumFrames > 0 ? maximumFrames : 4096; +- (int)computeBufferSizeFromSession { + AVAudioSession *session = [AVAudioSession sharedInstance]; + double frames = [self.audioEngine.outputNode outputFormatForBus:0].sampleRate * session.IOBufferDuration; + return std::isfinite(frames) && frames >= 1 && frames <= 4096 ? (int)std::round(frames) : 512; } #ifdef RCT_NEW_ARCH_ENABLED @@ -544,7 +570,13 @@ - (void)disableAudioSessionManagement RCT_EXPORT_METHOD(getAudioInfo:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) { - [self dispatchMainWithEngineInit:^{ + // Diagnostics must not realize a cold AVAudioEngine during navigation/import. + dispatch_async(dispatch_get_main_queue(), ^{ + if (!self.audioEngineInitialized || self.audioEngine == nil) { + resolve(@{@"channels": @0, @"sampleRate": @0, + @"engineRunning": @NO, @"runtimeReady": @NO}); + return; + } AVAudioFormat *format = [self.audioEngine.outputNode outputFormatForBus:0]; BOOL runtimeReady; { @@ -557,7 +589,7 @@ - (void)disableAudioSessionManagement @"engineRunning": @(self.audioEngine.isRunning), @"runtimeReady": @(runtimeReady), }); - } reject:reject]; + }); } #pragma mark - React Native Methods diff --git a/ios/FixedBlockRenderer.h b/ios/FixedBlockRenderer.h new file mode 100644 index 0000000..83c3a0a --- /dev/null +++ b/ios/FixedBlockRenderer.h @@ -0,0 +1,80 @@ +#pragma once + +#include +#include +#include +#include + +/// Serves variable-size host audio callbacks from a renderer that must always +/// be called with one fixed block size. +/// +/// Elementary's runtime is built for a fixed block size: its buffers hold that +/// many frames, and feedback taps (`el.tapIn` / `el.tapOut`) carry exactly one +/// block of history from the start of their buffers. iOS, however, asks an +/// AVAudioSourceNode for whatever frame count it likes (512 against a +/// 470-frame runtime, more while the screen is locked). Rendering more than the +/// block overruns the buffers; rendering a short remainder (470, 42, 470, …) +/// splices stale tap history into the feedback. So every render is a full +/// block into preallocated scratch, and frames the host didn't ask for yet are +/// carried over to its next callback. The cost is up to one block of latency. +/// +/// `configure` allocates and is called off the audio thread (under the same +/// lock as the runtime it pairs with); `render` never allocates. +class FixedBlockRenderer { +public: + void configure(std::size_t numChannels, std::size_t blockSize) + { + channels_ = numChannels; + blockSize_ = blockSize; + scratch_.assign(numChannels * blockSize, 0.0f); + blockPointers_.assign(numChannels, nullptr); + available_ = 0; + readPosition_ = 0; + } + + std::size_t blockSize() const { return blockSize_; } + + /// Fills `numFrames` frames of `output` (one pointer per channel), calling + /// `renderBlock(float** channels, std::size_t numChannels, std::size_t + /// blockSize)` with exactly `blockSize()` frames each time it needs more. + /// Leaves `output` untouched when not configured. + template + void render(float** output, std::size_t numOutputChannels, std::size_t numFrames, RenderBlock&& renderBlock) + { + if (blockSize_ == 0 || channels_ == 0) + return; + + const std::size_t channelsToCopy = std::min(numOutputChannels, channels_); + std::size_t written = 0; + + while (written < numFrames) { + if (available_ == 0) { + for (std::size_t c = 0; c < channels_; ++c) + blockPointers_[c] = scratch_.data() + c * blockSize_; + + renderBlock(blockPointers_.data(), channels_, blockSize_); + available_ = blockSize_; + readPosition_ = 0; + } + + const std::size_t count = std::min(numFrames - written, available_); + for (std::size_t c = 0; c < channelsToCopy; ++c) { + std::memcpy(output[c] + written, + scratch_.data() + c * blockSize_ + readPosition_, + count * sizeof(float)); + } + + written += count; + readPosition_ += count; + available_ -= count; + } + } + +private: + std::size_t channels_ = 0; + std::size_t blockSize_ = 0; + std::vector scratch_; + std::vector blockPointers_; + std::size_t available_ = 0; + std::size_t readPosition_ = 0; +}; diff --git a/ios/QueuedEventPoller.h b/ios/QueuedEventPoller.h new file mode 100644 index 0000000..ad4ac31 --- /dev/null +++ b/ios/QueuedEventPoller.h @@ -0,0 +1,30 @@ +#pragma once + +#include +#include +#include +#include + +#include "../cpp/vendor/elementary/runtime/elem/Value.h" + +// Inspect the current runtime only while holding its mutex. A contended tick +// leaves events queued; delivery happens after unlocking so listeners may +// re-enter the runtime without deadlocking or blocking the audio callback. +template +void pollRuntimeEvents(std::mutex& mutex, GetRuntime&& getRuntime, DeliverEvent&& deliverEvent) +{ + std::vector> events; + { + std::unique_lock lock(mutex, std::try_to_lock); + if (!lock.owns_lock()) + return; + auto runtime = getRuntime(); + if (!runtime) + return; + runtime->processQueuedEvents([&events](std::string const& type, elem::js::Value data) { + events.emplace_back(type, std::move(data)); + }); + } + for (auto const& [type, data] : events) + deliverEvent(type, data); +} diff --git a/ios/tests/AudioStabilityTests.cpp b/ios/tests/AudioStabilityTests.cpp new file mode 100644 index 0000000..a5365b4 --- /dev/null +++ b/ios/tests/AudioStabilityTests.cpp @@ -0,0 +1,86 @@ +#include "../FixedBlockRenderer.h" +#include "../QueuedEventPoller.h" + +#include +#include +#include + +static void testFixedBlocks() { + FixedBlockRenderer renderer; + renderer.configure(2, 470); + std::size_t generated = 0; + std::size_t consumed = 0; + auto process = [&](float** output, std::size_t channels, std::size_t frames) { + assert(channels == 2 && frames == 470); + for (std::size_t c = 0; c < channels; ++c) + for (std::size_t f = 0; f < frames; ++f) + output[c][f] = float(generated + f + c * 100000); + generated += frames; + }; + // Short, oversized, background-sized and zero callbacks keep sample order. + for (std::size_t frames : {512, 42, 0, 4096, 1, 8192, 470}) { + std::vector left(frames + 2, -1), right(frames + 2, -1); + float* output[] = {left.data() + 1, right.data() + 1}; + renderer.render(output, 2, frames, process); + assert(left.front() == -1 && left.back() == -1); + assert(right.front() == -1 && right.back() == -1); + for (std::size_t f = 0; f < frames; ++f) { + assert(left[f + 1] == float(consumed + f)); + assert(right[f + 1] == float(consumed + f + 100000)); + } + consumed += frames; + } + // A missing host channel does not shrink the runtime's DSP channel count. + float mono[8]{}; + float* output[] = {mono}; + renderer.render(output, 1, 8, process); + assert(mono[0] == float(consumed)); + renderer.configure(1, 4); // Route reset must discard old carry. + renderer.render(output, 1, 8, [](float** data, std::size_t channels, std::size_t frames) { + assert(channels == 1 && frames == 4); + std::fill_n(data[0], frames, 7.f); + }); + for (float sample : mono) assert(sample == 7.f); + renderer.configure(0, 0); + renderer.render(output, 1, 8, process); + for (float sample : mono) assert(sample == 7.f); +} + +struct FakeRuntime { + std::mutex& mutex; + int polls = 0; + template + void processQueuedEvents(Callback&& callback) { + ++polls; + callback("meter", elem::js::Value(12.0)); + } +}; + +static void testQueuedEvents() { + std::mutex mutex; + auto runtime = std::make_shared(FakeRuntime{mutex}); + int delivered = 0; + auto deliver = [&](std::string const& type, elem::js::Value const& value) { + // A listener may synchronously re-enter runtime code. + assert(mutex.try_lock()); + mutex.unlock(); + assert(type == "meter" && value.isNumber()); + ++delivered; + }; + auto getRuntime = [&] { return runtime; }; + pollRuntimeEvents(mutex, getRuntime, deliver); + assert(runtime->polls == 1 && delivered == 1); + mutex.lock(); + std::thread contended([&] { pollRuntimeEvents(mutex, getRuntime, deliver); }); + contended.join(); + mutex.unlock(); + assert(runtime->polls == 1 && delivered == 1); + runtime.reset(); + pollRuntimeEvents(mutex, getRuntime, deliver); + assert(delivered == 1); +} + +int main() { + testFixedBlocks(); + testQueuedEvents(); +} diff --git a/src/__tests__/iosAudioStability.test.ts b/src/__tests__/iosAudioStability.test.ts new file mode 100644 index 0000000..52c9546 --- /dev/null +++ b/src/__tests__/iosAudioStability.test.ts @@ -0,0 +1,34 @@ +import fs from 'node:fs'; +import path from 'node:path'; + +const source = fs.readFileSync( + path.resolve(__dirname, '../../ios/Elementary.mm'), + 'utf8' +); + +it('rejects invalid output formats before connecting or replacing the runtime', () => { + expect(source).toContain('std::isfinite(format.sampleRate)'); + const initializer = source.slice( + source.indexOf('- (BOOL)initializeAudioEngineIfNeeded'), + source.indexOf('- (void)startEventPolling') + ); + expect( + initializer.indexOf('hasUsableOutputFormat:outputFormat') + ).toBeLessThan(initializer.indexOf('connect:sourceNode')); + const route = source.slice( + source.indexOf('- (void)handleEngineConfigChange:') + ); + expect(route.indexOf('hasUsableOutputFormat:newFormat')).toBeLessThan( + route.indexOf('strongSelf.runtime =') + ); +}); + +it('does not initialize the audio engine to report diagnostics', () => { + const diagnostics = source.slice( + source.indexOf('RCT_EXPORT_METHOD(getAudioInfo:'), + source.indexOf('#pragma mark - React Native Methods') + ); + expect(diagnostics).not.toContain('dispatchMainWithEngineInit'); + expect(diagnostics).toContain('if (!self.audioEngineInitialized'); + expect(diagnostics).toContain('@"runtimeReady": @NO'); +}); diff --git a/src/__tests__/iosOutputBufferSafety.test.ts b/src/__tests__/iosOutputBufferSafety.test.ts index 9deb3ef..f09f6f8 100644 --- a/src/__tests__/iosOutputBufferSafety.test.ts +++ b/src/__tests__/iosOutputBufferSafety.test.ts @@ -11,12 +11,16 @@ describe('iOS render buffer safety', () => { expect(source).not.toContain( 'for (UInt8 channel = 0; channel < numOutputChannels; channel++)' ); - expect(source).toMatch( - /self\.runtime->process\([\s\S]*?outputBuffer,[\s\S]*?actualChannels,\s*frameCount/ + expect(source).toContain( + 'MIN(suppliedBufferCount, (UInt32)numOutputChannels)' + ); + expect(source).toContain( + 'outputBuffer->data(), actualChannels, frameCount' ); expect(source).toContain( - 'self.audioEngine.outputNode.AUAudioUnit.maximumFramesToRender' + 'frameCount > buffer.mDataByteSize / sizeof(float)' ); + expect(source).toContain('blockOutput, blockChannels, blockSize, nullptr'); }); it('keeps every replaceable runtime pointer access behind the mutex', () => { @@ -53,10 +57,10 @@ describe('iOS render buffer safety', () => { it('serializes runtime replacement before route callbacks resume', () => { expect(source).toMatch( - /Runtime max block size[\s\S]*?lock\(_runtimeMutex\);[\s\S]*?self\.runtime =/ + /Runtime fixed block size[\s\S]*?lock\(_runtimeMutex\);[\s\S]*?self\.runtime =/ ); expect(source).toMatch( - /dispatch_source_set_event_handler[\s\S]*?lock\(strongSelf->_runtimeMutex\);[\s\S]*?runtime = strongSelf\.runtime;[\s\S]*?runtime->processQueuedEvents/ + /dispatch_source_set_event_handler[\s\S]*?pollRuntimeEvents\(strongSelf->_runtimeMutex,[\s\S]*?return strongSelf\.runtime;/ ); const initializerStart = source.indexOf( diff --git a/src/__tests__/iosSimulatorRoutePriming.test.ts b/src/__tests__/iosSimulatorRoutePriming.test.ts index 5a4204f..9b73abf 100644 --- a/src/__tests__/iosSimulatorRoutePriming.test.ts +++ b/src/__tests__/iosSimulatorRoutePriming.test.ts @@ -61,12 +61,13 @@ describe('iOS Simulator audio route priming', () => { ); const engineStart = initializer.indexOf('startAndReturnError'); const primerStops = initializer.match(/\[routePrimer stop\]/g) ?? []; - const primerStop = initializer.indexOf('[routePrimer stop]'); + const primerStop = initializer.lastIndexOf('[routePrimer stop]'); expect(primerStart).toBeGreaterThanOrEqual(0); expect(engineAllocation).toBeGreaterThanOrEqual(0); expect(engineStart).toBeGreaterThanOrEqual(0); expect(primerStop).toBeGreaterThanOrEqual(0); - expect(primerStops).toHaveLength(2); + // Invalid format, failed engine start, and successful start all release it. + expect(primerStops).toHaveLength(3); expect(primerStart).toBeLessThan(engineAllocation); expect(primerStop).toBeGreaterThan(engineStart); });