study 07 of 10

Asking the player

A script runs on a machine you play. This study is about the moment between choosing a function and running it: the settings the player edits, the question asked before a change, and the message shown at the end. You build a hat generator with three settings.

Where the function appears: menu

menu "CATEGORY" >> "NAME" places the function in the script menu. A function may have several menu lines to appear in several places. The names are short, as on the Octatrack's screen: the checker refuses those that would not fit.

Settings: param

Each param is a setting shown before the run, read in the script like a number that cannot be changed. A function has up to eight. Four kinds exist:

def hat_maker
  menu "LEARN" >> "HATS"
  param hits 7 1 16
  param accent bool 1
  param curve option 1 "FLAT" "BEATS" "OFFBEATS"
  confirm "REPLACE THE HATS?"
  tr.clr
  l 1 16: if er hits 16 i: tr.add i
  if accent:
    steps has.trig:
      each: pl.set i amp.vol dr.v curve i
  msg hits "HITS"

hat_maker  seed 1 (--seed)  pattern A01 len 16 (default)  track 1
T1  1   5   9   13
    X..X.X.X..X.X.X.
    step 1: amp.vol 127   step 4: amp.vol 80   step 6: amp.vol 80   step 8: amp.vol 80
    step 11: amp.vol 80   step 13: amp.vol 127   step 15: amp.vol 80
      X trig  ! one-shot  o trigless trig  - trigless lock  l locks only  . none
part:  tempo 120
msg:   "7 HITS"
end box: "7 HITS" (the last msg, instead of DONE)
cost: 242/677   random draws: rand 0  toss 0  prob 0  drunk 0  file 0

The positions of the option labels, 0, 1 and 2, are also the numbers of the dr.v curves flat, accents on the beats and accents off the beats: the setting goes straight into the curve. On the computer, run … --param hits=11 tries another value.

A folder setting is not a number: only dir reads it, to list the files of the folder the player picked. The audio recipes of the cookbook use it to fill sample slots or build chains.

Asking first: confirm

Some operations change the project in a way you might regret: tr.clr, saving a file, copying a pattern. The command reference marks them destructive. A function that uses one, directly or through a brick, always asks YES or NO before it runs. confirm asks even when nothing is destructive, and confirm "TEXT" chooses the question.

The last word: msg

At the end of a run, a box shows DONE. msg replaces that text: up to eight items, texts and numbers, joined by spaces. Each msg replaces the previous one, so the last one wins. The box is small: the checker counts the longest text a msg could make (a number counts six characters) and refuses more than 29.

Two more declarations

• page "LABEL" lists the function on a page of encoders, when your firmware has one: its first six params are then on the encoders A to F.
• input sample says that the function works on a recorded take, and makes it appear where a take is available.

Like param and var, these declarations go at the top of the function, before the first statement.