User Manual

Undertone Generative Music System Manual

This manual provides an overview of the concepts underlying the Undertone generative music system, and describes some common workflows for managing content and generating soundscapes.

Undertone is first and foremost a generative sequencing and arrangement tool for various styles of music. It takes raw audio material in the form of Layers (single-shot samples and stems tracks), and various compositional and production oriented Attributes, and generates music out of them using the algorithmic rules embodied by a particular Engine.

This management user interface allows you to browse and administer the raw materials used by Undertone, and to generate music based on them.

There are two primary ways to use Undertone:

  1. To pre-generate tracks for use elsewhere. In this mode, you use Undertone to generate and export tracks as audio files for use outside of the system itself.
  2. To administer real-time generative music. In this mode, you manage audio streams generated in real time and heard directly by end users. Typically the music is generated by an Undertone runtime embedded in a mobile app, or one running on a server in a customer's server room.

Working Hygiene

When administering real-time generative music, it is important to understand that the changes you make in this system have direct consequences to the listening experience of end users. With this in mind, please adhere to the following general guidelines.

Audition Everything

There are track generation features embedded in all Layer, Attribute, and Genre editor pages. Use them whenever you create or modify something. Listen to your work not just in the context of a single generated track, but several of them. This will help you understand the range of possibilities that your changes introduce.

Keep Layers and Attribute In Draft State Until They Are Ready

For a Layer or an Attribute to be heard by end users, it must satisfy two conditions:

  1. Its status needs to be set to Live.
  2. It needs to be linked to at least one public-facing Genre.

So keep your content in a non-Live state until its ready. Alternatively, you can set it Live but refrain from linking it to a published Genre until you are ready.

Run Experiments Within Your Own Genres

Create your own Genres to experiment with. Link any experimental Layers and Attributes only to those Genres. Genres that are not linked to any public-facing playlist are safe to experiment with, since they are not heard by end users.

Concepts

Engines

An Engine implements an algorithm for generating a specific kind of music, e.g. "Ambient Electronic Stasis" of "Lo-Fi Hip Hop". Each Engine has a set of parameters that can be adjusted to control the nuances of the generated music.

You use an Engine by creating a Genre based on it.

Engines are created by the development team and are not user-editable through this interface.

Layers

A Layer is an audio file, or a collection of multiple audio files, that comprises raw source material in the form of a single-shot sample, stem track, or a full linear track.

There are various kind of Layers that differ in their content and their use, e.g. "Ambient Loop" and "Drum". See below for a reference.

You can browse, create, and manage Layers through the Layers page.

You use Layers by linking them to a Genre, which will allow the Engine running that Genre to use them as it generates Tracks.

Attributes

An Attribute embodies some characteristic of music that is not an audio file, but some other form of structured data. This might be a compositional attribute (e.g. a chord progression or a groove) or a production attribute (e.g. a reverb setting).

You can browse, create, and manage Attributes through the Attributes page.

Similar to Layers, you use Attributes by linking them to a Genre.

Genres

A Genre is a conglomeration of

  1. An Engine
  2. A set of Layers
  3. A set of Attributes

that together defines a generative space of music.

Genres are the central unit of music creation in Undertone, i.e. every generated Track is a track in a Genre.

Whenever a Track is generated, the Engine selects an assortment of Layers and Attributes from those linked to the Genre. This means that the same Engine may be used in different Genres for different musical results by virtue of having a different set of associated Layers and Attributes.

The number and variety of different Layers and Attributes linked to a Genre determines the generative variety of that Genre. A Genre with very few Layers and Attributes will generate more or less the same music every time, whereas a Genre with many Layers and Attributes can generate a wide variety of music.

You can browse, create, and manage Genres through the Genres page.

Tracks

A Track is an audio file generated by an Engine in a Genre. Tracks may be pre-generated and exported as audio files through this user interface, or generated in real time on end user devices by embedded Undertone runtimes.

A Genre can produce an infinite number of Tracks. Tracks are considered ephemeral and are not stored by the system. If you want to keep a specific Track, save it as an audio file yourself.

Playlists

A Playlist is a finite or infinite sequence of Tracks, defined by a specific configuration of Genres. Playlists are typically used in real-time listening contexts, to provide a continuous stream of music to end users. If you are only pre-generating tracks, you don't need a Playlist.

A Playlist may be a linear, specific sequence of Genres. It may also be a randomised sequence. Or it may be parameterised based on attributes such as time of day.

Some Playlists comprise of more than one Lane (A "Track" lane and a "Background" lane), where the "Track" lane is the primary music and the "Background" lane is a soundscape that plays underneath the primary music. This is used for cases where the music and the soundscape are of different Genres and play with different timing rules.

You can browse and edit Playlists and generate Tracks from them through the Playlists page.

Access Levels

The data you can see and operations you can do in Undertone are determined by your access level. There are three access levels:

  • As a System Admin you can do everything and see all data.
  • As an Account Owner you can do everything but only in the context of specific clients. You cannot see or modify the Genres and Playlists of other clients - and conversely, they cannot see or modify yours.
  • As a Creator you can contribute Layers and Attributes, and associate them with the Genres of those clients you have access to. You cannot modify Genres, nor can you directly set anything to the Live status. What you can do is submit your work for review by an Account Owner or System Admin, who will make the final decision to publish it as Live or to request changes.

Common Workflows

Generating Tracks

To print and export tracks of a Genre, simply navigate to the Genre's page in the Genres section, and click the "Render Audio" button. You can generate, review, and export as many tracks as you need. The tracks will be in WAV format when downloaded.

You can also navigate to a Playlist in the Playlists section and generate tracks from there. This can be useful if you need the specific duration or parameterisation of a track that is defined in the context of a certain playlist.

When you download a track, you can choose to either download the mastered stereo mixdown, or individual stereo stem packs (background, bass, harmony, melody, drums).

Please note that when you download stems, they will not be mastered, meaning that they will not have the genre's Master Volume gain applied, nor the Master Compressor or saturation.

To generate Tracks with varying mix levels or fade times, click the Edit button on a Genre's page. Here you can adjust the mix, fade, and other parameters on the form and use the Preview feature on the bottom of the form to render and download tracks with the adjusted settings. You don't need to save the settings before rendering, and indeed should not save them if it is a temporary adjustment to a Genre that has already been published.

Contributing a Layer

  1. Find the Genre you would like to contribute to in the Genres section.
  2. Locate the Layers tab, and find the layer type you are contributing.
  3. Click the Add new button for that layer type.
  4. Upload the audio file(s) for the layer.
  5. Fill in all the required metadata for the layer.
  6. If you'd like the layer to be associated with any other Genres than the one you started from, you can add them in the Genres section.
  7. Audition the layer by using the Render Preview feature. Listen to it in at least a handful of different generated tracks, and make any necessary volume and other adjustments if it doesn't sound right.
  8. Save the layer:
    • If you are a Creator, you can either save it as Draft (if it's not ready yet) or Submit it for Approval if it's ready to be reviewed.
    • If you are an Account Owner or System Admin, you can Submit and Approve it immediately, or save it as Draft if you need to come back to it later.

Contributing an Attribute

  1. Find the Genre you would like to contribute to in the Genres section.
  2. Locate the Attributes tab, and find the attribute type you are contributing.
  3. Click the Add new button for that attribute type.
  4. If the attribute has a MIDI file, upload it.
  5. Fill in all the required metadata for the attribute.
  6. If you'd like the attribute to be associated with any other Genres than the one you started from, you can add them in the Genres section.
  7. Audition the attribute by using the Render Preview feature. Listen to it in at least a handful of different generated tracks, and make any necessary adjustments if it doesn't sound right.
  8. Save the attribute:
    • If you are a Creator, you can either save it as Draft (if it's not ready yet) or Submit it for Approval if it's ready to be reviewed.
    • If you are an Account Owner or System Admin, you can Submit and Approve it immediately, or save it as Draft if you need to come back to it later.

Creating a New Genre

  1. Go to the Genres section.
  2. Click the New Genre button.
  3. Enter a name for the Genre.
  4. Select the Client for the Genre, or select "None" if it is not to be published with any client.
  5. Select the Engine for the Genre. See the Engine Reference below for more information.
  6. Enter the Engine specific parameters for the Genre. If you are unsure about any of them, the default values are usually a good starting point.
  7. Click "Create Genre"
  8. On the Genre page, locate the Layers and Attributes sections to understand which Layers and Attributes are used by the Engine of this Genre.
  9. Add new Layers and Attributes by using the "Add new" buttons, or associate already existing Layers and Attributes with the Genre by finding them in the Layers and Attributes sections, editing them, and adding your new Genre to the Genres list on the form.
  10. Audition the Genre by using the "Render Preview" feature on the bottom of the various forms. Note that most Attributes and Layers that are listed on the Genre pages are in fact required by the respective Engine, so you will need to add at least one of each type to be able to hear meaningful generated results.

Engine Reference

Undertone currently implements the following Engines. Each one implements a different algorithm for generating music, and requires a different set of Layers and Attributes.

Ambient Electronic Chords

Ambient music consisting of slow sampled pads following a chord progression, overlaid with sparse sampled melodic elements, high sustains, risers, fallers, and background ambiences.

Ambient Electronic Stasis

Ambient music consisting of a single, harmonic, looping drone, overlaid with slow sampled pads, synthesised and/or sampler-based bass, and background ambiences.

Ambient Guitar

Music in the "ambient guitar" style, consisting of a single pre-mixed track overlaid with a kick drum pulse, high sustains, risers, background brown noise, and background ambiences.

Ambient Keyboard Improv

Ambient music consisting of a sampled keyboard instrument (usually a piano) slowly improvising over a chord progression, overlaid with background ambiences.

Ambient Looping Mixer

Ambient music consisting of several layers of looped ambient material, usually drones, pads, and melodic stems. Plays up to four layers simultaneously — categorised as low, low-mid, high-mid dronal, and high-mid melodic — though a minimal Genre may omit some. May also include a synthesised binaural beats drone, single-shot pitched ornaments, background soundscapes, and track transition / bridging elements.

Keyboard Composition

Ambient music consisting of a sampled keyboard instrument playing a pre-defined MIDI note sequence (typically a classical piano composition), overlaid with background ambiences.

Disco Loop

Energetic music in a "French filter house" style, consisting of a single structured harmonic loop — typically sampled from disco music — and a sampled bass instrument playing a bassline composed for that loop, played over a drum track of top loops, kicks, shakers, rides, and cymbals.

Energy Stack

Energetic music consisting of a stack of structured stems designed to work together (one or two chord stems, one or two melodic stems, a bass stem, and ornamental stems), played over a drum track of top loops, kicks, shakers, rides, and cymbals, overlaid with background ambiences.

Linear Mixer

Music consisting of either a stack of stem tracks mixed linearly (all with the same duration, playing simultaneously) or a single pre-mixed track.

Structured Looping Mixer

Music consisting of a stack of structured stems designed to work together (one or two chord stems, one or two melodic stems, a bass stem, ornamental stems, and drum stems), ornamented with additional percussion (cymbals, fills), and optionally overlaid with brown noise or a nature soundscape.

Note: The "Stem Stack" layer type used in this video is now called the "Stem Loop Stack" layer type.

Nature Soundscape

A standalone non-musical nature soundscape track, consisting of one to three of biophony, geophony, and anthrophony layers.

Silence

Produces silent output. Useful for including in Playlists where silence is needed at specific points or at specific times of day. May also generate accurate reproductions of "4'33" by John Cage.

Structured Ambient

Structured, evolving ambient music built from harmonically compatible pad, bass, and driver stems at a fixed tempo, with optional drums that may enter late or run throughout. Layered with sustained, melodic, and percussive ornaments and background soundscapes, and shaped by intro fades and breakdown sections.

Layer Reference

The following types of Layers are currently supported by Undertone. Each Layer type has a different set of metadata. To understand which Layer types are used by a particular Genre, please refer to the Genre's page in the Genres section.

Background Layers

Seamlessly looped non-musical ambiences, typically 1-3 minutes in duration. Used to create background atmospheres by many Engines.

Subtypes:

  • Geophony — Sounds of the Earth, e.g. wind, rain, water, fire.
  • Biophony — Sounds of living organisms, e.g. birds, insects, frogs.
  • Anthrophony — Sounds of human activity, e.g. traffic, machinery, voices.
  • Segue — Sounds designed as transitions to bridge over two consecutive Tracks in a Playlist.
  • Brown Noise — A type of noise whose spectral density decreases with frequency. Often overlaid with other sounds (e.g. anthrophonic).
  • Texture — A textural background element sprayed intermittently as short grains, adding subtle movement and detail beneath the main soundscape.

Ambient Loop Layers

Seamlessly looped, harmonic, ambient material, typically 1-3 minutes in duration. Used to create ambient music by several Engines.

Subtypes:

  • Harmonic Drone — Harmonic material consisting of drones or slow pads.
  • Background Drone — Harmonic material designed to fade into the background as added texture.
  • Melodic — Melodic material.
  • Granulator Texture — A looped source for granular synthesis: the Engine slices it into overlapping grains to produce an evolving, atmospheric harmonic texture.

Structured Loop Layers

Seamlessly looped, harmonic material of a specific number of bars in duration at a specific tempo. Used by several non-ambient Engines.

Subtypes:

  • Chord Loop — A loop of harmonic material, e.g. a snippet of a disco track.

Linear Track Layers

A full linear track, typically several minutes in duration. Used by the Linear Mixer and a few other Engines.

Subtypes:

  • Full Track — A full, pre-mixed, standalone track.
  • Stem Track — A stem or a submix of a track.

Sampler Layers

A collection of single-shot samples comprising a "sound font" of a specific instrument played at various pitches. Used by several Engines to make melodies, pads, basslines, and the like.

Subtypes:

  • Bass — A bass instrument.
  • Lead — A lead instrument.
  • High Sustain — A high sustain instrument such as a held high synth or violin note. Usually seamlessly looped to support arbitrary durations.
  • Pad — A pad instrument.
  • Arp — An instrument suitable for arpeggio lines. Usually a short synth sound.
  • Keyboard Melody — A keyboard instrument for melodic ("right hand") playing. Often a piano.
  • Keyboard Chords — A keyboard instrument for chords ("left hand") playing. Often a piano.
  • Keyboard Release — Key-release samples for a keyboard instrument — the short sounds of keys and dampers releasing, layered under a keyboard performance for added realism.

Transition Layers

Single-shot samples designed to be used as transitions to tie together different sections of a track.

Subtypes:

  • Riser — A sound that marks a rise in energy.
  • Faller — A sound that marks a fall in energy.
  • Tempo Increase — A transition sound accompanying an increase in tempo, used to bridge into a faster section.
  • Tempo Decrease — A transition sound accompanying a decrease in tempo, used to bridge into a slower section.
  • Mega Riser — A long riser that can be used to build up energy over a sustained breakdown section.

Single Shot Layers

Pitched, single-shot samples.

Subtypes:

  • Pitched Ornament — An ornamental sample comprising harmonic material (a single note or a chord). Could be a vocal, a chime, or a bell.
  • Pitched Spray — A pitched sample sprayed intermittently as an ornament, the Engine scattering individual hits at irregular intervals over the soundscape.

Drum Single Shot Layers

Non-pitched, single-shot percussive samples.

Subtypes:

  • Kick — A kick drum sample.
  • Snare — A snare drum sample.
  • Dub Snare — A snare drum sample with a long reverb tail or delay effect, used for ornamentation.
  • Ride — A ride cymbal sample.
  • Cymbal — A crash cymbal sample.
  • Cymbal Layer — A sound designed to be layered with other cymbal sounds, e.g. a white noise sweep.
  • Reverse Cymbal — A reverse crash cymbal sample.
  • Shaker — A shaker or tambourine sample.
  • Fill — A percussive sample used for drum fills between sections of a track.
  • Ornament — A single-shot percussive ornament used to embellish the drum track.

Drum Slices Layers

A sequence of drum samples, sliced up from a loop, supporting recombination for different grooves and tempos.

Subtypes:

  • Percussion Loop Slices — A sliced up shaker, tambourine, or other percussive loop.
  • Build-Up Snare Stages — A sequence of snare drum samples increasing in energy, used for build-up sections.

Drum Loop Layers

A full drum loop, one or several bars in duration at a specific tempo.

Subtypes:

  • Top Loop — A drum loop consisting of tops, e.g. hi-hats and claps. Ideally with no kick included.
  • Full Loop — A full drum loop, including tops, kicks, and snares.

Stem Loop Stack Layers

A collection of structured looped stems designed to work together well, all at the same tempo and harmonically compatible.

Layer types:

  • Drums — A drum stem loop.
  • Drums Intro — A drum stem loop only to be used in an intro section of a track.
  • Drums Main — A drum stem loop only to be used in a non-intro section of a track.
  • Noise — A white / other noise stem loop.
  • Bass — A bass stem loop.
  • Chords Primary — A primary chords stem loop.
  • Chords Primary Intro — A primary chords stem loop only to be used in an intro section of a track.
  • Chords Primary Main — A primary chords stem loop only to be used in a non-intro section of a track.
  • Chords Secondary — A secondary chords stem loop. Often used by an Engine to create more energy at or after a build-up.
  • Melodic Primary — A primary melodic stem loop.
  • Melodic Primary Intro — A primary melodic stem loop only to be used in an intro section of a track.
  • Melodic Primary Main — A primary melodic stem loop only to be used in a non-intro section of a track.
  • Melodic Secondary — A secondary melodic stem loop. Often used by an Engine to create more energy at or after a build-up.
  • Strings — A strings / high sustains stem loop.
  • Bleeps — A bleeps / ornamental stem loop.
  • Tops — A tops / percussion stem loop.
  • Riser Primary — A riser.
  • Riser Secondary — A riser.
  • Faller — A faller.
  • Pitched Ornament — A pitched ornament.
  • Cymbal — A cymbal crash.

Note: This layer type was formerly called the "Stem Stack" layer type.

Linear Stem Stack Layers

A collection of structured stems designed to work together well, all at the same tempo and harmonically compatible. Used exclusively by the Linear Mixer Engine.

Layer types:

  • Background — A background soundscape stem.
  • Drums — A drum stem.
  • Bass — A bass stem.
  • Chords Primary — A primary chords stem.
  • Chords Secondary — A secondary chords stem.
  • Melodic Primary — A primary melodic stem.
  • Melodic Secondary — A secondary melodic stem.
  • Tops — A tops / FX / percussion stem.

Attribute Reference

The following types of Attributes are currently supported by Undertone. Each Attribute type has a different set of metadata and is used to control a different aspect of the music generated by an Engine.

To understand which Attributes are used by a particular Genre, please refer to the Genre's page in the Genres section.

Reverb Preset

A reverb preset controlling the settings of a reverb effect included in an Engine. Supports both plate and FDN reverb algorithms.

Shaker Pattern

A MIDI file providing a looping shaker or tambourine pattern. Should use the Shaker general MIDI instrument (MIDI note 69).

Ride Pattern

A MIDI file providing a looping ride cymbal pattern. Should use the Ride general MIDI instrument (MIDI note 51).

Kick Pattern

A MIDI file providing a looping kick drum pattern. Should use the Kick general MIDI instrument (MIDI note 36).

Fill Pattern

A MIDI file providing a snare fill pattern. Should use the Snare general MIDI instrument (MIDI note 37 or 64).

Bass Pattern

A MIDI file providing a looping bassline pattern.

Bass Movement

Settings for how the bassline of a track moves from note to note in pitch space. Supports two modes: Follow Chords (the bassline follows the chord progression, restricted to chosen chord tones) and Follow Scale (it follows chosen scale degrees of the track's key, optionally favouring chord tones).

Chord Progression

A sequential list of chords forming a chord progression, expressed as fully voiced chords in a specific key and mode. An AI assistant is available to generate chord progressions from text prompts.

Onset Pattern

A sequential numeric list specifying the number of notes triggered at successive sixteenth notes. Used for keyboard accompaniment (left-hand arpeggios and broken chords) or ornament placement (how many ornaments to trigger at each sixteenth). E.g. repeating `1 - 1 - 1 - 1` is a simple arpeggio; non-repeating `3` plays three chord notes together at the start of each bar.

Harmonic Rhythm Pattern

A sequential list of numbers giving the duration, in bars, of each chord in a chord progression. May differ in length from the chord progression, in which case the two lists cycle against each other to form a more complex structure.

Meter Pattern

A sequential list of numbers defining both the meter and the metric accentuation of a track. Each number is the velocity of a beat (0 silent, 1 loudest); the total length of the list is the number of sixteenth notes in a bar.

Binaural Beats Drone Preset

A preset controlling a synthesised binaural beats drone generated by an Engine. It specifies the range of difference frequencies produced; the base frequency is determined by the key of the track.

Noise Preset

A preset controlling a synthesised noise generator included in an Engine, specifying the type of noise generated (white, pink, or Brownian).

Granulator Preset

Settings for the granular-synthesis engine that reworks a Granulator Texture ambient loop into an evolving atmosphere. Controls the grain size (in milliseconds) used when slicing the source into overlapping grains.

Texture Spray Preset

Settings for a texture spray generator that scatters short grains of a Texture background layer over time. Controls the random interval and duration ranges (in milliseconds) between and of grains, their attack and release envelopes, the stereo panning range, and the number of concurrent buffers.

Timing Humanisation Preset

A range of numbers controlling, in milliseconds, how much the timing between consecutive notes should be varied to humanise a track and make it sound less mechanical.

Groove

A MIDI file providing a rhythmic Groove for a track. Should be a succession of sixteenth notes; deviations from the 16th-note grid drive timing humanisation and the note velocities drive dynamic humanisation.

Keyboard Composition

A MIDI file of a fixed keyboard performance (typically a classical piano composition) played back by a sampled keyboard instrument. Specifies the playback tempo and a transposition in semitones.

Melody Composition

A MIDI file of a composed melody, tied to a specific key and mode, with an associated meter and optional chord progression and harmonic rhythm. Specifies the duration in bars, the number of voices, and whether it plays as a one-shot linear phrase or a loop.

EQ Preset

A preset for a two-filter parametric equaliser, controlling the filter types, cutoffs, gains, and Q factors. May be applied to the master track or to individual instrument groups; its target is controlled by tagging.

Bass Synth Preset

Envelope and tone colour settings for a synthesised sub-bass instrument provided by some Engines.

Timeline

A sequence of sections and their durations (in bars) that define the structure of a track.

Lane Timeline

A per-track temporal form for an ambient-looping-mixer genre's author-defined lanes: a mapping from lane names to fade envelopes. A genre may link several forms; the composer picks one per track, so linking more than one gives per-track variety. A lane the form omits is dropped from that track entirely, so a form can vary instrumentation as well as timing. Lane names must match lanes defined in every linked genre. When a genre links no form, every lane plays a full-length default envelope — so lanes do not stagger or crossfade — making staggered form something you author here rather than a built-in default.

Compressor Preset

A compressor preset controlling a master bus compressor. When included, it is applied as a final mastering pass on the mixed output of the Engine.

Delay Preset

A preset for a stereo feedback delay added to a layer's audio chain. The delay time may be tempo-relative, may run in straight stereo or ping-pong mode, and includes an adjustable bandpass filter in the feedback path.

Chorus Preset

A preset for a multi-voice chorus effect added to a layer's audio chain, controlling the modulation rate and depth, base delay, feedback, wet/dry mix, number of voices, and stereo spread.

Phaser Preset

A preset for a phaser effect added to a layer's audio chain, controlling the modulation rate and depth, the centre frequency and sweep range of the all-pass stages, the number of stages, feedback, and wet/dry mix.

LFO Preset

A preset for a low-frequency oscillator that modulates a layer's amplitude and/or its dry and reverb sends over a set period (in seconds). Each target has its own activation, phase offset, and depth.

Envelope

An ADSR amplitude envelope applied to a sampled instrument's notes, with attack, decay, sustain, and release, plus a min/max articulation range that randomises note lengths for a more human feel.

Tempo Steps Control

A live control exposing a set of discrete tempo steps that a listener (or app UI) can switch between at runtime. Specifies the control id, the available tempo values, a default, and the number of bars over which tempo changes are quantised.

Mixer Control

A live control exposing a continuous 0-1 parameter that a listener (or app UI) can adjust at runtime, mapped to one or more mix targets — group or master gain, filtering, or reverb sends.

Voicing Evolution

A description of how the harmonic voicing density of a track evolves over its duration, as a sequence of phases each spanning a percentage range of the track and specifying a density (sparse, building, full, thinning, or pause).

Constrained Timing

A timing attribute expressing a uniform-random gap between triggers, quantised to a musical grid, with an optional density LFO. Grid Unit sets the grid in beats (most Engines count beats as sixteenth notes, so 16 is one bar); Min/Max Gap bound the gap drawn uniformly between triggers; LFO Period (seconds) optionally modulates the gap centre and LFO Phase (degrees) staggers multiple lanes against each other.