Reorder sampling docs

docs/reference/Oscillators.md

@@ -141,3 +141,34 @@ d1 $ s "bass:5*8" # lpf (slow 4 $ range 200 5000 $ sine)
 :::tip
 Notice that most of the time, the speed up/down will be in sync with your pattern. How convenient!
 :::
+
+## Sampling oscillators and signals
+
+### segment
+
+```haskell
+Type: segment :: Pattern Time -> Pattern a -> Pattern a
+```
+
+`segment` 'samples' the pattern at a rate of `n` events per cycle. Useful for turning a continuous pattern into a discrete one. In this example, the pattern originates from the shape of a sine wave, a continuous pattern. Without segment the samples will get triggered at an undefined frequency which may be very high.
+
+```haskell
+d1 $ n (slow 2 $ segment 16 $ range 0 32 $ sine) # sound "amencutup"
+```
+
+### discretise
+
+`segment` used to be known as `discretise`. The old name remains as an alias and will still work, but may be removed or repurposed in a future version of **Tidal**. 
+
+## Creating oscillators
+
+### sig
+
+```haskell
+Type: sig :: (Time -> a) -> Pattern a
+```
+`sig` takes a function of time and turns it into a pattern. It's very useful for creating continuous patterns such as `sine` or `perlin`. For example, `saw` is defined as
+
+```haskell
+saw = sig $ \t -> mod' (fromRational t) 1
+```

docs/reference/effects.md

@@ -5,6 +5,52 @@ id: audio_effects
 
 ## Basic effects
 
+### Amplitude manipulation
+
+These functions are used to control the amplitude (volume) of the sounds.
+
+#### amp
+
+```haskell
+Type: amp :: Pattern Double -> ControlPattern
+```
+
+`amp` controls the amplitude of the sound using a linear function. Its default value is `0.4`. For the power function equivalent, see `gain`.
+
+```haskell
+d1 $ s "arpy" # amp 0.6
+```
+
+This will play the first `arpy` sample at a volume slightly louder than the default.
+
+```haskell
+d1 $ s "arpy" # amp "<0.4 0.8 0.2>"
+```
+
+In the above example, the volume changes at each cycle.
+
+#### gain
+
+```haskell
+Type: gain :: Pattern Double -> ControlPattern
+```
+
+`gain` controls the amplitude of the sound using a power function. Its default value is `1`. Smaller values make the sound quieter, and greater values make the sound louder.
+
+As `gain` uses a power function, the volume change around `1` is subtle, but it gets more noticable as it increases or decreases. Typical values for `gain` are between `0` and `1.5`. For the linear equivalent, see `amp`.
+
+```haskell
+d1 $ s "arpy" # gain 0.8
+```
+
+This plays the first `arpy` sample at a quieter level than the default.
+
+```haskell
+d1 $ s "ab*16" # gain (range 0.8 1.3 $ sine)
+```
+
+This plays a hihat sound, `16` times per cycle, with a `gain` moving from `0.8` to `1.3` following a sine wave.
+
 ### Pitch
 
 #### Octer

docs/reference/sampling.md → docs/reference/sample_slicing.md

@@ -1,16 +1,15 @@
 ---
-title: Sampling
-id: sampling
+title: Sample slicing
+id: sample_slicing
 ---
 
 
-This page will present you all the functions that can be used to slice, cut, reverse or explode your audio samples, incoming signals or oscillators. Each function will be presented following the same model:
+This page will present you all the functions that can be used to slice, cut, reverse or explode your samples. Each function will be presented following the same model:
 * **Type signature**: how the function is declared on the **Haskell** side.
 * **Description**: verbal description of the function.
 * **Examples**: a small list of examples that you can copy/paste in your editor.
 
 
-## Audio sampling
 ### chop
 
 ```haskell
@@ -161,29 +160,6 @@ d1 $ bite 4 "0 1*2 2*2 [~ 3]" $ n "0 .. 7" # sound "drum"
 d1 $ chew 4 "0 1*2 2*2 [~ 3]" $ n "0 .. 7" # sound "drum"
 ```
 
-### loopAt
-
-```haskell
-Type: loopAt :: Pattern Time -> ControlPattern -> ControlPattern
-```
-
-`loopAt` makes sample fit the given number of cycles. Internally, it works by setting the unit control to "c", changing the playback speed of the sample with the speed parameter, and setting the density of the pattern to match.
-
-```haskell
-d1 $ loopAt 4 $ sound "breaks125"
-```
-
-It’s a good idea to use this in conjuction with `chop`, so the break is chopped into pieces and you don’t have to wait for the whole sample to start/stop.
-
-```haskell
-d1 $ loopAt 4 $ chop 32 $ sound "breaks125"
-```
-
-Like all **Tidal** functions, you can mess about with this considerably. The below example shows how you can supply a pattern of cycle counts to `loopAt`:
-```haskell
-d1 $ juxBy 0.6 (|* speed "2") $ loopAt "<4 6 2 3>" $ chop 12 $ sound "fm:14"
-```
-
 ### smash
 
 ```haskell
@@ -226,32 +202,4 @@ vs
 ```haskell
 d1 $ smash' 12 [2,3,4] $ s "bev*4"
 ```
-for a dramatic difference.
-
-## Signal sampling 
-### segment
-
-```haskell
-Type: segment :: Pattern Time -> Pattern a -> Pattern a
-```
-
-`segment` 'samples' the pattern at a rate of `n` events per cycle. Useful for turning a continuous pattern into a discrete one. In this example, the pattern originates from the shape of a sine wave, a continuous pattern. Without segment the samples will get triggered at an undefined frequency which may be very high.
-
-```haskell
-d1 $ n (slow 2 $ segment 16 $ range 0 32 $ sine) # sound "amencutup"
-```
-
-### discretise
-
-`segment` used to be known as `discretise`. The old name remains as an alias and will still work, but may be removed or repurposed in a future version of **Tidal**. 
-
-### sig
-
-```haskell
-Type: sig :: (Time -> a) -> Pattern a
-```
-`sig` takes a function of time and turns it into a pattern. It's very useful for creating continuous patterns such as `sine` or `perlin`. For example, `saw` is defined as
-
-```haskell
-saw = sig $ \t -> mod' (fromRational t) 1
-```
+for a dramatic difference.

docs/reference/samplers.md → docs/reference/sample_speed.md

@@ -1,162 +1,62 @@
 ---
-title: Samplers
-id: samplers
+title: Sample speed
+id: sample_speed
 ---
 
-This page presents many functions related to the use of samples inside TidalCycles.
-
-For specific information about functions used to slice and loop samples see [Sampling](https://tidalcycles.org/docs/reference/sampling).
+This page presents many functions that allow to change the speed at which samples play.
 
 Each function will be presented following the same model:
 * **Type signature**: how the function is declared on the **Haskell** side.
 * **Description**: verbal description of the function.
 * **Examples**: a small list of examples that you can copy/paste in your editor.
 
-## Basic sample manipulation
-
-### amp
-
-```haskell
-Type: amp :: Pattern Double -> ControlPattern
-```
-
-`amp` is used to control the amplitude (volume) of the sound. It's very similar
-to `gain`, but it uses a linear function. Its default value is `0.4`.
-
-```haskell
-d1 $ s "arpy" # amp 0.6
-```
-
-This will play the first `arpy` sample at a volume slightly louder than the default.
-
-```haskell
-d1 $ s "arpy" # amp "<0.4 0.8 0.2>"
-```
-
-In the above example, the volume changes at each cycle.
-
-### begin
-
-```haskell
-Type: begin :: Pattern Double -> ControlPattern
-```
-
-`begin` receives a pattern of numbers from 0 to 1. It skips the beginning of each sample. The numbers indicate the proportion of the samples that needs to be skipped (`0` would play the sample from the start, `1` would skip the whole sample, `0.25` would cut off the first quarter from each sample). For example:
-
-```haskell
-d1 $ s "bev" # begin 0.5 # legato 1
-```
-
-In the above example, the sample is started from the half of its total length.
+## Playback-rate effects
 
-```haskell
-d1 $ n "0 1 2" # s "ade" # begin "<0 0.25 0.5 0.75>" # legato 1
-```
-
-In this other example, the first `3` `ade` samples are playied on every cycle, but the start point from which they are playied changes on each cycle.
-
-### end
-
-```haskell
-Type: end :: Pattern Double -> ControlPattern
-```
-
-The same as `begin`, but cuts off the end of samples, shortening them. For example, `0.75` will cut off the last quarter of each sample.
-
-```haskell
-d1 $ s "bev" # begin 0.5 # end 0.65
-```
-
-This will play only a small part of the sample: from `50%` its length to `65%` its length.
+This section presents effects that change both the speed and the pitch of the samples. As frequencies are scaled at the same ratio of the speed, a 2x playback rate will correspond to half the duration and the pitch sounding an octave higher, and a 0.5x playback rate will correspond to double the duration and the pitch sounding an octave lower.
 
-```haskell
-d1 $ s "bev" >| begin 0.5 >| end "[0.65 0.55]"
-```
-
-The example above will play the sample two times for cycle, but the second time will play a shorter segment than the first time, creating some kind of canon effect.
-
-### gain
-
-```haskell
-Type: gain :: Pattern Double -> ControlPattern
-```
-
-`gain` is used to control the amplitude (volume) of the sound. Values less than `1` make the sound quieter. Values greater than `1` make the sound louder.
-
-`gain` uses a power function, so the volume change around `1` is subtle, but it gets more noticable as it increases or decreases. Typical values for `gain` are between `0` and `1.5`. For the linear equivalent, see `amp`.
-
-```haskell
-d1 $ s "arpy" # gain 0.8
-```
-
-This plays the first `arpy` sample at a quieter level than the default.
+### accelerate
 
 ```haskell
-d1 $ s "ab*16" # gain (range 0.8 1.3 $ sine)
+Type: accelerate :: Pattern Double -> ControlPattern
 ```
 
-This plays a hihat sound, `16` times per cycle, with a `gain` moving from `0.8` to `1.3` following a sine wave.
-
-### grain
+A pattern of numbers that speed up (or slow down) samples while they play.
 
 ```haskell
-Type: grain :: Pattern Double -> Pattern Double -> ControlPattern
+d1 $ s "arpy" # accelerate 2
 ```
 
-`grain` is another way to specify what part of samples we want to play. Instead of specifying the `begin` and `end`, here we write the `begin` and the `length`.
-
-For example:
+In this example, the sound starts at the original pitch, and gets higher as it plays. You can use a negative number to make the sound get lower.
 
 ```haskell
-d1 $ slow 2 $ s "bev" # grain 0.2 0.1 # legato 1
+d1 $ arp "up" $ note "c'maj'4" # s "arpy" # accelerateTake "susan" [0.2,1,-1]
 ```
 
-is equivalent to:
+Using [state values](https://tidalcycles.org/docs/reference/state_values/#introduction-to-state-values), in this example we apply a different acceleration to each played note.
 
+### loopAt
+
 ```haskell
-d1 $ slow 2 $ s "bev" # begin 0.2 # end 0.3 # legato 1
+Type: loopAt :: Pattern Time -> ControlPattern -> ControlPattern
 ```
 
-### grain'
+`loopAt` makes sample fit the given number of cycles. Internally, it works by setting the unit control to "c", changing the playback speed of the sample with the speed parameter, and setting the density of the pattern to match.
 
 ```haskell
-Type: grain' :: Pattern String -> ControlPattern
+d1 $ loopAt 4 $ sound "breaks125"
 ```
 
-`grain'` is simply a fast shortcut to join a `begin` and an `end`.
+It’s a good idea to use this in conjuction with `chop`, so the break is chopped into pieces and you don’t have to wait for the whole sample to start/stop.
 
 ```haskell
-d1 $ slow 2 $ s "bev" # grain' "0.2:0.3" # legato 1
+d1 $ loopAt 4 $ chop 32 $ sound "breaks125"
 ```
 
-This example is equivalent to:
-
+Like all **Tidal** functions, you can mess about with this considerably. The below example shows how you can supply a pattern of cycle counts to `loopAt`:
 ```haskell
-d1 $ slow 2 $ s "bev" # begin 0.2 # end 0.3 # legato 1
- ```
-
-## Sample effects
-
-### accelerate
-
-```haskell
-Type: accelerate :: Pattern Double -> ControlPattern
+d1 $ juxBy 0.6 (|* speed "2") $ loopAt "<4 6 2 3>" $ chop 12 $ sound "fm:14"
 ```
 
-A pattern of numbers that speed up (or slow down) samples while they play.
-
-```haskell
-d1 $ s "arpy" # accelerate 2
-```
-
-In this example, the sound starts at the original pitch, and gets higher as it plays. You can use a negative number to make the sound get lower.
-
-```haskell
-d1 $ arp "up" $ note "c'maj'4" # s "arpy" # accelerateTake "susan" [0.2,1,-1]
-```
-
-Using [state values](https://tidalcycles.org/docs/reference/state_values/#introduction-to-state-values), in this example we apply a different acceleration to each played note.
-
 ### speed
 
 ```haskell
@@ -177,29 +77,6 @@ d1 $ fast 2 $ s "breaks125:1" # cps (125/60/4) # speed (-2)
 
 In the above example, the break (which lasts for exactly one bar at 125 BPM), will be played backwards, and at double speed (so, we use `fast 2` to fill the whole cycle).
 
-### sustain
-
-```haskell
-Type: sustain :: Pattern Double -> ControlPattern
-```
-
-A pattern of numbers that indicates the total duration of sample playback in seconds.
-
-:::caution
-This `sustain` refers to the whole playback duration, and is not to be confused with the sustain level of a typical ADSR envelope.
-:::
-
-```haskell
-d1 $ fast 2 $ s "breaks125:1" # cps (120/60/4) # sustain 1
-```
-
-At 120 BPM, a cycle lasts for two seconds. In the above example, we cut the sample so it plays just for one second, and repeat this part two times, so we fill the whole cycle. Note that sample pitch isn't modified.
-
-```haskell
-d1 $ s "breaks125:2!3" # cps (120/60/4) # sustain "0.4 0.2 0.4" # begin "0 0 0.4"
-```
-
-Here, we take advantage that `sustain` receives a pattern to build a different break from the original sample.
 
 ### unit