Skip to content

Latest commit

 

History

History
510 lines (363 loc) · 21.8 KB

README.md

File metadata and controls

510 lines (363 loc) · 21.8 KB
Raw

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

  • 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, 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

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

  • Strudel REPL, exactly the same as the main Strudel Web site.

  • 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. Note: cloud-5 makes several necessary patches to the Strudel source code and distribution.

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

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 csoundm 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 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:

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

  • 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 (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

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