1# superdough
2
3superdough is a simple web audio sampler and synth, intended for live coding.
4It is the default output of [strudel](https://strudel.cc/).
5This package has no ties to strudel and can be used to quickly bake your own music system on the web.
6
7## Install
8
9via npm:
10
11```js
12npm i superdough --save
13```
14
15## Use
16
17```js
18import { superdough, samples, initAudioOnFirstClick, registerSynthSounds } from 'superdough';
19
20const init = Promise.all([
21  initAudioOnFirstClick(),
22  samples('github:tidalcycles/dirt-samples'),
23  registerSynthSounds(),
24]);
25
26const loop = (t = 0) => {
27  // superdough(value, time, duration)
28  superdough({ s: 'bd', delay: 0.5 }, t);
29  superdough({ note: 'g1', s: 'sawtooth', cutoff: 600, resonance: 8 }, t, 0.125);
30  superdough({ note: 'g2', s: 'sawtooth', cutoff: 600, resonance: 8 }, t + 0.25, 0.125);
31  superdough({ s: 'hh' }, t + 0.25);
32  superdough({ s: 'sd', room: 0.5 }, t + 0.5);
33  superdough({ s: 'hh' }, t + 0.75);
34};
35
36document.getElementById('play').addEventListener('click', async () => {
37  await init;
38  let t = 0.1;
39  while (t < 16) {
40    loop(t++);
41  }
42});
43```
44
45[Open this in Codesandbox](https://codesandbox.io/s/superdough-demo-forked-sf8djh?file=/src/index.js)
46
47## API
48
49### superdough(value, deadline, duration)
50
51```js
52superdough({ s: 'bd', delay: 0.5 }, 0, 1);
53```
54
55- `value`: the sound properties:
56  - `s`: the name of the sound as loaded via `samples` or `registerSound`
57  - `n`: selects sample with given index
58  - `bank`: prefix_ that is attached to the sound, e.g. `{ s: 'bd', bank: 'RolandTR909' }` = `{ s: 'RolandTR909_bd' }`
59  - `gain`: gain from 0 to 1 (higher values also work but might clip)
60  - `velocity`: additional gain multiplier
61  - `cutoff`: low pass filter cutoff
62  - `resonance`: low pass filter resonance
63  - `hcutoff`: high pass filter cutoff
64  - `hresonance`: high pass filter resonance
65  - `bandf`: band pass filter cutoff
66  - `bandq`: band pass  filter resonance
67  - `crush`: amplitude bit crusher using given number of bits
68  - `distort`: distortion effect. might get loud!
69  - `pan`: stereo panning from 0 (left) to 1 (right)
70  - `phaser`: sets the speed of the modulation
71  - `phaserdepth`: the amount the signal is affected by the phaser effect.
72  - `phasersweep`: the frequency sweep range of the lfo for the phaser effect.
73  - `phasercenter`: the amount the signal is affected by the phaser effect.
74  - `vowel`: vowel filter. possible values: "a", "e", "i", "o", "u"
75  - `delay`: delay mix
76  - `delayfeedback`: delay feedback
77  - `delaytime`: delay time
78  - `room`: reverb mix
79  - `size`: reverb room size
80  - `orbit`: bus name for global effects `delay` and `room`. same orbits will get the same effects
81  - `freq`: repitches sound to given frequency in Hz
82  - `note`: repitches sound to given note or midi number
83  - `cut`: sets cut group. Sounds of same group will cut each other off
84  - `clip`: multiplies duration with given number
85  - `speed`: repitches sound by given factor
86  - `begin`: moves beginning of sample to given factor (between 0 and 1)
87  - `end`: moves end of sample to given factor (between 0 and 1)
88  - `attack`: seconds of attack phase
89  - `decay`: seconds of decay phase
90  - `sustain`: gain of sustain phase
91  - `release`: seconds of release phase
92- `deadline`: seconds from audio context initialization before playing the sound (getAudioContextCurrentTime() = immediate)
93- `duration`: seconds the sound should last. optional for one shot samples, required for synth sounds
94
95### registerSynthSounds()
96
97Loads the default waveforms `sawtooth`, `square`, `triangle` and `sine`. Use them like this:
98
99```js
100superdough({ s:'sawtooth' }, 0, 1)
101```
102
103The duration needs to be set for these sounds!
104
105### samples(sampleMap)
106
107allows you to load samples from URLs. There are 3 ways to load samples
108
1091. sample map object
1102. url of sample map json file
1113. github repo
112
113#### sample map object
114
115You can pass a sample map like this:
116
117```js
118samples({
119  '_base': 'https://raw.githubusercontent.com/felixroos/samples/main/',
120  'bd': 'president/president_bd.mp3',
121  'sd': ['president/president_sd.mp3', 'president/president_sd2.mp3'],
122  'hh': ['president/president_hh.mp3'],
123})
124```
125
126The `_base` property defines the root url while the others declare one or more sample paths for each sound.
127
128For example the full URL for `bd` would then be `https://raw.githubusercontent.com/felixroos/samples/main/president/president_bd.mp3`
129
130A loaded sound can then be played with `superdough({ s: 'bd' }, 0)`.
131
132If you declare multiple sounds, you can select them with `n`: `superdough({ s: 'sd', n: 1 }, 0)`
133
134The duration property is not needed for samples.
135
136#### loading samples from a json file
137
138Instead of passing an object as a sample map, you can also pass a URL to a json that contains a sample map:
139
140```js
141samples('https://raw.githubusercontent.com/felixroos/samples/main/strudel.json')
142```
143
144The json file is expected to have the same format as described above.
145
146#### loading samples from a github repo
147
148Because it is common to use github for samples, there is a short way to load a sample map from github:
149
150```js
151samples('github:tidalcycles/dirt-samples')
152```
153
154The format is `github:<user>/<repo>/<branch>`.
155
156If `<repo>` and `<branch>` are not specified, they will default to `samples` and `main` respectively.
157It expects a `strudel.json` file to be present at the root of the given repository, which declares the sample paths in the repo.
158
159The format is also expected to be the same as explained above.
160
161### initAudioOnFirstClick()
162
163Initializes audio and makes sure it is playable after the first click in the document. A click is needed because of the [Autoplay Policy](https://www.w3.org/TR/autoplay-detection/).
164You can call this function when the document loads.
165Then just make sure your first call of `superdough` happens after a click of something.
166
167## Credits
168
169- [ZZFX](https://github.com/KilledByAPixel/ZzFX) used for synths starting with z
170- [SuperDirt](https://github.com/musikinformatik/SuperDirt)
171- [WebDirt](https://github.com/dktr0/WebDirt)