Room

Televisit Room

Configuring Room Triggers

There are three special trigger events for the room object: room.after, participant.after and track.after. Each occurs in response to a web hook call from the video provider. These events are also recorded in the room's events[] list.

Note recording.after and composition.after will be implemented in future versions.

To handle events triggered by the remote room provider, insert these Cortex script triggers.

org.objects.scripts.insertMany([{
  type: 'trigger',
  active: true,
  configuration: {
    event: 'room.after',
    object: 'room',
  },
  description: 'c_room_room_event',
  label: 'c_room_room_event',
  name: 'c_room_room_event',
  principal: null,
  script: `
    const { arguments: { event, old: room }, context } = script 
    require('logger').trace(event)
  `
},{
  type: 'trigger',
  active: true,
  configuration: {
    event: 'participant.after',
    object: 'room',
  },
  description: 'c_room_participant_event',
  label: 'c_room_participant_event',
  name: 'c_room_participant_event',
  principal: null,
  script: `
    const { arguments: { event, old: room }, context } = script 
    require('logger').trace(event)
  `
},{
  type: 'trigger',
  active: true,
  configuration: {
    event: 'track.after',
    object: 'room',
  },
  description: 'c_room_track_event',
  label: 'c_room_track_event',
  name: 'c_room_track_event',
  principal: null,
  script: `
    const { arguments: { event, old: room }, context } = script 
    require('logger').trace(event)
  `
}]).execute()

Room Events

All room events share the following properties:

• type { String } Indexed room event type [room, participant, track]

• name { String } Indexed room event name. created, ended, connected, etc.

• order { Number } Indexed integer representing the order in which the remote event was fired. It's possible that

  events are called and written out of order. The order property may be used to present the remote timeline.

• roomId { ObjectID } Indexed originating local room identifier.

room.after :: room.created - Room is open and available for connection.

{
  type: 'room',
  name: 'created',
  order: 0,
  roomId: '5df02d890535377c38cfdeef'
}

room.after :: room.ended - Room is closed, or ended due to a timeout (empty for 5 minutes).

• duration { Number } The number of seconds the room was active.

{
  type: 'room',
  name: 'ended',
  order: 12,
  roomId: '5df02d890535377c38cfdeef',
  duration: 156 
}

participant.after :: participant.connected - Participant entered a room

• status { String } The current status of the participant generating this event - either connected or disconnected.

• accountId { ObjectID } The id of the account generating the event.

{
  type: 'participant',
  name: 'connected',
  order: 1,
  roomId: '5df02d890535377c38cfdeef',
  status: 'connected',
  accountId: '58c87b958b8f160100812b70'
}

participant.after :: participant.disconnected - Participant left a room

• status { String } The current status of the participant generating this event - either connected or disconnected.

• accountId { ObjectID } The id of the account generating the event.

• duration { Number } The number of seconds the participant was connected to the room.

{
  type: 'participant',
  name: 'disconnected',
  order: 8,
  roomId: '5df02d890535377c38cfdeef',
  status: 'disconnected',
  accountId: '58c87b958b8f160100812b70',
  duration: 101 
}

track.after :: track.added - Participant added a track

• status { String } The current status of the participant generating this event - either connected or disconnected.

• accountId { ObjectID } The id of the account generating the event.

• trackKind { String } The kind of track - data, audio or video.

• trackName { String } The track name. Currently unused and set to a uuid.

{
  type: 'track',
  name: 'added',
  order: 2,
  roomId: '5df02d890535377c38cfdeef',
  status: 'connected',
  accountId: '58c87b958b8f160100812b70',
  trackKind: 'audio',
  trackName: '613ef5df-cdee-4fd6-8f19-7140deb08b81'  
}

track.after :: track.removed - Participant removed a track

• status { String } The current status of the participant generating this event - either connected or disconnected.

• accountId { ObjectID } The id of the account generating the event.

• trackKind { String } The kind of track - data, audio or video.

• trackName { String } The track name. Currently unused and set to a uuid.

{
  type: 'track',
  name: 'removed',
  order: 21,
  roomId: '5df02d890535377c38cfdeef',
  status: 'connected',
  accountId: '58c87b958b8f160100812b70',
  trackKind: 'video',
  trackName: '8bd80b33-34ab-4ac6-b2fd-23d51cfe9156'  

}

track.after :: track.enabled - Participant un-paused a track

• status { String } The current status of the participant generating this event - either connected or disconnected.

• accountId { ObjectID } The id of the account generating the event.

• trackKind { String } The kind of track - data, audio or video.

• trackName { String } The track name. Currently unused and set to a uuid.

{
  type: 'track',
  name: 'enabled',
  order: 22,
  roomId: '5df02d890535377c38cfdeef',
  status: 'connected',
  accountId: '58c87b958b8f160100812b70',
  trackKind: 'video',
  trackName: '8bd80b33-34ab-4ac6-b2fd-23d51cfe9156'  

}

track.after :: track.disabled - Participant paused a track

• status { String } The current status of the participant generating this event - either connected or disconnected.

• accountId { ObjectID } The id of the account generating the event.

• trackKind { String } The kind of track - data, audio or video.

• trackName { String } The track name. Currently unused and set to a uuid.

{
  type: 'track',
  name: 'enabled',
  order: 21,
  roomId: '5df02d890535377c38cfdeef',
  status: 'connected',
  accountId: '58c87b958b8f160100812b70',
  trackKind: 'video',
  trackName: '8bd80b33-34ab-4ac6-b2fd-23d51cfe9156'  

}

Configuring Access

The Room definition defaultAcl is owner.delete and there is no createAcl defined for Rooms; Rooms must be created in-script using bypassCreateAcl().

Alternatively, the Room definition may be extended with overriding createAcl, defaultAcl and - incidentally - custom properties.

org.objects.objects.insertOne({
  label: 'Room',
  name: 'room',
  createAcl: 'account.public', // any user can create rooms.
  properties: [{
    name: 'c_ustom',
    label: 'Custom',
    type: 'String'
  }]
})

Access to instances is provided using explicit acl writing. the shorthand import/export format can be used as well as the standard type, target, allow properties. Anyone with read access to the room instance is provided a token when reading the token property. For example:

org.objects.rooms.insertOne({  
  acl: [
    'account.public.read', // any logged in account
    'account.anonymous.read', // anyone anywhere
    'role.developer.read', // developer role
    `account.${emailToId('[e-mail]')}.read`, // specific account (by id)           
    { type: 1, target: emailToId('[e-mail]'), allow: 4 } // long form
  ]
})
.bypassCreateAcl()
.execute()

function emailToId(email) {
  return org.objects.accounts.readOne({ email }).skipAcl().grant('read').execute()._id
}

Creating Rooms

Some environment-level options are required to create rooms.

• org.configuration.televisit.roomsEnabled must be true in order to create rooms in an environment.

• org.configuration.televisit.maxConcurrentRooms determines how many open rooms are allowed in a given environment.

To see current values for the above read current environment as an administrator (return org.read('configuration.televisit'))

To create a room instance, write an acl and insert a room instance:

return org.objects.rooms.insertOne({
  acl: [   
    `role.developer.read` // example.
  ]
}).lean(false).execute()

The Cortex room instance is now created and the state is "new". The provider room to which clients connect is opened asynchronously. Once this process has completed, the room's state property will be set to "open" and fire any room.after script triggers ({type: 'room', name: 'created', ...}).

Participant may now use their tokens to connect to the remote room.

Participant Status

Current participant status is updated in the Room instance to reflect the state of connected participants as they connect, disconnect, add and pause tracks, etc. Participant status is updated prior to script triggers so the latest is available in room event triggers.

Example participants list where both are connected and streaming audio and video.

const doc = org.objects.room
  .readOne('5df2cb2a020fd46a6351e66b')
  .paths('participants.status', 'participants.audio', 'participants.video', 'participants.account.name')
  .execute()

let json = {
  "_id": "5df2cb2a020fd46a6351e66b",
  "object": "room",
  "participants": [
    {
      "_id": "5df2cb3d020fd46a6351e70b",
      "account": {
        "_id": "58c87b958b8f160100812b70",
        "name": {
          "additional": [],
          "first": "Jane",
          "last": "Doe"
        },
        "object": "account"       
      },
      "audio": [
        "connected"
      ],
      "status": "connected",
      "video": [
        "connected"
      ]
    },
    {
      "_id": "5df2cce5020fd46a6351ef86",
      "account": {
        "_id": "5da9ff0fff5c5eb553a557f1",
        "name": {
          "additional": [],
          "first": "John",
          "last": "Doe"
        },
        "object": "account"       
      },
      "audio": [
        "connected"
      ],
      "status": "connected",
      "video": [
        "connected"
      ]
    }
  ]
}

• The status of the participant is connected when they are connected to the room.

• The audio and video are arrays that contain connected and/or paused.

  • When either of these tracks are removed, connected will no longer appear in the array, but paused may linger and

    should be ignored.

• When a participant status is disconnected:

  • Ignore the values inaudio and video.

  • The participant remains in the list.