Automoderation
The Automoderation feature allows one to let the server organize a discussion (e.g. manage queue of speakers, select new speakers, etc.)
Kinds of operation
The automoderation feature uses a state machine which, depending on the configuration drive the state of the conference. The core concept is a selection strategy:
There are 4 strategies:
noneplaylistrandomnomination
Additionally there is a set of config option that need to be set when the automod feature is started.
show_list | When true, the module will relay information about the last and upcoming speakers to the frontend. |
consider_hand_raise | When true, the module will add the participant raising their hand to the playlist. |
time_limit | Time limit each speaker has before its speaking status get revoked |
allow_double_selection | Depending on the selection_strategy this will prevent participants to become speaker twice in a single automod session |
animation_on_random | When true, the frontend will play an animation when a random selection is being made. |
allow_list | Depending on the selection strategy, the list of Participant that can be chosen from. |
playlist | Ordered list of queued participants. |
The selection of the first speaker must be done by the frontend then, depending of the selection_strategy, the automod module will continue running until finished or stopped.
Once the active speaker yields or their time runs out, their automod module is responsible to select the next speaker (if the selection_strategy requires it).
This behavior MUST only be executed after ensuring that this participant is in fact still the speaker.
If the participant leaves while being speaker, its automod-module must execute the same behavior as if the participants simply yielded without selecting the next one (which would be required for the "nominate" selection_strategy.
A moderator has to intervene in this situation).
Moderators will always be able to execute a re-selection of the current speaker regardless of the selection_strategy.
Selection Strategy: None
No automatic reselection happens after the current speaker yields.
The next one must always be selected by the moderator.
The moderator may choose a participant directly or let the controller choose one randomly.
For that the controller holds a allow_list which is a set of participants which are able to be randomly selected.
Furthermore the controller will hold a list of start/stop speaker events.
That list can be used to avoid double selections (option) when randomly choosing a participant.
In this selection strategy the following holds.
allow_listis used to describe the pool of valid manual selection targets.playlistis not used.
Selection Strategy: Playlist
The playlist-strategy requires a playlist of participants. This list will be stored ordered inside the controller. Whenever a speaker yields the controller will automatically choose the next participant in the list to be the next speaker.
A moderator may choose to skip over a speaker. That can be done by selecting the next one or let the controller choose someone random from the playlist. The playlist can, while the automod is active, be edited.
In this selection strategy the following holds.
allow_listis not used.playlistis a ordered list of participants which will get used to select the next participant when yielding.
It is also used as a pool to select participants randomly from (moderator command select).
Selection Strategy: Random
This strategy behaves like None but will always choose the next speaker randomly from the allow_list as soon as the current speaker yields.
In this selection strategy the following holds.
allow_listis used to describe the pool of valid selection targets.playlistis not used.
Selection Strategy: Nomination
This strategy behaves like None but requires the current speaker to nominate the next participant to be speaker.
The nominated participant MUST be inside the allow_list and if double selection is not enabled the controller will check if the nominated participant already was a speaker.
In this selection strategy the following holds.
allow_listis used to describe the pool of valid manual selection targets.playlistis not used.
Joining the room
JoinSuccess
When joining a room, the join_success control event contains the module-specific fields decribed below.
Fields
| Field | Type | Always | Description |
|---|---|---|---|
config | PublicConfig | yes | Configuration of the auto-moderation |
speaker | string | no | The currently active speaker |
PublicConfig fields:
| Field | Type | Required | Description |
|---|---|---|---|
selection_strategy | enum | yes | See the same field in Start |
issued_by | string | yes | See the same field in Start |
show_list | bool | yes | See the same field in Start |
consider_hand_raise | bool | yes | See the same field in Start |
time_limit | int | no | See the same field in Start |
allow_double_selection | bool | yes | See the same field in Start |
animation_on_random | bool | yes | See the same field in Start |
auto_append_on_join | bool | yes | See the same field in Start |
history | string[] | no | See the same field in Start |
remaining | string[] | no | See the same field in Start |
Example
{
"config": {
"selection_strategy": "none",
"show_list": true,
"consider_hand_raise": false,
"time_limit": 10000,
"allow_double_selection": false,
"animation_on_random": true,
"auto_append_on_join": false,
"allow_list": ["00000000-0000-0000-0000-000000000000"],
"playlist": ["00000000-0000-0000-0000-000000000000"]
},
"speaker": "00000000-0000-0000-0000-000000000000"
}
Joined
When joining a room, the joined control event sent to all other participants contains the module-specific fields decribed below.
Commands
Commands are issued by a participant to start or interact with a automod session.
Overview
Start
The Start message can be send by a moderator (or user with the correct permissions) to start a automod session.
Fields
| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
action | enum | yes | Must be "start" | |
selection_strategy | enum | yes | Must be one of "none", "playlist", "random", "nomination" | The used selection strategy |
show_list | bool | yes | When true, the module will relay information about the last and upcoming speakers to the frontend. | |
consider_hand_raise | bool | yes | When true, the module will add the participant raising their hand to the playlist | |
time_limit | int | no | Time limit in milliseconds speaker has before its speaking status get revoked | |
allow_double_selection | bool | yes | Depending on selection_strategy this will prevent participants to become speaker twice in a single automod session | |
animation_on_random | bool | yes | When true, the frontend will play an animation when a random selection is being made | |
auto_append_on_join | bool | yes | When true, joining participants are automatically added to the speaker list | |
allow_list | string[] | no | Valid ParticipantIds | Depending on selection_strategy, the list of Participant that can be chosen from. |
playlist | string[] | no | Valid ParticipantIds | Ordered list of queued participants |
Example
{
"action": "start",
"selection_strategy": "none",
"show_list": true,
"consider_hand_raise": false,
"time_limit": 10000,
"allow_double_selection": false,
"animation_on_random": true,
"auto_append_on_join": false,
"allow_list": ["00000000-0000-0000-0000-000000000000"],
"playlist": ["00000000-0000-0000-0000-000000000000"]
}
Response
A Started message is sent to all participants that are currently in the room.
Stop
Stop the currently active automoderation session.
Fields
| Field | Type | Required | Validation |
|---|---|---|---|
action | enum | yes | Must be "stop". |
Example
{
"action": "stop",
}
Response
A Stopped message with the stopped_by_moderator reason is sent to all participants that are currently in the room.
Edit
Set either the allow_list or playlist or both.
Fields
| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
action | enum | yes | Must be "edit". | |
allow_list | string[] | no | Valid ParticipantId | |
playlist | string[] | no | Valid ParticipantId |
Example
Setting the allowlist to contain the zero participantId and the playlist to be empty
{
"action": "edit",
"allow_list": ["00000000-0000-0000-0000-000000000000"],
"playlist": []
}
Setting the allowlist to contain the zero and one participantId. The playlist is not changed
{
"action": "edit",
"allow_list": ["00000000-0000-0000-0000-000000000000", "00000000-0000-0000-0000-000000000001"]
}
Response
A Remaining Updated message is sent to all participants that are currently in the room.
Select
Select a user to be active speaker.
Fields
| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
action | enum | yes | Must be "select,. | |
how | enum | yes | Must be one of "none", "random,, "next", "specific". | |
participant | string | when how == specific | Valid ParticipantId | |
keep_in_remaining | bool | when how == specific | If true the selected participant will not be removed from either the allow- or playlist |
Example
Select a specific speaker
{
"action": "select",
"how": "random"
}
Select a specific speaker
{
"action": "select",
"how": "specific",
"participant": "00000000-0000-0000-0000-000000000000",
"keep_in_remaining": true
}
Response
Depending on the configuration a Speaker Updated or a Start Animation event is sent in response to this action. When a Start Animation event is sent, a Speaker Update follows.
Yield
User yields their speaker status.
Fields
| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
action | enum | yes | Must be "yield". | |
next | string | no | Valid ParticipantId | In some cases a user must select the next participant to be speaker. This is the case when the strategy is "nomination" |
Example
{
"action": "yield",
"next": "00000000-0000-0000-0000-000000000000",
}
Response
Depending on the configuration a Speaker Updated or a Start Animation event is sent in response to this action. When a Start Animation event is sent, a Speaker Update follows.
Events
Events are received by participants when the automod session state is changed.
Started
Signals the start of an automod session.
Fields
| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
message | enum | yes | Must be "started" | |
selection_strategy | enum | yes | Must be one of "none", "playlist", "random", "nomination" | The used selection strategy |
issued_by | string | yes | Valid ParticipantId | The ID of the participant who started the automoderation session |
show_list | bool | yes | When true, the module will relay information about the last and upcoming speakers to the frontend | |
consider_hand_raise | bool | yes | When true, the module will add the participant raising their hand to the playlist | |
time_limit | int | no | Time limit in milliseconds speaker has before its speaking status get revoked | |
allow_double_selection | bool | yes | Depending on selection_strategy this will prevent participants to become speaker twice in a single automod session | |
animation_on_random | bool | yes | When true, the frontend will play an animation when a random selection is being made | |
auto_append_on_join | bool | yes | When true, joining participants are automatically added to the speaker list | |
history | string[] | no | Valid ParticipantIds | Optional modification of the history. If set the frontend MUST replace its history with the given one. If not set the frontend MUST keep its current history. |
remaining | string[] | no | Valid ParticipantIds | Optional modification of the remaining participants. Remaining participants must be interpreted differently depending on the selection strategy. E.g. in the playlist strategy, remaining lists the participants left inside the playlist. All other strategies will use remaining (if at all) to list all participants (if public) that are eligible to be selected. This will only be set if selection_strategy is set to "playlist". If set, the frontend MUST replace its list with the given one. If not set, the frontend MUST keep its current remaining list |
Example
{
"message": "started",
"selection_strategy": "none",
"issued_by": "00000000-0000-0000-0000-000000000000",
"show_list": true,
"consider_hand_raise": false,
"time_limit": 5000,
"allow_double_selection": false,
"animation_on_random": true,
"auto_append_on_join": false,
"history": [
"00000000-0000-0000-0000-000000000000"
],
"remaining": [
"00000000-0000-0000-0000-000000000000"
]
}
Stopped
Signals the end of an automod session.
Fields
| Field | Type | Required | Description |
|---|---|---|---|
message | enum | yes | Is "stopped". |
reason | enum | yes | "stopped_by_moderator" or "session_finished". |
issued_by | string | no | The participant ID of the moderator who issues the Stopped command and it's only present for "stopped_by_moderator". |
Examples
Stopped by a moderator:
{
"message": "stopped",
"reason": "stopped_by_moderator",
"issued_by": "00000000-0000-0000-0000-000000000000"
}
Session finished:
{
"message": "stopped",
"reason": "session_finished"
}
Speaker Updated
The current speaker has been updated.
This event will ALWAYS notify of a speaker change, even if the speaker is the same participant as before, it MUST be handled as changed.
Both history and remaining: If the field is set it will contains the complete new list. If it doesn't exist it must be treated as unchanged.
Fields
| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
message | enum | yes | Is "speaker_updated". | |
history | string[] | no | Valid ParticipantIds | Optional modification of the history. If set, the frontend MUST replace its history with the given one. If not set the frontend MUST keep its current history. |
remaining | string[] | no | Valid ParticipantIds | Optional modification of the remaining participants. Remaining participants must be interpreted differently depending on the selection strategy. E.g. in the playlist moderation remaining lists the participants left inside the playlist. All other strategies will use remaining (if at all) to list all participants (if public) that are eligible to be selected. This will only be set when using the "playlist" selection_strategy. If set the frontend MUST replace its remaining list with the given one. If not set the frontend MUST keep its current remaining list. |
Example
{
"message": "speaker_updated",
"speaker": "00000000-0000-0000-0000-000000000000",
"history": [],
"remaining": [
"00000000-0000-0000-0000-000000000000"
]
}
Remaining Updated
The remaining list has been updated
A modification of the remaining list has taken place, because someone edited the list by hand or it got modified because a participant left/joined.
Fields
| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
message | enum | yes | Is "remaining_updated". | |
remaining | string[] | yes | Valid ParticipantIds |
Example
Stopped with valid results:
{
"message": "remaining_updated",
"remaining": [
"00000000-0000-0000-0000-000000000001",
"00000000-0000-0000-0000-000000000002"
]
}
Start Animation
Tell the frontend to start the animation for random selection. The animation must yield the result specified by this message.
Fields
| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
message | enum | yes | Is "start_animation". | |
pool | string[] | yes | Valid ParticipantIds | |
result | string | yes | Valid ParticipantId |
Example
{
"message": "start_animation",
"pool": [],
"result": "00000000-0000-0000-0000-000000000000"
}
Error
The error event is a message that may be triggered by syntactically correct but invalid commands inside the automod namespace
and therefore could be considered a kind of response. Errors must be handled outside of any context as they are considered events
that can happen at any time. (e.g. an internal error may occur at any time to signal an internal problem)
Fields
| Field | Type | Required | Description |
|---|---|---|---|
message | enum | yes | Is "error". |
error | enum | yes | Exhaustive list of error strings, see table below |
| Error | Description |
|---|---|
invalid_selection | The selection made by the frontend was invalid. Can originate from the "start", "yield" or "select" command. |
insufficient_permissions | The issued command can only be issued by a moderator, but the issuer isn't one. |
session_already_running | Attempted to start a new session when another active session is already running. |
Example
{
"message": "error",
"error": "invalid_selection"
}