This application provides an easy way to implement and run online listening experiments for music research. It presents questions, and typically audio stimuli, to participants, and collects their feedback.
-
Try the already implemented experiments at the Amsterdam Music Lab Website.
-
For documentation on how to use the infrastructure, refer to our documentation.
-
We are also happy if you file a feature request in our issues list, or if you fork this repository to add your own code.
We recommend downloading a code editor, for instance Visual Studio Code, and to use git to copy this repository to your machine, as this makes it easier to keep your local copy up to date.
The easiest way to run the application locally is through Docker. Docker is an application which runs a network of virtual machines ("containers") and is therefore (mostly) platform independent.
Install Docker Desktop.
- Install Docker Engine
- Install Docker Compose
- Install Docker Desktop
Make a copy of the file .env.dist (in the same directory as this README) and rename it to .env. This file contains variables used by Docker to start up a container network serving MUSCLE.
Start Docker (the app icon is a whale carrying containers). Then, open a terminal and run
docker compose up (add sudo on Linux).
This command starts up the containers defined in docker compose.yaml:
- a PostgreSQL container, for storing experiment/user/playlist data, saved on the host machine in the Docker user data, represented in the volume
db_data. Data added to the database will persist if the container is shut down. - a ip2country container, which provides country codes for ip addresses, used for demographic information of users.
- a container of the server, defined in DockerfileDevelop in
backend. The Dockerfile defines the Python version and installs development dependencies. The startup command runs migrations and then starts up a Django development server. - a container of the client, defined in DockerfileDevelop in
frontend. The Dockerfile defines the node version and installs node modules. The startup command kicks off a React development server.
Once you see all containers have started up, open your browser and navigate to localhost:3000. You should now be able to see the first screen of the Goldsmiths Musical Sophistication Index questionnaire.
Since the docker compose.yaml defines bind mounts for backend and frontend, any changes to the files on the host are immediately reflected in the containers, which means code watching works and hot reload works in the same way as with a native node or Django server.
To stop the containers, press ctrl-c or (in another terminal) run
docker compose down.
A production build should define its own docker compose.yaml, making use of the Dockerfile of the backend and frontend environments. It should also define a custom .env file, with safe passwords for the SQL database and the Python backend. Instead of mounting the entire backend and frontend directory and using the development servers, the backend should serve with gunicorn, and the frontend should use a build script to compile static html, css and JavaScript.
Please refer to the wiki a checklist of common issues and their solutions.