@streampixel/web-sdk/voice. A page that does not import it downloads no chat code. The SDK draws no chat interface: it gives you methods and events, and you draw the people, the messages and the buttons.
npm only. The script-tag build does not include chat.
Before you start
- Turn chat on for the project in the dashboard: Built-in voice and text chat. While it is off,
stream.voiceTokenisundefinedandVoiceChat.for()rejects. - You need a running stream: chat is created from a
streamobject. See Quick start. - If your site sends a Content-Security-Policy, allow the chat server. See Content-Security-Policy.
Add chat to your page
1
Install the package
Chat is in the package you already have. There is nothing extra to install.
2
Create the chat for a stream
VoiceChat.for() loads the chat code and prepares the chat. It does not connect yet.3
Listen, then join
Attach your listeners first, so you see the first list of people. Then call
join().roster fires with yourself as localParticipant. Open the page in a second browser: each page sees the other in remoteParticipants.4
Turn the microphone on from a button
The microphone starts off. Turn it on when the viewer asks for it. The browser shows its permission prompt the first time.
roomId for a separate room inside the project’s room.
When the stream ends, the chat leaves the room by itself.
A complete example
A complete example
A page with a list of people, a message list, a text field and a microphone button. It leaves out styling and the error handling around
Streampixel.create().chat.ts
VoiceChat.for(stream, options)
Returns a Promise of the chat object. It rejects when the project has chat off, and with an EngineLoadError when the chat code cannot be loaded.
The stream this chat belongs to. The chat uses the stream’s project and its chat token.
Methods
Events
A chat message arrived, or you sent one.
from is the sender’s id, or 'You' for your own message.Someone joined or left, started or stopped speaking, or changed microphone or camera. Redraw your list of people from it.
The microphone or camera could not be opened.
message is a short sentence: permission denied, no device found, or the device is in use by another app. name is the browser’s error name.localParticipant is null when you are not in the room.
Showing a participant's camera
Showing a participant's camera
videoTrack is the track object of the chat library (LiveKit). The SDK types it as unknown, so cast it. This is a pattern: test it in your page.Sound from the other participants
Sound from the other participants
Remote audio plays by itself: you do not attach audio elements. Browsers block sound until the viewer interacts with the page, so the SDK starts the audio on the viewer’s first click, tap or key press.
What the SDK sets for you
What the SDK sets for you
The capture sizes are small on purpose, so that sending a camera does not take bandwidth from the stream.
Chat the app asks for
Some apps put the viewer into chat themselves, by sending acomms message. The SDK does not join by itself: listen for the message and join.
The app sends { "message": { "type": "comms", "value": { "roomId": "...", "name": "..." } } } to join a room, and "value": "disconnect" to leave.
Chat in a shared session
Chat works the same for the host and the viewers of a shared session. Each page creates its own chat from its own stream.Content-Security-Policy
Chat connects to the chat server on LiveKit Cloud. If your site sends a Content-Security-Policy, add this toconnect-src:
script-src needs nothing extra. The full list is in Installation.
Troubleshooting
VoiceChat.for() rejects: the project has chat disabled
VoiceChat.for() rejects: the project has chat disabled
The project’s chat is off, so the ticket carried no chat token. Turn chat on in the dashboard, then start a new stream. Check
stream.voiceToken before you call VoiceChat.for().VoiceChat.for() rejects with EngineLoadError
VoiceChat.for() rejects with EngineLoadError
The chat code could not be downloaded or verified. It is loaded like the stream engine, in the same version as the stream’s engine. See the reasons in Errors and disconnects.
join() rejects
join() rejects
The platform refused the chat token, or the chat server could not be reached. Check your Content-Security-Policy first. On a dedicated or on-premises deployment, pass
platformHost to VoiceChat.for(): it is not taken from the stream.toggleMic(true) resolves to false
toggleMic(true) resolves to false
The browser did not give the microphone: the viewer refused the prompt, there is no device, or another app is using it. The
deviceError event says which. toggleMic() also resolves to false before join().I hear nobody until I click
I hear nobody until I click
Browsers block sound until the viewer interacts with the page. The SDK starts the audio on the first click, tap or key press.
I use the script-tag build
I use the script-tag build
Chat is not in the script-tag build. Install the package with npm and use a bundler.
Next steps
Shared sessions
One app for many people: the natural place for chat.
Talk to your Unreal app
Messages between your page and the app, such as
comms.The engine and updates
One level up: how the stream engine and the chat code are loaded and verified.
Stream API
Reference:
voiceToken and everything else on the stream object.