<commit_before># Orchestra

## Warnings and Disclaimers

**WARNING** **WARNING** **WARNING** **WARNING**

Moving machines can cause damage to personal property, personal injury or death. It is the responsibility of the reader of this document to take adequate safety precautions when operating, designing, or building any machinery, or when offering machinery to others for use.

None of the software, documents, firmware, schematics, drawings or other materials accompanying this document have been checked for errors, omissions or mistakes of any kind. Use it at your own risk.

Your use of the software, documents, firmware, schematics, drawings or other materials accompanying this document is governed by the [License Agreement](../LICENSE.txt). Read it before proceeding.

## Contents

* [History, Concept and Intent](#history-concept-and-intent)
* [What is the Orchestra system](#what-is-the-orchestra-system)
* [This Document](#this-document)
* [Architecture](#architecture)
* [Getting Started](#getting-started)
* [Reference](#reference)
	* [Requirements and Dependencies](#requirements-and-dependencies)
	* [Configuration](#configuration)

Copyright Notice:
Copyright 2013 Google Inc. All other copyrights and trademarks are property of their respective owners.

----------------------------------------------------------------

## History, Concept and Intent

The Universal Orchestra was originally conceived as one of five experiments devised for an interactive exhibit at the [Science Museum, London](http://www.sciencemuseum.org.uk/) called [Chrome Web Lab](http://www.chromeweblab.com/). These five experiments were created to demonstrate how modern Web technologies can be used together for purposes that go beyond “normal” webapps.  

Chrome Web Lab was made by Google Creative Labs, Tellart, B-Reel, Universal Design Studio, <NAME>, MAP, <NAME>, Weir+Wong and Bibliotheque. These five experiments can be accessed in person by visiting the Science Museum in London or over the web at [chromeweblab.com](http://www.chromeweblab.com/). Chrome Web Lab will run from July 2012 until July 2013.

Orchestra is designed for people across the world to make music collaboratively. Online visitors interact with Orchestra by selecting notes on a web-based time scale for a particular instrument. As the sequencer loops, it reads the selected note and then triggers the appropriate actuator for the instrument at the Science Museum in London.

![Screenshot showing video feed of an Orchestra instrument live from the Science Museum, London](docs/images/history1.png "Orchestra History")   ![Screenshot showing the Web user interface for the Orchestra](docs/images/history2.png "Orchestra History")

The intent of this open source project is to release the base software system for a collaborative, real time loop sequencer to control physical hardware.

----------------------------------------------------------------

## What is the Orchestra system?

The Web Lab Orchestra allows multiple users to control physical hardware,
collaboratively and in real time, using a browser-based loop sequencer interface.

This repository contains all the [software](sw) you need to run your own version,
plus some instructions to help you get started with your own [hardware](hw).

## This Document

In this document we will look briefly at how the Orchestra system is organized, followed by step-by-step instructions for getting started.

## Architecture

The system is organized into modules, each of which has a specific purpose. The modules communicate with each other via web sockets and MIDI. When the optional live video+audio components are used then either WebRTC or Adobe's proprietary RTMP streaming protocol are used (depending on your setup).

![Diagram showing how Orchestra modules communicate with each other](docs/images/orchestra_arch_main.png "Orchestra Modules")

- The **UI** is an HTML5 frontend (which is served via and communicates with
  the realtime server)
- The **realtime server** is a Node.js backend which accepts WebSockets
  connections from the other components, keeping them all in sync
- The **hub** is a combination of Python-based daemon and Max patch which commands MIDI hardware based on state data from the realtime server

Optionally, the system can be configured to stream live audio and video from one computer back to the UI. This is intended to allow someone to play an instrument in one location from a computer in another location and be able to hear the results.

The live audio and video streaming components can be configured to use the WebRTC standard, or use Flash video. The WebRTC setup is preferred because it involves running fewer pieces of software. However, WebRTC is in active development so its performance today may still have much room for improvement.

![Diagram showing how WebRC and Flash video can be used with the Orchestra](docs/images/orchestra_arch_streamer.png)


## Getting Started

### Assumptions

> These instructions assume:
* ...you will be running all software on a **single** computer which is running either Linux or Mac OS X. We will call this "the computer" from now on. The components can also be configured to each run on different hosts
(as they do in [the Chrome Web Lab](http://www.chromeweblab.com/)).
See the [Configuration](#configuration) section below.
* ...you have some development knowledge (ideally in JavaScript, Python and Max) and are comfortable typing commands into a shell or the Mac OS X Terminal.
* ...you have already cloned, forked or downloaded the [project repository](../../) onto the computer. If you haven't, just download it [here](../../archive/master.zip). You can also click the "Code" link at the top of this page and look at all of the cloning and forking options available.

### Running

Before start any of the Orchestra components, please update the repository's submodules via the GitHub app, or by running this shell command from the repository [root folder](../):

`git submodule update --init`


#### Realtime server

1. Download and install the latest version of Node.js from [this page](http://nodejs.org/).
2. Start a shell or Terminal and change to the [**sw/realtimeserver** folder](sw/realtimeserver).
3. Run
    ```<commit_msg>Added warning about git submodules to the sketchbots readme<commit_after># Orchestra

## Warnings and Disclaimers

**WARNING** **WARNING** **WARNING** **WARNING**

Moving machines can cause damage to personal property, personal injury or death. It is the responsibility of the reader of this document to take adequate safety precautions when operating, designing, or building any machinery, or when offering machinery to others for use.

None of the software, documents, firmware, schematics, drawings or other materials accompanying this document have been checked for errors, omissions or mistakes of any kind. Use it at your own risk.

Your use of the software, documents, firmware, schematics, drawings or other materials accompanying this document is governed by the [License Agreement](../LICENSE.txt). Read it before proceeding.

## Contents

* [History, Concept and Intent](#history-concept-and-intent)
* [What is the Orchestra system](#what-is-the-orchestra-system)
* [This Document](#this-document)
* [Architecture](#architecture)
* [Getting Started](#getting-started)
* [Reference](#reference)
	* [Requirements and Dependencies](#requirements-and-dependencies)
	* [Configuration](#configuration)

Copyright Notice:
Copyright 2013 Google Inc. All other copyrights and trademarks are property of their respective owners.

----------------------------------------------------------------

## History, Concept and Intent

The Universal Orchestra was originally conceived as one of five experiments devised for an interactive exhibit at the [Science Museum, London](http://www.sciencemuseum.org.uk/) called [Chrome Web Lab](http://www.chromeweblab.com/). These five experiments were created to demonstrate how modern Web technologies can be used together for purposes that go beyond “normal” webapps.  

Chrome Web Lab was made by Google Creative Labs, Tellart, B-Reel, Universal Design Studio, <NAME>, MAP, <NAME>, Weir+Wong and Bibliotheque. These five experiments can be accessed in person by visiting the Science Museum in London or over the web at [chromeweblab.com](http://www.chromeweblab.com/). Chrome Web Lab will run from July 2012 until July 2013.

Orchestra is designed for people across the world to make music collaboratively. Online visitors interact with Orchestra by selecting notes on a web-based time scale for a particular instrument. As the sequencer loops, it reads the selected note and then triggers the appropriate actuator for the instrument at the Science Museum in London.

![Screenshot showing video feed of an Orchestra instrument live from the Science Museum, London](docs/images/history1.png "Orchestra History")   ![Screenshot showing the Web user interface for the Orchestra](docs/images/history2.png "Orchestra History")

The intent of this open source project is to release the base software system for a collaborative, real time loop sequencer to control physical hardware.

----------------------------------------------------------------

## What is the Orchestra system?

The Web Lab Orchestra allows multiple users to control physical hardware,
collaboratively and in real time, using a browser-based loop sequencer interface.

This repository contains all the [software](sw) you need to run your own version,
plus some instructions to help you get started with your own [hardware](hw).

## This Document

In this document we will look briefly at how the Orchestra system is organized, followed by step-by-step instructions for getting started.

## Architecture

The system is organized into modules, each of which has a specific purpose. The modules communicate with each other via web sockets and MIDI. When the optional live video+audio components are used then either WebRTC or Adobe's proprietary RTMP streaming protocol are used (depending on your setup).

![Diagram showing how Orchestra modules communicate with each other](docs/images/orchestra_arch_main.png "Orchestra Modules")

- The **UI** is an HTML5 frontend (which is served via and communicates with
  the realtime server)
- The **realtime server** is a Node.js backend which accepts WebSockets
  connections from the other components, keeping them all in sync
- The **hub** is a combination of Python-based daemon and Max patch which commands MIDI hardware based on state data from the realtime server

Optionally, the system can be configured to stream live audio and video from one computer back to the UI. This is intended to allow someone to play an instrument in one location from a computer in another location and be able to hear the results.

The live audio and video streaming components can be configured to use the WebRTC standard, or use Flash video. The WebRTC setup is preferred because it involves running fewer pieces of software. However, WebRTC is in active development so its performance today may still have much room for improvement.

![Diagram showing how WebRC and Flash video can be used with the Orchestra](docs/images/orchestra_arch_streamer.png)


## Getting Started

### Assumptions

> These instructions assume:
* ...you will be running all software on a **single** computer which is running either Linux or Mac OS X. We will call this "the computer" from now on. The components can also be configured to each run on different hosts
(as they do in [the Chrome Web Lab](http://www.chromeweblab.com/)).
See the [Configuration](#configuration) section below.
* ...you have some development knowledge (ideally in JavaScript, Python and Max) and are comfortable typing commands into a shell or the Mac OS X Terminal.
* ...you have already cloned, forked or downloaded the [project repository](../../) onto the computer. If you haven't, just download it [here](../../archive/master.zip). You can also click the "Code" link at the top of this page and look at all of the cloning and forking options available.

### Running

The Orchestra project contains a git submodule for the signalmaster WebRTC component. It is important to understand that there are some potential issues when using git submodules. Please read this [note from the git documentation](http://git-scm.com/book/en/Git-Tools-Submodules#Issues-with-Submodules) before proceeding. Essentially, though, if you don't use branches within the submodule then you should be safe.

Before start any of the Orchestra components, please update the repository's submodules via the GitHub app, or by running this shell command from the repository [root folder](../):

`git submodule update --init`


#### Realtime server

1. Download and install the latest version of Node.js from [this page](http://nodejs.org/).
2. Start a shell or Terminal and change to the [**sw/realtimeserver** folder](sw/realtimeserver).
3. Run
    ```
{'fraction_non_alphanumeric': 0.08433549182855381, 'fraction_numerical': 0.0027752081406105457, 'mean_word_length': 4.314625153625563, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 8, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3055005', 'n_tokens_mistral': 3102, 'n_tokens_neox': 2948, 'n_words': 1740}