BuboBubo/topos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

push more work

Browse Source
This commit is contained in:
Raphaël Forment
2023-11-18 20:40:52 +01:00
parent 9161d6f9ee
commit 41df296319
10 changed files with 504 additions and 238 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
index.html
View File

@ -147,6 +147,8 @@
<details class="space-y-2" open=true>
<summary class="font-semibold lg:text-xl pb-1 pt-1 text-orange-300">Learning</summary>
<div class="flex flex-col">
<!-- Time -->
<details class="space-y-2" open=false>
<summary class="ml-2 lg:text-xl pb-1 pt-1 text-white">Time</summary>
<div class="flex flex-col">
@ -154,11 +156,22 @@
<p rel="noopener noreferrer" id="docs_linear" class="ml-8 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Time & Transport</p>
<p rel="noopener noreferrer" id="docs_cyclic" class="ml-8 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Time & Cycles</p>
<p rel="noopener noreferrer" id="docs_longform" class="ml-8 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Time & Structure</p>
</div>
</details>
<p rel="noopener noreferrer" id="docs_patterns" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Patterns</p>
<p rel="noopener noreferrer" id="docs_sound" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Audio Engine</p>
<!-- Samples -->
<details class="space-y-2" open=false>
<summary class="ml-2 lg:text-xl pb-1 pt-1 text-white">Audio Engine</summary>
<div class="flex flex-col">
<p rel="noopener noreferrer" id="docs_audio_basics" class="ml-8 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Basics</p>
<p rel="noopener noreferrer" id="docs_amplitude" class="ml-8 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Amplitude</p>
<p rel="noopener noreferrer" id="docs_sampler" class="ml-8 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Sampler</p>
<p rel="noopener noreferrer" id="docs_reverb_delay" class="ml-8 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Reverb & Delay</p>
<p rel="noopener noreferrer" id="docs_distortion" class="ml-8 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Distortion</p>
</div>
</details>
<!-- Audio Engine -->
<details class="space-y-2" open=false>
<summary class="ml-2 lg:text-xl pb-1 pt-1 text-white">Samples</summary>
<div class="flex flex-col">
@ -167,6 +180,7 @@
</div>
</details>
<p rel="noopener noreferrer" id="docs_patterns" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Patterns</p>
<p rel="noopener noreferrer" id="docs_samples" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Samples</p>
<p rel="noopener noreferrer" id="docs_synths" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">Synths</p>
<p rel="noopener noreferrer" id="docs_midi" class="pl-2 pr-2 lg:text-xl text-sm hover:bg-neutral-800 py-1 my-1 rounded-lg">MIDI</p>

10
src/Documentation.ts
View File

@ -2,7 +2,12 @@ import { type Editor } from "./main";
// Basics
import { introduction } from "./documentation/basics/welcome";
import { loading_samples } from "./documentation/samples/loading_samples";
import { amplitude } from "./documentation/audio_engine/amplitude";
import { distortion } from "./documentation/audio_engine/distortion";
import { reverb } from "./documentation/audio_engine/reverb_delay";
import { sampler } from "./documentation/audio_engine/sampler";
import { sample_banks } from "./documentation/samples/sample_banks";
import { audio_basics } from "./documentation/audio_engine/audio_basics";
import { sample_list } from "./documentation/samples/sample_list";
import { software_interface } from "./documentation/basics/interface";
import { shortcuts } from "./documentation/basics/keyboard";
@ -93,8 +98,13 @@ export const documentation_factory = (application: Editor) => {
functions: functions(application),
reference: reference(),
shortcuts: shortcuts(application),
amplitude: amplitude(application),
distortion: distortion(application),
reverb_delay: reverb(application),
sampler: sampler(application),
mouse: mouse(application),
oscilloscope: oscilloscope(application),
audio_basics: audio_basics(application),
synchronisation: synchronisation(application),
bonus: bonus(application),
sample_list: sample_list(application),

10
src/InterfaceLogic.ts
View File

@ -481,6 +481,11 @@ export const installInterfaceLogic = (app: Editor) => {
[
"introduction",
"sampler",
"amplitude",
"audio_basics",
"reverb_delay",
"distortion",
"interface",
"interaction",
"code",
@ -488,8 +493,7 @@ export const installInterfaceLogic = (app: Editor) => {
"linear",
"cyclic",
"longform",
"sound",
"samples",
// "sound",
"synths",
"chaining",
"patterns",
@ -499,7 +503,6 @@ export const installInterfaceLogic = (app: Editor) => {
"lfos",
"probabilities",
"variables",
// "reference",
"synchronisation",
"mouse",
"shortcuts",
@ -510,6 +513,7 @@ export const installInterfaceLogic = (app: Editor) => {
"loading_samples",
].forEach((e) => {
let name = `docs_` + e;
console.log(name)
document.getElementById(name)!.addEventListener("click", async () => {
if (name !== "docs_samples") {
app.currentDocumentationPane = e;

3
src/classes/SoundEvent.ts
View File

@ -436,7 +436,8 @@ export class SoundEvent extends AudibleEvent {
}
};
out = (): void => {
out = (orbit?: number | number[]): void => {
if (orbit) this.values["orbit"] = orbit;
const events = objectWithArraysToArrayOfObjects(this.values, [
"parsedScale",
]);

78
src/documentation/audio_engine/amplitude.ts Normal file
View File

@ -0,0 +1,78 @@
import { type Editor } from "../../main";
import { makeExampleFactory } from "../../Documentation";
export const amplitude = (application: Editor): string => {
// @ts-ignore
const makeExample = makeExampleFactory(application);
return `# Amplitude
Controlling the volume is probably the most important concept you need to know about. Let's learn the basics.
## Volume / Gain
| Method | Alias | Description |
|----------|-------|------------------------------------------------------------------------------------|
| <ic>gain</ic> | | Volume of the synth/sample (exponential). |
| <ic>velocity</ic> | vel | Velocity (amplitude) from <ic>0</ic> to <ic>1</ic>. Multipled with gain. |
| <ic>dbgain</ic> | db | Attenuation in dB from <ic>-inf</ic> to <ic>+10</ic> (acts as a sound mixer fader).|
${makeExample(
"Velocity manipulated by a counter",
`
beat(.5)::snd('cp').vel($(1)%10 / 10).out()`,
true
)}
## Amplitude Enveloppe
**Superdough** is applying an **ADSR** envelope to every sound being played. This is a very standard and conventional amplitude envelope composed of four stages: _attack_, _decay_, _sustain_ and _release_. You will find the same parameters on most synthesizers.
| Method | Alias | Description |
|---------|-------|-----------------------------------------------|
| <ic>attack</ic> | atk | Attack value (time to maximum volume) |
| <ic>decay</ic> | dec | Decay value (time to decay to sustain level) |
| <ic>sustain</ic> | sus | Sustain value (gain when sound is held) |
| <ic>release</ic> | rel | Release value (time for the sound to die off) |
Note that the **sustain** value is not a duration but an amplitude value (how loud). The other values are the time for each stage to take place. Here is a fairly complete example using the <ic>sawtooth</ic> basic waveform.
${makeExample(
"Simple synthesizer",
`
let smooth = (sound) => {
return sound.cutoff(r(100,500))
.lpadsr(usaw(1/8) * 8, 0.05, .125, 0, 0)
.gain(r(0.25, 0.4)).adsr(0, r(.2,.4), r(0,0.5), 0)
.room(0.9).size(2).o(2).vib(r(2,8)).vibmod(0.125)
}
beat(.25)::smooth(sound('sawtooth')
.note([50,57,55,60].beat(1))).out();
beat(.25)::smooth(sound('sawtooth')
.note([50,57,55,60].add(12).beat(1.5))).out();
`,
true
)};
Sometimes, using a full ADSR envelope is a bit overkill. There are other simpler controls to manipulate the envelope like the <ic>.ad</ic> method:
${makeExample(
"Replacing .adsr by .ad",
`
let smooth = (sound) => {
return sound.cutoff(r(100,500))
.lpadsr(usaw(1/8) * 8, 0.05, .125, 0, 0)
.gain(r(0.25, 0.4)).ad(0, .25)
.room(0.9).size(2).o(2).vib(r(2,8)).vibmod(0.125)
}
beat(.25)::smooth(sound('sawtooth')
.note([50,57,55,60].beat(1))).out();
beat(.25)::smooth(sound('sawtooth')
.note([50,57,55,60].add(12).beat(1.5))).out();
`,
true
)};
`}

177
src/documentation/audio_engine/audio_basics.ts Normal file
View File

@ -0,0 +1,177 @@
import { type Editor } from "../../main";
import { makeExampleFactory } from "../../Documentation";
export const audio_basics = (application: Editor): string => {
// @ts-ignore
const makeExample = makeExampleFactory(application);
return `# Audio Basics
The Topos audio engine is [SuperDough](https://www.npmjs.com/package/superdough). This audio engine that takes advantage of the [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API). The engine is capable of many things such as playing samples, synths and effects all at once. It is a very powerful and almost limitless tool to create complex sounds and textures. A set of default sounds are already provided but you can also load your own audio samples if you wish! Let's learn the basics.
## Sound basics
Use the <ic>sound(name: string)</ic> function to play a sound. You can also write <ic>snd</ic>. A sound can be:
- an audio sample: taken from the samples currently loaded
- a synthesizer: the name of a specific waveform
Whatever you choose, the syntax stays the same. See the following example:
${makeExample(
"Playing sounds is easy",
`
beat(1) && sound('bd').out()
beat(0.5) && sound('hh').out()
`,
true
)}
These commands, in plain english, can be translated to:
> Every beat, play a kick drum.
> Every half-beat, play a high-hat.
Let's make this example a bit more complex:
${makeExample(
"Adding some effects",
`
beat(1) && sound('bd').coarse(0.25).room(0.5).orbit(2).out();
beat(0.5) && sound('hh').delay(0.25).delaytime(0.125).out();
`,
true
)}
Now, it translates as follows:
> Every beat, play a kick drum with some amount of distortion on the third audio bus.
> Every half-beat, play a high-hat with 25% of the sound injected in
> a delay unit, with a delay time of 0.125 seconds.
If you remove <ic>beat</ic> instruction, you will end up with a deluge of kick drums and high-hats. <ic>beat</ic> in that case, is used to filter time. It is a very useful instruction to create basic rhythms. Check out the **Time** section if you haven't read it already.
## The <ic>.out</ic> method
To play a sound, you always need the <ic>.out()</ic> method at the end of your chain. THis method tells **Topos** to send the chain to the audio engine. The <ic>.out</ic> method can take an optional argument to send the sound to a numbered effect bus, from <ic>0</ic> to <ic>n</ic> :
${makeExample("Using the .out method",
`
// Playing a clap on the third bus (0-indexed)
beat(1)::sound('cp').out(2)
`, true
)}
Try to remove <ic>.out</ic>. You will see that no sound is playing at all!
## Sound chains
- Sounds are **composed** by adding qualifiers/parameters that modify the sound or synthesizer you have picked (_e.g_ <ic>sound('...').blabla(...)..something(...).out()</ic>. Think of it as _audio chains_.
${makeExample(
'"Composing" a complex sonic object by making a sound chain',
`
beat(1) :: sound('pad').n(1)
.begin(rand(0, 0.4))
.freq([50,52].beat())
.size(0.9).room(0.9)
.velocity(0.25)
.pan(usine()).release(2).out()`,
true
)}
## Picking a specific sound
If you choose the sound <ic>kick</ic>, you are asking for the first sample in the <ic>kick</ic> folder. All the sample names are folders. Synthesizers are not affected by this. Here is what the <ic>kick</ic>might be looking like:
\`\`\`shell
.
├── KICK9.wav
├── kick1.wav
├── kick10.wav
├── kick2-1.wav
├── kick2.wav
├── kick3-1.wav
├── kick3.wav
├── kick4.wav
├── kick5.wav
├── kick6.wav
├── kick7.wav
└── kick8.wav
\`\`\`
The <ic>.n(number)</ic> method can be used to pick a sample from the currently selected sample folder. For instance, the following script will play a random sample from the _kick_ folder:
${makeExample(
"Picking a sample",
`
beat(1) && sound('kick').n([1,2,3,4,5,6,7,8].pick()).out()
`,
true
)}
You can also use the <ic>:</ic> to pick a sample number directly from the <ic>sound</ic> function:
${makeExample(
"Picking a sample using :",
`
beat(1) && sound('kick:3').out()
`,
true
)}
You can use any number to pick a sound. Don't be afraid of using a number too big. If the number exceeds the number of available samples, it will simply wrap around and loop infinitely over the folder. Let's demonstrate this by using the mouse over a very large sample folder:
${makeExample(
"Picking a sample... with the mouse!",
`
// Move your mouse to change the sample being used!
beat(.25) && sound('ST09').n(Math.floor(mouseX())).out()`,
true
)}
The <ic>.n</ic> method is also used for synthesizers but it behaves differently. When using a synthesizer, this method can help you determine the number of harmonics in your waveform. See the **Synthesizers** section to learn more about this.
## Orbits and audio busses
**Topos** is inheriting some audio bus management principles taken from the [SuperDirt](https://github.com/musikinformatik/SuperDirt) and [Superdough](https://www.npmjs.com/package/superdough) engine, a WebAudio based recreation of the same engine.
Each sound that you play is associated with an audio bus, called an _orbit_. Some effects are affecting **all sounds currently playing on that bus**. These are called **global effects**, to distinguish from **local effects**:
- **global effects**: _reverberation_ and _delay_.
- **local effects**: everything else :smile:
There is a special method to choose the _orbit_ that your sound is going to use:
| Method | Alias | Description |
|----------|-------|------------------------------------------------------------|
| <ic>orbit</ic> | o | Orbit number |
You can play a sound _dry_ and another sound _wet_. Take a look at this example where the reverb is only affecting one of the sounds:
${makeExample("Dry and wet", `
// This sound is dry
beat(1)::sound('hh').out()
// This sound is wet (reverb)
beat(2)::sound('cp').orbit(2).room(0.5).size(8).out()
`, true)}
## The art of chaining
Learning to create complex chains is very important when using **Topos**. It can take some time to learn all the possible parameters. Don't worry, it's actually rather easy to learn.
${makeExample(
"Complex chain",
`
beat(0.25) && sound('fhh')
.sometimes(s=>s.speed([2, 0.5].pick()))
.room(0.9).size(0.9).gain(1)
.cutoff(usine(1/2) * 5000)
.out()`,
true
)}
Most audio parameters can be used both for samples and synthesizers. This is quite unconventional if you are familiar with a more traditional music software.
`}

31
src/documentation/audio_engine/distortion.ts Normal file
View File

@ -0,0 +1,31 @@
import { type Editor } from "../../main";
import { makeExampleFactory } from "../../Documentation";
export const distortion = (application: Editor): string => {
// @ts-ignore
const makeExample = makeExampleFactory(application);
return `# Distortion
## Distorsion, saturation, destruction
Three additional effects that are easy enough to understand. These effects are deteriorating the signal, making it easy to get digital or gritty audio sample playback or synthesizers destroyed beyond recognition. Be careful with your signal level!
| Method | Alias | Description |
|------------|-----------|---------------------------------|
| <ic>coarse</ic> | | Artificial sample-rate lowering |
| <ic>crush</ic> | | bitcrushing. <ic>1</ic> is extreme, the more you go up, the less it takes effect. |
| <ic>shape</ic> | | Waveshaping distortion (between <ic>0</ic> and <ic>1</ic>) |
${makeExample(
"Crunch... crunch... crunch!",
`
beat(.5)::snd('pad').coarse($(1) % 16).clip(.5).out(); // Comment me
beat(.5)::snd('pad').crush([16, 8, 4].beat(2)).clip(.5).out()
`,
true
)};
`}

52
src/documentation/audio_engine/reverb_delay.ts Normal file
View File

@ -0,0 +1,52 @@
import { type Editor } from "../../main";
import { makeExampleFactory } from "../../Documentation";
export const reverb = (application: Editor): string => {
// @ts-ignore
const makeExample = makeExampleFactory(application);
return `# Reverberation and delay
## Reverb
A good sounding reverb. This reverb unit is using a convolution that gets updated everytime you change a parameter.
For that reason, it is often a good idea to set fixed reverb values per orbit. Do not try to pattern the reverb too much.
| Method | Alias | Description |
|------------|-------|---------------------------------|
| <ic>room</ic> | rm | Reverb level (between <ic>0</ic> and <ic>1</ic> |
| <ic>size</ic> | sz | Reverb room size of the reverb, between <ic>0</ic> and <ic>n</ic> |
| <ic>roomfade</ic> | | Reverb fade time, in seconds |
| <ic>roomlp</ic> | | Reverb lowpass starting frequency (in hertz) |
| <ic>roomdim</ic> | | Reverb lowpass frequency at -60db (in hertz) |
${makeExample(
"Clapping in the cavern",
`
beat(2)::snd('cp').room(0.5).size(4).out()
`,
true
)};
## Delay
A good sounding delay unit that can go into feedback territory. Use it without moderation.
| Method | Alias | Description |
|------------|-----------|---------------------------------|
| <ic>delay</ic> | | Delay _wet/dry_ (between <ic>0</ic> and <ic>1</ic>) |
| <ic>delaytime</ic> | delayt | Delay time (in milliseconds) |
| <ic>delayfeedback</ic> | delayfb | Delay feedback (between <ic>0</ic> and <ic>1</ic>) |
${makeExample(
"Who doesn't like delay?",
`
beat(2)::snd('cp').delay(0.5).delaytime(0.75).delayfb(0.8).out()
beat(4)::snd('snare').out()
beat(1)::snd('kick').out()
`,
true
)};
`}

130
src/documentation/audio_engine/sampler.ts Normal file
View File

@ -0,0 +1,130 @@
import { type Editor } from "../../main";
import { makeExampleFactory } from "../../Documentation";
export const sampler = (application: Editor): string => {
// @ts-ignore
const makeExample = makeExampleFactory(application);
return `# Sampler
The sampler is a rather complex beast. There is a lot you can do by manipulating samples, from simple playback to complex granulation, wavetable synthesis and concrete music.
| Method | Alias | Description |
|---------|--------|--------------------------------------------------------|
| <ic>n</ic> | | Select a sample in the current folder (from <ic>0</ic> to infinity) |
| <ic>begin</ic> | | Beginning of the sample playback (between <ic>0</ic> and <ic>1</ic>) |
| <ic>end</ic> | | End of the sample (between <ic>0</ic> and <ic>1</ic>) |
| <ic>loopBegin</ic> | | Beginning of the loop section (between <ic>0</ic> and <ic>1</ic>) |
| <ic>loopEnd</ic> | | End of the loop section (between <ic>0</ic> and <ic>1</ic>) |
| <ic>loop</ic> | | Whether to loop or not the audio sample |
| <ic>stretch</ic> | | Stretches the audio playback rate of a sample over <ic>n</ic> beats |
| <ic>speed</ic> | | Playback speed (<ic>2</ic> = twice as fast) |
| <ic>cut</ic> | | Set with <ic>0</ic> or <ic>1</ic>. Will cut the sample as soon as another sample is played on the same bus |
| <ic>clip</ic> | | Multiply the duration of the sample with the given number |
| <ic>pan</ic> | | Stereo position of the audio playback (<ic>0</ic> = left, <ic>1</ic> = right)|
Let's apply some of these methods naïvely. We will then break everything using simpler examples.
${makeExample(
"Complex sampling duties",
`
// Using some of the modifiers described above :)
beat(.5)::snd('pad').begin(0.2)
.speed([1, 0.9, 0.8].beat(4))
.n(2).pan(usine(.5))
.end(rand(0.3,0.8))
.room(0.8).size(0.5)
.clip(1).out()
`,
true
)};
## Playback speed / pitching samples
Let's play with the <ic>speed</ic> parameter to control the pitch of sample playback:
${makeExample("Controlling the playback speed", `
beat(0.5)::sound('notes')
.speed([1,2,3,4].palindrome().beat(0.5)).out()
`, true)}
It also works by using negative values. It reverses the playback:
${makeExample("Playing samples backwards", `
beat(0.5)::sound('notes')
.speed(-[1,2,3,4].palindrome().beat(0.5)).out()
`, true)}
Of course you can play melodies using samples:
${makeExample("Playing melodies using samples", `
beat(0.5)::sound('notes')
.room(0.5).size(4)
.note([0, 2, 3, 4, 5].scale('minor', 50).beat(0.5)).out()
`, true)}
## Panning
To pan samples, use the <ic>.pan</ic> method with a number between <ic>0</ic> and <ic>1</ic>.
${makeExample("Playing melodies using samples", `
beat(0.25)::sound('notes')
.room(0.5).size(4).pan(r(0, 1))
.note([0, 2, 3, 4, 5].scale('minor', 50).beat(0.25)).out()
`, true)}
## Looping over a sample
Using <ic>loop</ic> (<ic>1</ic> for looping), <ic>loopBegin</ic> and <ic>loopEnd</ic> (between <ic>0</ic> and <ic>1</ic>), you can loop over the length of a sample. It can be super effective to create granular effects.
${makeExample("Granulation using loop", `
beat(0.25)::sound('fikea').loop(1)
.lpf(ir(2000, 5000))
.loopBegin(0).loopEnd(r(0, 1))
.room(0.5).size(4).pan(r(0, 1))
.note([0, 2, 3, 4, 5].scale('minor', 50).beat(0.25)).out()
`, true)}
## Stretching a sample
The <ic>stretch</ic> parameter can help you to stretch long samples like amen breaks:
${makeExample(
"Playing an amen break",
`
// Note that stretch has the same value as beat
beat(4) :: sound('amen1').n(11).stretch(4).out()
beat(1) :: sound('kick').shape(0.35).out()`,
true,
)};
## Cutting samples
Sometimes, you will find it necessary to cut a sample. It can be because the sample is too long but also because it takes too much CPU to play too many samples at the same time.
Know about the <ic>begin</ic> and <ic>end</ic> parameters. They are not related to the sampler itself, but to the length of the event you are playing. Let's cut the granular example:
${makeExample("Cutting a sample using end", `
beat(0.25)::sound('notes')
.end(usine(1/2)/0.5)
.room(0.5).size(4).pan(r(0, 1))
.note([0, 2, 3, 4, 5].scale('minor', 50).beat(0.25)).out()
`, true)}
You can also use <ic>clip</ic> to cut the sample everytime a new sample comes in:
${makeExample("Cutting a sample using end", `
beat(0.125)::sound('notes')
.cut(1)
.room(0.5).size(4).pan(r(0, 1))
.note([0, 2, 3, 4, 5].scale('minor', 50).beat(0.125)
+ [-12,12].beat()).out()
`, true)}
`}

231
src/documentation/engine.ts
View File

@ -4,179 +4,8 @@ import { makeExampleFactory } from "../Documentation";
export const sound = (application: Editor): string => {
const makeExample = makeExampleFactory(application);
return `
# Audio engine
The Topos audio engine is based on the [SuperDough](https://www.npmjs.com/package/superdough) audio backend that takes advantage of the [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API). The engine is capable of many things such as playing samples, synths and effects all at once. It is a very powerful and almost limitless tool to create complex sounds and textures. A set of default sounds are already provided but you can also load your own audio samples if you wish!
## Sound basics
The basic function to play a sound is... <ic>sound(name: string)</ic> (you can also write <ic>snd</ic> to save some precious time). If the given sound (or synthesizer) is already declared, it will be automatically queried/started and will start playing. Evaluate the following script in the global window:
${makeExample(
"Playing sounds is easy",
`
beat(1) && sound('bd').out()
beat(0.5) && sound('hh').out()
`,
true
)}
In plain english, this translates to:
> Every beat, play a kick drum.
> Every half-beat, play a high-hat.
Let's make it slightly more complex:
${makeExample(
"Adding some effects",
`
beat(1) && sound('bd').coarse(0.25).room(0.5).orbit(2).out();
beat(0.5) && sound('hh').delay(0.25).delaytime(0.125).out();
`,
true
)}
Now, it reads as follow:
> Every beat, play a kick drum with some amount of distortion.
> Every half-beat, play a high-hat with 25% of the sound injected in
> a delay unit, with a delay time of 0.125 seconds.
Let's pause for a moment and explain what is going on:
- If you remove <ic>beat</ic> instruction, you will end up with a deluge of kick drums and high-hats. <ic>beat</ic> in that case, is used to filter time. It is a very useful instruction to create basic rhythms. Check out the **Time** page if you haven't read it already.
- Playing a sound always ends up with the <ic>.out()</ic> method that gives the instruction to send a message to the audio engine.
- Sounds are **composed** by adding qualifiers/parameters that will modify the sound or synthesizer being played (_e.g_ <ic>sound('...').blabla(...)..something(...).out()</ic>. Think of it as _audio chains_.
${makeExample(
'"Composing" a complex sonic object by making a sound chain',
`
beat(1) :: sound('pad').n(1)
.begin(rand(0, 0.4))
.freq([50,52].beat())
.size(0.9).room(0.9)
.velocity(0.25)
.pan(usine()).release(2).out()`,
true
)}
## Audio Sample Folders / Sample Files
When you type <ic>kick</ic> in the <ic>sound('kick').out()</ic> expression, you are referring to a sample folder containing multiple audio samples. If you look at the sample folder, it would look something like this:
\`\`\`shell
.
├── KICK9.wav
├── kick1.wav
├── kick10.wav
├── kick2-1.wav
├── kick2.wav
├── kick3-1.wav
├── kick3.wav
├── kick4.wav
├── kick5.wav
├── kick6.wav
├── kick7.wav
└── kick8.wav
\`\`\`
The <ic>.n(number)</ic> method can be used to pick a sample from the currently selected sample folder. For instance, the following script will play a random sample from the _kick_ folder:
${makeExample(
"Picking a sample",
`
beat(1) && sound('kick').n([1,2,3,4,5,6,7,8].pick()).out()
`,
true
)}
Don't worry about the number. If it gets too big, it will be automatically wrapped to the number of samples in the folder. You can type any number, it will always fall on a sample. Let's use our mouse to select a sample number in a folder:
${makeExample(
"Picking a sample... with your mouse!",
`
// Move your mouse to change the sample being used!
beat(.25) && sound('numbers').n(Math.floor(mouseX())).out()`,
true
)}
**Note:** the <ic>sound</ic> function can also be used to play synthesizers (see the **Synthesizers** page). In that case, the <ic>.n(n: number)</ic> becomes totally useless!
## Learning about sound modifiers
As we said earlier, the <ic>sound('sample_name')</ic> function can be chained to _specify_ a sound more. For instance, you can add a filter and some effects to your high-hat:
${makeExample(
"Let's make something more complex",
`
beat(0.25) && sound('jvbass')
.sometimes(s=>s.speed([2, 0.5].pick()))
.room(0.9).size(0.9).gain(1)
.cutoff(usine(1/2) * 5000)
.out()`,
true
)}
There are many possible arguments that you can add to your sounds. Learning them can take a long time but it will open up a lot of possibilities. Let's try to make it through all of them. They can all be used both with synthesizers and audio samples, which is kind of unconventional with normal / standard electronic music softwares.
## Orbits and audio busses
Topos is inheriting some audio bus management principles taken from the [SuperDirt](https://github.com/musikinformatik/SuperDirt) and [Superdough](https://www.npmjs.com/package/superdough) engine, a WebAudio based recreation of the same engine. Each sound that you play is associated with an audio bus, called an _orbit_. Some effects are affecting **all sounds currently playing on that bus**. These are called **global effects**, to distinguish from **local effects**:
- **global effects**: _reverberation_ and _delay_.
- **local effects**: everything else :smile:
There is a special method to choose the _orbit_ that your sound is going to use:
| Method | Alias | Description |
|----------|-------|------------------------------------------------------------|
| <ic>orbit</ic> | o | Orbit number |
## Amplitude
Simple controls over the amplitude (volume) of a given sound.
| Method | Alias | Description |
|----------|-------|------------------------------------------------------------------------------------|
| <ic>gain</ic> | | Volume of the synth/sample (exponential) |
| <ic>velocity</ic> | vel | Velocity (amplitude) from <ic>0</ic> to <ic>1</ic>. Multipled with gain |
| <ic>dbgain</ic> | db | Attenuation in dB from <ic>-inf</ic> to <ic>+10</ic> (acts as a sound mixer fader) |
${makeExample(
"Velocity manipulated by a counter",
`
beat(.5)::snd('cp').vel($(1)%10 / 10).out()`,
true
)}
## Amplitude Enveloppe
**Superdough** is applying an **ADSR** envelope to every sound being played. This is a very standard and conventional amplitude envelope composed of four stages: _attack_, _decay_, _sustain_ and _release_. You will find the same parameters on most synthesizers.
| Method | Alias | Description |
|---------|-------|-----------------------------------------------|
| <ic>attack</ic> | atk | Attack value (time to maximum volume) |
| <ic>decay</ic> | dec | Decay value (time to decay to sustain level) |
| <ic>sustain</ic> | sus | Sustain value (gain when sound is held) |
| <ic>release</ic> | rel | Release value (time for the sound to die off) |
Note that the **sustain** value is not a duration but an amplitude value (how loud). The other values are the time for each stage to take place. Here is a fairly complete example using the <ic>sawtooth</ic> basic waveform.
${makeExample(
"Simple synthesizer",
`
let smooth = (sound) => {
return sound.cutoff(r(100,500))
.lpadsr(usaw(1/8) * 8, 0.05, .125, 0, 0)
.gain(r(0.25, 0.4)).adsr(0, r(.2,.4), r(0,0.5), 0)
.room(0.9).size(2).o(2).vib(r(2,8)).vibmod(0.125)
}
beat(.25)::smooth(sound('sawtooth').note([50,57,55,60].beat(1))).out();
beat(.25)::smooth(sound('sawtooth').note([50,57,55,60].add(12).beat(1.5))).out();
`,
true
)};
## Sample Controls
There are some basic controls over the playback of each sample. This allows you to get into more serious sampling if you take the time to really work with your audio materials.
@ -244,47 +73,6 @@ beat(.5) && snd('sawtooth')
true
)};
## Reverb
A good sounding reverb. This reverb unit is using a convolution that gets updated everytime you change a parameter.
For that reason, it is often a good idea to set fixed reverb values per orbit. Do not try to pattern the reverb too much.
| Method | Alias | Description |
|------------|-------|---------------------------------|
| <ic>room</ic> | rm | Reverb level (between <ic>0</ic> and <ic>1</ic> |
| <ic>size</ic> | sz | Reverb room size of the reverb, between <ic>0</ic> and <ic>n</ic> |
| <ic>roomfade</ic> | | Reverb fade time, in seconds |
| <ic>roomlp</ic> | | Reverb lowpass starting frequency (in hertz) |
| <ic>roomdim</ic> | | Reverb lowpass frequency at -60db (in hertz) |
${makeExample(
"Clapping in the cavern",
`
beat(2)::snd('cp').room(0.5).size(4).out()
`,
true
)};
## Delay
A good sounding delay unit that can go into feedback territory. Use it without moderation.
| Method | Alias | Description |
|------------|-----------|---------------------------------|
| <ic>delay</ic> | | Delay _wet/dry_ (between <ic>0</ic> and <ic>1</ic>) |
| <ic>delaytime</ic> | delayt | Delay time (in milliseconds) |
| <ic>delayfeedback</ic> | delayfb | Delay feedback (between <ic>0</ic> and <ic>1</ic>) |
${makeExample(
"Who doesn't like delay?",
`
beat(2)::snd('cp').delay(0.5).delaytime(0.75).delayfb(0.8).out()
beat(4)::snd('snare').out()
beat(1)::snd('kick').out()
`,
true
)};
## Compression
@ -299,24 +87,5 @@ This effect is leveraging the basic WebAudio compressor. More information can be
| <ic>compRelease</ic> | cmpr | In seconds, time to increase the gain by 10db |
## Distorsion, saturation, destruction
Three additional effects that are easy enough to understand. These effects are deteriorating the signal, making it easy to get digital or gritty audio sample playback or synthesizers destroyed beyond recognition. Be careful with your signal level!
| Method | Alias | Description |
|------------|-----------|---------------------------------|
| <ic>coarse</ic> | | Artificial sample-rate lowering |
| <ic>crush</ic> | | bitcrushing. <ic>1</ic> is extreme, the more you go up, the less it takes effect. |
| <ic>shape</ic> | | Waveshaping distortion (between <ic>0</ic> and <ic>1</ic>) |
${makeExample(
"Crunch... crunch... crunch!",
`
beat(.5)::snd('pad').coarse($(1) % 16).clip(.5).out(); // Comment me
beat(.5)::snd('pad').crush([16, 8, 4].beat(2)).clip(.5).out()
`,
true
)};
`;
};