Eyeson Node.js SDK

A Node.js library for the Eyeson API. It provides a client that allows to easily build applications that can start and manage eyeson video conferences.

tip

Consult the documentation of the Rest API for details.

The SDK can also be found on a Github repository

Installation

Add eyeson-node to your JavaScript project using npm or yarn.

$ npm install --save @eyeson/node
# or
$ yarn add @eyeson/node

Usage

Get an API-KEY from developers.eyeson.team.

import Eyeson from '@eyeson/node'
const eyeson = new Eyeson({ apiKey: '< api-key >' }) // configure to use your api key

This creates a new room and a user.

note

The string typed identifier id represents which room to join. Users joining the same room-id will be connected. If you do not specify an identifier, there will be a new meeting created with every join request.

const user = await eyeson.join(username, roomIdentifier, options)
// Ensure the user (and meeting) is ready
await user.waitReady()

// Send a message into meeting chat...
await user.chat("/me sends a message")

// Update Layers
await user.setLayer({ url })
await user.clearLayer(layerIndex)

// Start a playback
await user.startPlayback({ url })

// Set a layout
await user.setLayout({ layout: "auto", show_names: false })

// Start and Stop Recoding
await user.startRecording()
await user.stopRecording()

// Start and Stop Broadcast
await user.startBroadcast(streamUrl)
await user.stopBroadcast()

// Stop a meeting for all participants
await user.stopMeeting()

// Snapshot info and delete
const snapshotInfo = await eyeson.getSnapshot(snapshotId)
const snapshots = await eyeson.getRoomSnapshots(roomId, page, startedAt, since, until)
await eyeson.deleteSnapshot(snapshotId)

// Recording info and delete
const recordingInfo = await eyeson.getRecording(recordingId)
const recordings = await eyeson.getRoomRecordings(roomId, page, startedAt, since, until)
await eyeson.deleteRecording(recordingId)

// list all users of a meeting
 const users = await eyeson.getRoomUsers(roomId, isOnline)

// Get user object after join
const user = await eyeson.getUser(accessKey)

// Register a guest user
const guest = await eyeson.registerGuest(username, guestToken, options)

// Start and stop a playback
await user.startPlayback({ play_id, url })
await user.stopPlayback(play_id)

// Send a custom message
await user.sendCustomMessage(message)

// Create a snapshot
await user.snapshot()

// Lock meeting to prevent new participants
await user.lockMeeting()

Layer Updates

The SDK provides functionality to send local images as layers to be displayed during a meeting. You can upload PNG or JPG image files from your local filesystem:

import Eyeson from '@eyeson/node'
import fsPromise from 'node:fs/promise'

const eyeson = new Eyeson({ apiKey: '< api-key >' }) // configure to use your api key
const user = await eyeson.join(username)
const imageBuffer = await fsPromise.readFile('./overlay.png')
await user.sendLayer(imageBuffer, 1)
// or as jpg:
const imageBuffer = await fsPromise.readFile('./overlay.jpg')
await user.sendLayer(imageBuffer, 1)
// add an ID to check when it can be seen
await user.sendLayer(imageBuffer, 1, 'overlay-jpg')

Layer Creation with eyeson-node-layer

The @eyeson/node-layer plugin provides a powerful interface for creating and managing visual layers in your eyeson meetings. This plugin simplifies the process of generating dynamic overlays, text elements, and graphical components that can be sent to your meeting in real-time.

import Eyeson from '@eyeson/node'
import EyesonLayer from '@eyeson/node-layer'

const user = eyeson.join('< username >', '< room id >', { options: { widescreen: true } })
const overlay = new EyesonLayer({ widescreen: true })
const timeEntry = overlay.addTextBox(new Date().toLocaleTimeString(), font, fontColor, x, y, origin, padding, maxWidth, radius, backgroundColor)
await user.sendLayer(overlay)
setTimeout(async () => {
    timeEntry.text = new Date().toLocaleTimeString()
    await user.sendLayer(overlay)
}, 60 * 1000) // update time every minute

SVG Layers

For incorporating SVG graphics in your meeting layers, eyeson provides the @eyeson/node-layer-svg plugin. This extension enables you to create and manipulate SVG elements dynamically, supporting vector graphics for higher quality visual overlays that scale perfectly at any resolution.

The SVG plugin complements the standard layer functionality, allowing you to:

• Render SVG files or strings directly in your meeting
• Create complex vector graphics programmatically
• Combine SVG elements with other layer components

Refer to the full @eyeson/node-layer-svg documentation for implementation details and examples.

Meeting Observer

The Meeting Observer provides a real-time connection to monitor and react to events occurring within an Eyeson meeting. This feature enables applications to listen for specific events such as chat messages, participant updates, or room status changes. By implementing event handlers, developers can build responsive applications that automatically adapt to the current state of a video conference. The observer connection is designed to be lightweight and can be easily managed through the lifecycle of your application.

import Eyeson from '@eyeson/node'
const eyeson = new Eyeson({ apiKey: '< api-key >' }) // configure to use your api key

const meeting = await eyeson.join(username)

const connection = eyeson.observer.connect(meeting.roomId)
connection.on('event', event => {
    if (event.type === 'room_update') {
        console.log(event.content)
    }
    else if (event.type === 'chat') {
        console.log(event.content)
    }
    else if (event.type === 'participant_update') {
        console.log(event.participant)
    }
    // and many more
})
// ...later...
connection.close() // closes automatically on shutdown

Permalink API

The eyeson-node SDK includes functions to use with the Permalink API.

import Eyeson from '@eyeson/node'
const eyeson = new Eyeson({ apiKey: '< api-key >' }) // configure to use your api key

const permalink = await eyeson.permalink.create('<username>', {
    name: '<room_name>',
    user: { id: '<user-id>' },
    options: { widescreen: true },
})
console.log(permalink.userToken, permalink.guestToken, permalink.data.links.gui, permalink.data.links.guest_join)

const list = await eyeson.permalink.getAll({ limit: 50, expired: false })

const permalink = await eyeson.permalink.getbyId('<permalink-id>') // can also be used to update "permalink.started"

const permalink = await eyeson.permalink.update('<permalink-id>', { options: { widescreen: false } })

await eyeson.permalink.delete('<permalink-id>')

const permalink = await eyeson.permalink.addUser('<permalink-id>', '<username>', { id: '<user-id>' })
console.log(permalink.userToken, permalink.data.links.gui)

await eyeson.permalink.removeUser('<permalink-id>', '<user-token>')

const user = await eyeson.permalink.joinMeeting('<user-token>')

const guest = await eyeson.permalink.registerGuest('<username>', '<guest-token>', { id: '<user-id>' }) // works only if permalink.started === true

Forward Stream

eyeson-node provides comprehensive support for stream forward API functions. These functions allow you to forward audio and video streams from various sources to WebRTC-compatible endpoints using the WHIP protocol. This enables advanced streaming scenarios such as custom media routing, external recording, or integration with third-party services.

import Eyeson from '@eyeson/node'
const eyeson = new Eyeson({ apiKey: '< api-key >' }) // configure to use your api key

const meeting = await eyeson.join(username)

const forward = eyeson.createRoomForward(meeting.roomId)

await forward.source('<forward-id>', '<user-id>', 'audio,video', 'https://example.com/whip...')
await forward.mcu('<forward-id>', 'audio,video', 'https://example.com/whip...')
await forward.playback('<forward-id>', '<play-id>', 'audio,video', 'https://example.com/whip...')

await forward.stop('<forward-id>')