Sound Cells

Rendering braille music and sheet music in the web with abc notation.

The app is deployed to Heroku at https://soundcells.herokuapp.com/

Setup

This project is a Flask app meaning there are both Python and web dependencies to install.

Python

We are using a virtual environment venv to ensure that the Python version and dependencies are consistent. So to use, you'll need to create a virtual environment and then install all the dependencies listed in requirements.txt.

$ python3 -m venv venv
$ . venv/bin/activate
$ pip install -r requirements.txt

For Windows replace . venv/bin/activate with . venv/Scripts/activate

Web

To install web dependencies, use npm.

$ npm install

Development

To run the Flask app locally in development/debug mode:

$ export FLASK_ENV=development
$ python -m flask run

For Windows replace export FLASK_ENV=development with $env:FLASK_ENV = "development"

This app uses webpack to bundle and output js code. First, ensure that we are in development mode by updating the mode in webpack.config.js.

Then run the following command in a separate terminal window (while the flask command above is running).

$ npm run watch

This combines the code written in the source folder with modules installed to the file bundle.js which ends up in the Flask static directory.

Parser

The editor for this app uses CodeMirror 6. We wrote a custom abc grammar using the Lezer system which can be easily integrated into the CodeMirror. It is incomplete covering many of ABC's basic features, but not all of its standard syntax.

The parser was developed and tested separately - a TODO is to merge that code. If you make changes to the included parser, you can run the following code within the parser folder.

$ ../node_modules/.bin/lezer-generator abc.grammar -o ../src/js/abc_grammar.js

Deploy Process to Heroku

Currently, we are using Heroku to deploy. This is a little tricky because Heroku needs the static directory generated by Webpack, but generally we want to ignore these when pushing to GitHub. The current workflow involves temporarily creating and deploying a local production branch

1. Create and switch to a new branch.

$ git checkout -b prod

2. Remove "static/" from .gitignore.
3. Change "development" to "production" in webpack.config.js.
4. Build a production version of SoundCells.

$ npm run build

5. Commit locally. (Don't push to GitHub).
6. Push to heroku and check if it's been deployed.

$ git push --force heroku prod:main
$ heroku ps:scale web=1
$ heroku open   

7. Switch back to main and remove the temporary branch.

$ git branch -D prod

Tools

Python

• Flask
• music21

Web

• CodeMirror 6
• Lezer
• Bootstrap 5
• Tone
• Open Sheet Music Display
• JSZip
• FileSaver
• jsPDF
• svg2pdf

Dev

• Heroku
• Webpack

Notes

Bundling JS in Flask app

I could not figure out a clean way to use ES5 require statements and modules installed with npm along with Flask (hence the need for two processes running during development). I tried using Flask-Assets, but there was only support for minification and not for bundling files included with require. I looked into creating a custom filter and found an example with esbuild that looked promising, but it kept repeatedly getting an error message. The current solution is based on this 2017 blog post.

Parsing ABC

ABC notation has some strange characteristics, notably that header/metadata statements behave differently than music statements, but the only thing separating the two categories are newlines. Header statements ignore space and must end in a newline, while for our purposes, we don't want space and newlines to affect output. (In some abc examples, they affect measures per line and stemming.) This Lezer forum on line-oriented grammars helped get the current solution started.