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:

• none
• playlist
• random
• nomination

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_list is used to describe the pool of valid manual selection targets.
• playlist is 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_list is not used.
• playlist is 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_list is used to describe the pool of valid selection targets.
• playlist is 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_list is used to describe the pool of valid manual selection targets.
• playlist is 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
• edit
• stop
• select
• yield

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"
}