fleshing out the sound documentation

src/Documentation.ts

@@ -129,35 +129,40 @@ const midi: string = `
 `
 
 const sound: string = `
-# Sound and Notes
+# Sample playback
 
-Topos is capable of:
+The Topos audio engine is based on the [SuperDough](https://www.npmjs.com/package/superdough) audio backend. It is a very powerful and flexible audio backend. It is based on the [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API) and is capable of playing samples, synths, and effects. It is also capable of playing samples and synths in a polyphonic way. It is a very powerful tool to create complex sounds and textures. A set of default sounds are already provided by default but you can also load your own audio samples. They will be loaded through a special URL scheme using the <icode>sample</icode> function.
-- sending MIDI to your hardware or software synthesizers.
-- playing sound samples and internal synths using the [SuperDough](https://www.npmjs.com/package/superdough) audio backend.
 
-As a first test, try to evaluate the following scripts in the global script (${key_shortcut('Ctrl + G')}). We will first learn about the audio engine.
+I recommended you to run the following scripts in the global script (${key_shortcut('Ctrl + G')}).
 
 ## Audio Engine
 
-To play a very basic kick drum, evaluate the following script:
+The basic function to play a sound is <icode>sound('sample/synth').out()</icode>. If the given sound exists in the database, it will be automatically queried and will start playing once loaded. To play a very basic beat, evaluate the following script:
 
 \`\`\`javascript
 mod(48) && sound('bd').out()
-\`\`\`
-
-And for good measure, let's add a high-hat:
-
-\`\`\`javascript
 mod(24) && sound('hh').out()
 \`\`\`
 
-The sounds will be loaded automatically and start playing when they are ready. Let's translate these instructions to plain english. It reads like :
+In plain english, this translates to:
 
 > Every 48 pulses, play a kick drum.
 > Every 24 pulses, play a high-hat.
 
 If you remove the **mod** instruction, you will end up with a deluge of kick drums and high-hats. The **mod** instruction is used to filter out pulses. It is a very useful instruction to create basic rhythms. The **mod** function checks if the current pulse is a multiple of the given number. If it is, it returns <icode>true</icode>, otherwise it returns <icode>false</icode>. You will find a lot of these kind of logical functions in Topos.
 
+## Pick a sample
+
+The <icode>.n(number)</icode> 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:
+
+\`\`\`javascript
+mod(48) && sound('kick').n(pick(1,2,3,4,5,6,7,8)).out()
+\`\`\`
+
+Don't worry about the number. If it gets too big, it will be automatically wrapped to the number of samples in the folder.
+
+## Sound Chains
+
 The <icode>sound('sample_name')</icode> function can be chained to _specify_ a sound more. For instance, you can add a filter and some effects to your high-hat:
 \`\`\`javascript
 mod(24) && sound('hh')
@@ -169,39 +174,39 @@ mod(24) && sound('hh')
 
 No sound will play until you add <icode>.out()</icode> at the end of the chain. Chaining sounds makes it easy to compose and think about sound samples and synthesis. There are many possible arguments that you can add to your sounds.
 
-## Sound modifiers
+| Method                                 | Description |
-- <icode>unit(value: number)</icode>: Sets the unit value of the sound.
+| -------------------------------------- | ----------- |
-- <icode>frequency(value: number)</icode>: Sets the playback sample frequency. 
+| <icode>unit(value: number)</icode>     | Sets the unit value  |
-- <icode>nudge(value: number)</icode>: Adjusts the start time of the sound by the given value.
+| <icode>frequency(value: number)</icode>| Sets the playback sample frequency |
-- <icode>cut(value: number)</icode>: Cut the sample if it overlaps on the same orbit.
+| <icode>nudge(value: number)</icode>    | Adjusts the start time of the sound by the given value |
-- <icode>loop(value: number)</icode>: Loops the sample.
+| <icode>cut(value: number)</icode>| Cut the sample if it overlaps on the same orbit. |
-- <icode>clip(value: number)</icode>: Sets the clip value of the sound.
+| <icode>loop(value: number)</icode>| Loops the sample. |
-- <icode>n(value: number)</icode>: Choose a sample in the selected sample folder.
+| <icode>clip(value: number)</icode>| Sets the clip value of the sound. |
-- <icode>note(value: number)</icode>: Sets the note value of the sound.
+| <icode>n(value: number)</icode>| Sample number in the sample folder. |
-- <icode>speed(value: number)</icode>: Sets the playback speed for the given sound.
+| <icode>note(value: number)</icode>| Sets the note value of the sound. |
-- <icode>begin(value: number)</icode>: Sets the beginning of sample (between <icode>0.0</icode> and <icode>1.0</icode>).
+| <icode>speed(value: number)</icode>| Sets the playback speed. |
-- <icode>end(value: number)</icode>: Sets the end of sample (between <icode>0.0</icode> and <icode>1.0</icode>).
+| <icode>begin(value: number)</icode>| Sets the beginning of sample (between <icode>0.0</icode> and <icode>1.0</icode>). |
-- <icode>gain(value: number)</icode>: Sets the gain value of the given sound.
+| <icode>end(value: number)</icode>| Sets the end of sample (between <icode>0.0</icode> and <icode>1.0</icode>). |
-- <icode>cutoff(value: number)</icode>: Sets the cutoff frequency of the low-pass filter.
+| <icode>gain(value: number)</icode>| Sets the gain. |
-- <icode>resonance(value: number)</icode>: Sets the resonance value of the low-pass filter.
+| <icode>cutoff(value: number)</icode>| Sets the cutoff frequency of the low-pass filter. |
-- <icode>hcutoff(value: number)</icode>: Sets the high cutoff frequency value of high-pass filter.
+| <icode>resonance(value: number)</icode>| Sets the resonance value of the low-pass filter. |
-- <icode>hresonance(value: number)</icode>: Sets the high resonance value of high-pass filter.
+| <icode>hcutoff(value: number)</icode>| Sets the cutoff frequency value of high-pass filter. |
-- <icode>bandf(value: number)</icode>: Sets the band frequency value of the bandpass filter.
+| <icode>hresonance(value: number)</icode>| Sets the resonance value of high-pass filter. |
-- <icode>bandq(value: number)</icode>: Sets the band Q value of the bandpass filter.
+| <icode>bandf(value: number)</icode>| Sets the frequency value of the bandpass filter. |
-- <icode>coarse(value: number)</icode>: Sets the coarse value of the given sound.
+| <icode>bandq(value: number)</icode>| Sets the Q value of the bandpass filter. |
-- <icode>crush(value: number)</icode>: Sets some amount of bitcrush on the given sound.
+| <icode>coarse(value: number)</icode>| Adds some flavor of saturation. |
-- <icode>shape(value: number)</icode>: Sets some distortion on the given sound.
+| <icode>crush(value: number)</icode>| Adds some amount of bitcrush on the given sound. |
-- <icode>pan(value: number)</icode>: Sets the pan value of the sound (between <icode>0.0</icode> and <icode>1.0</icode>).
+| <icode>shape(value: number)</icode>| Adds some distortion. |
-- <icode>vowel(value: number)</icode>: Sets a formant vowel filter on the given sound(<icode>'a'</icode>, <icode>'e'</icode>, <icode>'i'</icode>, <icode>'o'</icode>, <icode>'u'</icode>.).
+| <icode>pan(value: number)</icode>| Sets the panoramic value of the sound (in stereo, between <icode>0.0</icode> and <icode>1.0</icode>). |
-- <icode>delay(value: number)</icode>: Sets the delay value of the sound.
+| <icode>vowel(value: number)</icode>| Sets a formant vowel filter on the given sound(<icode>'a'</icode>, <icode>'e'</icode>, <icode>'i'</icode>, <icode>'o'</icode>, <icode>'u'</icode>.). |
-- <icode>delayfeedback(value: number)</icode>: Sets the delay feedback value of the sound.
+| <icode>delay(value: number)</icode>| Sets the delay wet/dry value. |
-- <icode>delaytime(value: number)</icode>: Sets the delay time value of the sound.
+| <icode>delayfeedback(value: number)</icode>| Sets delay feedback. |
-- <icode>orbit(value: number)</icode>: Sets the orbit value of the sound.
+| <icode>delaytime(value: number)</icode>| Sets delay time (in seconds). |
-- <icode>room(value: number)</icode>: Sets the room value of the sound.
+| <icode>orbit(value: number)</icode>| Sets the orbit value of the sound. |
-- <icode>size(value: number)</icode>: Sets the size value of the sound.
+| <icode>room(value: number)</icode>| Sets reverb room. |
-- <icode>velocity(value: number)</icode>: Sets the velocity value of the sound.
+| <icode>size(value: number)</icode>| Sets reverb size. |
-- <icode>out()</icode>: Returns an object processed by the <icode>superdough</icode> function, using the current values in the <icode>values</icode> object and the <icode>pulse_duration</icode> from the <icode>app.clock</icode>.
+| <icode>velocity(value: number)</icode>| Sets velocity. |
-
+| <icode>out()</icode> | Returns an object processed by the <icode>superdough</icode> function, using the current values in the <icode>values</icode> object and the <icode>pulse_duration</icode> from the <icode>app.clock</icode>. |
 `
 
 

src/main.ts

@@ -37,6 +37,10 @@ const classMap = {
   code: "my-4 block whitespace-pre overflow-x-scroll",
   icode: "my-4 text-white font-mono bg-neutral-600",
   blockquote: "text-neutral-200 border-l-4 border-neutral-500 pl-4 my-4 mx-4",
+  table: "justify-center my-8 mx-8 text-2xl w-full text-left text-white border-collapse",
+  thead: "text-xs text-gray-700 uppercase bg-gray-50 dark:bg-gray-700 dark:text-gray-400",
+  th: "px-6 py-6",
+  td: "py-2"
 }
 // const bindings = Object.keys(classMap)
 //   .map(key => ({