livekit-client
    TypeScript icon, indicating that this package has built-in type declarations

    0.13.1 • Public • Published

    JavaScript/TypeScript client SDK for LiveKit

    livekit-client is the official client SDK for LiveKit. With it, you can add real time video and audio to your web apps.

    Docs

    Docs and guides at https://docs.livekit.io

    Installation

    Yarn

    yarn add livekit-client
    

    NPM

    npm install livekit-client --save
    

    Usage

    Examples below are in TypeScript, if using JS/CommonJS imports replace import with:

    const LiveKit = require('livekit-client');
    
    LiveKit.connect(...);

    Connecting to a room, publish video & audio

    import {
      connect,
      RoomEvent,
      RemoteParticipant,
      RemoteTrackPublication,
      RemoteTrack,
      Participant,
    } from 'livekit-client';
    
    connect('ws://localhost:7800', token, {
      audio: true,
      video: true,
    }).then((room) => {
      console.log('connected to room', room.name);
      console.log('participants in room:', room.participants.size);
    
      room
        .on(RoomEvent.TrackSubscribed, handleTrackSubscribed)
        .on(RoomEvent.TrackUnsubscribed, handleTrackUnsubscribed)
        .on(RoomEvent.ActiveSpeakersChanged, handleActiveSpeakerChange)
        .on(RoomEvent.Disconnected, handleDisconnect);
    });
    
    function handleTrackSubscribed(
      track: RemoteTrack,
      publication: RemoteTrackPublication,
      participant: RemoteParticipant
    ) {
      if (track.kind === Track.Kind.Video || track.kind === Track.Kind.Audio) {
        // attach it to a new HTMLVideoElement or HTMLAudioElement
        const element = track.attach();
        parentElement.appendChild(element);
      }
    }
    
    function handleTrackUnsubscribed(
      track: RemoteTrack,
      publication: RemoteTrackPublication,
      participant: RemoteParticipant
    ) {
      // remove tracks from all attached elements
      track.detach();
    }
    
    function handleActiveSpeakerChange(speakers: Participant[]) {
      // show UI indicators when participant is speaking
    }
    
    function handleDisconnect() {
      console.log('disconnected from room');
    }

    In order to connect to a room, you need to first create an access token.

    See access token docs for details

    Manually publish, mute, unpublish

    When a video track is muted, the camera indicator will be turned off. When the video is unmuted, the same camera source and capture settings will be re-aquired.

    import { createLocalVideoTrack } from 'livekit-client';
    
    const videoTrack = await createLocalVideoTrack();
    
    const publication = await room.localParticipant.publishTrack(videoTrack, {
      name: 'mytrack',
      simulcast: true,
    });
    
    videoTrack.mute();
    
    room.localParticipant.unpublishTrack(videoTrack);

    Audio playback

    Browsers can be restrictive with regards to audio playback that is not initiated by user interaction. What each browser considers as user interaction can vary by vendor (for example, Safari on iOS is very restrictive).

    LiveKit will attempt to autoplay all audio tracks when you attach them to audio elements. However, if that fails, we'll notify you via RoomEvent.AudioPlaybackStatusChanged. Room.canPlayAudio will indicate if audio playback is permitted. LiveKit takes an optimistic approach so it's possible for this value to change from true to false when we encounter a browser error.

    In the case user interaction is required, LiveKit provides Room.startAudio to start audio playback. This function must be triggered in an onclick or ontap event handler. In the same session, once audio playback is successful, additional audio tracks can be played without further user interactions.

    room.on(RoomEvent.AudioPlaybackStatusChanged, () => {
      if (!room.canPlayAudio) {
        // UI is necessary.
        ...
        button.onclick = () => {
          // this function *must* be triggered in an click/tap handler.
          room.startAudio().then(() => {
            // successful, UI can be removed now
            button.remove();
          });
        }
      }
    });

    Screen share

    On desktop browsers, you may also share your screen with others. Refer to browser compatibility.

    Audio capture is supported only a subset of desktop browsers.

    const tracks = await createLocalScreenTracks({
      // set to true in order to capture audio
      audio: true,
      // defaults to 1080p
      resolution: VideoPresets.fhd.resolution,
    });
    
    tracks.forEach((track) => {
      // publish video and audio of the screenshare
      room.localParticipant.publishTrack(track);
    });

    Switching input devices

    At any point after publishing, you can switch the input devices and other capture settings on both audio and video tracks. For example, switching between regular and selfie camera or changing microphone inputs. This is performed with restartTrack on the LocalAudioTrack or LocalVideoTrack.

    await room.localParticipant.publishTrack(videoTrack);
    await room.localParticipant.publishTrack(audioTrack);
    
    await videoTrack.restartTrack({
      facingMode: 'environment',
    });
    await audioTrack.restartTrack({
      deviceId: 'microphoneId',
    });

    Configuring logging

    This library uses loglevel for its internal logs. You can change the effective log level with the logLevel field in ConnectOptions.

    Examples

    SDK Sample

    example/sample.ts contains a demo webapp that uses the SDK. Run it with yarn sample

    Browser Support

    Browser Desktop OS Mobile OS
    Chrome Windows, macOS, Linux Android
    Firefox Windows, macOS, Linux Android
    Safari macOS iOS
    Edge (Chromium) Windows, macOS

    Keywords

    none

    Install

    npm i livekit-client

    DownloadsWeekly Downloads

    376

    Version

    0.13.1

    License

    MIT

    Unpacked Size

    564 kB

    Total Files

    104

    Last publish

    Collaborators

    • thedavidzhao