Events

Events are the core data construct provided by the eyeson library. Most interactions with the room will be processed through events. The identifying attribute of an event is its type. When listening for events the most common thing you want to do is to respond to an event, commonly distinguished by conditionals, a switch statement or a factory.

Note

eyeson js library will handle some additional events for you in order to provide a higher level abstraction and for ease of use you will not receive those events.

Connection and Setup

connection

Contains update information about your connection status to the eyeson api.

{
  type: 'connection',
  connectionStatus: 'fetch_room' | 'connected' | 'access_denied'
}

room_setup

Received once the real time channel connection is established. This event contains information about the state of the current room.

{
  type: 'room_setup',
  content: {
    access_key: 'token-for-room',
    ready: true | false,
    room: {
      id,
      name,
      ready: true | false,
      shutdown: true | false,
      sip: { /* omitted */ } // sip connection credentials
      guest_token: 'token-for-guest'
    },
    team: {
      name
    },
    user: {
      id,
      name,
      avatar,
      guest: true | false,
      ready: true | false,
      sip: { /* omitted */ } // sip connection credentials
    },
    links: {
      self: 'https://api.eyeson.team/rooms/token-for-room',
      gui: 'https://app.eyeson.team/?token-for-room',
      guest_join: 'https://app.eyeson.team/?guest=token-for-guest',
      websocket: 'https://api.eyeson.team/rt?access_key=token-for-room'
    },
    presentation: { /* ... */ },
    broadcasts: [],
    recording: null
  }
}

Note

An eyeson room server and user may not be available on the first request therefore there a three status flags included in the response above. Room ready and user ready status, as well as the top level ready flag combining those two.

room_ready

When you establish a real time connection but the eyeson room isn’t ready at that point (i.e. room_setup content ready is false) you’ll receive this separate message once the room is ready.

{
  type: 'room_ready',
  content: {
    ready: true,
    user: { /* ... */ },
    room: { /* ... */ }
  }
}

fetch_room

Fetch the room details, provides the room and user information and is also initially received when a room changes its status to ready. The event can be send to the eyeson room and will return with same type when a response is received.

eyeson.send({ type: 'fetch_room' });
{
  type: 'fetch_room',
  room: { /* ... */ }
}

accept

Received once a session for the room has been established.

{
  type: 'accept',
  remoteStream: MediaStream, // the remote stream you're receiving
  localStream: MediaStream   // your local stream
}

stream_update

Remote or local stream has been updated and needs to be replaced.

{
  type: 'stream_update',
  stream: MediaStream,     // new remote stream
  localStream: MediaStream // new local stream
}

disconnect

User has disconnected. If providing a presentation feature you should ensure to close any active presentation held by this user, and on demand remember to restore on reconnect.

{
  type: 'disconnect'
}

reconnect

A user has reconnected, received after disconnect.

{
  type: 'reconnect'
}

podium

A user has muted the camera, left the room or started a screen capture session. Every connected source, video source indexes and an optional presenter source index are provided.

{
  type: 'podium',
  sfu: true | false,                 // selective forwarding is enabled
  solo: true | false,                // client is the only participant
  audio: true | false,               // client participates with audio (is "hearable")
  video: true | false,               // client participates with video (is "visible")
  media: true | false,               // source list includes media (e.g. gifs or video files)
  sources: sources,                  // list of source ids
  isSource: true | false,            // client is a source
  isPresenter: true | false,         // client is presenter
  hasPresenter: true | false,        // a participant is presenting
  videoSources: videoSources,        // list of video sources
  hasVideoSources: true | false,     // session has video sources
  hasDesktopSources: true | false,   // session has desktop sources
  forwardedVideoMuted: true | false  // forwarded video (sfu) is muted
}

Chat

Any meeting provides a temporary real-time chat that can be used and customized for many applications.

chat

Receive a chat message.

{
  type: 'chat',
  user: {
    name,
    avatar
  }
  timestamp, // JavaScript Date
  content
}

send_chat

Send a chat message.

{
  type: 'send_chat',
  content
}

Joining and Leaving Users

add_user

A new user has joined the eyeson room.

{
  type: 'add_user',
  user: {
    id,
    name,
    avatar, // url to users avatar
    guest: true | false
  }
  initial: true | false // initial connect or reconnect
}

remove_user

A user has left the eyeson room.

{
  type: 'remove_user',
  userId,
  user: {
    id,
    name,
    avatar,
    guest: true | false
  }
}

stop_presenting

Stop a presentation.

eyeson.send({ type: 'stop_presenting' };

Recording

start_recording

Start a recording. The message is delivered to all users.

eyeson.send({
  type: 'start_recording',
});
{
  type: 'start_recording',
}

stop_recording

Stop a recording. The message is delivered to all users.

eyeson.send({
  type: 'stop_recording',
});
{
  type: 'stop_recording'
}

recording_update

Received when the rooms recording state is updated.

{
  type: 'recording_update',
  recording: {
    id: '598d8812ac605e3e4892470b',
    created_at, // Timestamp
    duration, // in seconds
    links: {
      self: 'https://api.eyeson.team/recordings/598d8812ac605e3e4892470b',
      download: null
    },
    user: {
      id,
      name,
      avatar,
      guest,
    },
    room: {
      id,
      name,
      ready: true | false,
      shutdown: true | false,
      sip: { /* ... */ },
      guest_token
    }
  }
}

Broadcast

start_rtmp

A user started an RTMP live stream.

{
  type: 'start_rtmp',
  url,
  key
}

stop_rtmp

A user started an RTMP live stream.

{
  type: 'stop_rtmp'
}

publish_broadcast

Received after a broadcast has been published to the streaming platform.

{
  type: 'publish_broadcast',
  playerUrl
}

start_youtube

A user started a YouTube live stream.

{
  type: 'start_youtube',
  broadcastId,
  playerUrl,
  streamUrl
}

start_facebook

A user started a Facebook live stream.

{
  type: 'start_facebook',
  streamUrl
}

stop_youtube

Stop a YouTube live stream.

eyes.send({
  type: 'stop_youtube'
});

stop_facebook

Stop a Facebook live stream.

eyeson.send({
  type: 'stop_facebook'
});

stop_broadcasts

To stop all currently running broadcasts

eyeson.send({
  type: 'stop_broadcasts'
});

handle_youtube_error

A YouTube error was received.

{
}

handle_facebook_error

A Facebook error was received.

{
}

broadcasts_update

One or more broadcast/s was/were updated.

{
  type: 'broadcasts_update',
  broadcasts: [
    {
      id,
      platform: 'youtube' | 'facebook',
      player_url,
      user: { /* ... */ },
      room: { /* ... */ }
    }
  ]
}

Error Handling and Notifications

The following warnings are sent by the eyeson room.

  • ice_disconnected … Interactive Connectivity Establishment (ICE) protocol reports the users connection to be gone. You might want to show your client a “offline” warning here.

warning

An issue described by name was detected.

{
  type: 'warning',
  name
}

clear_warning

An issue described by name has been resolved.

{
  type: 'clear_warning',
  name
}

Quick Join / Guest Access

request_guest_user

With a given guest_access_token you can quickly create temporary users for the current eyeson room meeting. This can be used to provide a direct quick join or guest access. The guest_access_token will be provided with the room information.

eyeson.send({
  type:  'request_guest_user',
  api:   this.eyeson.config.api, // set api as eyeson is not yet initialized
  token, // guest_access_token
  name,
  email  // optional
});

guest_user

Receive a newly created guest user. This is same response as for a regular user but has an additional guest flag set to true.

{
  type: 'guest_user',
  token
}

Stream Control

start_stream

After a presentation ends, re-start the local stream with the previously active options.
It can also be used after devices are changed. See Device Manager for further information.
If screen = true, video => false.

{
  type: 'start_stream',
  audio: true | false, // default: true
  video: true | false, // default: true
  screen: true | false // default: false
}

The screen parameter is used to switch from camera to screen stream.

{
  type: 'start_stream',
  audio: true | false, // set true to add microphone
  screen: true
}

change_stream

Update a stream e.g. to toggle audio/video/screen.
Note: To avoid issues with some devices, you can use StreamHelpers to toggle audio.

{
  type: 'change_stream',
  audio: true | false,
  video: true | false,
  screen: true | false
}

toggle_camera

Update the cameras facing mode on mobile devices.

{
  type: 'toggle_camera',
  stream: localStream,
  facingMode: 'user' | 'environment'
}

replace_stream

Replace current stream with any custom MediaStream.
(First audio track and/or first video track with readyState = "live" are used)

{
  type: 'replace_stream',
  stream
}