Script the tools

PresTools adds four functions to ReaScript, so a script can run the tools on items it picks, with or without the panel open. Their reference is in REAPER under Help → ReaScript documentation: search for PresTools.

Functions

Function	Does
`id = reaper.PresTools_Run(op, item, settingsJson)`	Runs one tool on an item and returns a task id. `settingsJson` is optional.
`id = reaper.PresTools_RunWorkflow(workflow, item, overwrite)`	Runs a saved workflow on an item and returns a task id. Stems go on new tracks under the item. `overwrite` is optional.
`status, progress, message, result = reaper.PresTools_Task(id)`	Reports a task. See Follow a task.
`ok = reaper.PresTools_Cancel(id)`	Cancels a task. Returns `false` if it has finished or there is no such task.

The tool needs its component, as in the panel: see Add the tools you need.

Tools and their settings

op is one of these tools. Settings are JSON, such as '{"snap": true}', the same as the workflow editor’s; any you leave out keep their defaults. A setting the tool doesn’t have fails the task, and its message lists the ones it has.

`op`	Tool	Settings, with their defaults
`pt_tempo_map`	Tempo map	`minBpm` 55, `maxBpm` 215, `transitionLambda` (Tempo stability) 250, `sharpness` (Beat sharpness) 24, `meters` (Time signatures) `"4"`, `countInAtStart` (Count-in in bar 1) `false`
`pt_detect_chords`	Detect chords	`snap` (Snap to the grid) `false`
`pt_recognize_lyrics`	Recognize lyrics	`to` `"%filename%.txt"`, `model` (the Whisper model chosen on the Lyrics page, `large-v3` unless you changed it), `language` `""` (detect)
`pt_align_lyrics`	Align lyrics	`words` `"%filename%.txt"`, `language` `""` (read from the words)

pt_tempo_map always builds the tempo map; it doesn’t stop at beat markers.

Recognition writes the words to a text file and does not change the project. Alignment reads its words from a file, so the two run one after the other. In to and words, %filename% is the song’s file name and %songdir% its folder; a name without a folder is beside the song, and a name without an extension gets .txt. Correct the file between the two steps if you like.

A tool writes into the item’s own project, whichever tab is in front. An item that is trimmed, stretched, or has take FX must be in the project in front, or the task fails with bring the item’s project to the front.

Run a workflow

workflow is the workflow’s file name without .yaml: the name you gave it, with spaces as underscores. A workflow named “Bassless BGV” runs as "Bassless_BGV". Its stems go on new tracks under the item, and its tempo, chord, and lyrics steps write into the item’s project.

A workflow fails rather than write over existing files, unless overwrite is true. Models it needs download first; meanwhile the message says Downloading and the model’s name.

Follow a task

Nothing waits while a task runs, so a script checks on it with reaper.defer. PresTools_Task returns:

status: starting, queued, running, done, failed, or canceled. For an id it doesn’t know, unknown.
progress: from 0 to 1.
message: what the task is doing, or why it failed or stopped.
result: JSON with what the tool found (result) and the files it wrote (outputs), for example the number of chords and the song’s key.

Tasks run one at a time, the panel’s included: a task waiting its turn is queued. Every mistake is a failed task with the reason as its message.

local item = reaper.GetSelectedMediaItem(0, 0)
if not item then return end
local id = reaper.PresTools_Run("pt_detect_chords", item, '{"snap": false}')

local function wait()
  local status, progress, message = reaper.PresTools_Task(id)
  if status == "done" then
    reaper.ShowConsoleMsg("Chords written\n")
  elseif status == "failed" or status == "canceled" then
    reaper.ShowConsoleMsg("Stopped: " .. message .. "\n")
  else
    reaper.defer(wait)
  end
end
wait()

Expected result: the chords appear on the Chordtrack, and REAPER’s console says Chords written.

Messages a script may get

Message	Means
that is not an audio item in an open project	The item is gone, is MIDI, or its project was closed.
the settings are not JSON	`settingsJson` doesn’t parse. Check its quotes.
there is no tool …; the tools are …	`op` is misspelled.
… is not installed yet. Install it in Settings, under Components.	Add the tool’s component in the panel.
it would overwrite …; run it with overwrite to go ahead	A workflow’s files exist. Pass `true` as `overwrite` to replace them.
there are no lyrics to align: … is not there	`pt_align_lyrics` found no words file. Run `pt_recognize_lyrics` first, or name the file in `words`.
no beats were found in this audio	The item has no beat to follow.
the PresTools core stopped unexpectedly	See Troubleshoot.

Example script

The installer copies a complete script to adapt into REAPER’s Scripts/PresTools/Scripts/examples folder: PresTools - Detect chords in a folder of projects. Pick any project in a folder, and it opens each project there in a tab, detects chords for the project’s only audio item, saves it, and closes it. REAPER’s console lists each project with the number of chords it found, or why it skipped it.

Load it with Actions → Show action list → New action → Load ReaScript.

Next: Troubleshoot, or Use Prest Server with REAPER.