SFSAudioManager

Manages the client-side Audio Streaming System.

This manager tracks the state of the client audio streaming. It also gives access to the list of capture and playback audio devices, allowing to set the active divices.

Note that all audio features require a secure context (HTTPS or http://localhost / 127.0.0.1) to work, as per web platform rules; a browser supporting Opus encoding/decoding of audio data is also required.

See

Members

captureDevice :AudioDevice

Device used to capture audio data to be transmitted to other clients.

If a specific device is not selected, the system default device is used.

Type:

(readonly) hasUserPermission :boolean

Indicates whether the user has granted permission to access the audio capture device.

Permission is requested by means of the requestUserPermission method and is mandatory before starting an audio stream. On browsers that support live permission tracking, this value reflects a later revocation; otherwise it stays true once the permission has been granted.

Type:
  • boolean

(readonly) isMuted :boolean

Indicates whether the current client is muted and no audio data is transmitted.
Type:
  • boolean

playbackDevice :AudioDevice

Device used to playback audio data transmitted by other clients or the server itself.

If a specific device is not selected, the system default device is used.

Note: selecting a specific output device relies on AudioContext.setSinkId, which may not be available on all browsers. If this setter is called on browsers without support, the selection is not applied nor stored, and playback stays on the system default output device.

Type:

Methods

getAudioStreamInfo(userId) → {AudioStreamInfo}

Retrieves an AudioStreamInfo object by its owner id.
Parameters:
NameTypeDescription
userIdnumberThe id of the User owning the audio stream.
Returns:
An object representing the requested audio stream; null if no AudioStreamInfo object with the passed id can be found.
Type: 
AudioStreamInfo

(async) getDevices() → {Promise.<AudioDevices>}

Returns a collection of AudioDevice objects, grouped by role (capture or playback devices), representing the devices available in the system.

This method is accessible after the Audio Streaming System is initialized and the permission to access audio devices is granted by the user (see requestUserPermission method).

Throws:
  • Error if context is not secure (HTTPS, or http://localhost).
    Type
    SFSError
  • Error if browser doesn't support Opus encoding/decoding of audio data.
    Type
    SFSError
  • User permission to access audio device was not granted, or grant request failed. For detailed information check the type and message of the nested Error returned by the cause property.
    Type
    SFSError
Returns:
A collection of audio devices, grouped by role (capture or playback).
Type: 
Promise.<AudioDevices>

isStreaming(userId) → {boolean}

Indicates whether the client is currently transmitting an audio stream.
Parameters:
NameTypeDescription
userIdnumberThe id of the User owning the audio stream.
Returns:
true if the client is currently streaming audio in any Room.
Type: 
boolean

isStreamingInRoom(room) → {boolean}

Indicates whether the client is currently transmitting an audio stream in a specific Room.
Parameters:
NameTypeDescription
roomSFSRoomThe object representing the Room where to check if the client is currently streaming audio.
Returns:
true if the client is currently streaming audio in the passed Room.
Type: 
boolean

(async) requestUserPermission()

Prompts user to grant permission to access the audio input device.

This method triggers the default browser's prompt for access to media inputs. It should be called as a consequence of a user gesture (for example click on a 'settings' button to access the list of audio devices, or click on a 'start stream' button right before starting audio capture from microphone) and it is mandatory before requesting to start an audio stream or accessing the list of audio devices. An error is thrown otherwise.

Throws:
  • Error if context is not secure (HTTPS, or http://localhost).
    Type
    SFSError
  • Error if browser doesn't support Opus encoding/decoding of audio data.
    Type
    SFSError
  • User permission to access audio device was not granted, or grant request failed. For detailed information check the type and message of the nested Error returned by the cause property.
    Type
    SFSError