A space where socially-distanced ringers can practice together.

Get the CSS set up with sass:

• Install dart-sass (e.g. brew install sass/sass/sass); https://github.com/sass/dart-sass/releases
• (Optional) Create & activate a virtual environment;
• Install python dependencies pip install -r requirements.txt
• In the project root, run sass app/static/sass/:app/static/css/. This will compile the sass to css.

Get the DB set up with Flask:

• In the project root, run flask db upgrade

You are now ready to run the server:

• In the project root, run flask run
• This will give you a local address where you can access the app

A feature flag is an environment variable used to enable or disable features at runtime. They enable the a given feature if they are set to 1. If they are not set or set to anything other than 1, the feature will be disabled.

• RR_ENABLE_WHEATLEY

  If set to 1 Wheatley will be enabled, otherwise Wheatley will be disabled.

• RR_WHEATLEY_METHOD_EXTENSION

  If the stage is changed and this is set to 1, Wheatley will try to load the same method on the new stage. This is disabled by default, because this check sends a request to Bob Wallis' blueline website which can block the thread for a long time and therefore cause the method change to be too late (if it happens at all).

• RR_WHEATLEY_PATH

  Set this if you want to run a version of Wheatley that isn't the latest stable version. This has to point to the file called run-wheatley inside the Wheatley repo.

  For example:

  export RR_WHEATLEY_PATH=/path/to/wheatley/run-wheatley
  flask run
  

• RR_SOCKETIO_PORT

  Currently used only by Wheatley; defaults to 5000 (the same as Flask), but should be set to 8080 for a production server.

Ringing Room supplies a basic API for use in 3rd-party apps.

GET /api/version: Gets version information. Responds with the fields:

• version: the overall RR version (which takes the form YY.WW, for year and week of release)
• api-version: the api version, which is semantically versioned
• socketio-version: the socketio version, which is semantically versioned

Initial authorization uses HTTP Basic Auth: POST to /api/tokens with the header Authorization: Basic <credentials>, where <credentials> is a base-64-encoded email:password. The response will include a bearer token valid for 24 hours.

All other endpoints (except POST /api/user for registering new users) require the header Authorization: Bearer <token>.

GET /api/user: Gets user details. Responds with a JSON including the fields username & email.

POST /api/user: Registers new user. Request must include a JSON with fields username, email, & password. Responds as per GET /api/user. (Does not require Bearer token.)

PUT /api/user: Modifies user details Request JSON may include new_username, new_email, new_password. Responds as per GET /api/user.

DELETE /api/user: Deletes user.

POST /api/user/reset_password: Must include an email field in the request JSON; if that email is associated with an account, an email will be sent to reset the password to that account. (Note: For security reasons, this endpoint will always respond with code 200 OK, no matter what email address was included.)

GET /api/user/keybindings: Gets all keybindings. Responds with a JSON including fields for each function (e.g "Call Bob" or "Ring left-hand bell"), with values a list of keybindings. (See config.py for the default keybindings and a list of all fields this will return.)

POST /api/user/keybindings: Update a specific keybinding. Request must include a JSON with a single field named for one of the functions where the value is the complete list of keys bound to that function. Responds as per GET /api/user/keybindings.

DELETE /api/user/keybindings: Reset either a specific keybinding or all keybindings. Request must include a string which is either a) the name of a specific keybinding function or b) the special key ALL_KEYBINDINGS. Responds as per GET /api/user/keybindings.

GET /api/user/controllers: Gets all controller parameters. Responds with a JSON including fields for each parameter. See config.py for the default parameters and a list of all fields this will return.

POST /api/user/controllers: Update a specific controller parameter. Request must include a JSON with a single field named for one of the controller parameters. Responds as per GET /api/user/controllers.

DELETE /api/user/controllers: Resets all controller parameters. Requet body is ignored. Responds as per GET /api/user/controllers.

GET /api/my_towers: Gets all related towers:

{
    "928134567": {
        "bookmark": 0,
        "creator": 1,
        "host": 1,
        "recent": 1,
        "tower_id": 928134567,
        "tower_name": "Advent",
        "visited": "Mon, 31 Aug 2020 15:45:54 GMT"
    },
    "987654321": {
        "bookmark": 0,
        "creator": 0,
        "host": 0,
        "recent": 1,
        "tower_id": 987654321,
        "tower_name": "Old North",
        "visited": "Mon, 31 Aug 2020 15:44:40 GMT"
    }
}

PUT /my_towers/<tower_id>: Toggles the bookmark value for that tower. Responds as per GET /api/my_towers but with only the details for the requested tower.

DELETE /my_towers/<tower_id>: Removes the tower from the current user's recent towers. Responds as per GET /api/my_towers but with only the details for the requested tower.

GET /api/tower/<tower_id>: Gets connection information for the tower, including tower settings. Response JSON includes tower_id, tower_name, server_address, additional_sizes_enabled, host_mode_permitted, half_muffled, and fully_muffled.

POST /api/tower: Creates a new tower. Request JSON should include tower_name. Responds as per GET /api/tower/<tower_id>.

DELETE /api/tower/<tower_id>: Deletes the tower, if the current user has permission to do so.

GET /api/tower/<tower_id>/settings: Gets tower settings, if the current user has permission to modify them. Response JSON includes host_mode_enabled, tower_id, tower_name, and hosts, a list of objects containing email & username.

PUT /api/tower/<tower_id>/settings: Modifies tower settings, if the current user has permission to do so. Request JSON may include tower_name, permit_host_mode, additional_sizes_enabled, half_muffled, fully_muffled. Responds as per GET /api/tower/<tower_id>/settings.

POST /api/tower/<tower_id>/hosts: Adds new hosts, if the current user has permission to do so. Request JSON must include new_hosts, a list of email addresses. Responds as per GET /api/tower/<tower_id>/settings.

DELETE /api/tower/<tower_id>/hosts: Remove hosts, if the current user has permission to do so. Request JSON must include hosts, a list of email addresses. Responds as per GET /api/tower/<tower_id>/settings.

All communication between the API consumer and an individual tower should take place through SocketIO. The basic workflow for setting up communication is:

1. Establish a connection with the server_address returned by GET /api/tower/<tower_id>.
2. Emit c_join with a JSON payload containing tower_id, user_token (the Bearer token), and anonymous_user. At present, our API doesn't support anonymous users, so this should always have the value false.
3. Listen for s_set_userlist, s_size_change, s_audio_change, s_host_mode, s_user_entered, and s_assign_user to set up the tower.
4. Once you've set up the rope circle, emit c_request_global_state and listen for s_global_state to set the bells at back/hand.
5. Ring!
6. Emit c_user_left when leaving.

Communication between client & server is handled by Socket.IO events.

Events are prefixed by origin:

• c_ for client
• s_ for server

What follows is a incomplete list of events — these should be only the events relevant to an API consumer (i.e. where functionality is not duplicated elsewhere).

The integration of Wheatley into Ringing Room has added a number of extra SocketIO signals, used for keeping Wheatley in sync with the rest of Ringing Room. Some of these signals have custom types (RowGen and Settings), which are described in detail below the table.

The Settings type is an object with 0 or more of the following properties:

sensitivity             : float; 0 <= x <= 1 (currently unused)
use_up_down_in          : Bool
stop_at_rounds          : Bool
peal_speed              : int; x >= 0
call_composition        : Bool

fixed_striking_interval : Bool (ignored by Wheatley, changes `peal_speed` when the tower size is changed)

The RowGen type is a JSON representation of the following structured enum (it's either a Method with a title, a stage, etc. or it's a Composition with a url and title):

enum RowGen {
    Method {
        title: String,
        stage: Int,
        notation: String,
        url: String,
        bob: Map<Int, String>,
        single: Map<Int, String>
    },
    Composition {
        url: String,
        title: String
    }
}

The Ints in the call maps correspond to indices within the lead, and the Strings are the place notations that should be made at that position. In JSON, the RowGen type corresponds to one of the following objects:

{
    type: "method",
    title: String,
    stage: Int,
    notation: String,
    url: String,
    bob: { Int: String },
    single: { Int: String }
}
/* or */
{
    type: "composition",
    url: String,
    title: String
}

.
├── LICENSE
├── README.md
├── app/
│   ├── __init__.py
│   ├── api/
│   │   ├── __init__.py
│   │   ├── auth.py
│   │   ├── errors.py
│   │   ├── tokens.py
│   │   └── routes.py
│   ├── email.py
│   ├── forms.py
│   ├── listeners.py
│   ├── models.py
│   ├── routes.py
│   ├── static
│   │   ├── audio/
│   │   │   ├── hand.ac3
│   │   │   ├── hand.json
│   │   │   ├── hand.m4a
│   │   │   ├── hand.mp3
│   │   │   ├── hand.ogg
│   │   │   ├── processed_audio/
│   │   │   ├── raw_audio/
│   │   │   ├── tower.ac3
│   │   │   ├── tower.json
│   │   │   ├── tower.m4a
│   │   │   ├── tower.mp3
│   │   │   └── tower.ogg
│   │   ├── audio.js
│   │   ├── bootstrap/
│   │   ├── dark-mode-switch/
│   │   ├── downloads/
│   │   ├── howler.core.min.js
│   │   ├── images/
│   │   │   ├── dncb.png
│   │   │   ├── favicon
│   │   │   ├── h-backstroke.png
│   │   │   ├── h-handstroke-treble.png
│   │   │   ├── h-handstroke.png
│   │   │   ├── logo.png
│   │   │   ├── t-backstroke.png
│   │   │   ├── t-handstroke-treble.png
│   │   │   ├── t-handstroke.png
│   │   ├── landing.js
│   │   ├── my_towers.js
│   │   ├── ringing_room.js
│   │   └── sass/
│   │       ├── circle.scss
│   │       ├── global_design.scss
│   │       ├── ringing_room.scss
│   │       └── static.scss
│   └── templates/
│       ├── _code_of_conduct.html
│       ├── _news_toast.html
│       ├── _privacy_policy.html
│       ├── _user_menu.html
│       ├── about.html
│       ├── authenticate.html
│       ├── base.html
│       ├── blog.html
│       ├── code_of_conduct.html
│       ├── contact.html
│       ├── donate.html
│       ├── email/
│       │   ├── reset_password.html
│       │   └── reset_password.txt
│       ├── help.html
│       ├── landing_page.html
│       ├── my_towers.html
│       ├── news/
│       ├── reset_password.html
│       ├── reset_password_request.html
│       ├── ringing_room.html
│       ├── tower_settings.html
│       └── user_settings.html
├── config.py
├── logs/
├── migrations/
├── requirements.txt
└── ringingroom.py