Home

cloud-5

Creative Commons License

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

Michael Gogins

The cloud-5 system is a toolkit and library designed for creating computer music that is hosted on Web servers and that runs and plays in the user's Web browser. In theory, that can be any current Web browser, even on smartphones and tablets, although performance might be an issue on less powerful systems. For examples of such music, see cloud-music.

The cloud-5 system 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 the more powerful smartphones and tablets.

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

Getting Started

Pre-requisites

  • A Web server that will run from a configurable directory in which you can read, edit, and write files. On most systems, the simplest way to get a Web server is to install Python 3.

  • A standards-compliant Web browser (currently, that includes nearly all Web browsers). Should already exist on your system. On Android, install a Web server app such as Phlox.

  • A text or code editor for writing your compositions. A simple text editor should already exist on your system. I use Visual Studio Code myself, as it is very powerful and yet easy to customize. On Android, install a text editor such as QuickEdit Pro.

Installation

There is no installation!

Simply download the release (cloud-5.zip), and unzip it into an empty directory.

cloud-5 can be stored on a USB thumb drive, and will run with all functionality from the thumb drive. That 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!

If you have built cloud-5 yourself, cloud-5's Web root directory is cloud-5/strudel/website/dist. If you have downloaded the prebuilt cloud-5 release, the Web root directory is where you unzipped cloud-5.zip.

Running

  1. Start a local Web server to serve the Web root directory. The easiest way to do this on most systems is to open a terminal, change to the Web root directory, and run 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. The home page of the default installation is cloud_music_no_1.html. Verify that you see animated graphics on this page, 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 end up in the cloud-5 Web root directory. Any Csound orchestra code, JavaScript code, and GLSL shader programs should simply be embedded in the HTML file, e.g. in 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 Things

  • Strudel REPL, exactly like the main Strudel Web site.

  • CsoundAC Reference, reference documentation for cloud-5's JavaScript code.

  • A minimal example that just plays an embedded Csound piece.

  • A Csound Player that will play, and let you edit, any Csound piece that you paste into the text area.

  • Message from Another Planet, a Csound piece with a basic HTML user interface.

  • Trichord Space, an interactive piece that displays Dmitri Tymoczko's chord space for trichords, with the ability to perform, hear, and visualize various operations on the chords in the space.

Components

  • Csound version 6.18, one of the oldest and most powerful sound programming languages, compiled for WebAssembly to run in Web browers in csound-wasm.

  • CsoundAC, my C++ library for algorithmic composition with Csound, compiled for WebAssembly to run in Web browsers in csound-wasm, and incorporating my implementation of mathematical theories of chord space and neo-Reimannian operations, and scales and functional harmony, by Dmitri Tymoczko.

  • A collection of predefined Csound instrument definitions by me from CsoundAC.

  • Strudel, a JavaScript port of the widely used live coding system Tidal Cycles, by Alex McLean, Felix Roos, and others.

  • Of course, a standards-compliant Web browser, which has an awesome set of capabilities, including the most widely used programming language, JavaScript, which can call Csound, CsoundAC, and Strudel.

Design Notes

The integration between Csound and Strudel has been implemented without any changes to Strudel's source code. Instead, the Csound and CsoundAC APIs are exposed as global singletons in globalThis.csound and globalThis.csoundac. These are copied into the Strudel REPL's JavaScript context, also as globalThis.csound and globalThis.csoundac. This is permitted because the cloud-5 Web site and the Strudel REPL's IFrame have the same HTTP origin.

The cloud-5 build copies cloud-5 pieces, examples, tests, documentation, and other resources from the cloud-5 repository's root directory (cloud-5) to the Strudel submodule's Web root directory (cloud-5/strudel/website/dist) -- after building Strudel.

This means that cloud-5 becomes a completely static Web site hosted from cloud-5/strudel/website/dist.

It also means that any Strudel patch can import or access Csound, CsoundAC, or any JavaScript or other resource in the Web root.

Capabilities

  • High-resolution, sample-accurate sound synthesis using one of the largest and most capable libraries that exists for synthesis and signal processing, the Csound opcodes.

  • Interactive live music coding using the domain-specific, real-time music programming language Strudel; this includes a neat animated piano roll display of currently playing notes in the music.

  • Control of Csound from Strudel. This includes both real-time notes generated by Strudel patches for the csound and csoundn outputs, and real-time control channel values created by Strudel Patterns, including the new slider widget.

  • MIDI input and output from Csound and Strudel.

  • Open Sound Control input and output from Csound and Strudel.

  • Several systems for time-frequency analysis/synthesis, from Csound, including Victor Lazzarini's phase vocoder streaming (PVS) opcodes.

  • Several high-fidelity sample players, from Csound (Fluidsynth opcodes) and Strudel (superdough).

  • High-resolution, three-dimensional, animated computer graphics using WebGL and/or OpenGL Shader Language (GLSL), from the Web browser.

  • All of the staggering panoply of capabilities that are built into every standards-compliant Web browser, see HTML5 Test.

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 soundfiles directly to the filesystem on the user's computer.

However, in some cloud-5 pieces, the Csound orchestra supports not only rendering to the sandbox filesystem, but also automatically downloading the finished soundfile to the user's Downloads directory. This done using the Render button on the cloud-5 menu. However, the WebAssembly runtime sets a hard limit on the size of such soundfiles, which cannot exceed the size of the WebAssembly heap; pieces should probably not be more than about 10 minutes long.

It is also 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, and there is no hard limit to the size of the resulting soundfiles.

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:

  • Write user-defined opcodes (UDOs) in Csound that you can #include in any Csound orchestra.

  • Write a custom JavaScript module that you can use in any .html file; it must be served from cloud-5's Web root, i.e. ./my_file.mjs.

  • Write code in another high-level language and compile it for WebAssembly, so that it will run in any standards-compliant Web browser.

  • Subclass any of cloud-5's custom HTML elements, or create your own.

  • Adapt for your musical purposes any other software that can run in a Web browser and be controlled by JavaScript. That covers rather a lot of ground....

Contributing to cloud-5

  • Enter an issue in the cloud-5 GitHub repository: either a bug, or a feature request. It should briefly describe what you are going to contribute.

  • Make your own fork of the cloud-5 repository.

  • Make any contributions or changes in your fork.

  • Create a pull request in your fork. Reference the issue you have created.

  • I will review the pull request, and I will probably merge it if it does not break existing functionality, is in keeping with the general objectives of cloud-5, and builds and runs for me.

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; that includes a bundled version of Strudel.

Building

It's not necessary to build cloud-5 in order to run it, or to write new pieces for it. But if you want to build it, the fundamental assumptions of the build are:

  1. Absolutely no changes or patches are made to any code in the strudel directory of this repository. The cloud-5 build invokes the Strudel build, and once that has completed, the cloud-5 build copies pieces and other files from the cloud-5 root directory to Strudel's Web root directory (cloud-5/strudel/website/dist), and renames some files.

  2. The end product is a static cloud-5 Web site in cloud-5/strudel/website/dist. Once this site has been built, a composer can simply drop new pieces (.html files) into that directory, and they will run. At any time, this directory can be published as a public Web site.

The actual build steps are:

  1. Clone the cloud-5 GitHub repository.

  2. 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.

  3. Change to the cloud-5 directory.

  4. Execute pnpm install to update dependencies of cloud-5.

  5. Execute pnpm run setup to bring in the Strudel submodule.

  6. Execute pnpm run build to build Strudel and copy cloud-5 into strudel/website/dist.

  7. Execute pnpm run local to run a local Web site from your dist directory.

Running in NW.js

It also is possible to run cloud-5 pieces locally in NW.js using csound.nwjs. In this case, csound.node is a native addon for NW.js based on the Csound shared library, 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. Be sure to install the SDK version of NW.js.

  5. On macOS, follow the instructions here to disable the Gatekeeper for the nwjs app.

Running

You will need to create a package.json in the directory containing your piece, as a manifest for your piece as an NW.js app, in the following format:

{
  "main": "MyPiece.html",
  "name": "MyPiece",
  "description": "HTML5 with Csound",
  "version": "0.1.0",
  "keywords": [ "Csound", "node-webkit" ],
  "window": {
    "title": "MyPiece",
    "icon": "link.png",
    "toolbar": true,
    "frame": true,
    "maximized": true,
    "position": "mouse",
    "fullscreen": true
  },
   "chromium-args": "--enable-logging=stderr --v=1 --device-scale-factor=2 --allow-running-insecure-content"
}

Then, run NW.js with one parameter, the path to the directory containing your package.json file, e.g. on macOS:

/Applications/nwjs.app/Contents/MacOS/nwjs /Users/michaelgogins/cloud-5/strudel/website/dist

NOTE WELL: Do not overwrite the package.json file in the cloud-5 repository root directory! That is required for building cloud-5.

Release Notes

v2.0

  • Moved cloud-5's Web root directory from cloud-5 to cloud-5/strudel/website/dist. This makes it possible to integrate Strudel, Csound, and CsoundAC without any patches or other modifications of Strudel source code.

  • Added one-time singleton creation code for Csound and CsoundAC to csound_loader.js.

  • Simplified the integration of Csound, CsoundAC, and Strudel by ensuring that Csound and CsoundAC exist as fully initialized global objects in the JavaScript context (as globalThis.csound and globalThis.csoundac), before any HTML elements run.

  • Updated documentation for running cloud-5 pieces in NW.js.

v1.1

  • Made a clearer distinction between the Web site serving showcase for cloud-music pieces, and the README.md for the cloud-5 system.

  • Added a global menu with a curated list of better pieces.

  • Improved layouts to deal with presence/absence of global menu.

v1

  • Updated Csound, CsoundAC, and Strudel.

  • Edited README.md for clearer build instructions.

  • Added non-chord tones to csound::Scale when conforming notes to a
    Chord of the Scale.

  • Added Polymetric piece.

v1.0beta

  • Added cloud-5.js, cloud-5.css, example pieces, and my paper on using cloud-5. These greatly simplify writing cloud music pieces.

  • Various bug fixes ported from CsoundAC's Silencio score, used for the piano roll display.

  • Updated Csound, CsoundAC, and Strudel.

v0.2

  • Added Record and Pause button to Cloud Music No. 14, for the user to download a soundfile that records the performance using Csound's fout opcode.

  • Updated Csound, csound-wasm, and Strudel to current versions.

v0.1

  • Improved user interface and code organization in some pieces, making them more usable as templates for newer pieces.

  • Improved documentation.

  • Updated Csound, csound-wasm, and Strudel to current versions.

  • Pieces in cloud-5, including pieces using Strudel, can now also run locally in NW.js using csound.node.

v0.1beta7

  • Updated Csound to version 6.19.0.

  • Improved csound-wasm and the Cloud Music No. 9 example to support running either in NW.js with native Csound, or in Web browsers with Csound for WebAssembly. This makes it possible to compose pieces using Strudel that use native Csound, VST plugins, access to the local filesystem, and so on.

v0.1beta6

  • Introduced the CsoundAC track function, a variant of Strudel's arrange that does not crash when the number of cycles for a section is set to zero to silence it.

  • Improved the CsoundAC csoundn output to send all control parameters with names beginning gi or gk to Csound as control channel values; these channels must first be set up in the Csound orchestra with the same names.

  • Added cancyle.html, a piece designed for live performance by doing a modest amount of live coding during play.

v0.1beta5

  • Updated Strudel to get the extremely useful slider, which can be either discrete or continuous. The slider is embedded directly into the Strudel patch.

  • Added some code to csoundn that sends the value of any Strudel control registered with createParam and whose name begins with gi or gk to Csound as a control channel value. This also means that the new slider widget in Strudel can send its value to the Csound control channel.

v0.1beta4

  • Attempts have been made to correct the scheduling of the csoundn output based on a trigger, and to get csoundn to output correct piano roll events.

  • Put in diagnostic messages marked sync for testing.

  • Colorize notes in the piano roll that come from csoundn.

  • In package.json always make a releasable zip file in each build.

v0.1beta3

  • Put in needed patch for cyclist.mjs.

  • Restored concatenated Strudel controls string in csoundac.mjs.

v0.1beta2

  • Improved README.md/index.html.

  • Corrected broken links and incorrect credits in example pieces.

  • Replaced the favicon from Strudel with cloud-5's own favicon.

v0.1beta

  • This was the initial release.