diff --git a/website/src/pages/learn/samples.mdx b/website/src/pages/learn/samples.mdx index 56b6e65c..c2c166b3 100644 --- a/website/src/pages/learn/samples.mdx +++ b/website/src/pages/learn/samples.mdx @@ -24,20 +24,31 @@ Here, we are using the `s` function to play back different default samples (`bd` For drum sounds, strudel uses the comprehensive [tidal-drum-machines](https://github.com/ritchse/tidal-drum-machines) library, with the following naming convention: -| Drum | Abbreviation | +| Drum | Abbreviation | +| -------------------- | ------------ | +| Bass drum, Kick drum | bd | +| Snare drum | sd | +| Rimshot | rim | +| Clap | cp | +| Closed hi-hat | hh | +| Open hi-hat | oh | +| Crash | cr | +| Ride | rd | +| High tom | ht | +| Medium tom | mt | +| Low tom | lt | + + + + + original von Pbroks13 + + +More percussive sounds: + +| Source | Abbreviation | | ----------------------------------- | ------------ | -| Bass drum, Kick drum | bd | -| Snare drum | sd | -| Rimshot | rim | -| Clap | cp | -| Closed hi-hat | hh | -| Open hi-hat | oh | -| Crash | cr | -| Ride | rd | | Shakers (and maracas, cabasas, etc) | sh | -| High tom | ht | -| Medium tom | mt | -| Low tom | lt | | Cowbell | cb | | Tambourine | tb | | Other percussions | perc | @@ -63,11 +74,11 @@ We _could_ use them like this: ... but thats obviously a bit much to write. Using the `bank` function, we can shorten this to: - + You could even pattern the bank to switch between different drum machines: - +")`} /> Behind the scenes, `bank` will just prepend the drum machine name to the sample name with `_` to get the full name. This of course only works because the name after `_` (`bd`, `sd` etc..) is standardized. @@ -97,159 +108,128 @@ Selecting sounds also works inside the mini notation, using "`:`" like this: # Loading Custom Samples -You can load your own sample map using the `samples` function. -In this example we create a map using sounds from the default sample map: +You can load a non-standard sample map using the `samples` function. - +## Loading samples from file URLs -When you load your own samples, you can choose the names that you will then refer to in your pattern string inside the `s` function. -Compare with this example which uses the same samples, but with different names. +In this example we assign names `bassdrum`, `hihat` and `snaredrum` to specific audio files on a server: -Here we have changed the "map" to include longer sample names. +You can freely choose any combination of letters for each sample name. It is even possible to override the default sounds. +The names you pick will be made available in the `s` function. +Make sure that the URL and each sample path form a correct URL! -## The `samples` function +In the above example, `bassdrum` will load: -The `samples` function has two arguments: +``` +https://raw.githubusercontent.com/tidalcycles/Dirt-Samples/master/bd/BT0AADA.wav +|----------------------base path --------------------------------|--sample path-| +``` -- A [JavaScript object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) that maps sound names to audio file paths. -- A base URL that comes before each path describing where the sample folder can be found online. - - Make sure your base URL ends with a slash, while your sample paths do **not** begin with one! +Note that we can either load a single file, like for `bassdrum` and `hihat`, or a list of files like for `snaredrum`! +As soon as you run the code, your chosen sample names will be listed in `sounds` -> `user`. -To see how this looks in practice, compare the [DirtSamples GitHub repo](https://github.com/tidalcycles/Dirt-Samples) with the previous sample map example. +## Loading Samples from a strudel.json file -Because GitHub is a popular place for uploading open source samples, it has its own shortcut: +The above way to load samples might be tedious to write out / copy paste each time you write a new pattern. +To avoid that, you can simply pass a URL to a `strudel.json` file somewhere on the internet: -The format is `github:user/repo/branch/`. +The file is expected to define a sample map using JSON, in the same format as described above. +Additionally, the base path can be defined with the `_base` key. +The last section could be written as: -Let's see another example, this time based on the following GitHub repo: https://github.com/jarmitage/jarmitage.github.io. -We can see there are some guitar samples inside the `/samples` folder, so let's try to load them: +```json +{ + "_base": "https://raw.githubusercontent.com/tidalcycles/Dirt-Samples/master/", + "bassdrum": "bd/BT0AADA.wav", + "snaredrum": "sd/rytm-01-classic.wav", + "hihat": "hh27/000_hh27closedhh.wav" +} +``` + +## Github Shortcut + +Because loading samples from github is common, there is a shortcut: /2")`} + tune={`samples('github:tidalcycles/dirt-samples') +s("bd sd bd sd,hh*16")`} /> -## Multiple Samples per Sound +The format is `samples('github://')`. If you omit `branch` (like above), the `main` branch will be used. +It assumes a `strudel.json` file to be present at the root of the repository: -It is also possible, to declare multiple files for one sound, using the array notation: +``` +https://raw.githubusercontent.com////strudel.json +``` + +## From Disk via "Import Sounds" + +If you don't want to upload your samples to the internet, you can also load them from your local disk. +Go to the `sounds` tab in the REPL and press "import sounds". +Then you can select a folder that contains audio files. The folder you select can also contain subfolders with audio files. +Example: + +``` +└─ samples + ├─ swoop + │ ├─ swoopshort.wav + │ ├─ swooplong.wav + │ └─ swooptight.wav + └─ smash + ├─ smashhigh.wav + ├─ smashlow.wav + └─ smashmiddle.wav +``` + +In the above example the folder `samples` contains 2 subfolders `swoop` and `smash`, which contain audio files. +If you select that `samples` folder, the `user` tab (next to the import sounds button) will then contain 2 new sounds: `swoop(3) smash(3)` +The individual samples can the be played normally like `s("swoop:0 swoop:1 smash:2")`. + +## From Disk via @strudel/sampler + +Instead of loading your samples into your browser with the "import sounds" button, you can also serve the samples from a local file server. +The easiest way to do this is using [@strudel/sampler](https://www.npmjs.com/package/@strudel/sampler): + +```sh +cd samples +npx @strudel/sampler +``` + +Then you can load it via: ~ sd:0,[hh:0 hh:1]*4")`} + tune={`samples('http://localhost:5432/'); + +n("<0 1 2>").s("swoop smash")`} /> -The `:0` `:1` etc. are the indices of the array. -The sample number can also be set using `n`: +The handy thing about `@strudel/sampler` is that it auto-generates the `strudel.json` file based on your folder structure. +You can see what it generated by going to `http://localhost:5432` with your browser. -")`} -/> +Note: You need [NodeJS](https://nodejs.org/) installed on your system for this to work. -In that case, we might load our guitar sample map a different way: +## Specifying Pitch -*2")`} -/> - -And as above, we can choose the sample number using `n` for even more flexibility: - -*2").s("guitar")`} -/> - -## Pitched Sounds - -For pitched sounds, you can use `note`, just like with synths: - -@2").s('gtr').gain(.5)`} -/> - -Here, the guitar samples will overlap, because they always play till the end. -If we want them to behave more like a synth, we can add `clip(1)`: - -@2").s('gtr').clip(1) - .gain(.5)`} -/> - -## Base Pitch - -If we have 2 samples with different base pitches, we can make them in tune by specifying the pitch like this: +To make sure your samples are in tune when playing them with `note`, you can specify a base pitch like this: @2").s("gtr,moog").clip(1) .gain(.5)`} /> -If a sample has no pitch set, `c3` is the default. - We can also declare different samples for different regions of the keyboard: !2, g4 f4]>") The sampler will always pick the closest matching sample for the current note! +Note that this notation for pitched sounds also works inside a `strudel.json` file. + ## Shabda If you don't want to select samples by hand, there is also the wonderful tool called [shabda](https://shabda.ndre.gr/).