Link search Menu Expand Document

params

functions

Syntax Description
params.new(id,name) Create a parameter from scratch (not typical, but useful to have)
params:add_separator(name) Create a horizontal line with a title in the parameters menu to demarcate a section of controls (users can press K3 if selected to jump through separators)
params:add_group(name,n) Group n controls under name, to help collapse parameter menu navigation. Note that groups cannot be made within groups (no nesting).
params:add(args) Create a parameter by passing an argument table
params:add_number(id, name, min, max, default, formatter, wrap) Create a parameter set for numbers
params:add_option(id, name, options, default) Create a parameter set for option selection (options must be passed as a table)
params:add_control(id, name, controlspec, formatter) Create a parameter set for controlspec formatting (see controlspec for more details)
params:add_file(id, name, path) Create a parameter set for file selection
params:add_text(id, name, text) Create a parameter set for text entry
params:add_taper(id, name, min, max, default, k, units) Create a parameter set for non-linear movement
params:add_trigger(id, name) Create a parameter set for an “on/off” action trigger
params:add_binary(id, name, behavior, default) Create a parameter set for either momentary, toggle, or trigger behavior with a default state
params:print() Print the index, name, and value for each parameter to the REPL
params:list() Print the names of each parameter to the REPL
params:get_id(index) Returns the string id of a given parameter’s index
params:string(id) Returns the string associated with the current value for a given parameter’s id
params:set(id,val,silent) Set a parameter’s value, with optional action execution
params:set_raw (index, v, silent) Set a parameter’s controlspec raw value, with optional action execution
params:get(id) Returns a parameter’s current number value
params:get_raw(id) Returns a parameter’s controlspec raw value
params:set_action(id, function) Assign an action to a parameter’s changes
params:t(index) Returns a given parameter’s type
params:get_range(index) Returns the min/max range of a parameter
params:get_allow_pmap(index) Returns whether a parameter is able to be MIDI-mapped (boolean)
params:hide(id) Hides the specified parameter in the UI menu, but parameter index and data is still retained. Use _menu.rebuild_params() after hiding to dynamically rebuild the menu UI.
params:show(id) Shows the specified parameter in the UI menu, after it is hidden (not required for default parameter building). Use _menu.rebuild_params() after hiding to dynamically rebuild the menu UI.
params:visible(id) Returns whether a parameter is visible in the UI menu (boolean)
params:write(filename,name) Save a .pset file of all parameters’ current states to disk
params:read(filename, silent) Read a .pset file from disk, restoring saved parameter states, with an option to avoid triggering parameters’ associated actions
params:default() Read the default .pset file from disk, if available
params:bang() Trigger all parameters’ associated actions
params:clear() Clear all parameters (system toolkit, not for script usage)

additional tools

The function calls listed above are supplemented by additional helpers + extensions, which are formatted differently.

Syntax Description
params.lookup[id] A table call (note the square brackets) which returns the index of a given parameter’s string id
params.action_write = function(filename) User script callback whenever a parameter write occurs, which passes the .pset’s filename
params.action_read = function(filename, name) User script callback whenever a parameter read occurs, which passes the .pset’s filename and name

example

MusicUtil = require "musicutil"
math.randomseed(os.time())

function init()
  params:add_separator("test script")
  params:add_group("example group",3)
  for i = 1,3 do
    params:add{
      type = "option",
      id = "example "..i,
      name = "parameter "..i,
      options = {"hi","hello","bye"},
      default = i
    }
  end
  params:add_number(
    "note_number", -- id
    "notes with wrap", -- name
    0, -- min
    127, -- max
    60, -- default
    function(param) return MusicUtil.note_num_to_name(param:get(), true) end, -- formatter
    true -- wrap
    )
  local groceries = {"green onions","shitake","brown rice","pop tarts","chicken thighs","apples"}
  params:add_option("grocery list","grocery list",groceries,1)
  params:add_control("frequency","frequency",controlspec.FREQ)
  params:add_file("clip sample", "clip sample")
  params:set_action("clip sample", function(file) load_sample(file) end)
  params:add_text("named thing", "my name is:", "")
  params:add_taper("taper_example", "taper", 0.5, 6.2, 3.3, 0, "%")
  params:add_separator()
  params:add_trigger("trig", "press K3 here")
  params:set_action("trig",function() print("boop!") end)
  params:add_binary("momentary", "press K3 here", "momentary")
  params:set_action("momentary",function(x) print(x) end)
  params:add_binary("toggle", "press K3 here", "toggle",1)
  params:set_action("toggle",function(x)
    if x == 0 then
      params:show("secrets")
    elseif x == 1 then
      params:hide("secrets")
    end
    _menu.rebuild_params()
  end)
  params:add_text("secrets","secret!!")
  params:hide("secrets")
  params:print()
  random_grocery()
end

function load_sample(file)
  print(file)  
end

function random_grocery()
  params:set("grocery list",math.random(params:get_range("grocery list")[1],params:get_range("grocery list")[2]))  
end

parameter types

norns can support many types of parameter declarations, to facilitate the ‘right’ type of control for the musical task at hand.

The types, with linked examples, are:

PSET save/load callback

Parameters are designed to make MIDI mapping and saving control values for a script very straightforward, using the PMAP and PSET functionality. However, you may find that you need to generate and save data which doesn’t fit the parameters model, like tables of sequencer steps (though awake does show how to efficiently work with patterns as parameters).

If you wish to perform additional actions when a PSET is saved or loaded, such as saving or loading non-params data into your script, params.action_write and params.action_read are two script-definable callback functions which are triggered whenever a PSET is saved or loaded. Here’s a quick overview of their use:

function init()
  params.action_write = function(filename,name)
    print("finished writing '"..filename.."' as '"..name.."'")
  end
  params.action_read = function(filename)
    print("finished reading '"..filename.."'")
  end
end

Run the above and save a few PSETs in the PARAMETERS > PSET menu. You’ll see the action_write callback print after each is saved. Try loading them back and you’ll see the action_read callback print after each is read.

When paired with other norns utilities, like tab.save and tab.load, the params.action_write / params.action_read combination can help you save/restore script-generated tables while keeping the parameters UI clear, eg:

MusicUtil = require 'musicutil' -- see https://monome.org/docs/norns/reference/lib/musicutil
engine.name = 'PolyPerc' -- an included norns engine
s = require 'sequins' -- see https://monome.org/docs/norns/reference/lib/sequins

function init()
  base_note = math.random(30,50)
  my_seq = s{}
  notes_array = MusicUtil.generate_scale_of_length(base_note, "dorian", 16)
  generate_random_notes()
  play = false

  -- here, we set our PSET callbacks:
  params.action_write = function(filename,name)
    print("finished writing '"..filename.."' as '"..name.."'")
    os.execute("mkdir -p ".._path.data..'/params-example/'..name..'/')
    -- save to 'data/params-example/[the PSET's name]/notes.data':
    tab.save(note_data,_path.data..'/params-example/'..name..'/notes.data')
  end
  params.action_read = function(filename)
    print("finished reading '"..filename.."'")
    local loaded_file = io.open(filename, "r")
    if loaded_file then
      io.input(loaded_file)
      local pset_name = string.sub(io.read(), 4, -1) -- grab the PSET name from the top of the PSET file
      io.close(loaded_file)
      -- load saved PSET note data into our note_data table:
      note_data = tab.load(_path.data..'/params-example/'..pset_name..'/notes.data')
      my_seq:settable(note_data) -- send this restored table to the sequins
    end
  end

end

function generate_random_notes()
  note_data = {}
  for j = 1,64 do
    -- auto-generate 64 steps of notes:
    note_data[j] = MusicUtil.snap_note_to_array(math.random(base_note, base_note+28),notes_array)
  end
  my_seq:settable(note_data) -- send this table of notes to the sequins
end

function play_notes()
  while true do
    clock.sync(1/3)
    engine.hz(MusicUtil.note_num_to_freq(my_seq())) -- PolyPerc accepts 'hz' arguments
    redraw()
  end
end

function key(n,z)
  if n == 3 and z == 1 then
    -- a simple start/stop mechanism
    -- can also be set to MIDI/Link transport: https://monome.org/docs/norns/clocks/#transport-callbacks
    play = not play
    if play then
      sequencer = clock.run(play_notes)
    else
      clock.cancel(sequencer)
      my_seq:reset()
    end
    redraw()
  end
end

function redraw()
  screen.clear()
  screen.move(120,55)
  screen.text_right(play and "K3: stop" or "K3: play")
  screen.move(30,30)
  screen.text(my_seq.ix..": "..note_data[my_seq.ix])
  screen.update()
end

bundling PSETs with a script

When sharing a script with others, it may be desirable to bundle it with pre-made PSETs to give artists a collection of known starting points.

As you ready your script for sharing, you can use the standard PSET save UI in norns to build and name PSETs – they will be saved under your device’s dust/data/(script) folder. Then, create a dust/code/(script)/data folder and copy the generated PSET files from dust/data/(script) into it.

Behind the scenes, norns checks if a dust/data/(script) folder already exists on a script’s first run – if it doesn’t, norns then checks if a dust/code/(script)/data folder exists. If it does and the folder has any .pset files in it, norns copies them from code/(script)/data to dust/data/(script), which surfaces the PSETs in the on-screen UI menu.

As the PSET-bundled script is first loaded onto a norns which doesn’t already have a corresponding dust/data/(script) folder, you will see the following print to matron:

# script clear
# script load: /home/we/dust/code/(script)/(script).lua
### initializing data folder
### copied default psets
# script run

To test, you can simply delete your dust/data/(script) folder after copying the .pset files to dust/code/(script)/data, and a fresh boot of the script will copy all the bundled PSETs into dust/data/(script).

description

Parameters are a fundamental component of the norns toolkit. They allow you to associate controls and data to variables and functions within your scripts. They offer MIDI mapping and OSC addresses, as well as state save and restore.

For more information about UI interactions with params, see the play docs.

For more information about scripting with params, see study 3: spacetime.