Merge pull request #320 from jarmitage/main

tutorial updates

package.json

@@ -10,7 +10,7 @@
     "test-ui": "vitest --ui",
     "test-coverage": "vitest --coverage",
     "bootstrap": "lerna bootstrap",
-    "setup": "npm i && npm run bootstrap && cd website && npm i",
+    "setup": "npm i && npm run jsdoc-json && npm run bootstrap && cd website && npm i",
     "snapshot": "vitest run -u --silent",
     "repl": "cd website && npm run dev",
     "osc": "cd packages/osc && npm run server",

website/src/config.ts

@@ -45,12 +45,17 @@ export const SIDEBAR: Sidebar = {
   en: {
     Tutorial: [
       { text: 'Getting Started', link: 'learn/getting-started' },
-      { text: 'Mini Notation', link: 'learn/mini-notation' },
-      { text: 'Synths, Samples & FX', link: 'learn/synths-samples-effects' },
+      { text: 'Notes', link: 'learn/notes' },
+      { text: 'Sounds', link: 'learn/sounds' },
+      { text: 'Coding syntax', link: 'learn/code' },
+      { text: 'Mini-notation', link: 'learn/mini-notation' },
+      { text: 'Samples', link: 'learn/samples' },
+      { text: 'Synths', link: 'learn/synths' },
+      { text: 'Audio effects', link: 'learn/effects' },
       { text: 'Functions', link: 'learn/functions' },
       { text: 'Signals', link: 'learn/signals' },
       { text: 'Tonal', link: 'learn/tonal' },
-      { text: 'Outputs', link: 'learn/outputs' },
+      { text: 'MIDI & OSC', link: 'learn/input-output' },
     ],
   },
 };

website/src/pages/learn/code.mdx

@@ -0,0 +1,82 @@
+---
+title: Coding syntax
+description: Strudel Tutorial - Coding syntax
+layout: ../../layouts/MainLayout.astro
+---
+
+import { MiniRepl } from '../../docs/MiniRepl';
+import { JsDoc } from '../../docs/JsDoc';
+
+# Strudel Code
+
+Now that we have played some notes using different sounds, let's take a step back and look how we actually achieved this using _code_.
+
+Let's look at this simple example again. What do we notice?
+
+<MiniRepl client:idle tune={`freq("220 275 330 440").s("sine")`} />
+
+- We have a word `freq` which is followed by some brackets `()` with some words/letters/numbers inside, surrounded by quotes `"a3 c#4 e4 a4"`.
+- Then we have a dot `.` followed by another similar piece of code `s("sawtooth")`.
+- We can also see these texts are _highlighted_ using colours: word `freq` is purple, the brackets `()` are grey, and the content inside the `""` are green.
+
+What happens if we try to 'break' this pattern in different ways?
+
+<MiniRepl client:idle tune={`freq(220 275 330 440).s(sine)`} />
+
+<MiniRepl client:idle tune={`freq("220 275 330 440")s("sine")`} />
+
+<MiniRepl client:idle tune={`freq["220 275 330 440"].s{"sine"}`} />
+
+Ok, none of these seem to work...
+
+<MiniRepl client:idle tune={`s("sine").freq("220 275 330 440")`} />
+
+This one does work, but now we can't hear the four different events and frequencies anymore.
+
+So what is going on here?
+
+# Functions, arguments and chaining
+
+So far, we've seen the following syntax:
+
+```
+xxx("foo").yyy("bar")
+```
+
+Generally, `xxx` and `yyy` are called [_functions_](<https://en.wikipedia.org/wiki/Function_(computer_programming)>), while `foo` and `bar` are called function [_arguments_ or _parameters_](<https://en.wikipedia.org/wiki/Parameter_(computer_programming)>).
+So far, we've used the functions to declare which aspect of the sound we want to control, and their arguments for the actual data.
+The `yyy` function is called a [_chained_ function](https://en.wikipedia.org/wiki/Method_chaining), because it is appended with a dot (`.`).
+
+Generally, the idea with chaining is that code such as `a("this").b("that").c("other")` allows `a`, `b` and `c` functions to happen in a specified order, without needing to write them as three separate lines of code.
+You can think of this as being similar to chaining audio effects together using guitar pedals or digital audio effects.
+
+Strudel makes heavy use of chained functions. Here is a more sophisticated example:
+
+<MiniRepl
+  client:idle
+  tune={`note("a3 c#4 e4 a4")
+.s("sawtooth")
+.cutoff(500)
+//.delay(0.5)
+.room(0.5)`}
+/>
+
+# Comments
+
+The `//` in the example above is a line comment, resulting in the `delay` function being ignored.
+It is a handy way to quickly turn code on and off.
+Try uncommenting this line by deleting `//` and refreshing the pattern.
+You can also use the keyboard shortcut `cmd-/` to toggle comments on and off.
+
+# Strings
+
+Ok, so what about the content inside the quotes (e.g. `"a3 c#4 e4 a4"`)?
+In JavaScript, as in most programming languages, this content is referred to as being a [_string_](<https://en.wikipedia.org/wiki/String_(computer_science)>).
+A string is simply a sequence of individual characters.
+In TidalCycles, strings are used to write _patterns_ using the mini-notation, and you may hear the phrase _pattern string_ from time to time.
+
+The good news is, that this covers 99% of the JavaScript syntax needed for Strudel!
+
+Let's now look at the way we can express [Rhythms](/learn/mini-notation)...
+
+<br />

website/src/pages/learn/effects.mdx

@@ -0,0 +1,65 @@
+---
+title: Audio effects
+description: Strudel Tutorial - Audio effects
+layout: ../../layouts/MainLayout.astro
+---
+
+import { MiniRepl } from '../../docs/MiniRepl';
+import { JsDoc } from '../../docs/JsDoc';
+
+# Audio Effects
+
+Wether you're using a synth or a sample, you can apply any of the following built-in audio effects.
+As you might suspect, the effects can be chained together, and they accept a pattern string as their argument.
+
+# bandf
+
+<JsDoc client:idle name="bandf" h={0} />
+
+# bandq
+
+<JsDoc client:idle name="bandq" h={0} />
+
+# coarse
+
+<JsDoc client:idle name="coarse" h={0} />
+
+# crush
+
+<JsDoc client:idle name="crush" h={0} />
+
+# cutoff
+
+<JsDoc client:idle name="cutoff" h={0} />
+
+# gain
+
+<JsDoc client:idle name="gain" h={0} />
+
+# hcutoff
+
+<JsDoc client:idle name="hcutoff" h={0} />
+
+# hresonance
+
+<JsDoc client:idle name="hresonance" h={0} />
+
+# pan
+
+<JsDoc client:idle name="pan" h={0} />
+
+# resonance
+
+<JsDoc client:idle name="resonance" h={0} />
+
+# shape
+
+<JsDoc client:idle name="shape" h={0} />
+
+# velocity
+
+<JsDoc client:idle name="velocity" h={0} />
+
+# vowel
+
+<JsDoc client:idle name="vowel" h={0} />

website/src/pages/learn/getting-started.mdx

@@ -1,26 +1,48 @@
 ---
 title: Getting Started
-description: Strudel Tutorial
+description: Strudel Tutorial - Getting Started
 layout: ../../layouts/MainLayout.astro
 ---
 
 import { MiniRepl } from '../../docs/MiniRepl';
 import { JsDoc } from '../../docs/JsDoc';
 
+# Welcome
+
+Welcome to the Strudel documentation pages!
+
+These pages will introduce you to [Strudel](https://strudel.tidalcycles.org/), a web-based [live coding](https://github.com/toplap/awesome-livecoding/) environment that implements the [Tidal Cycles](https://tidalcycles.org) algorithmic pattern language.
+
 # What is Strudel?
 
-With Strudel, you can expressively write dynamic music pieces.
-It aims to be [Tidal Cycles](https://tidalcycles.org/) for JavaScript (started by the same author).
+[Strudel](https://strudel.tidalcycles.org/) is a version of [Tidal Cycles](https://tidalcycles.org) written in [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript), initiated by [Alex McLean](https://slab.org) and [Felix Roos](https://github.com/felixroos) in 2022.
+Tidal Cycles, also known as Tidal, is a language for [algorithmic pattern](https://algorithmicpattern.org), and though it is most commonly used for [making music](https://tidalcycles.org/docs/showcase), it can be used for any kind of pattern making activity, including [weaving](https://www.youtube.com/watch?v=TfEmEsusXjU).
 
-You don't need to know JavaScript or Tidal Cycles to make music with Strudel.
+Tidal was first implemented as a library written in the [Haskell](https://www.haskell.org/) functional programming language, and by itself it does not make any sound.
+To make sound, it has to be connected to a sound engine, and by default this is a [SuperCollider](https://supercollider.github.io/) plugin called [SuperDirt](https://github.com/musikinformatik/SuperDirt/).
+As such, it can be difficult for first-time users to install both Tidal Cycles and SuperDirt, as there are many small details to get right.
+Strudel however runs directly in your web browser, does not require any custom software installation, and can make sound all by itself.
+
+# Strudel REPL and MiniREPL
 
+The main place to actually make music with Strudel is the [Strudel REPL](https://strudel.tidalcycles.org/) ([what is a REPL?](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop)), but in these pages you will also encounter interactive "MiniREPLs" where you can listen to and edit Strudel patterns.
+Try clicking the play icon below:
+
+<MiniRepl client:idle tune={`s("bd sn")`} />
+
+Then edit the text so it reads `s("bd sn cp hh")` and click the refresh icon.
+Congratulations, you have now live coded your first Strudel pattern!
+
+With Strudel, you can expressively write dynamic music pieces.
+You don't need to know JavaScript or Tidal Cycles to make music with Strudel.
 This interactive tutorial will guide you through the basics of Strudel.
 
-The best place to actually make music with Strudel is the [Strudel REPL](https://strudel.tidalcycles.org/).
+# Show me some demos!
 
-## Show me a Demo
+To see and hear what Strudel can do, visit the [Strudel REPL](https://strudel.tidalcycles.org/) and click the Shuffle icon in the top menu bar.
+You can get a feel for Strudel by browsing and editing these examples and clicking the Refresh icon to update.
 
-To get a taste of what Strudel can do, check out this track:
+Alternatively, you can get a taste of what Strudel can do by clicking play on this track:
 
 <MiniRepl
   client:idle
@@ -53,93 +75,15 @@ s("bd,[~ <sd!3 sd(3,4,2)>],hh(3,4)") // drums
 .slow(3/2)`}
 />
 
-## Disclaimer
-
-- This project is still in its experimental state. In the future, parts of it might change significantly.
-- This tutorial is far from complete.
-
-# Playing Pitches
-
-Pitches are an essential building block for music. In Strudel, there are 3 different options to express a pitch:
-
-- `note`: letter notation
-- `n`: number notation
-- `freq`: frequency notation
-
-## note
-
-Notes are notated with the note letter, followed by the octave number. You can notate flats with `b` and sharps with `#`.
-
-<MiniRepl client:only="react" tune={`note("a3 c#4 e4 a4")`} />
-
-By the way, you can edit the contents of the player, and press "update" to hear your change!
-You can also press "play" on the next player without needing to stop the last one.
-
-## n
-
-If you don't like notes, you can also use numbers with `n` instead:
-
-<MiniRepl client:only="react" tune={`n("57 61 64 69")`} />
-
-These numbers are interpreted as so called midi numbers, where adjacent whole numbers are 1 semitone apart.
-You could also write decimal numbers to get microtonal pitches:
-
-<MiniRepl client:only="react" tune={`n("74.5 75 75.5 76")`} />
-
-## freq
-
-To get maximum freedom, you can also use `freq` to directly control the frequency:
-
-<MiniRepl client:only="react" tune={`freq("220 275 330 440")`} />
-
-In this example, we play A3 (220Hz), C#4 natural (275Hz), E4 (330Hz) and A4 (440Hz).
-
-<br />
-
-# Playing Sounds
-
-Instead of pitches, we can also play sounds with `s`:
-
-<MiniRepl client:only="react" tune={`s("bd hh sd hh")`} />
-
-Similarly, we can also use `s` to change the sound of our pitches:
-
-<MiniRepl client:only="react" tune={`note("a3 c#4 e4 a4").s("sawtooth")`} />
-
-Try changing the sound to `square`, `triangle` or `sine`!
-
-We will go into the defails of sounds and synths [later](/learn/synths-samples-effects).
-
-<br />
-
-# Syntax
-
-So far, we've seen the following syntax:
-
-```
-xxx("foo").yyy("bar")
-```
-
-Generally, `xxx` and `yyy` are called functions, while `foo` and `bar` are called function arguments.
-So far, we've used the functions to declare which aspect of the sound we want to control, and their arguments for the actual data.
-The `yyy` function is called a chained function, because it is appended with a dot.
-
-Strudel makes heavy use of chained functions. Here is a more extreme example:
-
-<MiniRepl
-  client:idle
-  tune={`note("a3 c#4 e4 a4")
-.s("sawtooth")
-.cutoff(500)
-//.delay(0.5)
-.room(0.5)`}
-/>
+# Strudel is a work in progress 🚧
 
-The `//` is a line comment, resulting in the `delay` function being ignored.
-It is a handy way to quickly turn stuff on and off. Try uncommenting this line by deleting `//`!
+Please note that this project is still in its experimental state.
+In the future, parts of it might change significantly.
+This tutorial is also far from complete.
+You can contribute to it clicking 'Edit this page' in the top right, or by visiting the [Strudel GitHub page](https://github.com/tidalcycles/strudel/).
 
-The good news is, that this covers 99% of the JavaScript syntax needed for Strudel!
+# What's next?
 
-Let's now look at the way we can express rhythms..
+Head on over to the [Notes](/learn/notes) page.
 
 <br />