Reference - Web SDK
Symbl Class
The Symbl class takes in an optional SymblConfig. If no config is passed, you must authenticate later using the init
method.
init(symblConfig: SymblConfig)
init(symblConfig: SymblConfig)
Validates and initializes Symbl with application configuration.
Example
const symbl = new Symbl();
symbl.init({
accessToken: '<Your Access Token>',
// appId: '<Your App ID>',
// appSecret: '<Your App Secret>',
})
createConnection(sessionId?: string, audioStream?: AudioStream)
createConnection(sessionId?: string, audioStream?: AudioStream)
Accepts an optional sessionId
and an optional instance of AudioStream.
Validates that sessionId
is unique and then opens a Symbl Streaming API WebSocket connection.
Returns an instance of StreamingAPIConnection.
Example
const symbl = new Symbl();
const connection = symbl.createConnection("abc123");
createAndStartNewConnection(options: StreamingAPIConnectionConfig, audioStream?: AudioStream)
createAndStartNewConnection(options: StreamingAPIConnectionConfig, audioStream?: AudioStream)
Accepts a required Connection Config object and an optional instance of AudioStream.
Opens a new connection and starts processing audio.
Returns an instance of StreamingAPIConnection.
Example
const symbl = new Symbl();
const connection = symbl.createAndStartNewConnection({
config: {
encoding: "OPUS"
}
});
subscribeToConnection(sessionId: string)
subscribeToConnection(sessionId: string)
Accepts a required Session ID to subscribe to.
Establishes a Subscribe API connection with session ID.
Returns an instance of SubscribeAPIConnection
Example
const symbl = new Symbl();
const connection = symbl.subscribeToConnection(sessionId);
Symbl.wait(time: number, unit: string = TimeUnit.MS)
Symbl.wait(time: number, unit: string = TimeUnit.MS)
Waits for provided amount of time in the supplied units (ms
, s
, min
).
Example
// Waits 5 seconds
await Symbl.wait(5000);
StreamingAPIConnection Class
The StreamingAPIConnection
class represents a Streaming API WebSocket connection. In most instances you would be interfacing with this class from the return variable on createConnection
or createAndStartNewConnection
. You can also import it from the Web SDK and use it separately: import { StreamingAPIConnection } from '@symblai/symbl-web-sdk';
. StreamingAPIConnection
inherits from the BaseConnection
base class.
connect()
connect()
Opens a Symbl Streaming API WebSocket connection. If already connected it logs a warning. Once connected, it sends out the connected
event.
Example
let connection = new StreamingAPIConnection();
connection.connect();
disconnect()
disconnect()
Disconnects from Symbl Streaming API WebSocket.
Example
connection.disconnect();
startProcessing(options: StreamingAPIConnectionConfig)
startProcessing(options: StreamingAPIConnectionConfig)
Accepts a required Connection Config.
Triggers the streaming connection to begin processing audio through Symbl websocket.
Example
connection.startProcessing({
config: {
encoding: "OPUS"
}
});
stopProcessing()
stopProcessing()
Triggers the streaming connection to stop processing audio through Symbl websocket. If disconnectOnStopRequest
is set to false
, the WebSocket enters a non-processing state which can be resumed later by calling startProcessing
again. If disconnectOnStopRequest
is not set or set to true
the WebSocket connection must be re-opened to start processing audio again.
Example
connection.stopProcessing()
on(eventName: EventTypes, callback: Function)
on(eventName: EventTypes, callback: Function)
Subscribe to an event and perform a callback when it's fired.
Checkout out our Events and Callbacks reference for more information.
Example
connection.on('connected', () => {
console.log('I am connected!');
})
modifySampleRate(sampleRateHertz: number)
modifySampleRate(sampleRateHertz: number)
Accepts a sample rate in hertz, such as 48000
.
Updates the sample rate mid-stream and sends out the session_modified
event.
Example
connection.modifySampleRate(48000);
getSessionId()
getSessionId()
Getter for the sessionId
.
Example
const sessionId = connection.getSessionId();
isProcessing()
isProcessing()
Returns true if the connection is processing audio.
Example
connection.isProcessing();
isConnected()
isConnected()
Returns true if connected to the WebSocket.
Example
connection.isConnected();
updateAudioStream(audioStream: AudioStream)
updateAudioStream(audioStream: AudioStream)
Accepts an AudioStream instance.
Replaces the existing audio stream with the one provided. Stops processing if currently processing audio.
Example
const audioStream = new OpusAudioStream();
connection.updateAudioStream(audioStream);
SubscribeAPIConnection Class
The SubscribeAPIConnection
class represents a Subscribe API WebSocket connection. In most instances you would be interfacing with this class from the return variable on subscribeToConnection
. You can also import it from the Web SDK and use it separately: import { SubscribeAPIConnection } from '@symblai/symbl-web-sdk';
. SubscribeAPIConnection
inherits from the BaseConnection
base class.
connect()
connect()
Opens a Symbl Subscribe API WebSocket connection. If already connected it logs a warning. Once connected, it sends out the connected
event.
Example
let connection = new StreamingAPIConnection(id, audioStream);
connection.connect();
disconnect()
disconnect()
Disconnects from the Symbl Subscribe API WebSocket.
Example
connection.disconnect();
on(eventName: EventTypes, callback: Function)
on(eventName: EventTypes, callback: Function)
Subscribe to an event and perform a callback when it's fired.
Example
connection.on('connected', () => {
console.log('I am connected!');
})
isConnected()
isConnected()
Returns true if connected to the WebSocket.
Example
connection.isConnected();
AudioStream Class
LINEAR16AudioStream
and OpusAudioStream
both inherit from the AudioStream
base class, so their usage is identical. The main difference is LINEAR16AudioStream
is meant to be paired with the LINEAR16
encoding type, and the OpusAudioStream
is meant to be paired with the OPUS
encoding type.
attachAudioDevice(deviceId: string, mediaStream: MediaStream)
attachAudioDevice(deviceId: string, mediaStream: MediaStream)
Accepts an optional deviceId and an optional MediaStream. If no deviceId
is passed, the default device is used.
Attaches audio device either through default browser method creating a MediaStream or via a passed in MediaStream
Example
audioStream.attachAudioDevice("my-device-id");
detachAudioDevice()
detachAudioDevice()
Disconnects processor to cleanly detach the audio input device.
Example
audioStream.detachAudioDevice();
updateAudioDevice(deviceId: string, mediaStream: MediaStream)
updateAudioDevice(deviceId: string, mediaStream: MediaStream)
Accepts an optional deviceId and an optional MediaStream. If no deviceId
is passed, the default device is used.
Updates the audio device in use by the audio stream.
Example
audioStream.updateAudioDevice("my-device-id");
Make sure to use the appropriate DOM element type for
SourceElement
functions. Source elements include HTMLVideoElement and HTMLAudioElement.
attachAudioSourceElement(audioSourceDomElement)
attachAudioSourceElement(audioSourceDomElement)
Accepts a required HTMLAudioElement or HTMLSourceElement. A type
with the Content-Type is required and the src
attribute is also required. The src
attribute can be a URL or a Blob
Attaches an audio element to the processor and starts processing audio data from the audio file. In order to start processing you need to call .play()
on the audio element. We recommend doing this after the processing_started
Event has been fired.
Example
// Authenticate with Symbl
const symbl = new Symbl({
accessToken: "< MY ACCESS TOKEN >"
});
// Create your audio element
const myAudioElement = new Audio();
myAudioElement.type = "audio/mp3";
myAudioElement.src = "link-to-file.mp3";
// Attach audio element to AudioStream
const audioStream = new LINEAR16AudioStream();
audioStream.attachAudioSourceElement(myAudioElement);
// Create connection and start processing audio
const connection = symbl.createConnection("abc123", audioStream);
connection.startProcessing({
config: {
encoding: "LINEAR16"
}
});
// Play the element once audio is ready to be processed.
connection.on("processing_started", () => {
myAudioElement.play();
});
detachAudioSourceElement()
detachAudioSourceElement()
Disconnects processor to cleanly detach the audio source element.
Example
audioStream.detachAudioSourceElement();
updateAudioSourceElement(audioSourceDomElement)
updateAudioSourceElement(audioSourceDomElement)
Accepts a required HTMLAudioElement or HTMLSourceElement. A type
with the Content-Type is required and the src
attribute is also required. The src
attribute can be a URL or a Blob
Updates the audio element attached to the audio stream.
Example
audioStream.updateAudioSourceElement(myAudioElement);
attachVideoSourceElement(videoSourceDomElement)
attachVideoSourceElement(videoSourceDomElement)
Accepts a required HTMLVideoElement or HTMLSourceElement. A type
with the Content-Type is required and the src
attribute is also required. The src
attribute can be a URL or a Blob
Attaches a video element to the processor and starts processing audio data from the video file. To start processing you need to call .play()
on the video element. Symbl recommends doing this after the processing_started
event has been fired.
Example
// Authenticate with Symbl
const symbl = new Symbl({
accessToken: "< MY ACCESS TOKEN >"
});
// Create your audio element
const myVideoElement = document.createElement("video");
myVideoElement.type = "video/mp4";
myVideoElement.src = "link-to-file.mp4";
// Attach audio element to AudioStream
const audioStream = new LINEAR16AudioStream();
audioStream.attachVideoSourceElement(myVideoElement);
// Create connection and start processing audio
const connection = symbl.createConnection("abc123", audioStream);
connection.startProcessing({
config: {
encoding: "LINEAR16"
}
});
// Play the element once audio is ready to be processed.
connection.on("processing_started", () => {
myAudioElement.play();
});
detachVideoSourceElement()
detachVideoSourceElement()
Disconnects the processor to cleanly detach the video source element.
Example
audioStream.detachVideoSourceElement();
updateVideoSourceElement(videoSourceDomElement)
updateVideoSourceElement(videoSourceDomElement)
Accepts a required HTMLVideoElement or HTMLSourceElement. A type
with the Content-Type is required and the src
attribute is also required. The src
attribute can be a URL or a Blob
Updates the video element attached to the audio stream.
Example
audioStream.updateVideoSourceElement(myVideoElement);
Updated 4 months ago