Skip to content

cloud-5 version 1

Latest
Latest
Compare
Choose a tag to compare
@gogins gogins released this 15 Nov 20:35
v1
8afde41

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.
Assets 3
Loading