---
# System prepended metadata

title: PRD - Music Blocks (v4)

---

# PRD - Music Blocks (v4)

Music Blocks is a visual programming platform that enables users to explore concepts
of music, art, and logic building, using programming constructs. The Music Blocks
application is an IDE (Integrated Development Environment) for Music Blocks projects.

In addition to the IDE, there is also a repository for publicly shared Music Blocks
projects and assets, known as the Planet.

## Functionalities

Music Blocks enables users to:

- Create a new project, load an existing project, and save the current project
- Build, observe, and modify programs
- Run programs
- Observe the output of programs
- Export the output of programs
- Configure different aspects of the programs and their environment
- Manage program assets

### Managing Projects

A Music Blocks project encapsulates the program, configurations for its environment,
and assets used by the program.

A user would be able to:

1. Create a new project.
2. Load an existing project.
3. Save the current project.

The user would be able to load an existing project from a file, or from the Planet.
Similarly, they would be able to export their current project to a file, or to the
Planet. In addition, the Planet would contain a curated collection of example projects
to explore different constructs Music Blocks enables for program building.

#### UX

These functionalities would be exposed in a separate screen than the one where users
can view and modify projects.

More details will follow in its separate PRD. *Link TBD.*

### Building Programs

#### Concept

Music Blocks programs use graphical Lego-like snap-together bricks which represent
different program constructs. Users connect these bricks together to build the
logic of the program.

Music Blocks programs have two kinds of atomic constructs, namely Instructions
and Arguments. Instructions are of two types, namely Statements and Blocks.
Arguments are also of two types, namely Data and Expressions.

- **Data:** Constructs like literals, constants, or runtime (dynamic) values, e.g. 1, "foobar", etc.
- **Expressions:** Constructs that operate on the values of other arguments, and return a value, e.g. an add operation.
- **Statement:** Analogous to single-line statements in text-based programming languages, e.g. a print statement.
- **Block:** Contain one or more instructions nested within; may affect their execution behavior, e.g. an if block.

On top of these atomic constructs, Music Blocks programs support some additional
concepts. Programs can read and sometimes modify some runtime states — think of
these are variables in general purpose programming languages. Music Blocks programs
are inherently multi-threaded, which run concurrently. Some program blocks can be
reused by the same or different threads of executions — think of these as functions
in general purpose programming languages.

An independent thread of execution, henceforth, will be referred to as a Process,
and a reusable block of code will be referred to as a Routine. Since Routines
will be called from a Process, they'll have access to the states of the Process.

The core programming functionality will be expanded using Modules that enable
additional functionalities like art and music building. These Modules will bring
together a set of states, which can be read by programs, and some modified as well.

A program is essentially a tree where the nodes are the different programming
constructs (see Abstract Syntax Tree).

#### UX

On the main IDE screen, a significant area is allocated for the program workspace,
where users interact with the program constructs.

More details will follow in its separate PRD. *Link TBD.*

### Running Programs, Observing Output, and Exporting Artifacts

*TBD.*

### Configuring Program Environment

*TBD.*

### Managing Assets

*TBD.*

### Generating Program Statistics

*TBD.*

### User Guide

*TBD.*

### Application Settings

Users would be able to configure the following application level settings:

- Light Scheme (light/dark mode)
- Color Scheme (theme color)
- Interface Language

## Screens

1. Splash Screen
2. Main IDE
3. Project Management and Planet
4. Presentation Screen

*More details TBD.*

## Glossary

**Assets:** Artifacts used by programs, like music samples, images, etc.
**Bricks**
**Module**
**Project:** An encapsulation of a program, it's environment configurations, and assets.
**Program:** An amalgamation of programming constructs connected together to express some logic.
**Process**
**Routine**

---


# Programs

1. Workspace - an area to build, view, and modify programs

2. Bricks - visual representation of program constructs

3. Palette - A list of available constructs to build programs

4. Drag n drop bricks around, connect and disconnect bricks, to form program tree


## Project Management

1. Start a new Project
   (a button to create a new project)  

2. Load an existing project.  
   (a button to load an existing project, file explorer)  
   - Options:  
     1. Overwrite your current project.  
     2. Merge your existing project with the current project. (popover to confirm a choice)  

3. Save a project.
   A button to save a project locally, another button to save a project on the cloud. One button to expand to two?


## Program Execution

1. Run a program. (visible only when program not running)  
   (a button to run the program)  

2. Pausing a running Program (vice versa)  
   (a button for running the program)  

3. Stop a running Program (vice versa)  
   (a button for stopping a running program)  

4. Run one thread of a program slowly  
   (a button to play a thread slowly)  

5. Run one thread step by step.  
   (a button to play a thread step by step)  

## Secondary Sections

1. Show a guide/tutorial
    a. How to navigate through the application (running programs, CRUD projects, etc.)
    b. Description of usage of bricks
    
    Allocate an area of the screen to show text/image context. A button to toggle showing the guide?

2. Show statistics

    Allocate an area of the screen to show text/image context. A button to toggle showing the statistics section?

3. Show program output
    a. Output of artworks - drawings
    b. Output of music - play audio, show a timeline of notes being played
    
    A section of the screen allocated for this. Windows to see/visualize/preview runtime of a program. A button to toggle this section. There is a button that takes you to a different page where you only have these windows taking up most of the space in the interface, i.e. the windows are bigger. Have a button in that page to come back to you home page.
    
    Buttons to save artwork and sheet music within this section. Buttons to run, pause, and stop also show up around this section.
    
4. Configure different properties of a project

    Allocate an area of the screen to show text/image context. A button to toggle showing the config section?
    
Place all 4 buttons closeby. clicking on a button toggles the corresponding section. Default is the guide, eventually default becomes the program output. [up for discussion]

# Menu

1. Toggle interface language (i18n). List available languages.

    Dropdown list of languages. Selecting a language changes all the text strings in the interface to selected language.

2. Toggle fullscreen mode.

    A button to toggle inteface in and out of fullscreen mode.
    
3. A page to configure plugins and extentions.

    A button to toggle this page.

4. A settings page.
    a. Light scheme
    b. Color scheme
    c. [up for discussion] beginner/advanced mode
    
    A button to toggle setting page.


---

Program

1. A program is a set of instructions that tell the computer something to do.
2. We combine these instructions to implement logic.
3. a set of programming constructs


Programming Constructs

- Instruction
    - Statement
    - Block

- Argument
    - Value/Data
    - Expression


Process: Threads of execution

Routine: Reusable block to instructions that can be run independently from different threads of execution

States: values that can be stored (set), modified, and read (get)
