Documentation

Class: LocalAudioTrack

LocalAudioTrack

A LocalAudioTrack is an AudioTrack representing audio that your LocalParticipant can publish to a Room. It can be enabled and disabled with LocalAudioTrack#enable and LocalAudioTrack#disable or stopped completely with LocalAudioTrack#stop.

new Twilio.Video.LocalAudioTrack(mediaStreamTrack [, options])

Construct a LocalAudioTrack from a MediaStreamTrack.

Parameters:
Name Type Argument Description
mediaStreamTrack MediaStreamTrack

An audio MediaStreamTrack
options LocalTrackOptions <optional>

LocalTrack options
Properties:
Name Type Argument Description
id Track.ID

The LocalAudioTrack's ID
isMuted boolean

Whether or not the audio source has stopped sending samples to the LocalAudioTrack; This can happen when the microphone is taken over by another application, mainly on mobile devices; When this property toggles, then muted and unmuted events are fired appropriately
isStopped boolean

Whether or not the LocalAudioTrack is stopped
noiseCancellation NoiseCancellation <nullable>

When a LocalAudioTrack is created with NoiseCancellationOptions, this property provides interface to enable or disable the noise cancellation at runtime.
Fires:

Extends

Methods

attach()

Create an HTMLAudioElement and attach the AudioTrack to it.

The HTMLAudioElement's srcObject will be set to a new MediaStream containing the AudioTrack's MediaStreamTrack.

Inherited From:
Overrides:
Returns:

audioElement

Type
HTMLAudioElement
Example
const Video = require('twilio-video');

Video.createLocalAudioTrack().then(function(audioTrack) {
  const audioElement = audioTrack.attach();
  document.body.appendChild(audioElement);
});

detach()

Detach the AudioTrack from all previously attached HTMLMediaElements.

Inherited From:
Overrides:
Returns:

mediaElements

Type
Array.<HTMLMediaElement>
Example
const mediaElements = audioTrack.detach();
mediaElements.forEach(mediaElement => mediaElement.remove());

disable()

Disable the LocalAudioTrack. This is equivalent to muting the audio source.

Fires:
Returns:
Type
this

enable()

Enable the LocalAudioTrack. This is equivalent to unmuting the audio source.

Fires:
Returns:
Type
this

enable( [enabled])

Enable or disable the LocalAudioTrack. This is equivalent to unmuting or muting the audio source respectively.

Parameters:
Name Type Argument Description
enabled boolean <optional>

Specify false to disable the LocalAudioTrack
Fires:
Returns:
Type
this

restart( [constraints])

Restart the LocalAudioTrack. This stops the existing MediaStreamTrack and creates a new MediaStreamTrack. If the LocalAudioTrack is being published to a Room, then all the RemoteParticipants will start receiving media from the newly created MediaStreamTrack. You can access the new MediaStreamTrack via the mediaStreamTrack property. If you want to listen to events on the MediaStreamTrack directly, please do so in the "started" event handler. Also, the LocalAudioTrack's ID is no longer guaranteed to be the same as the underlying MediaStreamTrack's ID.

Parameters:
Name Type Argument Description
constraints MediaTrackConstraints <optional>

The optional MediaTrackConstraints for restarting the LocalAudioTrack; If not specified, then the current MediaTrackConstraints will be used; If {} (empty object) is specified, then the default MediaTrackConstraints will be used
Fires:
Returns:

Rejects with a TypeError if the LocalAudioTrack was not created using an one of createLocalAudioTrack, createLocalTracks or connect; Also rejects with the DOMException raised by getUserMedia when it fails

Type
Promise.<void>
Example
const { connect, createLocalAudioTrack } = require('twilio-video');

// Create a LocalAudioTrack that captures audio from a USB microphone.
createLocalAudioTrack({ deviceId: 'usb-mic-id' }).then(function(localAudioTrack) {
  return connect('token', {
    name: 'my-cool-room',
    tracks: [localAudioTrack]
  });
}).then(function(room) {
  // Restart the LocalAudioTrack to capture audio from the default microphone.
  const localAudioTrack = Array.from(room.localParticipant.audioTracks.values())[0].track;
  return localAudioTrack.restart({ deviceId: 'default-mic-id' });
});

stop()

Calls stop on the underlying MediaStreamTrack. If you choose to stop a LocalAudioTrack, you should unpublish it after stopping.

Fires:
Returns:
Type
this

Events

disabled

The LocalAudioTrack was disabled, i.e. the audio source was muted by the user.

Parameters:
Name Type Description
track LocalAudioTrack

The LocalAudioTrack that was disabled
Overrides:

enabled

The LocalAudioTrack was enabled, i.e. the audio source was unmuted by the user.

Parameters:
Name Type Description
track LocalAudioTrack

The LocalAudioTrack that was enabled
Overrides:

muted

The LocalAudioTrack was muted because the audio source stopped sending samples, most likely due to another application taking said audio source, especially on mobile devices.

Parameters:
Name Type Description
track LocalAudioTrack

The LocalAudioTrack that was muted

started

The LocalAudioTrack started. This means there is enough audio data to begin playback.

Parameters:
Name Type Description
track LocalAudioTrack

The LocalAudioTrack that started
Overrides:

stopped

The LocalAudioTrack stopped, either because LocalAudioTrack#stop or LocalAudioTrack#restart was called or because the underlying MediaStreamTrack ended.

Parameters:
Name Type Description
track LocalAudioTrack

The LocalAudioTrack that stopped

unmuted

The LocalAudioTrack was unmuted because the audio source resumed sending samples, most likely due to the application that took over the said audio source has released it back to the application, especially on mobile devices. This event is also fired when LocalAudioTrack#restart is called on a muted LocalAudioTrack with a new audio source.

Parameters:
Name Type Description
track LocalAudioTrack

The LocalAudioTrack that was unmuted