Skip to main content

Interface: RnMediaAudioSession

Defined in: packages/audio-session/src/specs/audio-session.nitro.ts:263

The single OS audio-session arbiter.

Listener registration is id-based rather than "pass the same function to remove": Nitro callbacks are opaque native closures (a Kotlin lambda / Swift closure), so identity comparison across the bridge is not dependable. add*Listener returns a monotonically increasing id; feed it back to remove*Listener.

All callbacks are invoked from whatever thread the OS delivers the event on (Android: the focus-listener Handler / a binder thread; iOS: the notification queue). That is safe — Nitro schedules callback invocation onto the JS thread itself ("Their execution is scheduled on the JS Thread […] you can call the callback from any Thread", nitro.margelo.com/docs/types/callbacks).

Extends​

  • HybridObject<{ android: "kotlin"; ios: "swift"; }>

Properties​

name​

readonly name: string;

Defined in: node_modules/react-native-nitro-modules/lib/typescript/HybridObject.d.ts:52

The HybridObject's name.

Inherited from​

HybridObject.name

Methods​

activate()​

activate(): Promise<boolean>;

Defined in: packages/audio-session/src/specs/audio-session.nitro.ts:313

Request the session.

Resolves true when the app may start playing and false when the OS refused. It never resolves false for a programming error — those reject.

  • Android: requestAudioFocus; true only for AUDIOFOCUS_REQUEST_GRANTED.
  • iOS: setActive(true); false for the four AVAudioSessionErrorCodes that mean "the system declined" — cannotStartPlaying ('!pla'), cannotInterruptOthers ('!int', a backgrounded non-mixable app that is not the Now Playing app), insufficientPriority ('!pri', another app such as Phone is controlling audio) and siriIsRecording ('siri'). Everything else (badParam, incompatibleCategory, missingEntitlement, mediaServicesFailed, …) rejects.

Also arms the platform listeners: on Android the focus listener, the becoming-noisy receiver and the audio-device callback; on iOS the AVAudioSession notification observers (which are also armed by configure and by adding any listener).

Returns​

Promise<boolean>

addBecomingNoisyListener()​

addBecomingNoisyListener(listener: () => void): number;

Defined in: packages/audio-session/src/specs/audio-session.nitro.ts:359

Observe "the output the user was listening on went away" — Android's ACTION_AUDIO_BECOMING_NOISY, iOS's oldDeviceUnavailable route change.

Delivered from the moment the listener is added on both platforms: the Android BroadcastReceiver and the iOS notification observer are derived from the listener set, not from activate.

Parameters​

ParameterType
listener() => void

Returns​

number

addInterruptionListener()​

addInterruptionListener(listener: (event: NativeInterruptionEvent) => void): number;

Defined in: packages/audio-session/src/specs/audio-session.nitro.ts:346

Observe interruptions.

Delivery window. iOS delivers from the moment the observer exists — adding a listener installs it — whether or not the session was ever activated. Android delivers only while a focus request is outstanding, because AudioManager.OnAudioFocusChangeListener is a field of the AudioFocusRequest and the system has nobody to call before requestAudioFocus (https://developer.android.com/media/optimize/audio-focus). In practice every app activates before it plays, and no interruption is meaningful to an app that holds no focus.

Parameters​

ParameterType
listener(event: NativeInterruptionEvent) => void

Returns​

number

addRouteChangeListener()​

addRouteChangeListener(listener: (event: NativeRouteChangeEvent) => void): number;

Defined in: packages/audio-session/src/specs/audio-session.nitro.ts:367

Observe output-route changes. Same delivery window as addBecomingNoisyListener; see AudioRouteChangeReason for which reasons each platform can produce.

Parameters​

ParameterType
listener(event: NativeRouteChangeEvent) => void

Returns​

number

configure()​

configure(config: AudioSessionConfig): Promise<void>;

Defined in: packages/audio-session/src/specs/audio-session.nitro.ts:290

Apply config to the OS session.

iOS: setCategory(_:mode:options:) (or the policy: overload when IosAudioSessionConfig.routeSharingPolicy is set) — applied immediately, and remembered so it can be replayed after a media-services reset. Android: stores the AudioAttributes + focus gain used by the next activate.

Platform asymmetry — when the config takes effect. On iOS the category is a property of the session and changing it is a live operation. On Android there is no session object to mutate: AudioAttributes and the focus gain are constructor arguments of an AudioFocusRequest, which only exists as an argument to requestAudioFocus (https://developer.android.com/reference/android/media/AudioFocusRequest). So calling configure() while already active changes the live session on iOS and takes effect on the next activate() on Android. Configure before activating — which both presets and every example do — and the two agree.

Rejects on iOS if setCategory fails (a category/mode/option combination the device does not support). Cannot reject on Android: nothing is called.

Parameters​

ParameterType
configAudioSessionConfig

Returns​

Promise<void>

deactivate()​

deactivate(): Promise<void>;

Defined in: packages/audio-session/src/specs/audio-session.nitro.ts:331

Give the session back.

iOS: setActive(false, options: .notifyOthersOnDeactivation). Android: abandonAudioFocusRequest.

Listeners are not removed: subscriptions outlive activation on both platforms (see addBecomingNoisyListener).

Platform asymmetry — this can reject on iOS and cannot on Android. setActive(false) fails with AVAudioSessionErrorCode.isBusy ('!act') when the app "attempted to set its audio session inactive … but it is still actively playing and/or recording" (CoreAudioTypes.framework/Headers/AudioSessionTypes.h). Stop the player first. AudioManager.abandonAudioFocusRequest has no comparable failure.

Returns​

Promise<void>

dispose()​

dispose(): void;

Defined in: node_modules/react-native-nitro-modules/lib/typescript/HybridObject.d.ts:94

Disposes any resources this HybridObject might hold natively, and releases this HybridObject's NativeState.

After calling (), this object can no longer be used.

Eagerly disposing a HybridObject could be beneficial for a queue-/handler-architecture where a bunch of Hybrid Objects are allocated, and later deallocated once a callback (e.g. a render function) completes.

Returns​

void

Note​

It is NOT required to call () manually, as the JavaScript Garbage Collector automatically disposes and releases any resources when needed. It is purely optional to eagerly-, and manually-, call () here - use with caution!

Inherited from​

HybridObject.dispose

equals()​

equals(other: HybridObject<{
  android: "kotlin";
  ios: "swift";
}>): boolean;

Defined in: node_modules/react-native-nitro-modules/lib/typescript/HybridObject.d.ts:79

Returns whether this HybridObject is the same object as other.

While two HybridObjects might not be equal when compared with ==, they might still hold the same underlying HybridObject, in which case equals(other) will return true.

Parameters​

ParameterType
otherHybridObject<{ android: "kotlin"; ios: "swift"; }>

Returns​

boolean

Example​

const hybridA = SomeModule.getExistingHybridInstance()
const hybridB = SomeModule.getExistingHybridInstance()
console.log(hybridA.equals(hybridB)) // true

Inherited from​

HybridObject.equals

removeBecomingNoisyListener()​

removeBecomingNoisyListener(listenerId: number): void;

Defined in: packages/audio-session/src/specs/audio-session.nitro.ts:360

Parameters​

ParameterType
listenerIdnumber

Returns​

void

removeInterruptionListener()​

removeInterruptionListener(listenerId: number): void;

Defined in: packages/audio-session/src/specs/audio-session.nitro.ts:349

Parameters​

ParameterType
listenerIdnumber

Returns​

void

removeRouteChangeListener()​

removeRouteChangeListener(listenerId: number): void;

Defined in: packages/audio-session/src/specs/audio-session.nitro.ts:370

Parameters​

ParameterType
listenerIdnumber

Returns​

void

toString()​

toString(): string;

Defined in: node_modules/react-native-nitro-modules/lib/typescript/HybridObject.d.ts:64

Returns a string representation of the given HybridObject.

Unless overridden by the HybridObject, this will return the name of the object.

Returns​

string

Example​

const hybridA = SomeModule.getExistingHybridInstance()
console.log(hybridA.toString()) // [HybridObject HybridA]

Inherited from​

HybridObject.toString