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,
)}
`;
};

162
src/documentation/learning/midi.ts Normal file
View File

@ -0,0 +1,162 @@
import { type Editor } from "../../main";
import { makeExampleFactory, key_shortcut } from "../../Documentation";
export const midi = (application: Editor): string => {
const makeExample = makeExampleFactory(application);
return `
# MIDI
You can use Topos to play MIDI thanks to the [WebMIDI API](https://developer.mozilla.org/en-US/docs/Web/API/Web_MIDI_API). You can currently send notes, control change, program change and so on. You can also send a MIDI Clock to your MIDI devices or favorite DAW. Note that Topos is also capable of playing MIDI using **Ziffers** which provides a better syntax for melodic expression.
**Important note:** for the examples on this page to work properly, you will need to configure your web browser to output **MIDI** on the right port. You will also need to make sure to have a synthesizer ready to receive MIDI data (hardware or software). You can use softwares like [VCVRack](https://vcvrack.com/), [Dexed](https://asb2m10.github.io/dexed/), [Surge](https://surge-synthesizer.github.io/) or [SunVox](https://www.warmplace.ru/soft/sunvox/) to get enough instruments for a lifetime.
## MIDI Configuration
Your web browser is capable of sending and receiving MIDI information through the [Web MIDI API](https://developer.mozilla.org/en-US/docs/Web/API/Web_MIDI_API). The support for MIDI on browsers is a bit shaky. Please, take some time to configure and test. To our best knowledge, **Chrome** is currently leading on this feature, followed closely by **Firefox**. The other major web browsers are also starting to support this API. **There are two important functions for configuration:**
- <ic>midi_outputs()</ic>: prints the list of available MIDI devices on the screen. You will have to open the web console using ${key_shortcut(
"Ctrl+Shift+I",
)} or sometimes ${key_shortcut(
"F12",
)}. You can also open it from the menu of your web browser. **Note:** close the docs to see it printed.
${makeExample(
"Listing MIDI outputs",
`
midi_outputs()
`,
true,
)}
- <ic>midi_output(output_name: string)</ic>: enter your desired output to connect to it.
${makeExample(
"Changing MIDI output",
`
midi_output("MIDI Rocket-Trumpet")
`,
true,
)}
That's it! You are now ready to play with MIDI.
## Notes
The most basic MIDI event is the note. MIDI notes traditionally take three parameters: _note_ (from <ic>0</ic> to <ic>127</ic>), _velocity_ (from <ic>0</ic> to <ic>127</ic>) and _channel_ (from <ic>0</ic> to <ic>15</ic>). MIDI notes are quite important and can be used for a lot of different things. You can use them to trigger a synthesizer, a drum machine, a robot, or anything really!
- <ic>midi(note: number|object)</ic>: send a MIDI Note. This function is quite bizarre. It can be written and used in many different ways. You can pass form one up to three arguments in different forms.
${makeExample(
"MIDI note using one parameter: note",
`
// Configure your MIDI first!
// => midi_output("MIDI Bus 1")
rhythm(.5, 5, 8) :: midi(50).out()
`,
true,
)}
${makeExample(
"MIDI note using three parameters: note, velocity, channel",
`
// MIDI Note 50, Velocity 50 + LFO, Channel 0
rhythm(.5, 5, 8) :: midi(50, 50 + usine(.5) * 20, 0).out()
`,
false,
)}
${makeExample(
"MIDI note by passing an object",
`
// MIDI Note 50, Velocity 50 + LFO, Channel 0
rhythm(.5, 5, 8) :: midi({note: 50, velocity: 50 + usine(.5) * 20, channel: 0}).out()
`,
false,
)}
We can now have some fun and starting playing a small piano piece:
${makeExample(
"Playing some piano",
`
tempo(80) // Setting a default BPM
beat(.5) && midi(36 + [0,12].beat()).sustain(0.02).out()
beat(.25) && midi([64, 76].pick()).sustain(0.05).out()
beat(.75) && midi([64, 67, 69].beat()).sustain(0.05).out()
beat(.25) && midi([64, 67, 69].beat() + 24).sustain(0.05).out()
`,
true,
)}
## Control and Program Changes
- <ic>control_change({control: number, value: number, channel: number})</ic>: send a MIDI Control Change. This function takes a single object argument to specify the control message (_e.g._ <ic>control_change({control: 1, value: 127, channel: 1})</ic>).
${makeExample(
"Imagine that I am tweaking an hardware synthesizer!",
`
control_change({control: [24,25].pick(), value: irand(1,120), channel: 1})
control_change({control: [30,35].pick(), value: irand(1,120) / 2, channel: 1})
`,
true,
)}
- <ic>program_change(program: number, channel: number)</ic>: send a MIDI Program Change. This function takes two arguments to specify the program and the channel (_e.g._ <ic>program_change(1, 1)</ic>).
${makeExample(
"Crashing old synthesizers: a hobby",
`
program_change([1,2,3,4,5,6,7,8].pick(), 1)
`,
true,
)}
## System Exclusive Messages
- <ic>sysex(...number[])</ic>: send a MIDI System Exclusive message. This function takes any number of arguments to specify the message (_e.g._ <ic>sysex(0x90, 0x40, 0x7f)</ic>).
${makeExample(
"Nobody can say that we don't support Sysex messages!",
`
sysex(0x90, 0x40, 0x7f)
`,
true,
)}
## Clock
- <ic>midi_clock()</ic>: send a MIDI Clock message. This function is used to synchronize Topos with other MIDI devices or DAWs.
${makeExample(
"Tic, tac, tic, tac...",
`
beat(.25) && midi_clock() // Sending clock to MIDI device from the global buffer
`,
true,
)}
## Using midi with ziffers
Ziffers offers some shorthands for defining channels within the patterns. See Ziffers for more information.
${makeExample(
"Using midi with ziffers",
`
z1('0 2 e 5 2 q 4 2').midi().port(2).channel(4).out()
`,
true,
)}
${makeExample(
"Setting the channel within the pattern",
`
z1('(0 2 e 5 2):0 (4 2):1').midi().out()
`,
true,
)}
`;
};

75
src/documentation/learning/osc.ts Normal file
View File

@ -0,0 +1,75 @@
import { type Editor } from "../../main";
import { makeExampleFactory } from "../../Documentation";
export const osc = (application: Editor): string => {
// @ts-ignore
const makeExample = makeExampleFactory(application);
return `
# Open Sound Control
Topos is a sandboxed web application. It cannot speak with your computer directly or only through a secure connexion. You can use the [Open Sound Control](https://en.wikipedia.org/wiki/Open_Sound_Control) protocol to send and receive data from your computer. This protocol is used by many softwares and hardware devices. You can use it to control your favorite DAW, your favorite synthesizer, your favorite robot, or anything really! To use **OSC** with Topos, you will need to download the <ic>ToposServer</ic> by [following this link](https://github.com/Bubobubobubobubo/Topos). You can download everything as a zip file or clone the project if you know what you are doing. Here is a quick guide to get you started:
- 1) Download <ic>Topos</ic> and navigate to the <ic>ToposServer</ic> folder.
- 2) Install the dependencies using <ic>npm install</ic>. Start the server using <ic>npm start</ic>.
- 3) Open the <ic>Topos</ic> application in your web browser (server first, then application).
The <ic>ToposServer</ic> server is used both for **OSC** _input_ and _output_.
## Input
Send an **OSC** message to the server from another application or device at the address <ic>localhost:30000</ic>. Topos will store the last 1000 messages in a queue. You can access this queue using the <ic>getOsc()</ic> function.
### Unfiltered messages
You can access the last 1000 messages using the <ic>getOsc()</ic> function without any argument. This is raw data, you will need to parse it yourself:
${makeExample(
"Reading the last OSC messages",
`
beat(1)::getOsc()
// 0 : {data: Array(2), address: '/lala'}
// 1 : {data: Array(2), address: '/lala'}
// 2 : {data: Array(2), address: '/lala'}`,
true,
)}
### Filtered messages
The <ic>getOsc()</ic> can receive an address filter as an argument. This will return only the messages that match the filter:
${makeExample(
"Reading the last OSC messages (filtered)",
`
beat(1)::getOsc("/lala")
// 0 : (2) [89, 'bob']
// 1 : (2) [84, 'bob']
// 2 : (2) [82, 'bob']
`,
true,
)}
## Output
Once the server is loaded, you are ready to send an **OSC** message:
${makeExample(
"Sending a simple OSC message",
`
beat(1)::sound('cp').speed(2).vel(0.5).osc()
`,
true,
)}
This is a simple **OSC** message that will inherit all the properties of the sound. You can also send customized OSC messages using the <ic>osc()</ic> function:
${makeExample(
"Sending a customized OSC message",
`
// osc(address, port, ...message)
osc('/my/osc/address', 5000, 1, 2, 3)
`,
true,
)}
`;
};

66
src/documentation/learning/samples/loading_samples.ts Normal file
View File

@ -0,0 +1,66 @@
import { type Editor } from "../../../main";
import { makeExampleFactory } from "../../../Documentation";
export const loading_samples = (application: Editor): string => {
// @ts-ignore
const makeExample = makeExampleFactory(application);
return `# Loading custom samples
Topos is exposing the <ic>samples</ic> function that you can use to load your own set of samples.
Samples are loaded on-the-fly from the web. Topos is a web application living in the browser. It is running in a sandboxed environment. Thus, it cannot have access to the files stored on your local system. Loading samples requires building a _map_ of the audio files, where a name is associated to a specific file:
${makeExample(
"Loading samples from a map",
`samples({
bd: ['bd/BT0AADA.wav','bd/BT0AAD0.wav'],
sd: ['sd/rytm-01-classic.wav','sd/rytm-00-hard.wav'],
hh: ['hh27/000_hh27closedhh.wav','hh/000_hh3closedhh.wav'],
}, 'github:tidalcycles/Dirt-Samples/master/');`,
true,
)}
This example is loading two samples from each folder declared in the original repository (in the <ic>strudel.json</ic> file). You can then play with them using the syntax you are already used to:
${makeExample(
"Playing with the loaded samples",
`rhythm(.5, 5, 8)::sound('bd').n(ir(1,2)).end(1).out()
`,
true,
)}
Internally, Topos is loading samples using a different technique where sample maps are directly taken from the previously mentioned <ic>strudel.json</ic> file that lives in each repository:
${makeExample(
"This is how Topos is loading its own samples",
`
// Visit the concerned repos and search for 'strudel.json'
samples("github:tidalcycles/Dirt-Samples/master");
samples("github:Bubobubobubobubo/Dough-Samples/main");
samples("github:Bubobubobubobubo/Dough-Amiga/main");
`,
true,
)}
To learn more about the audio sample loading mechanism, please refer to [this page](https://strudel.tidalcycles.org/learn/samples) written by Felix Roos who has implemented the sample loading mechanism. The API is absolutely identic in Topos!
# Loading sounds using Shabda
You can load samples coming from [Freesound](https://freesound.org/) using the [Shabda](https://shabda.ndre.gr/) API. To do so, study the following example:
${makeExample(
"Loading samples from shabda",
`
// Prepend the sample you want with 'shabda:'
samples("shabda:ocean")
// Use the sound without 'shabda:'
beat(1)::sound('ocean').clip(1).out()
`,
true,
)}
You can also use the <ic>.n</ic> attribute like usual to load a different sample.
`;
};

13
src/documentation/learning/samples/sample_banks.ts Normal file
View File

@ -0,0 +1,13 @@
import { type Editor } from "../../../main";
import { makeExampleFactory } from "../../../Documentation";
export const sample_banks = (application: Editor): string => {
// @ts-ignore
const makeExample = makeExampleFactory(application);
return `# Sample Banks
There is a <ic>bank</ic> attribute that can help you to sort audio samples from large collections.
**AJKPercusyn**, **AkaiLinn**, **AkaiMPC60**, **AkaiXR10**, **AlesisHR16**, **AlesisSR16**, **BossDR110**, **BossDR220**, **BossDR55**, **BossDR550**, **BossDR660**, **CasioRZ1**, **CasioSK1**, **CasioVL1**, **DoepferMS404**, **EmuDrumulator**, **EmuModular**, **EmuSP12**, **KorgDDM110**, **KorgKPR77**, **KorgKR55**, **KorgKRZ**, **KorgM1**, **KorgMinipops**, **KorgPoly800**, **KorgT3**, **Linn9000**, **LinnDrum**, **LinnLM1**, **LinnLM2**, **MFB512**, **MPC1000**, **MoogConcertMateMG1**, **OberheimDMX**, **RhodesPolaris**, **RhythmAce**, **RolandCompurhythm1000**, **RolandCompurhythm78**, **RolandCompurhythm8000**, **RolandD110**, **RolandD70**, **RolandDDR30**, **RolandJD990**, **RolandMC202**, **RolandMC303**, **RolandMT32**, **RolandR8**, **RolandS50**, **RolandSH09**, **RolandSystem100**, **RolandTR505**, **RolandTR606**, **RolandTR626**, **RolandTR707**, **RolandTR727**, **RolandTR808**, **RolandTR909**, **SakataDPM48**, **SequentialCircuitsDrumtracks**, **SequentialCircuitsTom**, **SergeModular**, **SimmonsSDS400**, **SimmonsSDS5**, **SoundmastersR88**, **UnivoxMicroRhythmer12**, **ViscoSpaceDrum**, **XdrumLM8953**, **YamahaRM50**, **YamahaRX21**, **YamahaRX5**, **YamahaRY30**, **YamahaTG33**.
`;
};

152
src/documentation/learning/samples/sample_list.ts Normal file
View File

@ -0,0 +1,152 @@
import { type Editor } from "../../../main";
import { makeExampleFactory } from "../../../Documentation";
export const samples_to_markdown = (
application: Editor,
tag_filter?: string,
) => {
let samples = application.api._all_samples();
let markdownList = "";
let keys = Object.keys(samples);
let i = -1;
while (i++ < keys.length - 1) {
//@ts-ignore
if (!samples[keys[i]].data) continue;
//@ts-ignore
if (!samples[keys[i]].data.samples) continue;
// @ts-ignore
if (samples[keys[i]].data.tag !== tag_filter) continue;
//markdownList += `**${keys[i]}** (_${
// //@ts-ignore
// samples[keys[i]].data.samples.length
//}_) `;
//
// Adding new examples for each sample folder!
const codeId = `sampleExample${i}`;
application.api.codeExamples[
codeId
] = `sound("${keys[i]}").n(irand(1, 5)).end(1).out()`;
// @ts-ignore
const howMany = samples[keys[i]].data.samples.length;
markdownList += `
<button
class="hover:bg-neutral-500 inline px-4 py-2 bg-neutral-700 text-orange-300 text-xl"
onclick="app.api._playDocExampleOnce(app.api.codeExamples['${codeId}'])"
>
${keys[i]}
<b class="text-white">(${howMany})</b>
</button>`;
}
return markdownList;
};
export const injectAllSamples = (application: Editor): string => {
let generatedPage = samples_to_markdown(application, "Topos");
return generatedPage;
};
export const injectDrumMachineSamples = (application: Editor): string => {
let generatedPage = samples_to_markdown(application, "Machines");
return generatedPage;
};
export const sample_list = (application: Editor): string => {
// @ts-ignore
const makeExample = makeExampleFactory(application);
return `
# Available audio samples
On this page, you will find an exhaustive list of all the samples currently loaded by default by the system. Samples are sorted by **sample packs**. I am gradually adding more of them.
## Waveforms
A very large collection of wavetables for wavetable synthesis. This collection has been released by Kristoffer Ekstrand: [AKWF Waveforms](https://www.adventurekid.se/akrt/waveforms/adventure-kid-waveforms/). Every sound sample that starts with <ic>wt_</ic> will be looped. Look at this demo:
${makeExample(
"Wavetable synthesis made easy :)",
`
beat(0.5)::sound('wt_stereo').n([0, 1].pick()).ad(0, .25).out()
`,
true,
)}
Pick one folder and spend some time exploring it. There is a lot of different waveforms.
<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-neutral-600 mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
${samples_to_markdown(application, "Waveforms")}
</div>
## Drum machines sample pack
A set of 72 classic drum machines created by **Geikha**: [Geikha Drum Machines](https://github.com/geikha/tidal-drum-machines). To use them efficiently, it is best to use the <ic>.bank()</ic> parameter like so:
${makeExample(
"Using a classic drum machine",
`
beat(0.5)::sound(['bd', 'cp'].pick()).bank("AkaiLinn").out()
`,
true,
)}
Here is the complete list of available machines:
<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-neutral-600 mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
${samples_to_markdown(application, "Machines")}
</div>
## FoxDot sample pack
The default sample pack used by Ryan Kirkbride's [FoxDot](https://github.com/Qirky/FoxDot). It is a nice curated sample pack that covers all the basic sounds you could want.
<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-neutral-600 mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
${samples_to_markdown(application, "FoxDot")}
</div>
## Amiga sample pack
This set of audio samples is taken from [this wonderful collection](https://archive.org/details/AmigaSoundtrackerSamplePacksst-xx) of **Ultimate Tracker Amiga samples**. They were initially made by Karsten Obarski. These files were processed: pitched down one octave, gain down 6db. The audio has been processed with [SoX](https://github.com/chirlu/sox). The script used to do so is also included in this repository.
<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-neutral-600 mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
${samples_to_markdown(application, "Amiga")}
</div>
## Amen break sample pack
A collection of many different amen breaks. Use <ic>.stretch()</ic> to play with these:
${makeExample(
"Stretching an amen break",
`
beat(4)::sound('amen1').stretch(4).out()
`,
true,
)}
The stretch should be adapted based on the length of each amen break.
<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-neutral-600 mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
${samples_to_markdown(application, "Amen")}
</div>
## TidalCycles sample library
Many live coders are expecting to find the Tidal sample library wherever they go, so here it is :)
<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-neutral-600 mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
${samples_to_markdown(application, "Tidal")}
</div>
## Juliette's voice
This sample pack is only one folder full of french phonems! It sounds super nice.
<div class="lg:pl-6 lg:pr-6 w-fit rounded-lg bg-neutral-600 mx-6 mt-2 my-6 px-2 py-2 max-h-96 flex flex-row flex-wrap gap-x-2 gap-y-2 overflow-y-scroll">
${samples_to_markdown(application, "Juliette")}
</div>
`;
};

256
src/documentation/learning/time/cyclical_time.ts Normal file
View File

@ -0,0 +1,256 @@
import { type Editor } from "../../../main";
import { makeExampleFactory } from "../../../Documentation";
export const cyclical_time = (app: Editor): string => {
// @ts-ignore
let makeExample = makeExampleFactory(app);
return `
# Cyclical time
Time as a cycle. A cycle can be quite long (a few bars) or very short (a few pulses). Cyclical time is extremely interesting for _live coders_ since it allows you to control a process that will eventually repeat. If your time constructs are repeating, you are able to hear them again and again. Since you can react and alter the code to change the loops, you become part of a complex feedback system between the computer and yourself.
## Simple rhythms
- <ic>beat(n: number | number[] = 1, offset: number = 1)</ic>: return true every _n_ beats.
- <ic>number</ic>: if <ic>number = 1</ic>, the function will return <ic>true</ic> every beat. Lists can be used too.
- <ic>offset</ic>: offset (in beats) to apply. An offset of <ic>0.5</ic> will return true against the beat.
${makeExample(
"Using different mod values",
`
// This code is alternating between different mod values
beat([1,1/2,1/4,1/8].beat(2)) :: sound('hat').n(0).out()
`,
true,
)}
${makeExample(
"Some sort of ringtone",
`
// Blip generator :)
let blip = (freq) => {
return sound('wt_piano')
.gain(1)
.sustain(0.1)
.freq(freq)
.cutoff(1500)
.lpadsr(4, 0, .25, 0, 0)
};
beat(1) :: blip(200).pan(r(0,1)).vib(0.5).vibmod(2).out();
beat(1/3) :: blip(400).pan(r(0,1)).out();
flip(3) :: beat(1/6) :: blip(800).pan(r(0,1)).out();
beat([1,0.75].beat(2)) :: blip([50, 100].beat(2)).pan(r(0,1)).out();
`,
false,
)}
${makeExample(
"Beat can match multiple values",
`
beat([.5, 1.25])::sound('hat').out()
`,
false,
)}
- <ic>pulse(n: number | number[] = 1, offset: number = 1)</ic>: return true every _n_ pulses. A pulse is the tiniest possible rhythmic value.
- <ic>number</ic>: if <ic>number = 1</ic>, the function will return <ic>true</ic> every pulse. Lists can be used too.
- <ic>offset</ic>: offset (in pulses) to apply.
${makeExample(
"Intriguing rhythms",
`
pulse([24, 16])::sound('hat').ad(0, .02).out()
pulse([48, [36,24].dur(4, 1)])::sound('fhardkick').ad(0, .1).out()
`,
true,
)}
${makeExample(
"pulse is the OG rhythmic function in Topos",
`
pulse([48, 24, 16].beat(4)) :: sound('linnhats').out()
beat(1)::snd(['bd', '808oh'].beat(1)).out()
`,
false,
)}
- <ic>bar(n: number | number[] = 1, offset: number = 1)</ic>: return true every _n_ bars.
- <ic>number</ic>: if <ic>number = 1</ic>, the function will return <ic>true</ic> every bar. Lists can be used too.
- <ic>offset</ic>: offset (in bars) to apply.
${makeExample(
"Four beats per bar: proof",
`
bar(1)::sound('kick').out()
beat(1)::sound('hat').speed(2).out()
`,
true,
)}
${makeExample(
"Offsetting beat and bar",
`
bar(1)::sound('kick').out()
beat(1)::sound('hat').speed(2).out()
beat(1, 0.5)::sound('hat').speed(4).out()
bar(1, 0.5)::sound('sn').out()
`,
false,
)}
- <ic>onbeat(...n: number[])</ic>: The <ic>onbeat</ic> function allows you to lock on to a specific beat from the clock to execute code. It can accept multiple arguments. It's usage is very straightforward and not hard to understand. You can pass either integers or floating point numbers. By default, topos is using a <ic>4/4</ic> bar meaning that you can target any of these beats (or in-between) with this function.
${makeExample(
"Some simple yet detailed rhythms",
`
onbeat(1,2,3,4)::snd('kick').out() // Bassdrum on each beat
onbeat(2,4)::snd('snare').n([8,4].beat(4)).out() // Snare on acccentuated beats
onbeat(1.5,2.5,3.5, 3.75)::snd('hat').gain(r(0.9,1.1)).out() // Cool high-hats
`,
true,
)}
## XOX Style sequencers
- <ic>seq(expr: string, duration: number = 0.5): boolean</ic> : this function takes a string composed of <ic>x</ic> and <ic>o</ic> symbols like so: <ic>"xoxxoo"</ic>. It will return <ic>true</ic> (<ic>x</ic>) or <ic>false</ic> (<ic>o</ic>) after a <ic>duration</ic> amount.
- <ic>expr: string</ic>: any string composed of <ic>x</ic> or <ic>o</ic> like so: <ic>"xooxoxxoxoo"</ic>.
- <ic>duration: number</ic>: an optional duration (in beats) like <ic>1</ic> or </ic>4</ic>. It can be patterned.
${makeExample(
"Sequence built using a classic XOX sequencer style",
`
seq('xoxo')::sound('fhardkick').out()
seq('ooxo')::sound('fsoftsnare').out()
seq('xoxo', 0.25)::sound('fhh').out()
`,
true,
)}
${makeExample(
"Another sequence using more complex parameters",
`
seq('xoxooxxoo', [0.5, 0.25].dur(2, 1))::sound('fhardkick').out()
seq('ooxo', [1, 2].bar())::sound('fsoftsnare').speed(0.5).out()
seq(['xoxoxoxx', 'xxoo'].bar())::sound('fhh').out()
`,
true,
)}
- <ic>fullseq(expr: string, duration: number = 0.5): boolean</ic> : a variant. Will return <ic>true</ic> or <ic>false</ic> for a whole period, depending on the symbol. Useful for long structure patterns.
- <ic>expr: string</ic>: any string composed of <ic>x</ic> or <ic>o</ic> like so: <ic>"xooxoxxoxoo"</ic>.
- <ic>duration: number</ic>: an optional duration (in beats) like <ic>1</ic> or </ic>4</ic>. It can be patterned.
${makeExample(
"Long structured patterns",
`
function simplePat() {
log('Simple pattern playing!')
seq('xoxooxxoo', [0.5, 0.25].dur(2, 1))::sound('fhardkick').out()
seq('ooxo', [1, 2].bar())::sound('fsoftsnare').speed(0.5).out()
seq(['xoxoxoxx', 'xxoo'].bar())::sound('fhh').out()
}
function complexPat() {
log('Complex pattern playing!')
seq('xoxooxxoo', [0.5, 0.25].dur(2, 1))::sound('fhardkick').out()
seq('ooxo', [1, 2].bar())::sound('fsoftsnare').speed(0.5).out()
seq(['xoxoxoxx', 'xxoo'].bar())::sound('fhh').out()
}
fullseq('xooxooxx', 4) ? simplePat() : complexPat()
`,
true,
)}
## Cyclical rhythm generators
We included a bunch of popular rhythm generators in Topos such as the euclidian rhythms algorithms or the one to generate rhythms based on a binary sequence. They all work using _iterators_ that you will gradually learn to use for iterating over lists. Note that they are levaraging <ic>mod(...n:number[])</ic> that you just learned about!
- <ic>rhythm(divisor: number, pulses: number, length: number, rotate: number): boolean</ic>: generates <ic>true</ic> or <ic>false</ic> values from an euclidian rhythm sequence. This is another version of <ic>euclid</ic> that does not take an iterator.
${makeExample(
"rhythm is a beginner friendly rhythmic function!",
`
rhythm(.5, 4, 8)::sound('sine')
.fmi(2)
.room(0.5).size(8)
.freq(250).ad(0, .2).out()
rhythm(.5, 7, 8)::sound('sine')
.freq(125).ad(0, .2).out()
rhythm(.5, 3, 8)::sound('sine').freq(500).ad(0, .5).out()
`,
true,
)}
- <ic>oneuclid(pulses: number, length: number, rotate: number): boolean</ic>: generates <ic>true</ic> or <ic>false</ic> values from an euclidian rhythm sequence. This is another version of <ic>euclid</ic> that does not take an iterator.
${makeExample(
"Using oneuclid to create a rhythm without iterators",
`
// Change speed using bpm
bpm(250)
oneuclid(5, 9) :: snd('kick').out()
oneuclid(7,16) :: snd('east').end(0.5).n(irand(3,5)).out()
`,
true,
)}
- <ic>bin(iterator: number, n: number): boolean</ic>: a binary rhythm generator. It transforms the given number into its binary representation (_e.g_ <ic>34</ic> becomes <ic>100010</ic>). It then returns a boolean value based on the iterator in order to generate a rhythm.
- <ic>binrhythm(divisor: number, n: number): boolean: boolean</ic>: iterator-less version of the binary rhythm generator.
${makeExample(
"Change the integers for a surprise rhythm!",
`
bpm(135);
beat(.5) && bin($(1), 12) && snd('kick').n([4,9].beat(1.5)).out()
beat(.5) && bin($(2), 34) && snd('snare').n([3,5].beat(1)).out()
`,
true,
)}
${makeExample(
"binrhythm for fast cool binary rhythms!",
`
let a = 0;
a = beat(4) ? irand(1,20) : a;
binrhythm(.5, 6) && snd(['kick', 'snare'].beat(0.5)).n(11).out()
binrhythm([.5, .25].beat(1), 30) && snd('wt_granular').n(a)
.cutoff(800).lpadsr(4, 0, 0.125, 0.5, 0.25)
.adsr(0, r(.1, .4), 0, 0).freq([50, 60, 72].beat(4))
.room(1).size(1).out()
`,
true,
)}
${makeExample(
"Submarine jungle music",
`
bpm(145);
beat(.5) && bin($(1), 911) && snd('ST69').n([2,3,4].beat())
.delay(0.125).delayt(0.25).end(0.25).speed(1/3)
.room(1).size(1).out()
beat(.5) && sound('amencutup').n(irand(2,7)).shape(0.3).out()
`,
false,
)}
If you don't find it spicy enough, you can add some more probabilities to your rhythms by taking advantage of the probability functions. See the functions documentation page to learn more about them.
${makeExample(
"Probablistic drums in one line!",
`
prob(60)::beat(.5) && euclid($(1), 5, 8) && snd('kick').out()
prob(60)::beat(.5) && euclid($(2), 3, 8) && snd('mash')
.n([1,2,3].beat(1))
.pan(usine(1/4)).out()
prob(80)::beat(.5) && sound(['hh', 'hat'].pick()).out()
`,
true,
)}
`;
};

192
src/documentation/learning/time/linear_time.ts Normal file
View File

@ -0,0 +1,192 @@
import { type Editor } from "../../../main";
import { makeExampleFactory } from "../../../Documentation";
import pulses from "./pulses.svg";
export const linear_time = (app: Editor): string => {
// @ts-ignore
let makeExample = makeExampleFactory(app);
return `
# Linear time
**Topos** time is flowing just like in your typical computer music program, with _bars_, _beats_, _pulses_ and so on. The transport can be **paused**, **resumed** and/or **stopped**. There are interface buttons to handle these tasks. The tiniest unit of time is the **pulse**. There is a finite number of **pulses** per **beat** (by default, <ic>48</ic> **PPQN**). Beats are passing at a given **BPM** (_beats per minute_). You can change the **BPM** anytime you want. You can also change the granularity of time.
<object type="image/svg+xml" data=${pulses} style="width: 100%; height: auto; background-color: transparent"></object>
### Beats, bar, pulses
**Topos** is using three core values to deal with time:
- **bars**: how many bars have elapsed since the origin of time.
- **beats**: how many beats have elapsed since the beginning of the bar.
- **pulse**: how many pulses have elapsed since the last beat.
There is a tiny widget at the bottom right of the screen showing you the current BPM and the status of the transport. You can turn it on or off in the settings menu.
${makeExample(
"Printing the transport",
`
log(\`\$\{cbar()}\, \$\{cbeat()\}, \$\{cpulse()\}\`)
`,
true,
)}
### BPM and PPQN
The base functions to control time are:
- <ic>bpm(number?)</ic> : get or set the current tempo.
- <ic>tempo(number?)</ic> : alias to <ic>bpm</ic>.
- <ic>ppqn(number?)</ic> : get or set the granularity of time
- The function name comes from [PPQN](https://en.wikipedia.org/wiki/Pulses_per_quarter_note) (_pulses per quarter notes_).
### Controlling time
Note that it is preferable to use the keyboard shortcuts to manipulate the transport system. You can also use the <ic>play()</ic>, <ic>pause()</ic> and <ic>stop()</ic> functions. It is generally preferable to program things instead of relying on the interface!
<br>
## Time Primitives
Every script can access the current time by using the following functions:
- <ic>cbar(n: number)</ic>: current bar since the origin of time.
- <ic>cbeat(n: number)</ic>: current beat since the beginning of the bar.
- <ic>ebeat()</ic>: current beat since the origin of time (counting from 1).
- <ic>cpulse()</ic>: current bar since the origin of the beat.
- <ic>ppqn()</ic>: current **PPQN** (see above).
- <ic>bpm()</ic>: current **BPM** (see above).
- <ic>time()</ic>: current wall clock time, the real time of the system.
These values are **extremely useful** to craft more complex syntax or to write musical scores. However, it means that you have to write more to be more precise. There is a tradeoff between _live-codeability_ and dealing with time manually (verbose). Topos is offering high-level functions to deal with that issue, don't worry :)
You can use time primitives as conditionals. The following example will play a pattern A for 2 bars and a pattern B for 2 bars:
${makeExample(
"Manual mode: using time primitives!",
`
// Manual time condition
if((cbar() % 4) > 1) {
beat(2) && sound('kick').out()
rarely() && beat(.5) && sound('sd').out()
beat([.5, .25].beat()) && sound('jvbass')
.freq(100 * [2, 1].pick()).dec(2)
.room(0.9).size(0.9).orbit(2).out()
} else {
beat(.5) && sound('hh').out()
beat(2) && sound('cp').out()
beat([.5, .5, .25].beat(.5)) && sound('jvbass')
.freq(100 * [3, 1].pick()).dec(2)
.room(0.9).size(0.9).orbit(2).out()
}
// This is always playing no matter what happens
beat([.5, .5, 1, .25].beat(0.5)) :: sound('shaker').out()
`,
true,
)}
## Time Warping
Time generally flows from the past to the future. However, you can manipulate it to jump back and forth. Think about looping a specific part of your current pattern or song or jumping all of the sudden in the future. This is entirely possible thanks to two simple functions: <ic>warp(n: number)</ic> and <ic>beat_warp(n: number)</ic>. They are both very easy to use and very powerful. Let's see how they work.
- <ic>warp(n: number)</ic>: this function jumps to the _n_ tick of the clock. <ic>1</ic> is the first pulsation ever and the number keeps increasing indefinitely. You are most likely currently listening to tick n°<ic>12838123</ic>.
${makeExample(
"Time is now super elastic!",
`
// Obscure Shenanigans - Bubobubobubo
beat([1/4,1/8,1/16].beat(8)):: sound('sine')
.freq([100,50].beat(16) + 50 * ($(1)%10))
.gain(0.5).room(0.9).size(0.9)
.sustain(0.1).out()
beat(1) :: sound('kick').out()
beat(2) :: sound('dr').n(5).out()
flip(3) :: beat([.25,.5].beat(.5)) :: sound('dr')
.n([8,9].pick()).gain([.8,.5,.25,.1,.0].beat(.25)).out()
// Jumping back and forth in time
beat(.25) :: warp([12, 48, 24, 1, 120, 30].pick())
`,
true,
)}
- <ic>beat_warp(beat: number)</ic>: this function jumps to the _n_ beat of the clock. The first beat is <ic>1</ic>.
${makeExample(
"Jumping back and forth with beats",
`
// Resonance bliss - Bubobubobubo
beat(.25)::snd('arpy')
.note(30 + [0,3,7,10].beat())
.cutoff(usine(.5) * 5000).resonance(10).gain(0.3)
.end(0.8).room(0.9).size(0.9).n(0).out();
beat([.25,.125].beat(2))::snd('arpy')
.note(30 + [0,3,7,10].beat())
.cutoff(usine(.5) * 5000).resonance(20).gain(0.3)
.end(0.8).room(0.9).size(0.9).n(3).out();
beat(.5) :: snd('arpy').note(
[30, 33, 35].repeatAll(4).beat(1) - [12,0].beat(0.5)).out()
// Comment me to stop warping!
beat(1) :: beat_warp([2,4,5,10,11].pick())
`,
true,
)}
## Transport-based rhythm generators
- <ic>onbeat(...n: number[])</ic>: The <ic>onbeat</ic> function allows you to lock on to a specific beat from the clock to execute code. It can accept multiple arguments. It's usage is very straightforward and not hard to understand. You can pass either integers or floating point numbers. By default, topos is using a <ic>4/4</ic> bar meaning that you can target any of these beats (or in-between) with this function.
${makeExample(
"Some simple yet detailed rhythms",
`
onbeat(1,2,3,4)::snd('kick').out() // Bassdrum on each beat
onbeat(2,4)::snd('snare').n([8,4].beat(4)).out() // Snare on acccentuated beats
onbeat(1.5,2.5,3.5, 3.75)::snd('hat').gain(r(0.9,1.1)).out() // Cool high-hats
`,
true,
)}
${makeExample(
"Let's do something more complex",
`
onbeat(0.5, 2, 3, 3.75)::snd('kick').n(2).out()
onbeat(2, [1.5, 3, 4].pick(), 4)::snd('snare').n(8).out()
beat([.25, 1/8].beat(1.5))::snd('hat').n(2)
.gain(rand(0.4, 0.7)).end(0.05)
.pan(usine()).out()
`,
false,
)}
- <ic>oncount(beats: number[], meter: number)</ic>: This function is similar to <ic>onbeat</ic> but it allows you to specify a custom number of beats as the last argument.
${makeExample(
"Using oncount to create more variation in the rhythm",
`
z1('1/16 (0 2 3 4)+(0 2 4 6)').scale('pentatonic').sound('sawtooth')
.cutoff([400,500,1000,2000].beat(1))
.lpadsr(2, 0, .2, 0, 0)
.delay(0.5).delayt(0.25).room(0.9).size(0.9).out()
onbeat(1,1.5,2,3,4) :: sound('bd').gain(2.0).out()
oncount([1,3,5.5,7,7.5,8],8) :: sound('hh').gain(irand(1.0,4.0)).out()
`,
true,
)}
${makeExample(
"Using oncount to create rhythms with a custom meter",
`
bpm(200)
oncount([1, 5, 9, 13],16) :: sound('808bd').n(4).shape(0.5).gain(1.0).out()
oncount([5, 6, 13],16) :: sound('shaker').room(0.25).gain(0.9).out()
oncount([2, 3, 3.5, 6, 7, 10, 15],16) :: sound('hh').n(8).gain(0.8).out()
oncount([1, 4, 5, 8, 9, 10, 11, 12, 13, 14, 15, 16],16) :: sound('hh').out()
`,
true,
)}
`;
};

162
src/documentation/learning/time/long_forms.ts Normal file
View File

@ -0,0 +1,162 @@
import { type Editor } from "../../../main";
import { makeExampleFactory } from "../../../Documentation";
export const long_forms = (app: Editor): string => {
// @ts-ignore
let makeExample = makeExampleFactory(app);
return `
# Long forms
Now you know how to play some basic rhythms but in any case, you are stuck in a loop. It's time to learn how to compose larger/longer musical structures. The functions you are going to learn are all about mastering the flow of time on longer periods. **Read and experiment a lot with the following examples**.
## Using scripts and universes
- **Use the nine local scripts as containers** for sections of your composition. When you start playing with **Topos**, it's easy to forget that there are multiple scripts you can play with. Each script can store a different section or part from your composition. Here is a simple example:
${makeExample(
"Eight bars per section",
`
// Playing each script for 8 bars in succession
script([1,2,3,4].bar(8))
`,
true,
)}
You can also give a specific duration to each section using <ic>.dur</ic>:
${makeExample(
"N beats per section",
`
script([1,2,3,4].dur(8, 2, 16, 4))
`,
true,
)}
- **Use universes as well**. Transitions between universes are _seamless_, instantaneous. Just switch to different content if you ever hit the limitations of the current _universe_.
## Long-form Functions
- <ic>flip(n: number, ratio: number = 50)</ic>: the <ic>flip</ic> method is a temporal switch. If the value <ic>2</ic> is given, the function will return <ic>true</ic> for two beats and <ic>false</ic> for two beats. There are multiple ways to use it effectively. You can pass an integer or a floating point number.
- <ic>ratio: number = 50</ic>: this argument is ratio expressed in %. It determines how much of the period should be true or false. A ratio of <ic>75</ic> means that 75% of the period will be true. A ratio of <ic>25</ic> means that 25% of the period will be true.
${makeExample(
"Two beats of silence, two beats of playing",
`
flip(4) :: beat(1) :: snd('kick').out()
`,
true,
)}
${makeExample(
"Clapping on the edge",
`
flip(2.5, 10) :: beat(.25) :: snd('cp').out()
flip(2.5, 75) :: beat(.25) :: snd('click')
.speed(2).end(0.2).out()
flip(2.5) :: beat(.5) :: snd('bd').out()
beat(.25) :: sound('hat').end(0.1).cutoff(1200).pan(usine(1/4)).out()
`,
false,
)}
${makeExample(
"Good old true and false",
`
if (flip(4, 75)) {
beat(1) :: snd('kick').out()
} else {
beat(.5) :: snd('snare').out()
}
`,
true,
)}
<ic>flip</ic> is extremely powerful and is used internally for a lot of other Topos functions. You can also use it to think about **longer durations** spanning over multiple bars. Here is a silly composition that is using <ic>flip</ic> to generate a 4 bars long pattern.
${makeExample(
"Clunky algorithmic rap music",
`
// Rap God VS Lil Wild -- Adel Faure
if (flip(8)) {
// Playing this part for two bars
beat(1.5)::snd('kick').out()
beat(2)::snd('snare').out()
beat(.5)::snd('hh').out()
} else {
// Now adding some birds and tablas
beat(1.5)::snd('kick').out()
beat(2)::snd('snare').out()
beat(.5)::snd('hh').out()
beat(.5)::snd('tabla').speed([1,2].pick()).end(0.5).out()
beat(2.34)::snd('birds').n(irand(1,10))
.delay(0.5).delaytime(0.5).delayfb(0.25).out()
beat(.5)::snd('diphone').end(0.5).n([1,2,3,4].pick()).out()
}
`,
true,
)}
You can use it everywhere to spice things up, including as a method parameter picker:
${makeExample(
"flip is great for parameter variation",
`
beat(.5)::snd(flip(2) ? 'kick' : 'hat').out()
`,
true,
)}
- <ic>flipbar(n: number = 1)</ic>: this method works just like <ic>flip</ic> but counts in bars instead of beats. It allows you to think about even larger time cycles. You can also pair it with regular <ic>flip</ic> for writing complex and long-spanning algorithmic beats.
${makeExample(
"Thinking music over bars",
`
let roomy = (n) => n.room(1).size(1).cutoff(500 + usaw(1/8) * 5000);
function a() {
beat(1) && roomy(sound('kick')).out()
beat(.5) && roomy(sound('hat')).out()
}
function b() {
beat(1/4) && roomy(sound('shaker')).out()
}
flipbar(2) && a()
flipbar(3) && b()
`,
true,
)}
${makeExample(
"Alternating over four bars",
`
flipbar(2)
? beat(.5) && snd(['kick', 'hh'].beat(1)).out()
: beat(.5) && snd(['east', 'east:2'].beat(1)).out()
`,
false,
)};
- <ic>onbar(bars: number | number[], n: number)</ic>: The second argument, <ic>n</ic>, is used to divide the time in a period of <ic>n</ic> consecutive bars. The first argument should be a bar number or a list of bar numbers to play on. For example, <ic>onbar([1, 4], 5)</ic> will return <ic>true</ic> on bar <ic>1</ic> and <ic>4</ic> but return <ic>false</ic> the rest of the time. You can easily divide time that way.
${makeExample(
"Using onbar for filler drums",
`
tempo(150);
// Only play on the third and fourth bar of the cycle.
onbar([3,4], 4)::beat(.25)::snd('hh').out();
// Using JavaScript regular control flow
if (onbar([1,2], 4)) {
beat(.5) :: sometimes() :: sound('east').out()
rhythm(.5, 3, 7) :: snd('kick').out();
rhythm(.5, 1, 7) :: snd('jvbass').out();
rhythm(.5, 2, 7) :: snd('snare').n(5).out();
} else {
beat(.5) :: rarely() :: sound('east').n($(1)).out()
rhythm(.5, 3, 7) :: snd('kick').n(4).out();
rhythm(.5, 1, 7) :: snd('jvbass').n(2).out();
rhythm(.5, 2, 7) :: snd('snare').n(3).out();
}`,
true,
)}
`;
};

4
src/documentation/learning/time/pulses.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 8.4 KiB

35
src/documentation/learning/time/time.ts Normal file
View File

@ -0,0 +1,35 @@
import { makeExampleFactory } from "../../../Documentation";
import { type Editor } from "../../../main";
import times from "./times.svg";
export const time = (application: Editor): string => {
//@ts-ignore
const makeExample = makeExampleFactory(application);
return `
# What is time?
There are two ways to think _intuitively_ about time:
- **linear time:** the _arrow_ of time, minutes/days/years passing. Time moving forward. In musical terms, a _piece_, _song_.
- **cyclical time:** seasons, cycles, etc. In musical terms, repetitions, _beats_, _sections_, etc.
A musician's job is to interweave cyclical and linear time, repetition and continuity.
<object type="image/svg+xml" data=${times} style="width: 100%; height: auto; background-color: transparent"></object>
# Time and programming
When you program on a computer, you can adopt a similar mindset to think about time, where time is sometimes cyclic, sometimes linear:
- **linear:** _runtime_, _process time_, _wall clock time_, etc...
- **cyclic:** _recursion_, repeating function, routine, etc.
# Time and Topos
By making music with **Topos**, you will mingle repetitive structures of different scale and deal with composition as well:
- **linear time:** using _bars_, _beats_, _pulses_, transport (_start_/_pause_/_stop_), etc...
- **cyclical time:** euclidean rhythms, beats, pulsed time, etc...
`;
};

4
src/documentation/learning/time/times.svg Normal file
View File

@ -0,0 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- Do not edit this file with editors other than draw.io -->
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="501px" height="151px" viewBox="-0.5 -0.5 501 151" class="ge-export-svg-dark" content="&lt;mxfile host=&quot;app.diagrams.net&quot; modified=&quot;2023-11-06T09:00:40.296Z&quot; agent=&quot;Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36&quot; etag=&quot;C_foan-BfT9OTEfKR49b&quot; version=&quot;22.0.8&quot; type=&quot;device&quot;&gt;&lt;diagram name=&quot;Page-1&quot; id=&quot;SVK7qbBq6eghmxk_gXBK&quot;&gt;7Zddb5swFIZ/DZeVAAfSXK5Jt2lN1Wq5aHs1efgULBlMjVOgv35mGIhjsqKoH7vIFebF59jnfYxsO2iZVt8EzpNrToA5vksqB60c3/dcd6YejVK3yjwMWiEWlOhOg7ChL9BFanVLCRRGR8k5kzQ3xYhnGUTS0LAQvDS7PXJmjprjGCxhE2Fmq3eUyESrXrgYPnwHGifd0GGgK05x11uXUiSY8HJHQpcOWgrOZdtKqyWwxr3OmDbu64Gv/cwEZHJKQDm/pz8u8mj+MydXv182kK/omc7yjNlWV6wnK+vOAsG3GYEmieugizKhEjY5jpqvpYKutESmTL15qqnTgZBQHZyn11ev1g3wFKSoVZdyMDhwtWnJrreBFrGGGvexQ9mqoSsfd+Hp4e7hHv1aXxU1ytcgrtObcIoLil7eNB8ZVF+ahaWKhYzo5ipiuChoZJphOnfAB98FYqzBV4yxfek0AQxL+myu3DGv9Ai3nKqZ+G7/s7YR+k8N98wu+FZEoGN2l9lemtni33kkFjFIK89fbn3Nx6P0TygtlJ5/JEsPvZLonWGiE8wJEKbS7Cf0STSDE80JEKbSRPPPpRmeaE6AcOyu+dE0FxbNNc0Ai+a8TVOw0B5xKByhaJ0TbY7jO1rnzg7l2fkI5n0X3+7EaG9NyzpiVN0c/lPLzt/PMvU6XGPaFTncBtHlHw==&lt;/diagram&gt;&lt;/mxfile&gt;" style="background-color: rgb(18, 18, 18);"><defs><style type="text/css">svg.ge-export-svg-dark &gt; * { filter: invert(100%) hue-rotate(180deg); }&#xa;svg.ge-export-svg-dark image { filter: invert(100%) hue-rotate(180deg) }</style></defs><g><rect x="0" y="0" width="500" height="150" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/><path d="M 10.5 65 L 10.5 55 L 470.5 55 L 470.5 44.5 L 489.5 60 L 470.5 75.5 L 470.5 65 Z" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><path d="M 10.5 125 L 10.5 115 L 110.5 115 L 110.5 104.5 L 129.5 120 L 110.5 135.5 L 110.5 125 Z" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><path d="M 130.5 125 L 130.5 115 L 230.5 115 L 230.5 104.5 L 249.5 120 L 230.5 135.5 L 230.5 125 Z" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><path d="M 250.5 125 L 250.5 115 L 350.5 115 L 350.5 104.5 L 369.5 120 L 350.5 135.5 L 350.5 125 Z" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><path d="M 370.5 125 L 370.5 115 L 470.5 115 L 470.5 104.5 L 489.5 120 L 470.5 135.5 L 470.5 125 Z" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><rect x="10" y="20" width="480" height="20" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 478px; height: 1px; padding-top: 30px; margin-left: 11px;"><div data-drawio-colors="color: rgb(0, 0, 0); " style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Linear time</div></div></div></foreignObject><text x="250" y="34" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">Linear time</text></switch></g><rect x="10" y="80" width="480" height="20" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 478px; height: 1px; padding-top: 90px; margin-left: 11px;"><div data-drawio-colors="color: rgb(0, 0, 0); " style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Cyclical time</div></div></div></foreignObject><text x="250" y="94" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">Cyclical time</text></switch></g></g><switch><g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/><a transform="translate(0,-5)" xlink:href="https://www.drawio.com/doc/faq/svg-export-text-problems" target="_blank"><text text-anchor="middle" font-size="10px" x="50%" y="100%">Text is not SVG - cannot display</text></a></switch></svg>
Side by Side

After

Width:  |  Height:  |  Size: 5.0 KiB