cloud-music

Creative Commons License

All music and examples herein are licensed under the
Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

Computer music in the cloud by Michael Gogins

This is computer music that is hosted online, but actually rendered in Web browsers. The pieces are not soundfiles and they are not streamed. Each piece is a Web page that contains embedded software that runs in the browser to synthesize the music. Most pieces will play indefinitely. There may or may not be animated visuals along with the music. The listener may or may not be able to control and/or customize the piece – perhaps quite a bit, amounting to a new piece, co-composed with me.

For more information on most of these pieces, open the piece and view its About tab, or use the browser’s inspector to view the underlying code.

cloud-5

The cloud-music pieces are implemented using my cloud-5 system for creating computer music that runs in Web browsers. This in turn is based on my own WebAssembly builds of Csound and CsoundAC. Some pieces may use third party libraries. The home page of Csound itself is here.

Code written as part of cloud-5 is licensed under the terms of the same license as Csound, the GNU Lesser Public License, version 2.1. Components and libraries used by cloud-5 come under a variety of open source licenses; see the links to individual packages for more information.

Introduction

The cloud-5 system is designed for making sophisticated computer music purely in the HTML5 environment. The system is especially suited for pieces that play online, for pieces that play indefinitely, for visual music, for algorithmic composition, and for live coding.

cloud-5 runs on every system with an audio output that can run a Web server and a standards compliant Web browser. That includes all computers running macOS, Linux, or Windows, as well as most Android devices.

For recent changes, see the Release Notes at the end of this document.

Getting Started

Pre-requisites

Installation

There is no installation! Simply download the release, and unzip it into a cloud-5 directory.

cloud-5 can be stored on a USB thumb drive, and will run with all functionality from the thumb drive. This makes it possible to carry all of your work in progress from computer to device to computer.

Or, simply copy the entire cloud-5 directory with all contents to your computer or device. Make sure you can execute, read, edit, and write files in your cloud-5 directory.

Configuration

There is no configuration!

Well, actually there might be one thing. You might need to configure your local Web server to serve files from your cloud-5 directory.

Running

  1. Start a local Web server to serve the cloud-5 directory. The easiest way to do this on most systems is to open a terminal, change to your cloud-5 directory, and execute python3 -m http.server.

  2. Start your Web browser, and navigate to your cloud-5 Web site (usually just something like https://localhost:8000). Some users have problems with Firefox, e.g. with WebMIDI permissions. If you experience this, try the Chrome browser.

  3. You should see this README as a Web page. Click on cloud_music_no_1.html and verify that you see animated graphics, and can play and hear the piece.

  4. Some cloud-5 pieces use the dat.gui library to create a popup menu of controls for Csound instruments or other purposes. You can create new presets, and you can get the Web browser to remember the current preset parameters in local storage. If you need to revert to the hard-coded parameters in a piece, clear local storage in the browser settings, or in the browser’s debugger.

Making Music

In cloud-5, musical compositions are written as Web pages, i.e. as .html files.

It’s a good idea for each composition to be written as just one .html file. It must be in your cloud-5 directory. Any Csound orchestra code, JavaScript code, and GLSL shader programs should simply be embedded in the HTML file in, e.g., template strings (string literals) in JavaScript code, or included as <script> or <textview> elements.

There are many ways to write compositions, because the capabilities of Csound, Strudel, and HTML5 are so vast. Start out by a making a copy of one of the examples below, and edit it to suit your own purposes.

Tutorial Examples

These are pieces designed to show how to use the new architecture for cloud-5 based on cloud-5.js, a library of resuable Web components that greatly simplifies writing cloud music pieces.

Other Examples

Components

Capabilities

Running in the Browser

Limitations

The major limitation of running in the browser is that csound-5 pieces are sandboxed, and can write files only to a temporary filesystem inside the sandbox. It is not possible to write directly to the filesystem on the user’s computer.

However, it is possible to use an audio loopback driver such as BlackHole to route audio produced by cloud-5 to a digital audio workstation that can write soundfiles. The maximum resolution of such soundfiles is floating-point samples at 48 KHz, significantly higher resolution than the CD format.

To set this up on the Mac, open the Audio MIDI Setup app, click on the + at the bottom, and click on Create Multi-Ouput Device, including both your standard audio output and BlackHole. Then, in the Sound settings, select that Multi-Output Device as the default output. Finally, in your DAW or recording software, select BlackHole as the audio input device.

Documentation

Extending cloud-5

You can extend the capabilities of cloud-5 in several ways, including:

Contributing to cloud-5

Avoid introducing new external dependencies as much as possible. Avoid introducing new programming languages as much as possible. Do not load dependencies from content distribution networks (CDNs); all dependendencies used by cloud-5 must be static resources in the cloud-5 directory (obviously, Strudel is a big exception, but I want to keep that the only one; besides, the build process bundles Strudel into .js files that are statically served from the cloud-5 directory).

Building

Building cloud-5 is not normally necessary, as pieces will run directly from the root directory of the system, which is a static Web site. However, if you plan to make substantial contributions to, or alterations of, cloud-5. these are the instructions for building.

Install pnpm, which cloud-5 and Strudel use rather than npm. On macOS (I don’t know about other platforms), you may need to specifically install node@18.

To initialize the local repository, obtain dependencies, build a static Web site, and run it locally, execute the following commands in the root directory:

cmake .
make

These commands will patch Strudel with my addons; build everything; and make a distributable copy of the cloud-5 Web site in the repository’s root directory, with all resources statically served. Examine CMakeLists.txt and package.json for details.

To test your build, run a local Web server and browse a piece such as cloud_music_no_9, which uses many facilities of the system.

THe build may fail due to failure to build canvas.node (not actually used here). If that happens, execute cd cloud-5/strudel/packages/canvas and node-gyp rebuild, and try again from pnpm run build.

Before updating Strudel from GitHub, make a branch to contain the updates if they break cloud-5.

If you see warnings or errors, don’t panic unless browsing localhost does not open a working Web site with playable pieces!

It may be necessary to clear the browser cache and application site data to see updated pieces.

The csound-wasm and csound-node targets will rebuild if the upstream Git sources are newer than the local sources, or if the targets of the build are missing. If you still have problems with one of these targets, completely delete the problematic external project source directory, e.g.  rm -rf csound-wasm-prefix/src, delete CMakeCache.txt, and rebuild.

NOTE WELL: The gogins.github.io repository is maintained using pnpm run deploy in this cloud-5 repository. DO NOT delete any files from gogins.github.io, although pieces may be added there. In other words, gogins.github.io can be the same as, or a superset of, cloud-5.

Running in NW.js

It also is possible to run cloud-5 pieces locally in NW.js using csound.node. In this case, csound.node provides a native code build of Csound, and such pieces can load native code plugins and read and write to the local filesystem.

This involves installing a number of pre-requisites, but the advantages include somewhat higher performance from native code Csound, the ability to use native plugins (both Csound plugin opcodes and VST3 plugins), and the ability to read and write in the local filesystem.

Installation

  1. Install regular Csound for desktop computers.
  2. Install pnpm.
  3. Install csound.node. Note that the API for csound.node is virtually the same as the API for my WebAssembly build of Csound.
  4. Install NW.js.

Configuration and Running

Read about csound.node and make sure that the application directory for your csound.node pieces is the cloud-5 directory, which includes necessary resources.

Release Notes

v1.0beta

v0.2

v0.1

v0.1beta7

v0.1beta6

v0.1beta5

v0.1beta4

v0.1beta3

v0.1beta2

v0.1beta