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

Moved doc files to same structure as in index

Browse Source
This commit is contained in:
Miika Alonen
2023-12-10 22:00:32 +02:00
parent e1a1a5e501
commit c04de0d582
27 changed files with 68 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
src/documentation/learning/audio_engine/amplitude.ts Normal file
View File

@ -0,0 +1,77 @@
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,
)};
`;
};

182
src/documentation/learning/audio_engine/audio_basics.ts Normal file
View File

@ -0,0 +1,182 @@
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(
"Complex sonic object",
`
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.
`;
};

30
src/documentation/learning/audio_engine/distortion.ts Normal file
View File

@ -0,0 +1,30 @@
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,
)};
`;
};

94
src/documentation/learning/audio_engine/reverb_delay.ts Normal file
View File

@ -0,0 +1,94 @@
import { type Editor } from "../../../main";
import { makeExampleFactory } from "../../../Documentation";
export const reverb = (application: Editor): string => {
// @ts-ignore
const makeExample = makeExampleFactory(application);
return `
# Audio effects
There is a growing collection of audio effects you can use directly baked in the engine. You can create a wide variety of sonic effects by being creative with the parameters they offer.
## 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,
)}
## Phaser
| Method | Alias | Description |
|------------|-----------|---------------------------------|
| <ic>phaser</ic> | <ic>phas</ic> | Phaser speed, between <ic>1</ic> and <ic>n</ic> |
| <ic>phaserDepth</ic> | <ic>phasdepth</ic> | How much of the signal goes through phaser (<ic>0</ic> to <ic>1</ic>) |
| <ic>phaserSweep</ic> | <ic>phassweep</ic> | Phaser frequency sweep (in hertz) |
| <ic>phaserCenter</ic> | <ic>phascenter</ic> | Phaser center frequency (default to 1000) |
${makeExample(
"Super cool phaser lick",
`
rhythm(.5, 7, 8)::sound('wt_stereo')
.phaser(0.75).phaserSweep(3000)
.phaserCenter(1500).phaserDepth(1)
.note([0, 1, 2, 3, 4, 5, 6].scale('pentatonic', 50).beat(0.25))
.room(0.5).size(4).out()
`,
true,
)}
## 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,
)};
`;
};

175
src/documentation/learning/audio_engine/sampler.ts Normal file
View File

@ -0,0 +1,175 @@
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)|
| <ic>vib</ic> | | vibrato speed (in hertz)|
| <ic>vibmod</ic> | | vibrato depth (from <ic>0</ic> to <ic>n</ic>)|
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,
)}
## Adding vibrato to samples
You can add vibrato to any sample using <ic>vib</ic> and <ic>vibmod</ic>:
${makeExample(
"Adding vibrato to a sample",
`
beat(1)::sound('fhang').vib([1, 2, 4].bar()).vibmod([0.5, 2].beat()).out()
`,
true,
)}
`;
};

629
src/documentation/learning/audio_engine/synths.ts Normal file
View File

@ -0,0 +1,629 @@
import { type Editor } from "../../../main";
import { makeExampleFactory } from "../../../Documentation";
export const synths = (application: Editor): string => {
const makeExample = makeExampleFactory(application);
return `
# Synthesizers
Topos comes by default with a forever-increasing number of synthesis capabilities. These synths are based on basic [WebAudio](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API) designs. For heavy synthesis duties, I recommend you to user other synthesizers or softwares through MIDI. There is already a lot you can do with the built-in synths though!
# Timbre, pitch and frequency
The <ic>sound</ic> function can take the name of a synthesizer or waveform as first argument. This has for effect to turn the sampler we all know and love into a synthesizer. <ic>sine</ic>, <ic>sawtooth</ic>,<ic>triangle</ic>, <ic>square</ic> are the names used to select classic oscillator waveforms. Note that you can also make use of filters and envelopes to shape the sound to your liking.
${makeExample(
"Listening to the different waveforms from the sweetest to the harshest",
`
beat(.5) && snd(['sine', 'triangle', 'sawtooth', 'square'].beat()).freq(100).out()
`,
true,
)}
Note that you can also use noise if you do not want to use a periodic oscillator:
${makeExample(
"Listening to the different types of noise",
`
beat(.5) && snd(['brown', 'pink', 'white'].beat()).adsr(0,.1,0,0).out()
`,
true,
)}
Two functions are primarily used to control the frequency of the synthesizer:
- <ic>freq(hz: number)</ic>: sets the frequency of the oscillator.
- <ic>note(note: number|string)</ic>: sets the MIDI note of the oscillator (MIDI note converted to hertz).
${makeExample(
"Selecting a pitch",
`
beat(.5) && snd('triangle').freq([100,200,400].beat(2)).out()
`,
true,
)}
${makeExample(
"Selecting a note",
`
beat(.5) && snd('triangle').note([60,"F4"].pick()).out()
`,
true,
)}
Chords can also played using different parameters:
- <ic>chord(string||number[]|...number)</ic>: parses and sets notes for the chord
${makeExample(
"Playing a named chord",
`
beat(1) && snd('triangle').chord(["C","Em7","Fmaj7","Emin"].beat(2)).adsr(0,.2).out()
`,
true,
)}
${makeExample(
"Playing a chord from a list of notes and doing inversions",
`
beat(.5) && snd('triangle').chord(60,64,67,72).invert([1,-3,4,-5].pick()).adsr(0,.2).out()
`,
true,
)}
## Vibrato
You can also add some amount of vibrato to the sound using the <ic>vib</ic> and <ic>vibmod</ic> methods. These can turn any oscillator into something more lively and/or into a sound effect when used with a high amount of modulation.
${makeExample(
"Different vibrato settings",
`
tempo(140);
beat(1) :: sound('triangle')
.freq(400).release(0.2)
.vib([1/2, 1, 2, 4].beat())
.vibmod([1,2,4,8].beat(2))
.out()`,
true,
)}
## Noise
A certain amount of brown noise can be added by using the <ic>.noise</ic> key:
${makeExample(
"Different vibrato settings",
`
tempo(140);
beat(1) :: sound('triangle')
.freq(400).release(0.2)
.noise([0.2,0.4,0.5].bar())
.vib([1/2, 1, 2, 4].beat())
.vibmod([1,2,4,8].beat(2))
.out()`,
true,
)}
## Controlling the amplitude
Controlling the amplitude and duration of the sound can be done using various techniques. The most important thing to learn is probably how set the amplitude (volume) of your synthesizer:
- <ic>gain(gain: number)</ic>: sets the gain of the oscillator.
- <ic>velocity(velocity: number)</ic>: sets the velocity of the oscillator (velocity is a multiple of gain).
${makeExample(
"Setting the gain",
`beat(0.25) :: sound('sawtooth').gain([0.0, 1/8, 1/4, 1/2, 1].beat(0.5)).out()`,
true,
)}
${makeExample(
"Setting the velocity",
`beat(0.25) :: sound('sawtooth').velocity([0.0, 1/8, 1/4, 1/2, 1].beat(0.5)).out()`,
true,
)}
<div class="mt-4 mb-4 lg:grid lg:grid-cols-4 lg:gap-4">
<img class="col-span-1 lg:ml-12 bg-gray-100 rounded-lg px-2 py-2", src="https://upload.wikimedia.org/wikipedia/commons/thumb/e/ef/ADSR_Envelope_Graph.svg/1280px-ADSR_Envelope_Graph.svg.png" width="400" />
<z class="pl-8 lg:text-2xl text-base text-white lg:mx-6 mx-2 my-4 leading-normal col-span-3 ">Synthesizers typically come with an amplitude envelope that can help you to shape the sound with a slow attack or long release. This is done in Topos using the amplitude envelope, composed of four parameters: <ic>attack</ic>, <ic>decay</ic>, <ic>sustain</ic> and <ic>release</ic>:</z>
</div>
- <ic>attack(attack: number)</ic> / <ic>atk(atk: number)</ic>: sets the attack time of the envelope.
- <ic>decay(decay: number)</ic> / <ic>dec(dec: number)</ic>: sets the decay time of the envelope.
- <ic>sustain(sustain: number)</ic> / <ic>sus(sus: number)</ic>: sets the sustain time of the envelope.
- <ic>release(release: number)</ic> / <ic>rel(rel: number)</ic>: sets the release time of the envelope.
${makeExample(
"Using decay and sustain to set the ADSR envelope",
`
beat(0.5) :: sound('wt_piano')
.cutoff(1000 + usine() * 4000)
.freq(100).decay(.2)
.sustain([0.1,0.5].beat(4))
.out()`,
true,
)}
This ADSR envelope design is important to know because it is used for other aspects of the synthesis engine such as the filters that we are now going to talk about. But wait, I've kept the best for the end. The <ic>adsr()</ic> combines all the parameters together. It is a shortcut for setting the ADSR envelope:
- <ic>adsr(attack: number, decay: number, sustain: number, release: number)</ic>: sets the ADSR envelope.
${makeExample(
"Replacing the previous example with the adsr() method",
`
beat(0.5) :: sound('wt_piano')
.cutoff(1000 + usine() * 4000)
.freq(100)
.adsr(0, .2, [0.1,0.5].beat(4), 0)
.out()
`,
true,
)}
- <ic>ad(attack: number, decay: number)</ic>: sets the attack and decay phases, setting sustain and release to <ic>0</ic>.
${makeExample(
"Two segment envelope",
`
beat(0.5) :: sound('wt_piano')
.cutoff(1000 + usine() * 4000)
.freq(100)
.ad(0, .2)
.out()
`,
true,
)}
## Substractive synthesis using filters
The most basic synthesis technique used since the 1970s is called substractive synthesis. This technique is based on the use of rich sound sources (oscillators) as a base to build rich and moving timbres. Because rich sources contain a lot of different harmonics, you might want to filter some of them to obtain the timbre you are looking for. To do so, Topos comes with a set of basic filters that can be used to shape the sound exactly to your liking. There are three filter types by defaut, with more to be added in the future:
- **lowpass filter**: filters the high frequencies, keeping the low frequencies.
- **highpass filter**: filtering the low frequencies, keeping the high frequencies.
- **bandpass filter**: filters the low and high frequencies around a frequency band, keeping what's in the middle.
${makeExample(
"Filtering the high frequencies of an oscillator",
`beat(.5) :: sound('sawtooth').cutoff(50 + usine(1/8) * 2000).out()`,
true,
)}
These filters all come with their own set of parameters. Note that we are describing the parameters of the three different filter types here. Choose the right parameters depending on the filter type you are using:
### Lowpass filter
| Method | Alias | Description |
|------------|-----------|---------------------------------|
| <ic>cutoff</ic> | <ic>lpf</ic> | cutoff frequency of the lowpass filter |
| <ic>resonance</ic> | <ic>lpq</ic> | resonance of the lowpass filter (0-1) |
${makeExample(
"Filtering a bass",
`beat(.5) :: sound('jvbass').lpf([250,1000,8000].beat()).out()`,
true,
)}
### Highpass filter
| Method | Alias | Description |
|------------|-----------|---------------------------------|
| <ic>hcutoff</ic> | <ic>hpf</ic> | cutoff frequency of the highpass filter |
| <ic>hresonance</ic> | <ic>hpq</ic> | resonance of the highpass filter (0-1) |
${makeExample(
"Filtering a noise source",
`beat(.5) :: sound('gtr').hpf([250,1000, 2000, 3000, 4000].beat()).end(0.5).out()`,
true,
)}
### Bandpass filter
| Method | Alias | Description |
|------------|-----------|---------------------------------|
| <ic>bandf</ic> | <ic>bpf</ic> | cutoff frequency of the bandpass filter |
| <ic>bandq</ic> | <ic>bpq</ic> | resonance of the bandpass filter (0-1) |
${makeExample(
"Sweeping the filter on the same guitar sample",
`beat(.5) :: sound('gtr').bandf(100 + usine(1/8) * 4000).end(0.5).out()`,
true,
)}
Alternatively, <ic>lpf</ic>, <ic>hpf</ic> and <ic>bpf</ic> can take a second argument, the **resonance**.
## Filter order (type)
You can also use the <ic>ftype</ic> method to change the filter type (order). There are two types by default, <ic>12db</ic> for a gentle slope or <ic>24db</ic> for a really steep filtering slope. The <ic>24db</ic> type is particularly useful for substractive synthesis if you are trying to emulate some of the Moog or Prophet sounds:
- <ic>ftype(type: string)</ic>: sets the filter type (order), either <ic>12db</ic> or <ic>24db</ic>.
${makeExample(
"Filtering a bass",
`beat(.5) :: sound('jvbass').ftype(['12db', '24db'].beat(4)).lpf([250,1000,8000].beat()).out()`,
true,
)}
I also encourage you to study these simple examples to get more familiar with the construction of basic substractive synthesizers:
${makeExample(
"Simple synthesizer voice with filter",
`
beat(.5) && snd('sawtooth')
.cutoff([2000,500].pick() + usine(.5) * 4000)
.resonance(0.2).freq([100,150].pick())
.out()
`,
true,
)}
${makeExample(
"Blessed by the square wave",
`
beat(4) :: [100,101].forEach((freq) => sound('square').freq(freq).sustain(0.1).out())
beat(.5) :: [100,101].forEach((freq) => sound('square').freq(freq*2).sustain(0.01).out())
beat([.5, .75, 2].beat()) :: [100,101].forEach((freq) => sound('square')
.freq(freq*4 + usquare(2) * 200).sustain(0.125).out())
beat(.25) :: sound('square').freq(100*[1,2,4,8].beat()).sustain(0.1).out()`,
false,
)}
${makeExample(
"Ghost carillon (move your mouse!)",
`
beat(1/8)::sound('sine')
.velocity(rand(0.0, 1.0))
.delay(0.75).delayt(.5)
.sustain(0.4)
.cutoff(2000)
.freq(mouseX())
.gain(0.25)
.out()`,
false,
)}
## Filter envelopes
The examples we have studied so far are static. They filter the sound around a fixed cutoff frequency. To make the sound more interesting, you can use the ADSR filter envelopes to shape the filter cutoff frequency over time. You will always find amplitude and filter envelopes on most commercial synthesizers. This is done using the following methods:
### Lowpass envelope
| Method | Alias | Description |
|------------|-----------|---------------------------------|
| <ic>lpenv</ic> | <ic>lpe</ic> | lowpass frequency modulation amount (negative or positive) |
| <ic>lpattack</ic> | <ic>lpa</ic> | attack of the lowpass filter |
| <ic>lpdecay</ic> | <ic>lpd</ic> | decay of the lowpass filter |
| <ic>lpsustain</ic> | <ic>lps</ic> | sustain of the lowpass filter |
| <ic>lprelease</ic> | <ic>lpr</ic> | release of the lowpass filter |
| <ic>lpadsr</ic> | | (**takes five arguments**) set all the parameters |
${makeExample(
"Filtering a sawtooth wave dynamically",
`beat(.5) :: sound('sawtooth').note([48,60].beat())
.cutoff(5000).lpa([0.05, 0.25, 0.5].beat(2))
.lpenv(-8).lpq(10).out()`,
true,
)}
### Highpass envelope
| Method | Alias | Description |
|------------|-----------|---------------------------------|
| <ic>hpenv</ic> | <ic>hpe</ic> | highpass frequency modulation amount (negative or positive) |
| <ic>hpattack</ic> | <ic>hpa</ic> | attack of the highpass filter |
| <ic>hpdecay</ic> | <ic>hpd</ic> | decay of the highpass filter |
| <ic>hpsustain</ic> | <ic>hps</ic> | sustain of the highpass filter |
| <ic>hprelease</ic> | <ic>hpr</ic> | release of the highpass filter |
| <ic>hpadsr</ic> | | (**takes five arguments**) set all the parameters |
${makeExample(
"Let's use another filter using the same example",
`beat(.5) :: sound('sawtooth').note([48,60].beat())
.hcutoff(1000).hpa([0.05, 0.25, 0.5].beat(2))
.hpenv(8).hpq(10).out()`,
true,
)}
### Bandpass envelope
| Method | Alias | Description |
|------------|-----------|---------------------------------|
| <ic>bpenv</ic> | <ic>bpe</ic> | bandpass frequency modulation amount (negative or positive) |
| <ic>bpattack</ic> | <ic>bpa</ic> | attack of the bandpass filter |
| <ic>bpdecay</ic> | <ic>bpd</ic> | decay of the bandpass filter |
| <ic>bpsustain</ic> | <ic>bps</ic> | sustain of the bandpass filter |
| <ic>bprelease</ic> | <ic>bpr</ic> | release of the bandpass filter |
| <ic>bpadsr</ic> | | (**takes five arguments**) set all the parameters |
${makeExample(
"And the bandpass filter, just for fun",
`beat(.5) :: sound('sawtooth').note([48,60].beat())
.bandf([500,1000,2000].beat(2))
.bpa([0.25, 0.125, 0.5].beat(2) * 4)
.bpenv(-4).release(2).out()
`,
true,
)}
## Wavetable synthesis
Topos can also do wavetable synthesis. Wavetable synthesis allows you to use any sound file as a source to build an oscillator. By default, Topos comes with more than 1000 waveforms thanks to the awesome [AKWF](https://www.adventurekid.se/akrt/waveforms/adventure-kid-waveforms/) pack made by Kristoffer Ekstrand. Any sample name that contains <ic>wt_</ic> as a prefix will be interpreted by the sampler as a wavetable and thus as an oscillator. See for yourself:
${makeExample(
"Acidity test",
`
beat(.25) :: sound('wt_symetric:8').note([50,55,57,60].beat(.25) - [12,0]
.pick()).ftype('12db').adsr(0.05/4, 1/16, 0.25/4, 0)
.cutoff(1500 + usine(1/8) * 5000).lpadsr(16, 0.2, 0.2, 0.125/2, 0)
.room(0.9).size(0.9).resonance(0.2).gain(0.3).out()
beat(1) :: sound('kick').n(4).out()
beat(2) :: sound('snare').out()
beat(.5) :: sound('hh').out()`,
true,
)}
Let's explore the galaxy of possible waveforms. It can be hard to explore them all, there is a **lot** of them:
${makeExample(
"Let's explore some wavetables",
`
// Exploring a vast galaxy of waveforms
let collection = [
'wt_sinharm', 'wt_linear', 'wt_bw_sawrounded',
'wt_eorgan', 'wt_theremin', 'wt_overtone',
'wt_fmsynth', 'wt_bitreduced', 'wt_bw_squrounded'];
beat(2) :: v('selec', irand(1, 100))
beat(2) :: v('swave', collection.pick())
beat(0.5) :: sound(v('swave')).n(v('selec')).out()
`,
true,
)}
You can work with them just like with any other waveform. Having so many of them makes them also very useful for generating sound effects, percussive, sounds, etc...
# Frequency Modulation Synthesis (FM)
Another really useful technique to know about is FM synthesis, FM standing for _frequency modulation_. Our basic waveforms can take some additional parameters to be transformed into a two operators FM synthesizer (with _carrier_ and _modulator_). FM Synthesis is a very complex and fascinating topic. There are a lot of things you can design using this technique but keep in mind this advice: **simple ratios will yield stable and harmonic sounds, complex ratios will generate noises, percussions and gritty sounds**.
- <ic>fmi</ic> (_frequency modulation index_): a floating point value between <ic>1</ic> and <ic>n</ic>.
- <ic>fmh</ic> (_frequency modulation harmonic ratio_): a floating point value between <ic>1</ic> and <ic>n</ic>.
- <ic>fmwave</ic> (_frequency modulation waveform_): a waveform name (_sine_, _triangle_, _sawtooth_ or _pulse_).
There is also an additional parameter, <ic>fm</ic> that combines <ic>fmi</ic> and <ic>fmh</ic> using strings: <ic>fm('2:4')</ic>. Think of it as a static shortcut for getting some timbres more quickly.
${makeExample(
"80s nostalgia",
`
beat([.5, 1].beat(8)) && snd('triangle').adsr(0.02, 0.5, 0.5, 0.25)
.fmi(2).fmh(1.5).note([60,55, 60, 63].beat() - 12)
.pan(noise()).out()
beat(.25) && snd('triangle').adsr(0.02, 0.1, 0.1, 0.1)
.fmi([2,4].beat(4)).fmh(1.5)
.pan(noise()).note([60,55, 60, 63].beat() + [0, 7].pick()).out()
beat(2) :: sound('cp').room(1).sz(1).out()
`,
true,
)}
${makeExample(
"Giving some love to ugly inharmonic sounds",
`
beat([.5, .25].bar()) :: sound('sine').fm('2.2183:3.18293').sustain(0.05).out()
beat([4].bar()) :: sound('sine').fm('5.2183:4.5').sustain(0.05).out()
beat(.5) :: sound('sine')
.fmh([1, 1.75].beat())
.fmi($(1) % 30).orbit(2).room(0.5).out()`,
true,
)}
${makeExample(
"Peace and serenity through FM synthesis",
`
beat(0.25) :: sound('sine')
.note([60, 67, 70, 72, 77].beat() - [0,12].bar())
.attack(0.2).release(0.5).gain(0.25)
.room(0.9).size(0.8).sustain(0.5)
.fmi(Math.floor(usine(.25) * 10))
.cutoff(1500).delay(0.5).delayt(0.125)
.delayfb(0.8).fmh(Math.floor(usine(.5) * 4))
.out()`,
true,
)}
**Note:** you can also set the _modulation index_ and the _harmonic ratio_ with the <ic>fm</ic> argument. You will have to feed both as a string: <ic>fm('2:4')</ic>. If you only feed one number, only the _modulation index_ will be updated.
There is also a more advanced set of parameters you can use to control the envelope of the modulator. These parameters are:
- <ic>fmattack</ic> / <ic>fmatk</ic>: attack time of the modulator envelope.
- <ic>fmdecay</ic> / <ic>fmdec</ic>: decay time of the modulator envelope.
- <ic>fmsustain</ic> / <ic>fmsus</ic>: sustain time of the modulator envelope.
- <ic>fmrelease</ic> / <ic>fmrel</ic>: release time of the modulator envelope.
${makeExample(
"FM Synthesis with envelope control",
`
beat(.5) :: sound('sine')
.note([50,53,55,57].beat(.5) - 12)
.fmi(0.5 + usine(.25) * 1.5)
.fmh([2,4].beat(.125))
.fmwave('triangle')
.fmsus(0).fmdec(0.2).out()
`,
true,
)}
## ZzFX
[ZzFX](https://github.com/KilledByAPixel/ZzFX) is a _Zuper Zmall Zound Zynth_. It was created by Frank Force (_aka_ KilledByAPixel) to generate small sound effects for games. It is a very simple synthesizer that can generate a wide range of sounds. It is based on a single oscillator with a simple envelope. ZzFX is very useful for generating percussive sounds and short sound effects. It is also very useful for generating chiptune sounds. You can use it in Topos just like the regular basic synthesizer.
ZZfX can be triggered by picking a default ZZfX waveform in the following list: <ic>z_sine</ic>, <ic>z_triangle</ic>, <ic>z_sawtooth</ic>, <ic>z_tan</ic>, <ic>z_noise</ic>.
${makeExample(
"Picking a waveform",
`
beat(.5) :: sound(['z_sine', 'z_triangle', 'z_sawtooth', 'z_tan', 'z_noise'].beat()).out()
`,
true,
)}
${makeExample(
"Minimalist chiptune",
`
beat(.5) :: sound('z_triangle')
.note([60, 67, 72, 63, 65, 70].beat(.5))
.zrand(0).curve([1,2,3,4].beat(1))
.slide(0.01).tremolo(12)
.noise([0,0.5].beat())
.decay(0.3).sustain(0)
.room(0.5).size(0.9)
.pitchJumpTime(0.01).out()
`,
true,
)}
It comes with a set of parameters that can be used to tweak the sound. Don't underestimate this synth! It is very powerful for generating anything ranging from chaotic noise sources to lush pads:
| Method | Alias | Description |
|----------|-------|------------------------------------------------------------|
|<ic>zrand</ic>| | randomisation factor.|
|<ic>attack</ic>|<ic>atk</ic>| attack time of the envelope.|
|<ic>decay</ic>|<ic>dec</ic>| decay time of the envelope.|
|<ic>sustain</ic>|<ic>sus</ic>| sustain time of the envelope.|
|<ic>release</ic>|<ic>rel</ic>| release time of the envelope.|
|<ic>volume</ic>|<ic>vol</ic>| overall volume |
|<ic>frequency</ic>|freq| sound frequency, also supports <ic>note</ic>.
|<ic>curve</ic>| | Oscillator waveshaping (0-3) |
|<ic>slide</ic>|<ic>sld</ic>| Pitch slide |
|<ic>deltaSlide</ic>|<ic>dslide</ic>| Other pitch slide parameter |
|<ic>pitchJump</ic>|<ic>pj</ic>| Pitch change after pitchJumpTime |
|<ic>pitchJumpTime</ic>|<ic>pjt</ic>| Applies pitchJump after _n_ |
|<ic>noise</ic>| | adds noise|
|<ic>zcrush</ic>| | Bitcrushing |
|<ic>zdelay</ic>| | Weird tiny delay |
|<ic>tremolo</ic>| | Amplitude tremolo (can be loud) |
|<ic>zmod</ic>|| frequency modulation speed.|
|<ic>duration</ic>|| Total sound duration (overrides envelope) |
${makeExample(
"Chaotic Noise source",
`
beat(.25) :: sound('z_tan')
.note(40).noise(rand(0.0, 1.0))
.pitchJump(84).pitchJumpTime(rand(0.0, 1.0))
.zcrush([0,1,2,3,4].beat())
.zmod(rand(0.0, 1.0))
.cutoff(irand(2000,5000))
.sustain(0).decay([0.2, 0.1].pick())
.out()
`,
true,
)}
${makeExample(
"What is happening to me?",
`
beat(1) :: snd('zzfx').zzfx([
[4.77,,25,,.15,.2,3,.21,,2.4,,,,,,,.23,.35],
[1.12,,97,.11,.16,.01,4,.77,,,30,.17,,,-1.9,,.01,.67,.2]
].beat()).out()
`,
false,
)}
${makeExample(
"Les voitures dans le futur",
`
beat(1) :: sound(['z_triangle', 'z_sine'].pick())
.note([60,63,72,75].pick()).tremolo(16)
.zmod([0, 1/2, 1/8].div(2).pick())
.attack(0.5).release(0.5).sustain(2).delay(0.8)
.room(0.9).size(0.9)
.delayt(0.75).delayfb(0.5).out()
`,
false,
)}
Note that you can also design sounds [on this website](https://killedbyapixel.github.io/ZzFX/) and copy the generated code in Topos. To do so, please use the <ic>zzfx</ic> method with the generated array:
${makeExample(
"Designing a sound on the ZzFX website",
`
beat(2) :: sound('zzfx').zzfx([3.62,,452,.16,.1,.21,,2.5,,,403,.05,.29,,,,.17,.34,.22,.68]).out()
`,
true,
)}
# Speech synthesis
Topos can also speak using the [Web Speech API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Speech_API). There are two ways to use speech synthesis:
- <ic>speak(text: string, lang: string, voice: number, rate: number, pitch: number, volume: number)</ic>
- <ic>text</ic>: the text you would like to synthesize (_e.g_ <ic>"Wow, Topos can speak!"</ic>).
- <ic>lang</ic>: language code, for example <ic>en</ic> for English, <ic>fr</ic> for French or with the country code for example British English <ic>en-GB</ic>. See supported values from the [list](https://cloud.google.com/speech-to-text/docs/speech-to-text-supported-languages).
- <ic>voice</ic>: voice index, for example <ic>0</ic> for the first voice, <ic>1</ic> for the second voice, etc.
- <ic>rate(number)</ic>: speaking rate, from <ic>0.0</ic> to <ic>10</ic>.
- <ic>pitch(number)</ic>: speaking pitch, from <ic>0.0</ic> to <ic>2</ic>.
- <ic>volume(number)</ic>: speaking volume, from <ic>0.0</ic> to <ic>1.0</ic>.
${makeExample(
"Hello world!",
`
beat(4) :: speak("Hello world!")
`,
true,
)}
${makeExample(
"Let's hear people talking about Topos",
`
beat(2) :: speak("Topos!","fr",irand(0,5))
`,
true,
)}
You can also use speech by chaining methods to a string:
${makeExample(
"Foobaba is the real deal",
`
onbeat(4) :: "Foobaba".voice(irand(0,10)).speak()
`,
true,
)}
${makeExample(
"Building string and chaining",
`
const subject = ["coder","user","loser"].pick()
const verb = ["is", "was", "isnt"].pick()
const object = ["happy","sad","tired"].pick()
const sentence = subject+" "+verb+" "+" "+object
beat(6) :: sentence.pitch(0).rate(0).voice([0,2].pick()).speak()
`,
true,
)}
${makeExample(
"Live coded poetry with array and string chaining",
`
tempo(70)
const croissant = [
"Volant", "Arc-en-ciel", "Chocolat", "Dansant",
"Nuage", "Tournant", "Galaxie", "Chatoyant",
"Flamboyant", "Cosmique", "Croissant!"
];
onbeat(4) :: croissant.bar()
.lang("fr")
.volume(rand(0.2,2.0))
.rate(rand(.4,.6))
.speak();
`,
true,
)}
`;
};