Integrating BBB with hardware in lecture rooms
==============================================

The general idea is to bring your BBB meeting into the lecture room and join the lecture room into the meeting. That means that the teacher can choose any frontend to start a meeting, for example Moodle or Greenlight. The teacher owns the moodle or greenlight room. That means that the teacher is in control of

- who is allowed to join the meeting
- recordings and publishing of them
- presentations could be preuploaded
- learning analytics could be used like in a virtual classroom
- this should not introduce new difficulties with the GDPR

# Users perspective of joining a room into a meeting

1. A teacher is in a lecture room and creates a BBB meeting on his laptop.
2. In the meeting he clicks on the plus button, and activates the function "invite room". He the selects the institution the lecture room belongs to such as John Doe University, Jack Daniels school etc
3. BBB shows the user a nonce which is valid for a short period of time (minutes)
4. In the room equipment the teacher enters this nonce
5. The room equipments joins the meeting

## What needs to happen behind the scenes

Step `2` offers the user a list of known institutions. An operator of a server which belongs to Humboldt University (HU) Berlin might preconfigure the following institutions:

- Humboldt Universität Berlin (HU)
- Freie Universität berlin (FU)
- Technische Universität Berlin (TU)

as all of them are located in Berlin. Each of the universities operates a BBB cluster as well as a directory server. The purpose of the directory server is to exchange a join link to the meeting for a nonce which can be used by the room to join the meeting. Each institution which wants to integrate rooms into BBB should run one directory. So it should be one per university, not one per department of the university (if there are multiple BBB clusters at one university).

Lets assume a teacher from HU is giving a presentation in a lecture room of TU. He brings his laptop and creates a meeting which is running on the BBB cluster of HU Berlin. He invites a room chooses TU as location of the room.

1. BBB Server of HU generates a unique join URL (Note: We would need two join URLs to create a unique client for two screens)
2. BBB Server sends this JOIN URL to the directory of TU Berlin
3. The directory of TU Berlin generates a unique nonce and sends it to the BBB Server of HU Berlin and remembers the combination of nonce/join url for the next `N` minutes
4. The BBB Server of HU Berlin transmits this nonce to the client of the teacher

In the lecture room of TU Berlin:

5. the teacher enters the nonce into the room equipment of TU Berlin
6. the equipment belongs to TU Berlin and their operator has the directory server of TU Berlin configured (not changable by the teacher)
7. the equipment contacts the directory server of TU Berlin, presenting it the nonce
8. the directory server of TU Berlin sends the join link generated by BBB Server of HU Berlin in step `1` to the equipment.
9. the equipment launches one or more clients (if the room has multiple screens) and joins the meeting with this URL. Note: These Join URLs could trigger the waiting room notificatio, requiring the moderator to then approve the incoming lecture hall user (or users).

# Changes required in BBB to implement this

1. BBB needs an API which can be used by the client to generate a unique join URL
2. A user should be allowed to join with multiple clients at the same time, but appear only as one user in the users list (the room)
3. room users need different handling:
1. should not be able to participate in polls
2. should not be chosen in the select random user feature
3. should not be able to send or receive chat messages
4. should not be allowed to edit shared notes
5. they should be allowed to share their screen (which could be an HDMI input source)
6. they need to be remote controllable by moderators
1. change layout (includes screen layout as well as shared cameras from the room)
2. mute/unmute room
3. start screen sharing from a list of input sources (may be one or more HDMI inputs)
4. users who invited a room should automatically mute if the invited room joins to prevent audio feedback loops

## Why users should be able to join with multiple clients at the same time (item 2)

Lecture rooms have a great variety of setups. There are rooms with a single screen, dual screen and even rooms with 3 screens exist. Unless a dedicated BBB client exists for lecture rooms, each screen might be covered by a BBB client which shows the components that are defined in the currently active layout.

Let's assume a room has two screens above the blackboard, left and right. When the room joins a meeting, two browser instances are launched, one per screen. The default layout might look like this:

- presentation area on the left screen
- presentation area on the right screen
- no users list, no cameras, no chat, no icons from the action bar are visible

As soon as cameras are shared, the layout might change to:

- presentation area on the left screen
- cameras on the right screen

A different room might have a high quality camera which is focused to the blackboard. In this room the setup might look different:

The default layout might look like this:

- presentation area on the left screen, cameras above
- blackboard camera on the right screen

The teacher might decide to share the blackboard camera as content in the meeting. Layout might change to

- cameras on the left screen
- presentation area (showing the blackboard camera) on the right screen

The layouts should be configurable, the owner of the room should be able to predefine some layouts which the instructor can choose from. Maybe it is possible to define some rules for automatic layout. The room owner usually has the best knowledge which layouts are the best for a specific room.

----------------------------------------------------------------------------

It would be nice if 3rd party implementos may be able to create a non-browser BBB client for rooms (long term goal). For this a stable API and a clean interface between client and server is required. GraphQL might be a good choice for that.

# BigBlueButton Server

## API/Config changes
- Add option `mediaAuthServer` and `defaultMediaAuthServer` to `/usr/share/bbb-web/WEB-INF/classes/bigbluebutton.properties`
- Add option to create meeting api `mediaAuthServer` and `defaultMediaAuthServer`
- Add new option `mediaDevices` to disabled features in create meeting api

## Dataflow
**TODO**: Create UML sequence diagram + UI Mockup

- Frontend adds the element "invite media device" to the drop-up menu triggered by the plus button if `mediaAuthServer` is set
- Frontend makes request to `mediaAuthServer` `/server` endpoint (if set for the meeting, otherwise use global setting) with `per_page` + `page` (for pagination) and `default_server` (if set for the meeting, otherwise use global setting)
- Frontend shows list of servers (use `name` attribute as description)
- Frontend shows text-input for search, on update re-send request with `query` parameter
- Frontend shows `url` of the selected media server to the user to confirm
- User clicks on button "Create nonce"
- Frontend sends request to the backend with the selected server id
- Backend makes request to the `mediaAuthServer` `/server/SERVER_ID` endpoint to get the `url`
- Backend creates a new join meeting url
- Backend send the join meeting url as a post request to the url of the selected MediaAuthService `/meeting` endpoint and recieves a noce (`code`) and expiration date of the nonce and return this the frontend
- Frontend shows the noce and the expiration time
- (Optional) Restart the whole process

# BigBlueButton MediaAuthService

The MediaAuthService is a service to store a join url using a short-living securly generated code. Using this code a media device can get the join url of a meeting.

It also provides a discovery service to find other MediaAuthServices

## Endpoint /meeting
### Request
Type: GET
Header: Code: ABC-DEF-123
### Response

{
    "data": {
       "join_url": "http://yourserver.com/bigbluebutton/api/join?..." 
    },
    "meta": {
        "status": "success"
    }
    
}

## Endpoint /meeting
### Request
Type: POST

Body:

{
    "data": {
       "join_url": "http://yourserver.com/bigbluebutton/api/join?..." 
    }
    
}

### Response

{
    "data": {
       "code": "ABC-DEF-123"
       "expires": "2023-08-31T13:23:20+00:00"
    },
    "meta": {
        "status": "success"
    }
    
}

## Endpoint /server
### Request
Type: GET
Query: per_page: 2; page: 1; default-server: "bbb-media-berlin"; search: "University"

### Response

Use the pagination parameters of the request to paginate the results; if a default-server is provided and found, show as the first element, then sort by name ASC; if search query is set search in name with wildcards

{
    "data": {
       "severs": [
            {
                "id" : "bbb-media-berlin",
                "name": "University of Berlin",
                "url": "https://bbb-mediaauth.uni-berlin.de"
            },
            {
                "id" : "bbb-media-sydney",
                "name": "University of Sydney",
                "url": "https://bbb.uni-Sydney.au/mediaauth"
            }
        ]
    },
    "meta": {
        "total": "20",
        "per_page": "2",
        "current_page": "1",
        "start": "1",
        "end": "2",
    }
}

## Endpoint /server/bbb-media-berlin
### Request
Type: GET

### Response

{
    "data": {
                "id" : "bbb-media-berlin",
                "name": "University of Berlin",
                "url": "https://bbb-mediaauth.uni-berlin.de"
    },
    "meta": {
        "status": "success"
    }
}

# Actions

- Generate a UI mockup of what it looks like
- Specifications for the profile of the two rooms in the room