Room Previews

Getting Thumbnails for Video Rooms

Once you start to host multiple rooms with several people each, you might want a way to peek into the rooms. Room names only take you so far.

Introducing Video Previews

Video previews are live thumbnails of the ongoing room sessions. They refresh twice every minute, and record a small slice of the room. You can use these previews to represent a room.

Turning Video Previews On

Depending on how you are creating your rooms, you need to enable video previews before you can begin using them.

If you’re using the API to programmatically create rooms, you need to set the enable_room_previews attribute to true when creating the new room.

If you’re auto-creating a new room when requesting a room token, you need to set the enable_room_previews attribute to true .

If you’re using the new programmable video communication tool, just turn on Enable Room Previews option from settings.

Using the video previews

SignalWire makes the video previews accessible as a .webp image. The URL to the image is available in the RoomSession object.

Getting the RoomSession object

There are a few ways you can get the RoomSession object for a room. Some might be easier or better suited based on your application.

1. Rest API
If you have a proxy backend (as described in the Simple Video Demo), you can query the Rest API for the room sessions. You can either list all room sessions with the GET /api/video/room_sessions endpoint. Or if you have the id of your current room session, you can GET /api/video/room_sessions/{id}.

The URL for the preview image will be in the attribute, preview_url for the room session. If preview is turned off, there'll be a null instead of the URL.

2. Realtime API and Video Client SDK

For Realtime API, you can add an event listener for room.started event to get new room sessions as they are created.

For the Video Client SDK running in the browser, the previewUrl is available in the same RoomSession object you create to start the video call.

You will find the preview image in the previewUrl attribute of the RoomSession object.

3. Programmable Video Communication

If you're using SignalWire's Programmable Video Communication to create and administrate rooms through the dashboard, you can access the Video Preview by tapping into the setupRoomSession parameter when setting up the video room.

Refreshing the previews

The previews of the room are regenerated a few times every minute. To keep them up to date in your website, you should keep on updating them using a timing mechanism like createInterval.

<body>
    <img id="preview"/>
    <script>
    SignalWire.Prebuilt.VideoRoom({
        token: '<your room token>',
        setupRoomSession: function(roomSession){
            window.room = roomSession;
            roomSession.on("room.joined",(room)=>{
                console.log(roomSession.previewUrl)
                setInterval(()=>{
                    console.log("Trying to refresh preview.")
                    let preview_img = roomSession.previewUrl;
                    let previewContainer = document.getElementById("preview").src=preview_img;
                },10000)
            })
        }
    });
    </script>
  </body>

Demo

If you'd like to explore and tinker with this feature, you can do so right from the browser in Code Sandbox

The demo code is also available on GitHub


Did this page help you?