# General
Jitsi Videobridge supports a *lastN* feature for video channels. This is an
integer, which can be set on a specific video channel. If set to *N* for a
channel, only the video from the first *N* other endpoints in the conference
will be sent to the channel. The endpoints are ordered by the last time they
were the "dominant speaker".
To enable lastN and dominant speaker switching, a few things must happen. First, when allocating video channels
for a client on the Jitsi Videobridge, the "last-n" value of the video channel must >= 0.
Secondly, a data channel must be established between the client and the Jitsi Videobridge. Third, the client must implement
the client-to-mixer audio level RTP header extension (RFC6464) and the focus must forward them to the videobridge. The Jitsi Videobridge uses this RTP header extension data to determine the current dominant speaker.
# Client Side Events
Clients will receive events over the data channel from the Jitsi Videobridge whenever there is a change in
the dominant speaker or lastN endpoints.
**LastNEndpointsChangeEvent**
```json
{
"colibriClass": "LastNEndpointsChangeEvent",
"endpointsEnteringLastN": [
"myuserJid@somewhere.com/chat-1234"
],
"lastNEndpoints": [
"myuserJid@somewhere.com/chat-1234"
],
"conferenceEndpoints": [
"myuserJid@somewhere.com/chat-1234", "another-endpoint"
]
}
```
The "lastNEndpoints" array contains the IDs of the endpoints for which video is
currently being forwarded from the bridge to the client, and only these
endpoints. The list is ordered according to the history of the speech activity in
the conference. That is, the first entry in the list is the one which has been dominant
speaker most recently. This list is not necessarily an initial segment of the
"conferenceEndpoints" list, because of endpoint pinning.
The "endpointsEnteringLastN" array contains the IDs of the endpoints which are
in the "lastNEndpoints" array, but were not in the array the last time the
event was sent. I.e. their video was not being forwarded, but now it is.
The "conferenceEndpoints" array contains the IDs of the endpoints in the
conference, ordered by speech activity. That is, the first element is the
current dominant speaker, the second element is the previous dominant speaker
and so on. The list is limited to the "lastN" value for the endpoint (which may
or may not be the same as the size of "lastNEndpoints").
For example, if we have a conference with endpoints "a", "b", "c", "d", "e",
ordered by speech activity in this way, we have lastN=4, we have "e" as a pinned endpoint,
and previously no video was being forwarded (e.g. adaptive last-n had dropped the
number of forwarded streams to 0), we could receive the following:
```json
{
"colibriClass": "LastNEndpointsChangeEvent",
"endpointsEnteringLastN": [
"a", "b", "e"
],
"lastNEndpoints": [
"a", "b", "e"
],
"conferenceEndpoints": [
"a", "b", "c", "d"
]
}
```
**DominantSpeakerEndpointChangeEvent**
```json
{
"colibriClass":"DominantSpeakerEndpointChangeEvent",
"dominantSpeakerEndpoint":"myuserJid@somewhere.com/chat-1234"
}
```
This event could be used by the client to raise the UI component displaying the new
dominant speaker and minimize UI components for participants who are not currently
the dominant speaker.
# Pinning
Clients can "pin" specific endpoints in order to "override" the set of streams being forwarded according to LastN. For example:
- LastN = 2
- Clients Alice and Bob are speaking
- Client Charlie is sharing his screen but not speaking
- Client Diane wants to get Charlie's screen stream regardless of who is speaking
To achieve this:
- Client Diane sends a `PinnedEndpointChangedEvent` event over the LastN data channel with Charlie's endpoint
- Jitsi VideoBridge begins forwarding Charlie's screen stream and either Alice's or Bob's video streams
```json
{
"colibriClass": "PinnedEndpointChangedEvent",
"pinnedEndpoint": "charlie@somewhere.com/chat-1234"
}
```
# Signaling Example
The following example is for a case where a focus controller is handling signaling between a jingle
client and the Jitsi Videobridge.
**Focus To Videobridge Signaling To Allocate Channels for a Client (Colibri)**
Example stanza to allocate audio and video channels for a client on the bridge setting the last-n value to 2.
Note: the parameter passed to the bridge is "last-n" but elsewhere in documentation it is referred to as "lastN".
```xml
```
**Focus to Client Signaling (Jingle)**
Below is an example jingle session-init stanza that would be sent to the client including the audio-level hdr extension
and the data channel needed for dominant speaker and lastN capability.
```xml
D7:FB:A1:9E:67:58:FC:60:73:C0:49:E3:15:7E:45:66:0F:30:9D:3A
8C:B8:1B:AE:EE:01:23:E1:C1:8F:FC:17:D4:E6:CD:1C:CC:1C:F0:47
01:B3:47:71:57:28:7E:5D:9A:69:82:A1:AB:47:2B:94:2A:BF:B9:44
```