Skip to content

Commit 58164ca

Browse files
authored
Merge pull request #3235 from CUBICinfinity/dev
Updates to tutorial and documentation for play_pattern and play_pattern_timed
2 parents e5a3fff + 898aa63 commit 58164ca

File tree

2 files changed

+55
-32
lines changed

2 files changed

+55
-32
lines changed

app/server/ruby/lib/sonicpi/lang/sound.rb

Lines changed: 36 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1261,11 +1261,12 @@ def play_pattern(notes, *args)
12611261
accepts_block: false,
12621262
examples: ["
12631263
play_pattern [40, 41, 42] # Same as:
1264-
# play 40
1264+
# play 40, sustain: 1
12651265
# sleep 1
1266-
# play 41
1266+
# play 41, sustain: 1
1267+
# sleep 1
1268+
# play 42, sustain: 1
12671269
# sleep 1
1268-
# play 42
12691270
",
12701271
"play_pattern [:d3, :c1, :Eb5] # You can use keyword notes",
12711272

@@ -1291,62 +1292,75 @@ def play_pattern_timed(notes, times, *args)
12911292
doc name: :play_pattern_timed,
12921293
introduced: Version.new(2,0,0),
12931294
summary: "Play pattern of notes with specific times",
1294-
doc: "Play each note in a list of notes one after another with specified times between them. The notes should be a list of MIDI numbers, symbols such as :E4 or chords such as chord(:A3, :major) - identical to the first parameter of the play function. The times should be a list of times between the notes in beats.
1295+
doc: "Play each note in a list of notes one after another with specified durations. The notes should be a list of MIDI numbers, symbols such as :E4 or chords such as chord(:A3, :major) - identical to the first parameter of the play function. The times should be a list of durations for each note in beats.
12951296
1296-
If the list of times is smaller than the number of gaps between notes, the list is repeated again. If the list of times is longer than the number of gaps between notes, then some of the times are ignored. See examples for more detail.
1297+
If the list of times is smaller than the number of notes, the list is repeated again. If the list of times is longer than the number of notes, then some of the times are ignored. See examples for more detail.
12971298
12981299
Accepts optional args for modification of the synth being played. See each synth's documentation for synth-specific opts. See `use_synth` and `with_synth` for changing the current synth.",
12991300
args: [[:notes, :list], [:times, :list_or_number]],
13001301
opts: DEFAULT_PLAY_OPTS,
13011302
accepts_block: false,
13021303
examples: ["
1303-
play_pattern_timed [40, 42, 44, 46], [1, 2, 3]
1304+
play_pattern_timed [40, 42, 44], [1, 2, 3]
13041305
13051306
# same as:
13061307
1307-
play 40
1308+
play 40, sustain: 1
13081309
sleep 1
1309-
play 42
1310+
play 42, sustain: 2
13101311
sleep 2
1311-
play 44
1312-
sleep 3
1313-
play 46",
1312+
play 44, sustain: 3
1313+
sleep 3",
13141314

13151315
"play_pattern_timed [40, 42, 44, 46, 49], [1, 0.5]
13161316
13171317
# same as:
13181318
1319-
play 40
1319+
play 40, sustain: 1
13201320
sleep 1
1321-
play 42
1321+
play 42, sustain: 0.5
13221322
sleep 0.5
1323-
play 44
1323+
play 44, sustain: 1
13241324
sleep 1
1325-
play 46
1325+
play 46, sustain: 0.5
13261326
sleep 0.5
1327-
play 49",
1327+
play 49, sustain: 1
1328+
sleep 1",
13281329

13291330
"play_pattern_timed [40, 42, 44, 46], [0.5]
13301331
13311332
# same as:
13321333
1333-
play 40
1334+
play 40, sustain: 0.5
13341335
sleep 0.5
1335-
play 42
1336+
play 42, sustain: 0.5
13361337
sleep 0.5
1337-
play 44
1338+
play 44, sustain: 0.5
13381339
sleep 0.5
1339-
play 46",
1340+
play 46, sustain: 0.5
1341+
sleep 0.5",
13401342

13411343
"play_pattern_timed [40, 42, 44], [1, 2, 3, 4, 5]
13421344
1343-
#same as:
1345+
# same as:
1346+
1347+
play 40, sustain: 1
1348+
sleep 1
1349+
play 42, sustain: 2
1350+
sleep 2
1351+
play 44, sustain: 3
1352+
sleep 3",
1353+
1354+
"play_pattern_timed [40, 42, 44], [1, 2, 3], sustain: 0
1355+
1356+
# effectively same as:
13441357
13451358
play 40
13461359
sleep 1
13471360
play 42
13481361
sleep 2
1349-
play 44"]
1362+
play 44
1363+
sleep 3"]
13501364

13511365

13521366

etc/doc/tutorial/08.2-Chords.md

Lines changed: 19 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,9 @@ play_pattern chord(:E3, :m7)
2828
```
2929

3030
Ok, that's not so fun - it played it really slowly. `play_pattern` will
31-
play each note in the list separated with a call to `sleep 1` between
32-
each call to `play`. We can use another function `play_pattern_timed` to
33-
specify our own timings and speed things up:
31+
play each note in the list with a call to `sleep 1` after each call to
32+
`play`. We can use another function `play_pattern_timed` to specify our
33+
own timings and speed things up:
3434

3535
```
3636
play_pattern_timed chord(:E3, :m7), 0.25
@@ -46,19 +46,28 @@ play_pattern_timed chord(:E3, :m13), [0.25, 0.5]
4646
This is the equivalent to:
4747

4848
```
49-
play 52
49+
play 52, sustain: 0.25
5050
sleep 0.25
51-
play 55
51+
play 55, sustain: 0.5
5252
sleep 0.5
53-
play 59
53+
play 59, sustain: 0.25
5454
sleep 0.25
55-
play 62
55+
play 62, sustain: 0.5
5656
sleep 0.5
57-
play 66
57+
play 66, sustain: 0.25
5858
sleep 0.25
59-
play 69
59+
play 69, sustain: 0.5
6060
sleep 0.5
61-
play 73
61+
play 73, sustain: 0.25
62+
sleep 0.25
6263
```
6364

6465
Which would you prefer to write?
66+
67+
Note that `play_pattern` and `play_pattern_timed` alter the sustain of
68+
the notes to fill the times. You can remove this behavior by setting the
69+
`sustain:` opt to `0`:
70+
71+
```
72+
play_pattern_timed chord(:E3, :m13), [0.25, 0.5], sustain: 0
73+
```

0 commit comments

Comments
 (0)