Music Blocks

“_All musicians are subconsciously mathematicians._” — Monk

“_Music is a hidden arithmetic exercise of the soul, which does not know that it is counting._” — Leibniz

Music Blocks is a _Visual Programming Language_ and a collection of _manipulative tools_ for exploring musical and mathematical concepts in an integrative and entertaining way.

Getting Started

Music Blocks is an interactive Web Application — the interaction is done via basic mouse events like _click_, _right click_, _click and drag_, etc. and keyboard events like _hotkey press_. The application is audio-visual; it produces graphics, artwork and music. Here are a couple of screenshots to give you an idea of how the application looks like:

!Music Blocks workspace showing block-based music programming

!Music Blocks rhythm and melody blocks interface

Visit the Music Blocks website for a hands on experience: https://musicblocks.sugarlabs.org.

Or download Music Blocks from the Google Play Store

Additional background on why we combine music and programming can be found here.

Refer to the following sections to get familiar with this application:

• Running Music Blocks
• How to set up a local server
• Using Music Blocks

Refer to the following sections to get an idea:

• Code of Conduct
• Contributing
• Modifying Music Blocks
• Reporting Bugs

• Credits
• Music Blocks in Japan

Running Music Blocks

Music Blocks is available under the _GNU Affero General Public License (AGPL) v3.0_, a free, copyleft license.

Music Blocks is designed to run on a web browser. The ideal way to run Music Blocks is to visit the URL _musicblocks.sugarlabs.org_ in your browser — _Google Chrome_ (or _Chromium_), _Microsoft Edge_ (_Chromium-based_), _Mozilla Firefox_, and _Opera_ work best.

To run from the most recent master branch (experimental), visit _sugarlabs.github.io/musicblocks_.

How to set up a _local server_

Music Blocks is written using native browser technologies. The bulk of the functionality is in vanilla _JavaScript_. Therefore, most of the functionality can be accessed by launching the index.html file in the browser using file:///absolute/path/to/index.html.

However, doing so, some functionality will be unavailable. Therefore, it is best to launch a _local web server_ from the directory of Music Blocks.

1. Download

1. In a terminal, cd to the directory where you downloaded/cloned

1. After you are in path/to/musicblocks/ directory, install the

npm install

1. After cloning the musicblocks repository, you can start a local

npm run dev

1. You should see a message Serving HTTP on 127.0.0.1 port 3000

1. Open your favorite browser and visit localhost:3000 or 127.0.0.1:3000.

Local Setup with Docker

Prerequisites

Before you begin, ensure you have Docker installed on your machine. You can download and install Docker from the official Docker website.

Installation

1. Clone the Music Blocks repository to your local machine:

git clone https://github.com/sugarlabs/musicblocks.git

1. Navigate to the cloned repository:

cd musicblocks

1. Build the Docker image using the provided Dockerfile:

docker build -t musicblocks .

Running Music Blocks

1. Run the Docker container using the built image:

docker run -p 3000:3000 musicblocks

This command will start a Docker container running Music Blocks and expose it on port 3000.

1. Access Music Blocks in your web browser by navigating to

Stopping the Docker container

To stop the Docker container, use Ctrl + C in your terminal. This will stop the container and free up the port it was using.

Troubleshooting

New contributors may observe console errors such as:

• $ is not defined
• lang is not defined
• p5 is not defined

If the UI loads and assets render correctly, the setup is generally considered successful for development purposes.

Future improvements may address these issues as part of ongoing refactoring efforts.

Additional Notes

• Make sure to replace musicblocks with the appropriate image name

• You can customize the port mapping (-p) if you prefer to use a

This documentation provides a basic setup for running Music Blocks locally using Docker. Feel free to customize it further based on your specific requirements and environment.

Using Music Blocks

Once Music Blocks is running, you'll want suggestions on how to use it. Follow Using Music Blocks and Music Blocks Guide.

For Scratch and Snap users, you may want to look at Music Blocks for Snap Users.

Looking for a block? Find it in the Palette Tables.

Code of Conduct

The Music Blocks project adheres to the Sugar Labs Code of Conduct

Contributing

Contributing.md provides a general overview of Sugar Lab's guidelines.

It contains best practices for writing code, submitting pull requests, and following coding standards. Please refer to this guide before making contributions to ensure consistency and maintain the quality of the project.

Modifying Music Blocks

The core functionality for Music Blocks resides in the js/ directory. Individual modules are described in more detail in js/README.md.

NOTE: As for any changes, please make a local copy by cloning this repository. Make your changes, test them, and only then make a pull request.

Contributing Code provides a general overview of Sugar Lab's guidelines. See Contributing section for specific details about this repository.

Containerized Development Environment

You may find it convenient to use a containerized environment for your development. See DevContainer README.md for details.

Developer Quick Start

1. Clone and install: git clone https://github.com/sugarlabs/musicblocks.git && npm install
2. Run locally: npm run dev
3. Before pushing: npm run lint && npx prettier --check . && npm test

Reporting Bugs

Bugs can be reported in the issues tab of this repository.

If possible, please include the browser _console log output_, and _steps to reproduce_, when reporting bugs. To access the console, type Ctrl-Shift-J/F12 on most browsers. Alternately, _right click_ and select Inspect. You may need to set the Default levels for the console to Verbose in order to see all of the output, however, in most cases that won't be required. In fact, it'll only clutter the list, so select it only when required.

Credits

Music Blocks is a fork of Turtle Blocks JS created by _Walter Bender (@walterbender)_.

_Devin Ulibarri_ has contributed functional and user-interface designs. Many of his contributions were inspired by the music education ideas, representations and practices (e.g. aspects of matrix, musical cups) developed and published by _Larry Scripp_ with whom _Devin_ studied at New England Conservatory and for whom he worked at Affron Scripp & Associates, LLC, Center for Music and the Arts in Education (CMAIE), and Music in Education. Some of the initial graphics were contributed by _Chie Yasuda_.

Much of the initial coding specific to Music Blocks was done by _Yash Khandelwal (@khandelwalYash)_ as part of Google Summer of Code (GSoC) 2015. _Hemant Kasat (@hemantkasat)_ contributed to additional widgets as part of GSoC 2016. Additional contributions were made by _Tayba Wasim (@Tabs16)_, _Dinuka Tharangi Jayaweera (@Tharangi)_, _Prachi Agrawal (@prachiagrawal269)_, _Cristina Del Puerto (@cristinadp)_, and _Hrishi Patel (@Hrishi1999)_ as part of GSoC 2017. During GSoC 2018, _Riya Lohia (@riyalohia)_ developed a Temperament widget. _Ritwik Abhishek (@a-ritwik)_ added a keyboard widget and a pitch-tracking widget. During GSoC 2019, _Favor Kelvin (@fakela)_ refactored much of the code to use promises. During GSoC 2020, _Anindya Kundu (@meganindya)_ did a major refactoring of the code base to support JavaScript export. _Aviral Gangwar (@aviral243)_ enhanced the internal representation of mode and key. _Saksham Mrig (@sksum)_ fixed 70+ bugs and added support for pitch tracking and MIDI import.

Many students contributed to the project as part of Google Code-in (2015–2019). _Sam Parkinson (@samdroid-apps)_ built the Planet during GCI. _Emily Ong (@EmilyOng)_ designed our mouse icon and _Euan Ong (@eohomegrownapps)_ redesigned the Planet code as a series of GCI tasks. _Austin George (@aust-n)_ refactored the toolbars as a series of GCI tasks. _Bottersnike (@Bottersnike)_ redesigned the widgets and the Block API, _Andrea Gonzales (@AndreaGon)_ made the widgets responsive, _Marcus Chong (@pidddgy)_ refactored the update code, resulting in an order-of-magnitude improvement in CPU usage, and _Samyok Nepal (@nepaltechguy2)_ updated the local storage mechanism to use localForage.

A full list of contributors is available.

Music Blocks in Japan

Gakken STEAM

License

Music Blocks is licensed under the AGPL, which means it will always be free to copy, modify, and hopefully improve. We respect your privacy: while Music Blocks stores your session information in your browser's local storage, it does not and will never access these data for purposes other than to restore your session. Music Blocks will never share these data with any third parties.

There is a Planet where you can share your projects with others and remix projects created by other Music Blocks users. Use of the Planet is anonymous and not required in order to enjoy Music Blocks.

Have fun, play hard, and learn.