@amazon-devices/keplerscript-audio-lib

The Vega Audio Interface API provides functionality for managing audio in apps. It consists of several key components:

Audio Manager: Handles system-level audio controls like volume, mute, and device management.
Audio Playback: Enables audio stream playback with configurable attributes.
Audio Focus Management: Manages audio focus for different audio streams.

The API is designed to work with React Native for Vega apps and provides a foundation for building audio-enabled apps with features such as:

Volume and mute control for different audio types
Audio device management
System sound management
Audio focus handling
Audio stream configuration and management

Get started

Setup

Add the following library dependency to the dependencies section of your package.json file.

    "@amazon-devices/keplerscript-audio-lib": "~2.0.18"

Add the following privilege and services request in your manifest.toml.

[[needs.privilege]]
id = "com.amazon.audio.privilege.microphone.access" 

[wants]

// only add the services that are needed
[[wants.service]]
id = "com.amazon.audio.stream" // For performing audio playback with the AudioStream API.
[[wants.service]]
id = "com.amazon.audio.control" // For AudioManager, AudioFocus APIs usage.
[[wants.service]]
id = "com.amazon.audio.system" // For playing brief sounds with low latency using SoundPlayer or SystemSound APIs.

For more information on the needs section of the manifest file, see Manifest needs Section.

Usage

Import the KeplerAudioInterface turbo module into your project.

import { 
    AudioManager,
    AudioPlaybackStream,
    AudioPlaybackStreamBuilder,
    AudioFocusManager,
    AudioFocusSession
} from '@amazon-devices/keplerscript-audio-lib';

Audio

Manage Audio Volume

// Set volume for media
await AudioManager.setVolumeAsync(AudioVolumeType.VOLUME_TYPE_MEDIA, 75, AudioVolumeFlags.VOLUME_FLAG_SHOW_UI);

// Get current volume
const volume = await AudioManager.getVolumeAsync(AudioVolumeType.VOLUME_TYPE_MEDIA);

Create and Manage audio playback

// Create a playback stream
const builder = new AudioPlaybackStreamBuilder();
builder.setAudioConfig({
    sampleRate: AudioSampleRate.SAMPLE_RATE_44_1_KHZ,
    channelMask: AudioChannelMask.CHANNEL_STEREO,
    format: AudioSampleFormat.FORMAT_PCM_16_BIT
});
builder.setAudioAttributes({
    contentType: AudioContentType.CONTENT_TYPE_MUSIC,
    usage: AudioUsageType.USAGE_MEDIA,
    flags: AudioFlags.FLAG_NONE
});

const playbackStream = await builder.buildAsync();
await playbackStream.startAsync();

Managing audio focus

// Create and request audio focus
const focusSession = await AudioFocusManager.createAudioFocusSessionAsync();
await focusSession.requestAudioFocusAsync({
    usage: AudioUsageType.USAGE_MEDIA
});

// Register for focus changes
await focusSession.registerAudioFocusListenerAsync((focusChange) => {
    console.log('Focus changed:', focusChange);
});

Event Observers

Audio Manager events

// Register for system-wide audio events
await AudioManager.registerAudioEventObserverAsync((event) => {
    // Event object will contain different properties based on the event type
    switch (event.audioEvent) {
        case AudioEvent.DEVICE_STATE_UPDATE:
            // Triggered when an audio device's connection state changes
            // Parameters:
            // - device: AudioDevice enum value
            // - role: AudioRole enum value
            // - connect: boolean indicating if device was connected (true) or disconnected (false)
            console.log(`Device ${event.device} with role ${event.role} ${event.connect ? 'connected' : 'disconnected'}`);
            break;

        case AudioEvent.VOLUME_UPDATE:
            // Triggered when volume changes for any audio type
            // Parameters:
            // - type: AudioVolumeType enum value
            // - volume: number (0-100)
            console.log('Volume changed for:', event.type, 'to:', event.volume);
            break;

        case AudioEvent.GLOBAL_VOLUME_MUTE_UPDATE:
            // Triggered when global mute state changes
            // Parameters:
            // - mute: boolean indicating if system is muted
            console.log('Global mute updated to state: ', event.mute);
            break;

        case AudioEvent.SERVER_DOWN:
            // Triggered when audio server becomes unavailable
            console.log('Audio server is down');
            break;

        case AudioEvent.SERVER_UP:
            // Triggered when audio server becomes available
            console.log('Audio server is up');
            break;

        case AudioEvent.AUDIO_USAGE_STATE_CHANGE:
            // Triggered when audio usage state changes
            // Parameters:
            // - usage: AudioUsageType enum value
            // - active: boolean indicating if usage became active
            console.log('Usage: ', event.usage);
            console.log('Active status: ', event.active);
            break;

        case AudioEvent.MIC_MUTE_STATE_UPDATE:
            // Triggered when microphone mute state changes
            // Parameters:
            // - state: boolean indicating if mic is muted
            console.log('Mic mute state changed: ', event.muteState);
            break;

        case AudioEvent.VOLUME_MUTE_UPDATE:
            // Triggered when volume mute state changes for specific volume type
            // Parameters:
            // - volumeType: AudioVolumeType enum value
            // - mute: boolean indicating if type is muted
            console.log('Volume type: ', event.volumeType);
            console.log('Mute state: ', event.muteState);
            break;

        case AudioEvent.TELEPHONY_MUTE_UPDATE:
            // Triggered when telephony mute state changes
            // Parameters:
            // - deviceType: AudioDevice enum value
            // - address: string representing device address
            // - deviceName: string representing device name
            // - mute: boolean indicating if telephony is muted
            console.log('Telephony mute update!: ');
            console.log('Device type: ', event.deviceType);
            console.log('Device address: ', event.deviceAddress);
            console.log('Device name: ', event.deviceName);
            console.log('Device mute state: ', event.muteState);
            break;
    }
});

// Cleanup
await AudioManager.unregisterAudioEventObserverAsync();

Playback a stream

const playbackStream = await builder.buildAsync();

await playbackStream.registerEventObserverAsync((event) => {
    switch (event.type) {
        case AudioPlaybackEvent.DIED:
            // Triggered when the playback stream becomes unavailable
            break;

        case AudioPlaybackEvent.RECOVERED:
            // Triggered when the playback stream recovers from a died state
            break;

        case AudioPlaybackEvent.STOPPED:
            // Triggered when the playback stream stops
            break;

        case AudioPlaybackEvent.MUTE_STATE_UPDATE:
            // Triggered when the stream's mute state changes
            // Parameters:
            // - muted: boolean indicating if stream is muted
            console.log('MuteState: ', event.muteState);
            break;

        case AudioPlaybackEvent.FRAME_UNDERRUN:
            // Triggered when a buffer underrun occurs
            // Parameters:
            // - size: number indicating the underrun size in frames
            console.log('Underrun count: ', event.underrunCount);
            break;
    }
});

// Cleanup
await playbackStream.unregisterEventObserverAsync();

Audio focus

const focusSession = await AudioFocusManager.createAudioFocusSessionAsync();

await focusSession.registerAudioFocusListenerAsync((focusChange) => {
    switch (focusChange.type) {
        case AudioFocusChange.GRANTED:
            // Triggered when audio focus is granted
            break;

        case AudioFocusChange.RELEASED:
            // Triggered when audio focus is released
            break;

        case AudioFocusChange.DUCKED:
            // Triggered when audio should be ducked (reduced in volume)
            break;

        case AudioFocusChange.PAUSED:
            // Triggered when audio should be paused
            break;

        case AudioFocusChange.STOPPED:
            // Triggered when audio should be stopped
            break;
    }
});

// Cleanup
await focusSession.unregisterAudioFocusListenerAsync();

Troubleshooting

Permission issues:
1. Error: No Permission exception
2. Solution: Make sure that you have declared the required privileges in your manifest.toml.
AudioManager not created:
1. Error: getAudioManager() returns undefined
2. Solution: Make sure that you have properly set up the KeplerAudioInterface Turbo Module is properly in your app environment.
Invalid Observer or callback:
1. Error: “not invoking Callback”
2. Solution: Make sure that you are correctly subscribing to the Observers.
Unsubscription failures:
1. Error: Unsubscribe rejection
2. Solution: Check that you’re using the correct observer object and that it isn’t already being used to unsubscribe.

Support

For specific issues or bugs, please contact the Audio development support team.

API Reference

Classes

AudioAttributes — Determines the audio attributes to build the audio playback stream with, affects things like content type, usage, and flags.
AudioConfig — Determines the audio configuration to build the audio playback stream with, affects things like audio sample rate, and format.
AudioConfigAttr — AudioConfig to retrieve the supported configurations
AudioDeviceInfo — Data type that contains the description of an audio device
AudioFocusAttributes — AudioFocusAttributes used while requesting AudioFocus
AudioFocusManager — Audio Focus Manager allows the creation and destruction of Audio Focus Sessions.
AudioFocusSession — Audio Focus Session allows audio focus management such as requesting audio focus and
AudioManager — Audio Manager allows audio management such as volume adjustment and mute control.
AudioPlaybackStream — Audio Playback Stream allows for control of playback streams such as pausing,
AudioPlaybackStreamBuilder — Audio Playback Stream Builder allows for the configuration, creation, and destruction
AudioRecordStream
AudioRecordStreamBuilder — ## Required Privileges
AudioTheme — AudioTheme object
SinkPolicies — SinkPolicies object

Enumerations

AudioChannelMask — Enum for Audio Channel Mask
AudioContentType — Enum for audio content type
AudioDevice — Available audio devices to be used
AudioEvent — Enum for Audio Event
AudioFadeType — Audio fade curve types for volume transitions.
AudioFlags — Enum for Audio Flags
AudioFocusChange — Each value represents a different type of audio focus change event that can occur,
AudioFocusStatus — Represents different statuses that can occur when an audio focus call is made.
AudioPlaybackEvent — Possible playback events used by the playback builder
AudioRecordEvent — Enum for Audio Record Event
AudioRole — The possible role of an audio device
AudioSampleFormat — Enum for Audio Sample Format
AudioSampleRate — Enum for Audio Sample Rate
AudioSource — Possible audio sources
AudioStatus — Enum for audio status code.
AudioSystemSound — Available system sound types to be used
AudioTelephonyMode — Available Telephony modes
AudioUsageType — Enum for Audio Usage Types
AudioVolumeFlags — Each value represents a different type of audio volume flag. If SHOW_UI is set, a separate
AudioVolumeType — Each value represents a different volume type like media, voice call, navigation, etc.
DuckingMode — Struct whose value field is used to signify the Audio Ducking Mode
SampleLayout — Enum to indicate the Audio Sample Layout
SinkFormatsSelectionPolicy — Struct whose value field is used to signify the User Audio Mode for HDMI output
StreamDuckingPolicy — Available audio ducking policies
VolumeUpdate — Enum used for the Audio Volume Update Type

​Get started

​Setup

​Usage

​Audio

​Event Observers

​Troubleshooting

​Support

​API Reference

​Classes

​Enumerations