Classes (extension) | Live Coding

# SuperDirt : Object
Extension

Synth and Sampler for the Tidal programming language
Source: SuperDirt.sc
See also: DirtOrbit, DirtEvent

## Description

This is a SuperCollider variant of Dirt, the sound engine for the Tidal http://tidalcycles.org/ programming language by Alex McLean. Most of SuperDirt can be rewritten at runtime: you can add and modify effects, synth defs, load samples incrementally, and spatialise to any number of channels. You can use SuperCollider as usual.

NOTE: This system is experimental.

Many examples can be found in the folders: `hacks/` and `scripts/`

The examples suppose that environment variables are accessible. If you want to use ProxySpace or similar redirect environments, see below.

// starting up ( // configure the sound server: here you could add hardware specific options // see http://doc.sccode.org/Classes/ServerOptions.html s.options.numBuffers = 1024 * 16; // increase this if you need to load more samples s.options.memSize = 8192 * 16; // increase this if you get "alloc failed" messages s.options.maxNodes = 1024 * 32; // increase this if you are getting drop outs and the message "too many nodes" s.options.numOutputBusChannels = 2; // set this to your hardware output channel size, if necessary s.options.numInputBusChannels = 2; // set this to your hardware input channel size, if necessary // boot the server and start SuperDirt s.waitForBoot { ~dirt = SuperDirt(2, s); // two output channels, increase if you want to pan across more channels ~dirt.loadSoundFiles; // load samples (path containing a wildcard can be passed in) s.sync; // wait for samples to be read ~dirt.start(57120, [0, 0]); // start listening on port 57120, create two orbits, each sending audio to channel 0. You can direct sounds to the orbits from tidal e.g. by: `# orbit "0 1 1" } ) // now you should be able to send from tidal via port 57120

## Class Methods

### SuperDirt.new(numChannels: 2, server)

Return a new instance, ready to be started

#### Arguments:

numChannels | The number of channels of the internal bus (this is also the maximal number of output channels).
server | Server to play on.

### SuperDirt.maxSampleNumChannels

### SuperDirt.maxSampleNumChannels = value

Specifies the maximum number of channels your sound files have (default is 2: stereo samples)

### SuperDirt.start(numChannels: 2, server, numOrbits: 12, port: 57120, senderAddr, path)

From extension in /Users/zzk/Library/Application Support/SuperCollider/downloaded-quarks/SuperDirt/classes/extSuperDirtStartup.sc

Convenience method that gives defaults for many situations. It configures the server and starts SuperDirt with a number of orbits. It allows you to pass a few parameters:

#### Arguments:

numChannels | The number of channels of the SuperDirt instance (see above).
server | Server to play on.
numOrbits | number of orbits to create on startup (see: DirtOrbit). You can add or remove them later.
port | The port to listen on (default is 57120)
senderAddr | The address to listen to (a String).
path | A path that is used to load some sound files. This is a string, a path pointing to a number of files, which usually contains a wildcard (`*`). E.g. `"~/samples/special/*"`

### SuperDirt.postTidalParameters(synthNames, excluding)

Post a string with the tidal language parameter definitions for a number of SynthDefs. Duplicates are removed automatically. Note that these all use `(Nothing)`, because defaults are defined in the SynthDef default arguments.

Example: `let (freq, _) = pF "freq" (Nothing)`SuperDirt.postTidalParameters([\default, \supercomparator])

#### Arguments:

synthNames | A symbol or array of symbols of the SynthDef names for which to generate the tidal code.
excluding | The parameter names which should be excluded. Names already defined and used internally by SuperDirt will be excluded in additinon tho these.

### Inherited class methods

### Undocumented class methods

### SuperDirt.default

### SuperDirt.default = value

### SuperDirt.postBadValues

### SuperDirt.postBadValues = value

### SuperDirt.predefinedSynthParameters

### SuperDirt.resetEverything

### SuperDirt.tidalParameterString(keys)

## Instance Methods

### .orbits

### .orbits = value

A list of DirtOrbits. Orbits are the basic elements of dirt. Each has its own global effects and global settings. You can start any number of orbits any time. From tidal, you can direct sounds into an orbit by the parameter: `# orbit "7"` (this sends to orbit 7, if it exists, otherwise it'll wrap to whatever is available.)// in the default startup, dirt is kept in the ~dirt environment variable // you can access the orbit by index: ~dirt.orbits[0].set(\amp, 0.1) // reduce the amplitude of one orbit // make a mixer for the orbits, using dB scaling ( var w, spec; spec = \db.asSpec; w = Window("orbital volume", Rect(240, 240, 300, 500)).front; w.view.layout = HLayout(*~dirt.orbits.collect { |x| var val = spec.unmap(x.get(\amp).ampdb); Slider().value_(val).action_({ |v| x.set(\amp, spec.map(v.value).dbamp.postln) }) }); )

### .loadSoundFiles(paths, appendToExisting: false, namingFunction)

Read a number of sound file from disk and load them into the server memory. The buffer information is also kept in buffers, a dictionary. You can do this any time while running, and incrementally add more files. ~dirt.loadSoundFiles("<your sound file path>");

NOTE: The naming scheme works as follows:

Given a path like: `"path/to/my/basedrum/*"`.

The dictionary will contain under the key `'basedrum'` an Array of all the Buffers from the samples found in the folder.

From tidal, they can be accessed e.g. by `d1 $ sound $ "basedrum:1 basedrum:4"`, or alternatively by the `n` parameter. Sample numbers below zero or above the number of samples in the folder will wrap, i.e. if you have a folder of 4 samples, 5 will play 0.

#### Arguments:

paths | Specifies paths for sound files. This is a string, a path pointing to a number of files, which usually contains a wildcard (`*`). E.g. `"~/samples/special/*"`. For the glob syntax, see https://en.wikipedia.org/wiki/Glob_%28programming%29. Alternatively, you can pass in an Array of full paths, e.g. `["~/samples/drums/", "~/samples/cats/"]`.
appendToExisting | If set to true, this will keep existing dictionary keys (see above) and add the new samples to any existing ones. This allows you to load different folders with the same name. Otherwise it will only keep those existing names which are not found in the new set of samples.
namingFunction | Provide a function to generate your own instrument names, which you call from tidal. The function is passed the folder path (a String). By default, this function is `_.basename`, which returns the folder name.

### .loadSoundFileFolder(folderPath, name, appendToExisting: false)

Read a single folder of sound files and add all of them under `'name'` to the sample instruments. You can do this any time while running, and incrementally add more files.

#### Arguments:

folderPath | The path for the folder.
name | The name of the sample instrument as it will be used in tidal. Subsequent sound files can be addressed by passing the "n" parameter, e.g. `"bd:1 bd:2"`.
appendToExisting | See: -loadSoundFiles ~dirt.loadSoundFileFolder(Platform.resourceDir +/+ "sounds/", \teletubbies); // play them in tidal with "teletubbies" // play from sclang (type: \dirt, dirt: ~dirt, sound: "teletubbies:2", speed: 0.5, n: 0).play; (type: \dirt, dirt: ~dirt, sound: "teletubbies:2", speed: 0.5, n: 1).play; // play from sclang

### .loadSoundFile(path, name, appendToExisting: false)

Read a single sound file and add it under `'name'` to the sample instruments. You can do this any time while running, and incrementally add more files.

#### Arguments:

path | The path for the file.
name | The name of the sample instrument as it will be used in tidal
appendToExisting | See: -loadSoundFiles ~dirt.loadSoundFile(Platform.resourceDir +/+ "sounds/a11wlk01.wav", \a11); // play them in tidal with "a11" ~dirt.buffers[\a11]; (type: \dirt, dirt: ~dirt, sound: "a11", speed: 0.5).play; // play from sclang

### .loadOnly(names, path, appendToExisting: false)

Read a number of named folders. You can do this any time while running, and incrementally add more files.

#### Arguments:

names | An array of symbols or strings. These are folder names and at the same time instrument names for tidal.
path | The path in which the folders can be found.
appendToExisting | See: -loadSoundFiles ~dirt.loadOnly([\bd, \moog, \hh, \cp]);

### .freeSoundFiles(names)

Remove sound files and free their memory.

#### Arguments:

names | An array of sample instrument names which to remove. ~dirt.postSampleInfo; ~dirt.freeSoundFiles([\bubble]); ~dirt.postSampleInfo; // now, the bubbles should be gone.

### .freeAllSoundFiles

Remove all sound files and free their memory.

### .fileExtensions

### .fileExtensions = list

A list of valid sound file extensions, which can be extended (default: `["wav", "aif", "aiff", "aifc"]`). In theory, all libsndfile formats should be supported http://www.mega-nerd.com/libsndfile/#Features.

### .postSampleInfo

Post a list of all existing sample names, the number of variants, the range of durations, and memory requirement.

e.g.

`circus (3) 0.17 - 0.52 sec (171 kB)`. ~dirt.postSampleInfo

### .loadSynthDefs(path)

Load a number of files, usually containing SynthDefs.

#### Arguments:

path | This is a string, a path pointing as´file or a to a number of files, which then contains a wildcard (`*`). E.g. `"~/synths/special/*"`

### .start(port: 57120, outBusses, senderAddr)

This method starts SuperDirt. It creates a number of DirtOrbits (each of which has global effects, output busses, and settings). It also opens a network connection.

#### Arguments:

port | The port to listen on (default is 57120)
outBusses | An (a Array) of audio output channels: it determines how many DirtOrbits there will be.
senderAddr | The address to listen to (a String).

### .stop

End all audio processes and close network responder.

### .free

End all audio processes, close network responder, and free sound file resources.

### Inherited instance methods

### Undocumented instance methods

### .addFilterModule(synthName, synthFunc, test)

### .addModule(name, func, test)

### .audioRoutingBusses

### .audioRoutingBusses = value

### .buffers

### .clearModules

### .closeNetworkConnection

### .connect(argSenderAddr, argPort)

### .controlBusses

### .controlBusses = value

### .dropWhen

### .dropWhen = value

### .getModule(name)

### .handshakeReplyData

### .initRoutingBusses

### .initVowels(register)

### .makeOrbits(outBusses)

### .maxLatency

### .maxLatency = value

### .modules

### .modules = value

### .numChannels

### .numControlBusses

### .numControlBusses = value

### .numRoutingBusses

### .numRoutingBusses = value

### .orderModules(names)

### .port

### .receiveAction

### .receiveAction = value

### .removeModule(name)

### .replyAddr

### .sendToTidal(args)

### .senderAddr

### .server

### .set( ... pairs)

### .setControlBus( ... pairs)

### .soundLibrary

### .soundLibrary = argSoundLibrary

### .startSendRMS(rmsReplyRate: 20, rmsPeakLag: 3)

### .stopSendRMS

### .verbose

### .verbose = bool

### .vowels

### .warnOutOfOrbit

### .warnOutOfOrbit = value

## Using SuperDirt examples together with ProxySpace

All startup files and examples use the environment variables, like `~dirt`. If you want to use ProxySpace or similar redirect environments, you should bind these to their respective file (which needs to be saved to disk):p = ProxySpace.push(s).linkDoc; // now the proxyspace is only active in that document

helpfile source: /Users/zzk/Library/Application Support/SuperCollider/downloaded-quarks/SuperDirt/HelpSource/Classes/SuperDirt.schelp
link::Classes/SuperDirt::