From 35fdd53e74ff904587d0d02e6ab75ef68530428c Mon Sep 17 00:00:00 2001 From: michal Date: Tue, 20 May 2025 18:19:01 +0200 Subject: [PATCH 1/7] docs: add audio manager documentation --- .../audiodocs/docs/system/_category_.json | 8 + .../audiodocs/docs/system/audio-manager.mdx | 151 ++++++++++++++++++ 2 files changed, 159 insertions(+) create mode 100644 packages/audiodocs/docs/system/_category_.json create mode 100644 packages/audiodocs/docs/system/audio-manager.mdx diff --git a/packages/audiodocs/docs/system/_category_.json b/packages/audiodocs/docs/system/_category_.json new file mode 100644 index 00000000..843d5398 --- /dev/null +++ b/packages/audiodocs/docs/system/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "System", + "position": 6, + "link": { + "type": "generated-index" + } + } + \ No newline at end of file diff --git a/packages/audiodocs/docs/system/audio-manager.mdx b/packages/audiodocs/docs/system/audio-manager.mdx new file mode 100644 index 00000000..6cd33714 --- /dev/null +++ b/packages/audiodocs/docs/system/audio-manager.mdx @@ -0,0 +1,151 @@ +--- +sidebar_position: 1 +--- + +import { Optional, ReadOnly } from '@site/src/components/Badges'; + +# AudioManager + +The `AudioManager` is a layer of an abstraction between user and a system. +It provides a set of system-specific functions that are invoked directly in native code, by related system. + +## Properties + +| Name | Type | Description | +| :----: | :----: | :-------- | +| `audioEventEmitter` | `AudioEventEmitter` | Custom event emmiter that allows to create listener, to events that are invoked from a system. | + +## Methods + +### `setLockScreenInfo` + +| Parameters | Type | +| :---: | :---: | +| `info` | [`LockScreenInfo`](/system/audio-manager#lockscreeninfo) | + +### `resetLockScreenInfo` + +Resets all of the lock screen data. + +### `setAudioSessionOptions` + +| Parameters | Type | Description | +| :---: | :---: | :---- | +| options `iOS` only | [`SessionOptions`](/system/audio-manager#sessionoptions) | Options to be set for session | + +### `getDevicePreferredSampleRate` + +Returns preferred sample rate by the device. + +### `observeAudioInterruptions` + +| Parameters | Type | Description | +| :---: | :---: | :---- | +| `enabled` | `boolean` | Can be used to enable or disable observing audio interruptions | + +### `observeVolumeChanges` + +| Parameters | Type | Description | +| :---: | :---: | :---- | +| `enabled` | `boolean` | Can be used to enable or disable observing volume changes | + +### `enableSystemEvent` + +| Parameters | Type | Description | +| :---: | :---: | :---- | +| `name` | [`Name`](/system/audio-manager#name) | Name of an event listener | +| `callback` | [`SystemEventCallback`](/system/audio-manager#systemeventcallbackname) | Callback that will be invoked upon hearing an event | +| `enabled` | `boolean` (default value is `true`)| Can be used to enable or disable emmiting system event | + +### `requestRecordingPermissions` + +Allows to bring up the system microphone permissions pop-up on demand. The pop-up automatically shows if microphone data +is directly requested, but sometimes it is better to ask beforehand. +Returns promise of [`PermissionStatus`](/system/audio-manager#permissionstatus) type, which is resolved after receiving answer from the system. + +### `checkRecordingPermissions` + +Allows to check if permissions were previously granted. +Returns promise of [`PermissionStatus`](/system/audio-manager#permissionstatus) type, which is resolved after receiving answer from the system. + +## Remarks + +### `LockScreenInfo` + +| Name | Type | Description | +| :----: | :----: | :-------- | +| `title` | `string` | Title of the track | +| `artwork` | `string` | Uri to the artwork | +| `artist` | `string` | Name of the artist | +| `album` | `string` | Name of the album | +| `duration` | `number` | Duration of the song in seconds | +| `description` `android` only | `string` | Description of the track | +| `state` | `string` | `state_playing` if track is played, `state_paused` otherwise | +| `speed` | `number` | Speed rate of playing | +| `elapsedTime` | `number` | In seconds, how many time of audio has elapsed | + +### `SessionOptions` + +| Name | Type | Possible values | +| :----: | :----: | :-------- | +| `iosMode` | `string` | `default`, `gameChat`, `videoChat`, `voiceChat`, `measurement`, `voicePrompt`, `spokenAudio`, `moviePlayback`, `videoRecording`| +| `iosOptions` | `string[]` | `duckOthers`, `allowAirPlay`, `mixWithOthers`, `allowBluetooth`, `defaultToSpeaker`, `allowBluetoothA2DP`, `overrideMutedMicrophoneInterruption`, `interruptSpokenAudioAndMixWithOthers`| +| `iosCategory` | `string` | `record`, `ambient`, `playback`, `multiRoute`, `soloAmbient`, `playAndRecord`| + + +### `Name` + +TODO: description of what each of the name does + + +Available values: +- `remotePlay` +- `remotePause` +- `remoteStop` +- `remoteTogglePlayPause` +- `remoteChangePlaybackRate` +- `remoteNextTrack` +- `remotePreviousTrack` +- `remoteSkipForward` +- `remoteSkipBackward` +- `remoteSeekForward` +- `remoteSeekBackward` +- `remoteChangePlaybackPosition` +- `volumeChange` +- `interruption` +- `routeChange` + + +### `SystemEventCallback` + +It maps `Name` value to a corresponding type of callback. + +- `remotePlay`, `remotePause`, `remoteStop`, `remoteTogglePlayPause`, `remoteNextTrack`, `remoteSkipForward`, `remoteSkipBackward` + +`Empty` type + +- `remoteChangePlaybackRate`, `remoteSeekForward`, `remoteSeekBackward`, `remoteChangePlaybackPosition`, `volumeChange` + +| Parameters | Type | Description | +| :---: | :---: | :---- | +| `value` | `number` | value from system described in [`Name`](/system/audio-manager#name) section + +- `interruption` + +| Parameters | Type | Description | +| :---: | :---: | :---- | +| `type` | `string` | `began` or `ended` value that indicates if interruption event has started or ended | +| `shouldResume` | `boolean` | if we should resume playing upon receiving event | + +- `routeChange` + +| Parameters | Type | Description | +| :---: | :---: | :---- | +| `reason` | `string` | cause of event emition | + +### `PermissionStatus` + +Available `string` values: +- `Denied` -> Indicates that user did not grant permission. +- `Granted` -> Indicates that user did grant permission. +- `Undetermined` -> In rare cases, system can return "not granted, but not denied" f.e. when something interrupt an app while asking. From fee7d6fe94c6e217908be9cdf36e82fe7a3459b8 Mon Sep 17 00:00:00 2001 From: michal Date: Wed, 21 May 2025 12:33:04 +0200 Subject: [PATCH 2/7] feat: rewrote types section --- .../audiodocs/docs/system/audio-manager.mdx | 227 +++++++++++------- .../audiodocs/src/components/Badges/index.tsx | 4 + 2 files changed, 148 insertions(+), 83 deletions(-) diff --git a/packages/audiodocs/docs/system/audio-manager.mdx b/packages/audiodocs/docs/system/audio-manager.mdx index 6cd33714..a6d365c8 100644 --- a/packages/audiodocs/docs/system/audio-manager.mdx +++ b/packages/audiodocs/docs/system/audio-manager.mdx @@ -2,7 +2,7 @@ sidebar_position: 1 --- -import { Optional, ReadOnly } from '@site/src/components/Badges'; +import { Optional, ReadOnly, OnlyiOS } from '@site/src/components/Badges'; # AudioManager @@ -13,25 +13,41 @@ It provides a set of system-specific functions that are invoked directly in nati | Name | Type | Description | | :----: | :----: | :-------- | -| `audioEventEmitter` | `AudioEventEmitter` | Custom event emmiter that allows to create listener, to events that are invoked from a system. | +| `audioEventEmitter` | `AudioEventEmitter` | Custom event emmiter that allows to create listener to events, that are invoked from a system. | + +## Example + +```tsx +import { AudioManager } from 'react-native-audio-api'; + +function App() { + // set info for track to be visible while device is locked + AudioManager.setLockScreenInfo({ + title: 'Audio file', + artist: 'Software Mansion', + album: 'Audio API', + duration: 10, + }); +} +``` ## Methods ### `setLockScreenInfo` -| Parameters | Type | -| :---: | :---: | -| `info` | [`LockScreenInfo`](/system/audio-manager#lockscreeninfo) | +| Parameters | Type | Description | +| :---: | :---: | :-----: | +| `info` | [`LockScreenInfo`](/system/audio-manager#lockscreeninfo) | Info to be displayed on lock screen | ### `resetLockScreenInfo` Resets all of the lock screen data. -### `setAudioSessionOptions` +### `setAudioSessionOptions` | Parameters | Type | Description | | :---: | :---: | :---- | -| options `iOS` only | [`SessionOptions`](/system/audio-manager#sessionoptions) | Options to be set for session | +| options | [`SessionOptions`](/system/audio-manager#sessionoptions) | Options to be set for session | ### `getDevicePreferredSampleRate` @@ -53,8 +69,8 @@ Returns preferred sample rate by the device. | Parameters | Type | Description | | :---: | :---: | :---- | -| `name` | [`Name`](/system/audio-manager#name) | Name of an event listener | -| `callback` | [`SystemEventCallback`](/system/audio-manager#systemeventcallbackname) | Callback that will be invoked upon hearing an event | +| `name` | [`Name`](/system/audio-manager#name-systemeventcallbackname) | Name of an event listener | +| `callback` | [`SystemEventCallback`](/system/audio-manager#name-systemeventcallbackname) | Callback that will be invoked upon hearing an event | | `enabled` | `boolean` (default value is `true`)| Can be used to enable or disable emmiting system event | ### `requestRecordingPermissions` @@ -72,80 +88,125 @@ Returns promise of [`PermissionStatus`](/system/audio-manager#permissionstatus) ### `LockScreenInfo` -| Name | Type | Description | -| :----: | :----: | :-------- | -| `title` | `string` | Title of the track | -| `artwork` | `string` | Uri to the artwork | -| `artist` | `string` | Name of the artist | -| `album` | `string` | Name of the album | -| `duration` | `number` | Duration of the song in seconds | -| `description` `android` only | `string` | Description of the track | -| `state` | `string` | `state_playing` if track is played, `state_paused` otherwise | -| `speed` | `number` | Speed rate of playing | -| `elapsedTime` | `number` | In seconds, how many time of audio has elapsed | - -### `SessionOptions` - -| Name | Type | Possible values | -| :----: | :----: | :-------- | -| `iosMode` | `string` | `default`, `gameChat`, `videoChat`, `voiceChat`, `measurement`, `voicePrompt`, `spokenAudio`, `moviePlayback`, `videoRecording`| -| `iosOptions` | `string[]` | `duckOthers`, `allowAirPlay`, `mixWithOthers`, `allowBluetooth`, `defaultToSpeaker`, `allowBluetoothA2DP`, `overrideMutedMicrophoneInterruption`, `interruptSpokenAudioAndMixWithOthers`| -| `iosCategory` | `string` | `record`, `ambient`, `playback`, `multiRoute`, `soloAmbient`, `playAndRecord`| - - -### `Name` - -TODO: description of what each of the name does - - -Available values: -- `remotePlay` -- `remotePause` -- `remoteStop` -- `remoteTogglePlayPause` -- `remoteChangePlaybackRate` -- `remoteNextTrack` -- `remotePreviousTrack` -- `remoteSkipForward` -- `remoteSkipBackward` -- `remoteSeekForward` -- `remoteSeekBackward` -- `remoteChangePlaybackPosition` -- `volumeChange` -- `interruption` -- `routeChange` - - -### `SystemEventCallback` - -It maps `Name` value to a corresponding type of callback. - -- `remotePlay`, `remotePause`, `remoteStop`, `remoteTogglePlayPause`, `remoteNextTrack`, `remoteSkipForward`, `remoteSkipBackward` - -`Empty` type - -- `remoteChangePlaybackRate`, `remoteSeekForward`, `remoteSeekBackward`, `remoteChangePlaybackPosition`, `volumeChange` - -| Parameters | Type | Description | -| :---: | :---: | :---- | -| `value` | `number` | value from system described in [`Name`](/system/audio-manager#name) section - -- `interruption` - -| Parameters | Type | Description | -| :---: | :---: | :---- | -| `type` | `string` | `began` or `ended` value that indicates if interruption event has started or ended | -| `shouldResume` | `boolean` | if we should resume playing upon receiving event | - -- `routeChange` - -| Parameters | Type | Description | -| :---: | :---: | :---- | -| `reason` | `string` | cause of event emition | +
+Type definitions +```typescript +interface BaseLockScreenInfo { + [key: string]: string | boolean | number | undefined; +} + +//state_playing if track is played, state_paused otherwise +type MediaState = 'state_playing' | 'state_paused'; + +interface LockScreenInfo extends BaseLockScreenInfo { + title?: string; //title of the track + artwork?: string; //uri to the artwork + artist?: string; //name of the artist + album?: string; //name of the album + duration?: number; //duration in seconds + description?: string; // android only, description of the track + state?: MediaState; + speed?: number; //playback rate + elapsedTime?: number; //elapsed time of an audio in seconds +} +``` +
+ +### `SessionOptions` + +
+Type definitions +```typescript +type IOSCategory = + | 'record' + | 'ambient' + | 'playback' + | 'multiRoute' + | 'soloAmbient' + | 'playAndRecord'; + +type IOSMode = + | 'default' + | 'gameChat' + | 'videoChat' + | 'voiceChat' + | 'measurement' + | 'voicePrompt' + | 'spokenAudio' + | 'moviePlayback' + | 'videoRecording'; + +type IOSOption = + | 'duckOthers' + | 'allowAirPlay' + | 'mixWithOthers' + | 'allowBluetooth' + | 'defaultToSpeaker' + | 'allowBluetoothA2DP' + | 'overrideMutedMicrophoneInterruption' + | 'interruptSpokenAudioAndMixWithOthers'; + +interface SessionOptions { + iosMode?: IOSMode; + iosOptions?: IOSOption[]; + iosCategory?: IOSCategory; +} +``` +
+ + +### `Name` `SystemEventCallback` + +TODO: description of what each of the name means + +
+Type definitions +```typescript +interface EventEmptyType {} + +interface EventTypeWithValue { + value: number; +} + +interface OnInterruptionEventType { + type: 'ended' | 'began'; //if interruption event has started or ended + shouldResume: boolean; //if we should resume playing after interruption +} + +interface OnRouteChangeEventType { + reason: string; //cause of event emmition +} + +interface SystemEvents { + remotePlay: EventEmptyType; + remotePause: EventEmptyType; + remoteStop: EventEmptyType; + remoteTogglePlayPause: EventEmptyType; + remoteChangePlaybackRate: EventTypeWithValue; + remoteNextTrack: EventEmptyType; + remotePreviousTrack: EventEmptyType; + remoteSkipForward: EventEmptyType; + remoteSkipBackward: EventEmptyType; + remoteSeekForward: EventTypeWithValue; + remoteSeekBackward: EventTypeWithValue; + remoteChangePlaybackPosition: EventTypeWithValue; + volumeChange: EventTypeWithValue; + interruption: OnInterruptionEventType; + routeChange: OnRouteChangeEventType; +} + +type SystemEventName = keyof SystemEvents; +type SystemEventCallback = ( + event: SystemEvents[Name] +) => void; +``` +
### `PermissionStatus` -Available `string` values: -- `Denied` -> Indicates that user did not grant permission. -- `Granted` -> Indicates that user did grant permission. -- `Undetermined` -> In rare cases, system can return "not granted, but not denied" f.e. when something interrupt an app while asking. +
+Type definitions +```typescript +type PermissionStatus = 'Undetermined' | 'Denied' | 'Granted'; +``` +
diff --git a/packages/audiodocs/src/components/Badges/index.tsx b/packages/audiodocs/src/components/Badges/index.tsx index 3bc9478a..ccc14271 100644 --- a/packages/audiodocs/src/components/Badges/index.tsx +++ b/packages/audiodocs/src/components/Badges/index.tsx @@ -13,6 +13,10 @@ export function Overridden({ footnote }) { return
Overridden{footnote ? '*' : ''}
; } +export function OnlyiOS({ footnote }) { + return
iOS only{footnote ? '*' : ''}
; +} + export function Experimental({ footnote }) { return
Experimental{footnote ? '*' : ''}
; } From 148f632aa640e4f8b10fd1bd94d9ca3b857e9f7a Mon Sep 17 00:00:00 2001 From: michal Date: Wed, 21 May 2025 17:47:35 +0200 Subject: [PATCH 3/7] docs: better info on returning types --- .../audiodocs/docs/system/audio-manager.mdx | 52 +++++++++++++++++-- 1 file changed, 49 insertions(+), 3 deletions(-) diff --git a/packages/audiodocs/docs/system/audio-manager.mdx b/packages/audiodocs/docs/system/audio-manager.mdx index a6d365c8..fc63a150 100644 --- a/packages/audiodocs/docs/system/audio-manager.mdx +++ b/packages/audiodocs/docs/system/audio-manager.mdx @@ -39,19 +39,25 @@ function App() { | :---: | :---: | :-----: | | `info` | [`LockScreenInfo`](/system/audio-manager#lockscreeninfo) | Info to be displayed on lock screen | +#### Returns `undefined` + ### `resetLockScreenInfo` Resets all of the lock screen data. +#### Returns `undefined` + ### `setAudioSessionOptions` | Parameters | Type | Description | | :---: | :---: | :---- | | options | [`SessionOptions`](/system/audio-manager#sessionoptions) | Options to be set for session | +#### Returns `undefined` + ### `getDevicePreferredSampleRate` -Returns preferred sample rate by the device. +#### Returns `number`. ### `observeAudioInterruptions` @@ -59,12 +65,16 @@ Returns preferred sample rate by the device. | :---: | :---: | :---- | | `enabled` | `boolean` | Can be used to enable or disable observing audio interruptions | +#### Returns `undefined` + ### `observeVolumeChanges` | Parameters | Type | Description | | :---: | :---: | :---- | | `enabled` | `boolean` | Can be used to enable or disable observing volume changes | +#### Returns `undefined` + ### `enableSystemEvent` | Parameters | Type | Description | @@ -73,16 +83,20 @@ Returns preferred sample rate by the device. | `callback` | [`SystemEventCallback`](/system/audio-manager#name-systemeventcallbackname) | Callback that will be invoked upon hearing an event | | `enabled` | `boolean` (default value is `true`)| Can be used to enable or disable emmiting system event | +#### Returns [`AudioEventSubscription`](/system/audio-manager#audioeventsubscription) if `enabled` is set to true, `undefined` otherwise + ### `requestRecordingPermissions` Allows to bring up the system microphone permissions pop-up on demand. The pop-up automatically shows if microphone data is directly requested, but sometimes it is better to ask beforehand. -Returns promise of [`PermissionStatus`](/system/audio-manager#permissionstatus) type, which is resolved after receiving answer from the system. + +#### Returns promise of [`PermissionStatus`](/system/audio-manager#permissionstatus) type, which is resolved after receiving answer from the system. ### `checkRecordingPermissions` Allows to check if permissions were previously granted. -Returns promise of [`PermissionStatus`](/system/audio-manager#permissionstatus) type, which is resolved after receiving answer from the system. + +#### Returns promise of [`PermissionStatus`](/system/audio-manager#permissionstatus) type, which is resolved after receiving answer from the system. ## Remarks @@ -202,6 +216,38 @@ type SystemEventCallback = ( ``` + +### `AudioEventSubscription` + +
+Type definitions +```typescript +class AudioEventSubscription { + private readonly audioEventEmitter: AudioEventEmitter; + private readonly eventName: AudioEventName; + /** @internal */ + public readonly subscriptionId: string; + + constructor( + subscriptionId: string, + eventName: AudioEventName, + audioEventEmitter: AudioEventEmitter + ) { + this.subscriptionId = subscriptionId; + this.eventName = eventName; + this.audioEventEmitter = audioEventEmitter; + } + + public remove(): void { + this.audioEventEmitter.removeAudioEventListener( + this.eventName, + this.subscriptionId + ); + } +} +``` +
+ ### `PermissionStatus`
From d4fed04a85a1192f7a2c08e3b7d70e100f4acc2c Mon Sep 17 00:00:00 2001 From: michal Date: Mon, 26 May 2025 16:41:26 +0200 Subject: [PATCH 4/7] docs: added missing explanation and aligned with new impl --- .../audiodocs/docs/system/audio-manager.mdx | 56 +++++++++++++------ 1 file changed, 40 insertions(+), 16 deletions(-) diff --git a/packages/audiodocs/docs/system/audio-manager.mdx b/packages/audiodocs/docs/system/audio-manager.mdx index fc63a150..567d960f 100644 --- a/packages/audiodocs/docs/system/audio-manager.mdx +++ b/packages/audiodocs/docs/system/audio-manager.mdx @@ -75,13 +75,33 @@ Resets all of the lock screen data. #### Returns `undefined` -### `enableSystemEvent` +### `enableRemoteCommand` + +Enables emmition of some system events. + +| Parameters | Type | Description | +| :---: | :---: | :---- | +| `name` | [`RemoteCommandEventName`](/system/audio-manager#name--systemeventcallbackname--remotecommandeventname) | Name of an event | +| `enabled` | `boolean` | Indicates the start or the end of event emmition | + +#### Returns `undefined` + +:::info + +If you want to add callback upon hearing event, remember to call [`addSystemEventListener`](/system/audio-manager#addsystemeventlistener) +with proper parameters. + +::: + + +### `addSystemEventListener` + +Adds callback to be invoked upon hearing an event. | Parameters | Type | Description | | :---: | :---: | :---- | -| `name` | [`Name`](/system/audio-manager#name-systemeventcallbackname) | Name of an event listener | -| `callback` | [`SystemEventCallback`](/system/audio-manager#name-systemeventcallbackname) | Callback that will be invoked upon hearing an event | -| `enabled` | `boolean` (default value is `true`)| Can be used to enable or disable emmiting system event | +| `name` | [`Name`](/system/audio-manager#name--systemeventcallbackname--remotecommandeventname) | Name of an event listener | +| `callback` | [`SystemEventCallback`](/system/audio-manager#name--systemeventcallbackname--remotecommandeventname) | Callback that will be invoked upon hearing an event | #### Returns [`AudioEventSubscription`](/system/audio-manager#audioeventsubscription) if `enabled` is set to true, `undefined` otherwise @@ -169,9 +189,7 @@ interface SessionOptions {
-### `Name` `SystemEventCallback` - -TODO: description of what each of the name means +### `Name` | `SystemEventCallback` | `RemoteCommandEventName`
Type definitions @@ -191,24 +209,30 @@ interface OnRouteChangeEventType { reason: string; //cause of event emmition } -interface SystemEvents { +// visit https://developer.apple.com/documentation/mediaplayer/mpremotecommandcenter?language=objc +// for further info +interface RemoteCommandEvents { remotePlay: EventEmptyType; remotePause: EventEmptyType; remoteStop: EventEmptyType; - remoteTogglePlayPause: EventEmptyType; + remoteTogglePlayPause: EventEmptyType; // iOS only remoteChangePlaybackRate: EventTypeWithValue; remoteNextTrack: EventEmptyType; remotePreviousTrack: EventEmptyType; - remoteSkipForward: EventEmptyType; - remoteSkipBackward: EventEmptyType; - remoteSeekForward: EventTypeWithValue; - remoteSeekBackward: EventTypeWithValue; + remoteSkipForward: EventTypeWithValue; + remoteSkipBackward: EventTypeWithValue; // iOS only + remoteSeekForward: EventEmptyType; // iOS only + remoteSeekBackward: EventEmptyType; remoteChangePlaybackPosition: EventTypeWithValue; - volumeChange: EventTypeWithValue; - interruption: OnInterruptionEventType; - routeChange: OnRouteChangeEventType; } +type SystemEvents = RemoteCommandEvents & { + volumeChange: EventTypeWithValue; //triggered when volume level is changed + interruption: OnInterruptionEventType; //triggered when f.e. some app wants to play music when we are playing + routeChange: OnRouteChangeEventType; //change of output f.e. from speaker to headphones +}; + +type RemoteCommandEventName = keyof RemoteCommandEvents; type SystemEventName = keyof SystemEvents; type SystemEventCallback = ( event: SystemEvents[Name] From 5a9ddc64309fe6fc858107525d7243b8b885cb5e Mon Sep 17 00:00:00 2001 From: michal Date: Mon, 26 May 2025 17:06:20 +0200 Subject: [PATCH 5/7] fix: small typos --- packages/audiodocs/docs/system/audio-manager.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/audiodocs/docs/system/audio-manager.mdx b/packages/audiodocs/docs/system/audio-manager.mdx index 567d960f..5454e8b8 100644 --- a/packages/audiodocs/docs/system/audio-manager.mdx +++ b/packages/audiodocs/docs/system/audio-manager.mdx @@ -13,7 +13,7 @@ It provides a set of system-specific functions that are invoked directly in nati | Name | Type | Description | | :----: | :----: | :-------- | -| `audioEventEmitter` | `AudioEventEmitter` | Custom event emmiter that allows to create listener to events, that are invoked from a system. | +| `audioEventEmitter` | `AudioEventEmitter` | Custom event emiter that allows to create listener to events, that are invoked from a system. | ## Example @@ -77,12 +77,12 @@ Resets all of the lock screen data. ### `enableRemoteCommand` -Enables emmition of some system events. +Enables emition of some system events. | Parameters | Type | Description | | :---: | :---: | :---- | | `name` | [`RemoteCommandEventName`](/system/audio-manager#name--systemeventcallbackname--remotecommandeventname) | Name of an event | -| `enabled` | `boolean` | Indicates the start or the end of event emmition | +| `enabled` | `boolean` | Indicates the start or the end of event emition | #### Returns `undefined` @@ -206,7 +206,7 @@ interface OnInterruptionEventType { } interface OnRouteChangeEventType { - reason: string; //cause of event emmition + reason: string; //cause of event emition } // visit https://developer.apple.com/documentation/mediaplayer/mpremotecommandcenter?language=objc @@ -229,7 +229,7 @@ interface RemoteCommandEvents { type SystemEvents = RemoteCommandEvents & { volumeChange: EventTypeWithValue; //triggered when volume level is changed interruption: OnInterruptionEventType; //triggered when f.e. some app wants to play music when we are playing - routeChange: OnRouteChangeEventType; //change of output f.e. from speaker to headphones + routeChange: OnRouteChangeEventType; //change of output f.e. from speaker to headphones, events are always emitted! }; type RemoteCommandEventName = keyof RemoteCommandEvents; From cb700bcc616d326a415d8e17aac62be5bf7a5c48 Mon Sep 17 00:00:00 2001 From: michal Date: Tue, 27 May 2025 10:18:47 +0200 Subject: [PATCH 6/7] fix: typos --- .../audiodocs/docs/system/audio-manager.mdx | 24 +++++++------------ 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/packages/audiodocs/docs/system/audio-manager.mdx b/packages/audiodocs/docs/system/audio-manager.mdx index 5454e8b8..32394671 100644 --- a/packages/audiodocs/docs/system/audio-manager.mdx +++ b/packages/audiodocs/docs/system/audio-manager.mdx @@ -9,12 +9,6 @@ import { Optional, ReadOnly, OnlyiOS } from '@site/src/components/Badges'; The `AudioManager` is a layer of an abstraction between user and a system. It provides a set of system-specific functions that are invoked directly in native code, by related system. -## Properties - -| Name | Type | Description | -| :----: | :----: | :-------- | -| `audioEventEmitter` | `AudioEventEmitter` | Custom event emiter that allows to create listener to events, that are invoked from a system. | - ## Example ```tsx @@ -37,7 +31,7 @@ function App() { | Parameters | Type | Description | | :---: | :---: | :-----: | -| `info` | [`LockScreenInfo`](/system/audio-manager#lockscreeninfo) | Info to be displayed on lock screen | +| `info` | [`LockScreenInfo`](/system/audio-manager#lockscreeninfo) | Information to be displayed on the lock screen | #### Returns `undefined` @@ -51,7 +45,7 @@ Resets all of the lock screen data. | Parameters | Type | Description | | :---: | :---: | :---- | -| options | [`SessionOptions`](/system/audio-manager#sessionoptions) | Options to be set for session | +| options | [`SessionOptions`](/system/audio-manager#sessionoptions) | Options to be set for AVAudioSession | #### Returns `undefined` @@ -63,7 +57,7 @@ Resets all of the lock screen data. | Parameters | Type | Description | | :---: | :---: | :---- | -| `enabled` | `boolean` | Can be used to enable or disable observing audio interruptions | +| `enabled` | `boolean` | It is used to enable/disable observing audio interruptions | #### Returns `undefined` @@ -71,7 +65,7 @@ Resets all of the lock screen data. | Parameters | Type | Description | | :---: | :---: | :---- | -| `enabled` | `boolean` | Can be used to enable or disable observing volume changes | +| `enabled` | `boolean` | It is used to enable/disable observing volume changes | #### Returns `undefined` @@ -81,8 +75,8 @@ Enables emition of some system events. | Parameters | Type | Description | | :---: | :---: | :---- | -| `name` | [`RemoteCommandEventName`](/system/audio-manager#name--systemeventcallbackname--remotecommandeventname) | Name of an event | -| `enabled` | `boolean` | Indicates the start or the end of event emition | +| `name` | [`RemoteCommandEventName`](/system/audio-manager#systemeventname--remotecommandeventname) | Name of an event | +| `enabled` | `boolean` | Indicates the start or the end of event emission | #### Returns `undefined` @@ -100,8 +94,8 @@ Adds callback to be invoked upon hearing an event. | Parameters | Type | Description | | :---: | :---: | :---- | -| `name` | [`Name`](/system/audio-manager#name--systemeventcallbackname--remotecommandeventname) | Name of an event listener | -| `callback` | [`SystemEventCallback`](/system/audio-manager#name--systemeventcallbackname--remotecommandeventname) | Callback that will be invoked upon hearing an event | +| `name` | [`SystemEventName`](/system/audio-manager#systemeventname--remotecommandeventname) | Name of an event listener | +| `callback` | [`SystemEventCallback`](/system/audio-manager#systemeventname--remotecommandeventname) | Callback that will be invoked upon hearing an event | #### Returns [`AudioEventSubscription`](/system/audio-manager#audioeventsubscription) if `enabled` is set to true, `undefined` otherwise @@ -189,7 +183,7 @@ interface SessionOptions {
-### `Name` | `SystemEventCallback` | `RemoteCommandEventName` +### `SystemEventName` | `RemoteCommandEventName`
Type definitions From a47865c6bad31e9c5d60b63dd85f316e5bd489a6 Mon Sep 17 00:00:00 2001 From: michal Date: Tue, 27 May 2025 10:54:11 +0200 Subject: [PATCH 7/7] feat: extended examples --- .../audiodocs/docs/system/audio-manager.mdx | 65 ++++++++++++++++++- 1 file changed, 64 insertions(+), 1 deletion(-) diff --git a/packages/audiodocs/docs/system/audio-manager.mdx b/packages/audiodocs/docs/system/audio-manager.mdx index 32394671..7a277534 100644 --- a/packages/audiodocs/docs/system/audio-manager.mdx +++ b/packages/audiodocs/docs/system/audio-manager.mdx @@ -13,8 +13,16 @@ It provides a set of system-specific functions that are invoked directly in nati ```tsx import { AudioManager } from 'react-native-audio-api'; +import { useEffect } from 'react'; function App() { + // set AVAudioSession example options (iOS only) + AudioManager.setAudioSessionOptions({ + iosCategory: 'playback', + iosMode: 'default', + iosOptions: ['allowBluetooth', 'allowAirPlay'], + }) + // set info for track to be visible while device is locked AudioManager.setLockScreenInfo({ title: 'Audio file', @@ -22,6 +30,45 @@ function App() { album: 'Audio API', duration: 10, }); + + useEffect(() => { + + // enabling emission of events + AudioManager.enableRemoteCommand('remotePlay', true); + AudioManager.enableRemoteCommand('remotePause', true); + AudioManager.observeAudioInterruptions(true); + + // callback to be invoked on 'remotePlay' event + const remotePlaySubscription = AudioManager.addSystemEventListener( + 'remotePlay', + (event) => { + console.log('remotePlay event:', event); + } + ); + + // callback to be invoked on 'remotePause' event + const remotePauseSubscription = AudioManager.addSystemEventListener( + 'remotePause', + (event) => { + console.log('remotePause event:', event); + } + ); + + // callback to be invoked on 'interruption' event + const interruptionSubscription = AudioManager.addSystemEventListener( + 'interruption', + (event) => { + console.log('Interruption event:', event); + } + ); + + + return () => { + remotePlaySubscription?.remove(); + remotePauseSubscription?.remove(); + interruptionSubscription?.remove(); + }; + }, []); } ``` @@ -49,6 +96,14 @@ Resets all of the lock screen data. #### Returns `undefined` +### `setAudioSessionActivity` + +| Parameters | Type | Description | +| :---: | :---: | :---- | +| enabled | `boolean` | It is used to set/unset AVAudioSession activity | + +#### Returns promise of `boolean` type, which is resolved to `true` if invokation ended with success, `false` otherwise. + ### `getDevicePreferredSampleRate` #### Returns `number`. @@ -200,7 +255,15 @@ interface OnInterruptionEventType { } interface OnRouteChangeEventType { - reason: string; //cause of event emition + reason: + | 'Unknown' + | 'Override' + | 'CategoryChange' + | 'WakeFromSleep' + | 'NewDeviceAvailable' + | 'OldDeviceUnavailable' + | 'ConfigurationChange' + | 'NoSuitableRouteForCategory'; } // visit https://developer.apple.com/documentation/mediaplayer/mpremotecommandcenter?language=objc