Welcome

... to the Renoise Lua Scripting Guide! This book is intended for developers who want to write their own scripts & tools for Renoise.

If you are only interested in downloading tools for Renoise and not in developing your own tools, please have a look at the Renoise Tools Page.

If you want to develop your own tools for Renoise, just keep reading.

Possibilities

Before you delve into writing your own scripts and tools, it worth considering what is even possible to do with them. In general, you can automate and manage different aspects Renoise, add or modify song data using algorithms or create interfaces to connect with other software or hardware. You can see some examples below about what you can access inside Renoise, for a complete reference, check out the API Definitions.

Process song data

• Generate, modify or filter notes, patterns or phrases
• Access volume, delays and panning values
• Write effect commands and automation
• Rearrange the pattern matrix and more

Manage tracks and instruments

• Create and modify instruments or tracks
• Add built-in DSP devices to tracks or FX chains and set their parameters
• Generate modulation chains on instruments
• Load samples and configure them
• Manage slices and keyzones

Sample generation and mangling

• Generate new samples and change existing ones
• Chop samples and create slices and intruments based on custom rules
• Implement offline audio effects

Custom graphical interfaces

• Use built-in sliders, buttons, switches and more to compose a GUI
• Listen to keyboard and mouse events to define custom behaviour
• Use bitmaps to create unique buttons
• Hook up the interface to the rest of your tool

Controller support

• Write logic for bidirectional communication between Renoise and MIDI controllers
• Implement custom functionality for MIDI control surfaces
• Control Renoise via customized OSC messages
• Exchange information with other software like VJ tools or web services

Interactions

There are a few ways tool creators can make the functionality they provide available for users, below is a brief summary of the most used methods.

• Define keybindings that can be assigned to shortcuts and executed from certain contexts in Renoise
• Add new entries to menus like the Tools menu or one of the right-click context menus
• Create custom views that do things on button presses, slider drags and so on
• Listen to MIDI, OSC or WebSocket messages to execute actions
• React to events inside Renoise like "do something any time a new song is loaded"

Limitations

Finally, let's look at what is not possible via tools.

• You cannot override the existing behaviour of Renoise. You can add functionality on top of what's already there, but you can't disable or change how the built-in features work.
  For example, you can create a completely custom GUI to compose patterns in a novel way but you cannot change how the built-in pattern editor works or looks like. Similarly, you can add a new shortcut that does something extra to the selected sample block or places new slices but you can't modify how the built-in autoslicing works.

• You cannot write real-time DSP code like synths, effects or modulators (except for scripts inside the Formula device), which is not using the Renoise Tool API. If you want to design your own synths and effects you should look into plugin development (using DISTRHO, nih-plug etc.), you could also use existing plugins that allow you to build your own DSP patches (like plugdata or Cardinal). Of course you can generate and modify samples using your tool, but it will have to be implemented as offline rendering instead of real-time processing.

Setting up your development environment

To start developing Scripts in Renoise, use the following two menu entries inside the Tools menu on the top bar.

• Scripting Terminal & Editor - This will open the debugging console used to test things and see your tool's output
• Reload All Tools - This will force a reload of all installed and running tools. It can be useful when adding new tools by hand or when changing them.

Lua

Tools in Renoise are written using the Lua programming language. Lua is a dynamic language with a friendly syntax and good performance. While Renoise itself is written in C++, it has an API layer that exposes all sorts of aspects of the tracker so that tools can implement new functionality without the dangers of crashing Renoise itself or having to worry about low level programming challenges.

Language Server

Luckily Lua has a language server called LuaLS which - when paired with the definitions for the Renoise API - can help you write code by providing useful hints about functions and variables, autocompletion and code diagnostics. You can even annotate your own code to keep things more explicit and well documented. While you can absolutely write Lua and create tools without any of this, we highly recommend setting it up.

If you are using VSCode you will have to do three things

• Install the Lua extension by sumneko
• Download the Renoise API definitions from Github
• Configure VSCode so that LuaLS knows where to find the definition files. For this you will have to either put this into your workspace's settings in your project folder (as .vscode/settings.json), or the global User Settings JSON file. Make sure to fill the paths below according to where you've extracted the previously downloaded definitions.

{
    "Lua.workspace.library": [ "PATH/TO/RENOISE_DEFINITION_FOLDER" ],
    "Lua.runtime.plugin": "PATH/TO/RENOISE_DEFINITION_FOLDER/plugin.lua"
}

For configuring other editors, you can check out the official docs about installation

Anatomy of a tool

There are a few things that all tools must conform to for Renoise to successfully recognize and load them.

com.domain_of_developer.name_of_tool.xrnx
├── manifest.xml
├── main.lua
├── cover.png
├── thumbnail.png
├── LICENSE
└── README.md

A tool is a folder or a zip file with the extension .xrnx.

Required files:

• main.lua contains the tool's program.
• manifest.xml is an XML file which describes your tool.

Optional files:

• cover.png 600x350 px is a large image, used on the tools page overview and on the pages of individual tools.
• thumbnail.png 120x45 px is a small capsule image, used when tools are shown in a list on the tools website.
• README.md is a markdown-formatted file that the website will render on the tool's page.
• LICENSE is a raw text license file.

The paths to the cover, thumbnail, readme, and license files can be customized using the ...Path tags in the manifest. See below for more info.

If needed, you can split your tool into multiple files and use the "require" function to load them inside your main script, but to start with, you will be fine just using a single main script.

Some tools will also make use of other resources like bitmaps or audio samples; these should all be placed in the same folder (or any subfolders inside it).

Let's look at a basic tool to see what goes into these two files. You can find more elaborate examples by browsing the example tools.

Manifest

The manifest is a short XML file with the name manifest.xml. It contains a few tag pairs like <Tag>...</Tag> and some text between them. Renoise reads these and loads your tool based on the information it finds within.

Here is an entire manifest file from a HelloWorld tool:

<?xml version="1.0" encoding="UTF-8"?>
<RenoiseScriptingTool doc_version="0">
  <!-- REQUIRED -->
  <Id>com.yourDomain.HelloWorld</Id>
  <ApiVersion>6.2</ApiVersion>
  <Version>1.02</Version>
  <Author>Your Name [your@email.com]</Author>
  <Name>Hello World</Name>
  <!-- OPTIONAL -->
  <Category>Development, Workflow</Category>
  <Description>
    This tool is for printing &quot;Hello World!&quot; to the terminal when loaded.
  </Description>
  <Platform>Windows, Mac, Linux</Platform>
  <License>MIT</License>
  <LicensePath>LICENSE.md</LicensePath>
  <ThumbnailPath>images/thumbnail.png</ThumbnailPath>
  <CoverPath>images/cover.png</CoverPath>
  <DocumentationPath>docs/README.md</DocumentationPath>
  <Homepage>https://some.url/my-tool</Homepage>
  <Documentation>https://some.url/my-tool-docs</Documentation>
  <Discussion>https://some.url/my-tool</Discussion>
  <Repository>https://git.some.url/my-tool</Repository>
  <Donate>https://some.url/donate</Donate>
</RenoiseScriptingTool>

Let's go through what each of these tags means and what you should put inside them.

<?xml> is the header for the XML file; this will stay the same across all tools.
<RenoiseScriptingTool> tells Renoise that this XML describes a tool. Don't change this.
<!-- ... --> is a XML comment, which will be ignored by Renoise.

Required Properties

• <Id> Should match the folder name of your tool exactly, without the .xrnx at the end.
• <ApiVersion> The version of the Renoise API your tool is using. This should be 6.2 for the latest version.
• <Version> The version of your tool. Whenever you release a new update, you should increase the version. Note that this is a number value and not a semantic version. So 1.02 is a valid version, while 1.0.2 is not.
• <Author> Your name and contact information. Whenever your tool crashes, this information is going to be provided for the user alongside the crash message. You should provide a contact method where you can receive bug reports or questions.
• <Name> The human-readable name of your tool. It can be anything you want, and you can change it anytime you feel like it.

Optional Properties

• <Category> One or more categories for your tool, separated via ,, which will be used to categorize your tool on the official Tools page if you ever decide to submit it there. See below for a valid list of categories.
• <Description> A short description of your tool which will be displayed inside the Tool Browser in Renoise and on the official Tools page.
• <License> The type of license, e.g., MIT or AGPL.
• <LicensePath> Relative path to the license file within the XRNX bundle.
• <ThumbnailPath> Relative path to the thumbnail icon file for the Tools page.
• <CoverPath> Relative path to the cover image file for the Tools page.
• <DocumentationPath> Relative path to a plain text or markdown documentation file.
• <Homepage> The URL of your tool's homepage.
• <Discussion> The URL of your tool's discussion page, e.g., on the Renoise forums.
• <Repository> The URL of your tool's source code repository.
• <Donate> A URL to a website where donations can be made to support your tool.
• <Documentation> A URL to a website where your tool's documentation can be viewed.

Tool Categories

Valid categories are: Analysis,Automation,Bridge,Coding,Control,Development,DSP,Editing,Export,Game,Generator,Hardware,Import,Instrument,Integration,Live,MIDI,Mixing,Modulation,Networking,OSC,Pattern,Phrase,Plugin,Recording,Rendering,Sample,Sequencer,Slicing,Tuning,Workflow

XML Text Encoding

When writing the XML file in a regular text editor, ensure that text content is encoded correctly. Otherwise, the XML file will be invalid.

• " -> "
• ' -> '
• < -> <
• > -> >
• & -> &

main.lua

Now that we have a manifest file, we can get to the exciting part of printing a message to the Renoise console. The contents of the main.lua file will just have a single line for now:

print("Hello world!")

Done! Now that you have written your first tool, you probably want to install and test it.

Installing tools

You can install any tool by dragging its folder (or a zip file with the .xrnx extension and the tool's contents) onto Renoise. You can also copy the folder manually into your Tools folder.

After you've installed a tool, it will be activated automatically. When in doubt, click the Tools / Reload All Tools.

Debugging

Scripting Terminal

By default, all prints from all tools are redirected to the Renoise Scripting Terminal. So the easiest way to debug a tool is to add debug prints to your tool.

Since the prints are redirected only when the terminal is open, it doesn't hurt to keep them in distributed tools, but the prints do create some overhead, so remove them if that's relevant - before releasing your tool.

In addition to the standard Lua print, the Renoise APi offers two other print functions that can help with debugging:

• oprint(some_object) prints all methods/properties of API objects (or your own class objects), e.g. oprint(renoise.song()).
• rprint(some_table) prints tables recursively, which is handy for printing the layout of the renoise module/class, e.g. rprint(renoise)

Autoreloading Tools

When working with Renoise's Scripting Editor, saving a script will automatically reload the tool that belongs to the file. This way you can simply change your files and immediately see/test the changes. When changing any files that are part of the "Libraries" folder, all scripts will get reloaded.

When working with an external text editor, you can enable the following debug option somewhere in the tool's main.lua file:

_AUTO_RELOAD_DEBUG = function()
    -- do tests like showing a dialog, prompts whatever, or simply do nothing
end

As soon as you save your script outside of Renoise, and then focus Renoise again (alt-tab to Renoise, for example), your script will instantly get reloaded and the notifier is called.

If you don't need a notifier to be called each time the script reloads, you can also simply set _AUTO_RELOAD_DEBUG to true:

_AUTO_RELOAD_DEBUG = true

Remote Debugging

If printing isn't enough, there is also remote debugging support built into Renoise via Remdebug.

Remdebug is a command line based remote debugger for Lua that comes with Renoise.

Prerequisites

To use the debugger you will need:

• Renoise's "remdebug" module, which can be found in "Scripts/Libraries/remdebug" (no installation required - included in Renoise)

• Lua support on your system's command-line with the Lua "socket" module See http://w3.impa.br/~diego/software/luasocket/

Overview

The debugger will be controlled via a command-line Lua interpreter, outside of Renoise via the remdebug/controller.lua script. To start a local debug session from within Renoise you can use the function debug.start():

-- Opens a debugger controller in a new terminal/cmd window and
-- attaches the debugger to this script. Immediately breaks execution.
debug.start()

You can add this anywhere in any script that runs in Renoise. This will work in a tool's main.lua main() body, just like a local function that you include. It also works in the TestPad.lua script that is used in Renoise's Scripting Editor.

Step By Step Guide

Let's debug the following small test script, paste into RENOISE_PREFERENCES/Scripts/TestPad.lua:

debug.start()

local function sum(a, b)
    return a + b
end

local c = sum(1, 2)
print(c)

debug.stop()

• Launch Renoise's scripting editor, open "TestPad.lua", and hit the "Execute" button to run the script.

  If Lua is correctly installed on your system, and remdebug was found, Renoise should be frozen now, with a terminal window opened showing something like:

> "Lua Remote Debugger"
> "Paused at file RENOISE_PREFERENCES_FOLDER/Scripts/TestPad.lua line 5"
>
> 1    debug.start()
> 2
> 3    local function sum(a, b)
> 4      return a + b
> 5*** end
> 6
> 7    local c = sum(1, 2)
> 8    print(c)
> 9
> 10   debug.stop()
>
>>

• To step through the code, you can use the "s" and "n" commands in the terminal. Let's do so by entering "s" (Return) until we've reached line 8. Anything you type into the debugger, which is not a debugger command, will get evaluated in your running script as an expression. So let's try this by entering: c=99

• Then step over the line by entering "n" (Return) to evaluate the "print(c)" on line 9 in the script. You should see a "99" dumped out. To watch the value again, enter for example a print(c). You should again see a "99" dumped out.

You can also set break and watchpoints in the debugger. Type 'help' in the terminal to get more info about this. Those who are familiar with gdb on the command-line may be able to quickly get up to speed when using the most common shortcuts (c,b,q, and so on...).

Please note that although "debug.stop()" is not necessary (you can simply quit the controller at any time to exit), its recommended and will be more comfortable when running a session over and over again.

Remote and Lua Editor debugging

Renoise's remdebug is fully compatible with the original remdebug controller from the kepler project. This means you can, in theory, also use debugger GUIs that use the original remdebug, like Lua Eclipse or SciTE for Lua.

However, this is often a PITA to setup and configure, and might not be worth the trouble. Try at your own risk...

The debugger can also be used to remote debug scripts, scripts running on other computers. To do so, use remdebug.engine.start/stop instead of "debug". debug.start/stop is just a shortcut to remdebug.session.start/stop.

"remdebug.engine.start" will only attach the debugger to your script and break execution. You then have to run the debugger controller manually on another computer. To do so, launch the remdebug.controller.lua file manually in a terminal:

• First we start the debugger controller. To do so, open a command-line on your system and invoke the remdebug/controller.lua script. You should see something like:

lua RENOISE_RESOURCE_FOLDER/Scripts/Libraries/remdebug/controller.lua
"Lua Remote Debugger"
"Run the program you wish to debug with 'remdebug.engine.start()' now"

• Now you can connect to this controller by running a script with remdebug.engine.start(), configured to find the controller on another machine (or the same one.)

require "remdebug.engine"
-- default config is "localhost" on port 8171
remdebug.engine.configure { host = "some_host", port = 1234 }
remdebug.engine.start()

Distribution

Eventually you might want to share your work with others, in this case you will have to use the zipped format.

• First, we recommend sharing your tool on the Tools section of the forum to get some feedback and early testing done. If you create a topic there, you can also use it to notify users about updates or discuss potential improvements.
• Later on, you might want to submit your tool to the official Tool library so that users can find it easier and have automatic updates.

Community channels

If you have further questions or just want to discuss tools with fellow devs you can reach out over the following channels

• The official Renoise forum has a dedicated topic
• The Discord server has a room for scripting
• Enter the Matrix at Renoise space on Matrix
• Post on Reddit
• Join the Facebook Group
• Find community channels on the Renoise site

Now that you can write, package and test your tool, you are ready to explore the depths of the API and start implementing your ideas.

Guides to the Renoise API

Welcome to the guides for the Renoise Scripting API.

In this section, you can learn about different aspects of the API through practical examples and explanations. These guides assume you have already read the chapters in our introduction and are familiar with how to package and install tools.

Classes

The Lua language does not have a built-in class construct. However, the Renoise Lua API provides simple object-oriented programming support via a global class() function. All Renoise API objects use such classes, and you can use them in your tools as well.

See the luabind documentation for more technical information, and the examples below for how to use them.

Examples

-- abstract class
class 'Animal'

  function Animal:__init(name)
    self.name = name
    self.can_fly = nil
  end  

  function Animal:__tostring()
    assert(self.can_fly ~= nil, "I don't know if I can fly or not")
    
    return ("I am a %s (%s) and I %s"):format(self.name, type(self), 
      (self.can_fly and "can fly" or "cannot fly"))
  end


-- derived classes

-- MAMMAL
class 'Mammal' (Animal)

  function Mammal:__init(str)
    Animal.__init(self, str)
    self.can_fly = false
  end

-- BIRD
class 'Bird' (Animal)

  function Bird:__init(str)
    Animal.__init(self, str)
    self.can_fly = true
  end

-- FISH
class 'Fish' (Animal)

  function Fish:__init(str)
    Animal.__init(self, str)
    self.can_fly = false
  end


-- run

local farm = {}

table.insert(farm, Mammal("cow"))
table.insert(farm, Bird("sparrow"))
table.insert(farm, Fish("bass"))

print(("type(Mammal('cow')) -> %s"):format(type(Mammal("cow"))))
print(("type(Mammal) -> %s"):format(type(Mammal)))

for _,animal in ipairs(farm) do
  print(animal)
end

Something to keep in mind:

• A constructor, function MyClass:__init(args), must be defined for each class, or the class cannot be used to instantiate objects.
• Class definitions are always global, so even locally defined classes will be registered globally.

Class operators

You can overload most operators in Lua for your classes. You do this by simply declaring a member function with the same name as an operator's corresponding metamethod in Lua.

The operators you can overload are:

• __add (addition)
• __sub (subtraction)
• __mul (multiplication)
• __div (division)
• __pow (exponentiation)
• __lt (less than)
• __le (less than or equal to)
• __eq (equality)
• __call (function call)
• __unm (unary minus)
• __tostring (serialization)
• __len (length operator #)

Note: __tostring isn't really an operator, but it's the metamethod that is called by the standard library's tostring() function.

Observables

The Renoise API makes extensive use of the Observer pattern. In short, many values are wrapped in "Observable" objects. You can register "notifier" functions on these objects, which will be called whenever the underlying value changes. This is a powerful way to react to changes in the application state without constantly polling and comparing values.

When browsing the API documentation, you will find many properties with an _observable suffix. Let's see how to use this feature by attaching a notifier that runs when the user loads a new song.

local function on_new_document()
  renoise.app():show_message("Loaded a new song!")
end

-- Get the tool's new_document observable and add our function as a notifier.
renoise.tool().app_new_document_observable:add_notifier(on_new_document)

A common pattern is to attach notifiers to song-specific properties inside the app_new_document_observable notifier. This ensures that your notifiers are re-attached whenever a new song is loaded. To listen for changes on a specific value, you typically add _observable to the property name and add a notifier to it.

Let's extend the previous snippet to also fire a message whenever the name of the song changes.

local function on_song_name_changed()
  local song_name = renoise.song().name
  renoise.app():show_message("New name was set!\nName: " .. song_name)
end

local function on_new_document()
  renoise.app():show_message("Loaded a new song!")
  -- When a new song is loaded, attach a notifier to its name_observable
  renoise.song().name_observable:add_notifier(on_song_name_changed)
end

renoise.tool().app_new_document_observable:add_notifier(on_new_document)

Now, try changing the song title in the "Song Settings" tab to see your message pop up.

With this technique, you can listen to all sorts of events, which is very useful when you want your tool to react to user actions like selecting a new instrument, track, or sample.

There are different Observables for each primitive type, such as ObservableBoolean, ObservableNumber, or ObservableString, as well as list types like ObservableBooleanList. You can explore the entire Observables API to see them all.

Renoise Application

The renoise.app() function is the entry point for interacting with the Renoise application itself. It returns a renoise.Application object, which provides access to global application states, functions for user interaction like dialogs, and control over the main window.

Controlling the Application Window

The renoise.ApplicationWindow object, accessed via renoise.app().window, allows you to query and control the state of the main Renoise UI.

local window = renoise.app().window

-- Toggle fullscreen mode
window.fullscreen = not window.fullscreen

-- Check if the disk browser is visible
if window.disk_browser_is_visible then
  print("Disk browser is currently open.")
end

-- Switch the middle frame to the Mixer view
window.active_middle_frame = 
  renoise.ApplicationWindow.MIDDLE_FRAME_MIXER

You can also attach notifiers to many window properties to react to UI changes made by the user.

local window = renoise.app().window

-- Be notified when the disk browser visibility changes
function disk_browser_visibility_changed()
  if window.disk_browser_is_visible then
    renoise.app():show_status("Disk browser was opened.")
  else
    renoise.app():show_status("Disk browser was closed.")
  end
end

window.disk_browser_is_visible_observable:add_notifier(
  disk_browser_visibility_changed
)

Song and File Handling

The application object provides functions to load, and save songs, instrument and other kinds of components. Note that these operations are not always instantaneous, as Renoise may need to prompt the user to save changes.

To reliably execute code after a new song is created or loaded, you should use notifiers.

local app = renoise.app()

-- This will show a file dialog to the user. The song is not loaded immediately.
app:load_song("/path/to/some/song_file") 

-- To run code after a new song is ready, use a notifier.
-- This is typically done in your tool's initialization code.
function handle_new_document()
  print("A new song was created or loaded. The new song name is: " ..
    renoise.song().name)
end

-- The 'new_document_observable' is fired after a new song is
--- successfully created or loaded.
renoise.tool().app_new_document_observable:add_notifier(handle_new_document)

-- To save a song to a specific file:
app:save_song_as("/path/to/MyNewSong.xrns")

Showing Dialogs and Messages

A common task for tools is to communicate with the user. The application object provides several functions to show different kinds of dialogs and messages.

Simple Messages

For simple notifications, you can use show_message, show_error, show_warning, or show_status.

local app = renoise.app()

-- Show a message in the status bar
app:show_status("This is a status message.")

-- Show a modal info dialog
app:show_message("This is an informational message.")

-- Show a modal warning dialog
app:show_warning("This is a warning message.")

-- Show a modal error dialog
app:show_error("This is an error message.")

User Prompts

To ask the user for a choice, you can use show_prompt. It displays a dialog with custom buttons and returns the label of the button that was pressed.

local app = renoise.app()

local pressed_button = app:show_prompt(
  "Confirm Action", 
  "Do you want to proceed?", 
  { "Yes", "No", "Cancel" }
)

if pressed_button == "Yes" then
  app:show_message("You chose to proceed.")
elseif pressed_button == "No" then
  app:show_message("You chose not to proceed.")
else
  app:show_message("You canceled the operation.")
end

Custom Dialogs

For more complex user interfaces, you can create custom non-modal dialogs (tool windows) with show_custom_dialog. This requires using the renoise.ViewBuilder API to construct the UI.

-- A simple custom dialog example
local vb = renoise.ViewBuilder()

local my_dialog = nil
local my_dialog_content = vb:column {
  margin = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN,
  spacing = renoise.ViewBuilder.DEFAULT_DIALOG_SPACING,
  views = {
    vb:text {
      text = "This is a custom dialog."
    },
    vb:button {
      text = "Close Me",
      notifier = function()
        -- my_dialog is defined when calling show_custom_dialog
        my_dialog:close()
      end
    }
  }
}

my_dialog = renoise.app():show_custom_dialog(
  "My Tool Window", my_dialog_content
)

File and Path Prompts

Your tool might need to read from or write to files. The API provides functions to open native file browser dialogs.

local app = renoise.app()

-- Prompt the user to select a directory
local dir_path = app:prompt_for_path("Select a Project Folder")
if dir_path and #dir_path > 0 then
  app:show_message("You selected the directory: " .. dir_path)
end

-- Prompt the user to select a file to open
local file_to_read = app:prompt_for_filename_to_read(
  { "txt", "lua" }, 
  "Open a Text File"
)
if file_to_read and #file_to_read > 0 then
  app:show_message("You selected the file: " .. file_to_read)
end

-- Prompt the user for a filename to save
local file_to_write = app:prompt_for_filename_to_write(
  "xml", 
  "Save Configuration"
)
if file_to_write and #file_to_write > 0 then
  app:show_message("File will be saved to: " .. file_to_write)
end

Renoise Song

The renoise.song() function is the main entry point for scripting in Renoise. It returns a renoise.Song object that represents the entire project currently loaded in the application.

Here is a simplified tree view of the song object model:

renoise.song()
├── transport              (BPM, LPB, playback control)
├── tracks[]               (List of all tracks in the song)
│   ├── devices[]
│   │   └── parameters[]
│   └── ...
├── instruments[]          (List of all instruments)
│   ├── samples[]
│   │   └── sample_buffer
│   └── ...
├── patterns[]             (The pool of all available patterns)
│   └── tracks[]
│       ├── lines[]
│       │   ├── note_columns[]
│       │   └── ...
│       └── automation[]
├── sequencer              (The pattern sequence matrix)
│   └── pattern_sequence[]
└── selected_track         (And other `selected_...` properties)

Let's look at some important components in more detail.

Transport

The renoise.Transport object controls global song properties related to timing and playback.

local song = renoise.song()
local transport = song.transport

-- Read properties
print("Current BPM: " .. transport.bpm)
print("Current LinesPerBeat: " .. transport.lpb)

-- Change properties
transport.bpm = 140

-- Start playback
if not transport.playing then
  transport:start(renoise.Transport.PLAYMODE_RESTART_PATTERN)
end

Tracks

The renoise.song().tracks property is a list of all tracks in the song, including sequencer tracks, group tracks, send tracks, the master track. Each renoise.Track has its own device chain and other properties.

local song = renoise.song()

-- Iterate over all tracks
for _, track in ipairs(song.tracks) do
  -- Check the track type
  if track.type == renoise.Track.TRACK_TYPE_SEQUENCER then
    print("Sequencer Track: " .. track.name)
    -- Access the track's device chain
    local devices = track.devices
    print("  - Devices: " .. #devices)
  end
end

-- Access a specific track by its index (1-based)
local first_track = song.tracks[1]
first_track.name = "New Name" -- Set the track's name

Track Devices and Parameters

Once you have a device chain, you can iterate over its devices renoise.AudioDevice and parameters renoise.DeviceParameter. The first device in a track's chain is always the "Mixer" device, which contains the track's built-in parameters like volume and panning.

local selected_track = renoise.song().selected_track
local mixer_device = selected_track.devices[1]

print("Parameters for '" .. mixer_device.display_name .. "':")

for _, param in ipairs(mixer_device.parameters) do
  print(string.format("  - %s: %s", param.name, param.value_string))
end

Modifying Parameter Values

You can read and write a parameter's value using its .value (a number from 0.0 to 1.0) or .value_string (a formatted string like "1.000 dB") properties.

Also, the Mixer device properties can also be accessed directly from the track object.

local selected_track = renoise.song().selected_track

-- Access a parameter by its property name on the track object
local pre_volume = selected_track.prefx_volume
print("Pre-Mixer Volume is: " .. pre_volume.value_string)

-- Set the value using a string
pre_volume.value_string = "1.0 dB"
-- Note: When reading the value back, the string may be formatted differently
assert(pre_volume.value_string == "1.000 dB")

-- Set the value using a normalized number
local pre_width = selected_track.prefx_width
pre_width.value = 1.0 -- 100% wide
assert(pre_width.value == 1.0)

Adding, Removing, and Swapping Devices

You can dynamically manage the devices in a chain. To add a device, you need its identifier path, which you can query via track.available_devices.

local track = renoise.song().selected_track

print("Available devices:")
-- `rprint` is a Renoise extension which also pretty prints tables 
rprint(track.available_devices)

-- Get a random device path (excluding plugins to avoid popups)
local device_path
repeat
  device_path = track.available_devices[
    math.random(1, #track.available_devices)]
until device_path:find("Native/")

-- Insert the device at the end of the chain
local device_count = #track.devices
local new_device = track:insert_device_at(
  device_path, device_count + 1)
assert(#track.devices == device_count + 1)
print("Added device: " .. new_device.display_name)

-- Insert another one
track:insert_device_at(device_path, #track.devices + 1)

-- Swap the last two devices
track:swap_devices_at(#track.devices, #track.devices - 1)
print("Swapped the last two devices.")

-- Remove the last device
track:delete_device_at(#track.devices)
print("Removed the last added device.")

PatternTrack Lines

A renoise.PatternTrack holds pattern lines and automations for a single track in a single pattern.

The following example writes a C-4 note in the first pattern's track.

local song = renoise.song()

-- Get the first pattern in the song
local pattern = song.patterns[1]

-- Get the first pattern track within that pattern
local pattern_track = pattern.tracks[1]

-- Access a specific line (1-based)
local line = pattern_track:line(1)

-- Access the first note column in that line
local note_column = line.note_columns[1]
if note_column then
  -- Set a C-4 note
  note_column.note_string = "C-4"
end

For efficiently iterating over pattern data, it's recommended to use the renoise.PatternIterator.

This example changes all C-4 notes to E-4 within the current selection in the pattern editor.

local song = renoise.song()
local pattern_iter = song.pattern_iterator
local pattern_index = song.selected_pattern_index

for pos,line in pattern_iter:lines_in_pattern(pattern_index) do
  for _,note_column in ipairs(line.note_columns) do 
    if (note_column.is_selected and 
        note_column.note_string == "C-4") then
      note_column.note_string = "E-4"
    end
  end
end

PatternTrack Automation

A renoise.PatternTrackAutomation automates track device parameters.

This example accesses the automation for the parameter currently selected in the "Automation" tab in Renoise.

local song = renoise.song()
local selected_parameter = song.selected_automation_parameter
local selected_pattern_track = song.selected_pattern_track

-- Is a parameter selected?
if selected_parameter then
  local automation = selected_pattern_track:find_automation(
    selected_parameter)

  -- Check if automation for the selected parameter already exists
  if not automation then
    -- If not, create it for the current pattern/track
    automation = selected_pattern_track:create_automation(
      selected_parameter)
  end

  ---- Do something with the automation ----
  
  -- Iterate over all existing automation points
  for _,point in ipairs(automation.points) do
    print(("track automation: time=%s, value=%s"):format( 
      point.time, point.value))
  end
  
  -- Clear all points
  automation.points = {} 

  -- Insert a single new point at line 2
  automation:add_point_at(2, 0.5) 
  -- Change its value if it already exists
  automation:add_point_at(2, 0.8) 
  -- Remove it again (a point must exist at this time)
  automation:remove_point_at(2) 
  
  -- Batch creation/insertion of points
  local new_points = {}
  for i=1, #selected_pattern_track.lines do
    table.insert(new_points, {
      time = i, 
      value = i / automation.length
    })
  end
  
  -- Assign them (note: new_points must be sorted by time)
  automation.points = new_points 

  -- Change the automation's interpolation mode
  automation.playmode =
    renoise.PatternTrackAutomation.PLAYMODE_POINTS
end

Instruments

The renoise.song().instruments property contains a list of all instruments. An renoise.Instrument may contain phrases, midi in/out properties, plugin devices, samples, sample modulation, and sample DSP FX chains.

local song = renoise.song()

-- Get the selected instrument
local instrument = song.selected_instrument
if instrument then
  print("Selected instrument: " .. instrument.name)
  
  -- Access its samples
  if #instrument.samples > 0 then
    print("  - It has " .. #instrument.samples .. " samples.")
    local first_sample = instrument.samples[1]
    print("    - First sample name: " .. first_sample.name)
  end
end

Samples

The renoise.SampleBuffer object provides low-level access to the audio data of a sample.

This example inverts the phase of the selected sample data.

local sample = renoise.song().selected_sample
if not sample then 
  print("No sample selected") 
  return
end

local sample_buffer = sample.sample_buffer
if not sample_buffer.has_sample_data then 
  print("No sample buffer present")
  return
end

-- Before modifying sample data, let Renoise prepare for undo/redo actions
sample_buffer:prepare_sample_data_changes()

-- Modify sample data in the selection (defaults to the whole sample)
for channel = 1, sample_buffer.number_of_channels do
  for frame = sample_buffer.selection_start, sample_buffer.selection_end do
    local value = sample_buffer:sample_data(channel, frame)
    value = -value -- Invert the sample value
    sample_buffer:set_sample_data(channel, frame, value)
  end
end

-- Let Renoise know the changes are done. This updates UI overviews,
-- applies bit-depth quantization, and finalizes the undo/redo data.
sample_buffer:finalize_sample_data_changes()

This example creates a new sample from scratch and generates a simple sine wave.

local selected_sample = renoise.song().selected_sample
if not selected_sample then return end

local sample_buffer = selected_sample.sample_buffer

-- Define properties for the new sample data
local sample_rate = 44100
local num_channels = 1
local bit_depth = 32
local num_frames = sample_rate / 2 -- half a second

-- Create new or overwrite existing sample data
local allocation_succeeded = sample_buffer:create_sample_data(
  sample_rate, bit_depth, num_channels, num_frames)

-- Check for allocation failures
if not allocation_succeeded then
  renoise.app():show_error("Out of memory. Failed to allocate sample data.")
  return
end

-- Let Renoise know we are about to change the sample buffer
sample_buffer:prepare_sample_data_changes()
  
-- Fill the sample data with a sine wave
for frame = 1, num_frames do
  -- We only have one channel, so we use 1
  local sample_value = math.sin((frame / num_frames) * math.pi * 2)
  sample_buffer:set_sample_data(1, frame, sample_value)
end

-- Finalize the changes
sample_buffer:finalize_sample_data_changes()

-- Set up a ping-pong loop for our new sample
selected_sample.loop_mode = renoise.Sample.LOOP_MODE_PING_PONG
selected_sample.loop_start = 1
selected_sample.loop_end = num_frames

Sequencer

The renoise.PatternSequencer manages the arrangement of patterns in the song.

The pattern_sequence property is a list of pattern indices that defines the playback order.

local song = renoise.song()
local sequencer = song.sequencer

print("Song sequence:")
for position, pattern_index in ipairs(sequencer.pattern_sequence) do
  print(string.format("  Position %d: Pattern %d", position, pattern_index))
end

-- Set a new sequence
sequencer.pattern_sequence = { 1, 1 }

-- Change the sequence: make the second slot play pattern 2
sequencer:set_pattern(2, 2)

-- Add a new slot at the end of the sequence, playing pattern 3
sequencer:insert_sequence_at(#sequencer.pattern_sequence + 1, 3)

Selected Elements

The song object also provides convenient properties to directly access elements that are currently selected in the Renoise user interface. This is very useful for creating tools that operate on the user's current context.

local song = renoise.song()

-- Get the currently selected track object
local selected_track = song.selected_track
print("Selected track: " .. selected_track.name)

-- Get the index of the selected pattern
local selected_pattern_index = song.selected_pattern_index
print("Selected pattern index: " .. selected_pattern_index)

-- Get the selected device in a track's device chain
local selected_device = song.selected_track_device
if selected_device then
  print("Selected device: " .. selected_device.display_name)
end

Renoise Tool

The renoise.tool() function is the entry point for interacting with your tool's own context. It returns a renoise.ScriptingTool object, which allows you to integrate your tool with Renoise by adding menu entries, keybindings, and MIDI mappings. It also provides ways to handle application-wide events, manage timers, define preferences, and much more.

Menu Entries

You can add new menu entries into any existing context menu or the main application menu in Renoise.

To do so, use the tool's renoise.tool():add_menu_entry function.

Example

renoise.tool():add_menu_entry {
  name = "Main Menu:Tools:My Tool:Show Message...",
  invoke = function()
    renoise.app():show_prompt(
      "Congrats!",
      "You've pressed the 'Show Message...' menu entry from the tools menu, " ..
      "which was defined by a scripting tool.",
      {"OK?"}
    )
  end
}

Available Menus

You can place your entries in any context menu or window menu in Renoise. To do so, specify the target menu category in the name property.

For a complete list of available menu locations, see the API documentation for ToolMenuEntry.

Separating Entries

To divide entries into groups with a separating line, prepend one or more dashes to the name, like so:

name = "--- Main Menu:Tools:My Tool Group Starts Here"

Entry Sub-Groups

To group entries into a sub-menu, use a common path for them in the name property:

"Main Menu:Tools:My Tool Group:First Entry"
"Main Menu:Tools:My Tool Group:Second Entry"
"Main Menu:Tools:My Tool Group:Third Entry"

Keybindings

Tools can add custom key bindings to Renoise's existing set of key commands. These new bindings can be activated and mapped by the user just like any other key binding in Renoise.

Keybindings can be global (applied everywhere in the GUI) or local to a specific part of the GUI, like the Pattern Editor.

To add a key binding, use the tool's renoise.tool():add_keybinding function.

Example

renoise.tool():add_keybinding {
  name = "Global:Tools:Example Script Shortcut",
  invoke = function(repeated)
    -- we ignore soft repeated keys here
    if (not repeated) then
      renoise.app():show_prompt(
        "Congrats!",
        "You've pressed a magic keyboard combo " ..
        "which was defined by a scripting tool.",
        {"OK"}
      )
    end
  end
}

Scopes

The scope, topic, and name of the key binding are defined in the name property, using the format: $scope:$topic_name:$binding_name.

• scope: This is where the shortcut will be applied, corresponding to the categories in the keyboard assignment preference pane. Your key binding will only fire when its scope is focused, unless it's the Global scope. Using an unavailable scope will not cause an error, but it will render the binding useless—it will be listed and mappable, but never invoked.

• topic_name: This is used for grouping entries in the key assignment pane. Use "Tools" if you can't come up with something more specific.

• binding_name: This is the display name of the binding.

For a list of available scopes, see the API documentation for ToolKeybindingEntry.

Separating entries

To divide entries into groups with a separating line, prepend one or more dashes to the name, like so:

name = "--- Main Menu:Tools:My Tool Group Starts Here"

Custom GUIs

You can create custom dialogs and tool windows for your tools using the renoise.ViewBuilder and renoise.Application.

Modal and Non-Modal Dialogs

There are two main ways to show a custom view:

-- Shows a modal dialog with a title, custom content, and custom button labels.
-- It blocks interaction with the main window until closed.
renoise.app():show_custom_prompt(
  title, content_view, {button_labels} [, key_handler_func, key_handler_options])
  -> [pressed_button_index]

See the API docs for renoise.app():show_custom_prompt for more info.

-- Shows a non-modal dialog (a floating tool window) with custom content.
renoise.app():show_custom_dialog(
  title, content_view [, key_handler_func, key_handler_options])
  -> [dialog_object]

See the API docs for renoise.app():show_custom_dialog for more info.

The optional key_handler_func allows you to capture keyboard events in the dialog. See the API docs for KeyHandler for details.

Creating Views with ViewBuilder

Widgets are created with the renoise.ViewBuilder class.

Hello World

-- We start by instantiating a view builder object.
local vb = renoise.ViewBuilder()

-- We will use a "column" view to stack other views vertically.
-- A column can:
-- 1. Show a background style.
-- 2. Stack child views vertically (vb:column) or horizontally (vb:row).
-- 3. Align child views using margins and spacing.

local dialog_title = "Hello World"
local dialog_buttons = { "OK" }

-- Fetch some constants to make the dialog look like Renoise's native views.
local DEFAULT_MARGIN = renoise.ViewBuilder.DEFAULT_CONTROL_MARGIN

-- Start with a 'column' view to stack other views vertically.
local dialog_content = vb:column {
  -- Set a margin around our main content.
  margin = DEFAULT_MARGIN,
  views = {
    -- Create another column to group our text with a different background.
    vb:column {
      -- A background style that is usually used for "groups".
      style = "group",
      -- Add some margin inside the group to make it look nice.
      margin = DEFAULT_MARGIN,
      views = {
        -- Finally, add the text to the inner column.
        vb:text {
          text = "from the Renoise Scripting API\n" ..
                 "in a vb:column with a background."
        },
      }
    }
  }
}

-- Show the custom content in a prompt.
renoise.app():show_custom_prompt(
  dialog_title, dialog_content, dialog_buttons)

Dynamic Content

GUIs are usually dynamic. To interact with widgets after they are created, you need a way to reference them. Here's how this works with the ViewBuilder API.

local vb = renoise.ViewBuilder()

-- You can build views step-by-step instead of nesting them all at once.
-- This can be clearer for complex layouts.

-- This step-by-step approach:
local my_column_view = vb:column{}
my_column_view.margin = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN
my_column_view.style = "group"

local my_text_view = vb:text{}
my_text_view.text = "My text"
my_column_view:add_child(my_text_view)

-- ...is equivalent to this nested approach:
local my_column_view_nested = vb:column {
  margin = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN,
  style = "group",
  views = {
    vb:text {
      text = "My text"
    }
  }
}

-- The nested notation has a problem: you can't easily get references to your
-- views later (e.g., to hide them or change their text). This is what view
-- builder "id"s are for.

-- Let's build a simple view that dynamically reacts to a button press.

local DEFAULT_DIALOG_MARGIN = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN
local DEFAULT_CONTROL_SPACING = renoise.ViewBuilder.DEFAULT_CONTROL_SPACING

local dialog_title = "ViewBuilder IDs"
local dialog_buttons = {"OK"}

local dialog_content = vb:column {
  margin = DEFAULT_DIALOG_MARGIN,
  spacing = DEFAULT_CONTROL_SPACING,
  views = {
    vb:text {
      id = "my_text", -- We give the view a unique id here.
      text = "Do what you see"
    },
    vb:button {
      text = "Hit Me!",
      tooltip = "Hit this button to change the text above.",
      notifier = function()
        -- Here we resolve the id to get a reference to the text view.
        local my_text_view = vb.views.my_text
        my_text_view.text = "Button was hit."
      end
    }
  }
}

-- We are doing two things here:
-- 1. We create a vb:text view and give it a unique `id`. This id can be
--    used at any time to access this view via `vb.views.my_text`.
-- 2. We add a `vb:button` control with a `notifier` function. The notifier
--    is called as soon as the button is pressed.

-- Please note that ids are unique per ViewBuilder object. You can create
-- multiple ViewBuilder instances (e.g., one for each component) to manage
-- different sets of ids.

renoise.app():show_custom_prompt(
  dialog_title, dialog_content, dialog_buttons)

More Examples

See the com.renoise.ExampleToolGui.xrnx tool for more examples. This tool can be read as its own little guide and provides many more in-depth examples.

The example tools can be downloaded as part of the XRNX Starter Pack from the official repository's releases page.

MIDI Mappings

You can extend Renoise's default MIDI mapping set or add custom MIDI mappings for your tool using renoise.tool():add_midi_mapping.

A tool's MIDI mapping can be used just like regular mappings: by manually binding it in the MIDI mapping dialog, or by assigning it to a custom GUI control via the midi_mapping property.

renoise.tool():add_midi_mapping {
  name = "My Tool:Control Something",
  invoke = function(message)
    -- message is a renoise.ScriptingTool.MidiMessage
    if message.is_trigger then
      renoise.app():show_status("MIDI trigger received!")
    end
    if message.is_abs_value then
      local value = message.int_value
      renoise.app():show_status("MIDI value received: " .. value)
    end
  end
}

The name property follows the format $topic_name:$optional_sub_topic_name:$mapping_name to organize mappings in the list. The invoke function receives a MidiMessage object that describes the incoming MIDI data.

File Import Hooks

You can add support for new filetypes in Renoise using renoise.tool():add_file_import_hook. Registered file types will appear in Renoise's disk browser and can be loaded via drag-and-drop.

renoise.tool():add_file_import_hook {
  category = "sample",
  extensions = {"txt"},
  invoke = function(file_name)
    -- This is a dummy example. A real implementation would
    -- parse the file and create sample data.
    local file = io.open(file_name, "r")
    if not file then return false end
    local content = file:read("*a")
    file:close()
    
    local sample = renoise.song().selected_sample
    if not sample then return false end
    
    -- For simplicity, we just show the content in a dialog
    -- instead of creating a sample from it.
    renoise.app():show_message(
      "Imported TXT as Sample",
      "File content:\n" .. content
    )
    
    -- Return true on success, false on failure.
    return true
  end
}

Your hook must specify a category (e.g., "sample", "instrument"), a list of file extensions, and an invoke function that performs the import logic.

Timers

Tools can register functions that are called periodically using renoise.tool():add_timer. This is useful for background tasks or animations in custom GUIs.

local tick_count = 0
local function my_timer_func()
  tick_count = tick_count + 1
  renoise.app():show_status("Timer tick: " .. tick_count)
  if tick_count >= 10 then
    -- To create a one-shot timer, remove it when it's no longer needed.
    renoise.tool():remove_timer(my_timer_func)
    renoise.app():show_status("Timer removed.")
  end
end

-- Call my_timer_func every 1000ms (1 second).
renoise.tool():add_timer(my_timer_func, 1000)

Timers are paused when modal dialogs are open. The interval is not guaranteed to be exact, but it's usually accurate to within a few milliseconds.

Application Notifiers

The tool object provides several ..._observable properties that allow you to react to application-level events, such as loading a new song or the tool being shut down. This is the primary way to manage your tool's lifecycle.

local function on_new_song()
  local song_name = renoise.song() and renoise.song().name or "Untitled"
  renoise.app():show_status("New song loaded: " .. song_name)
end

-- Called every time a new song is created or loaded.
renoise.tool().app_new_document_observable:add_notifier(on_new_song)

local function on_tool_shutdown()
  -- This is a good place to clean up resources.
  print("My tool is unloading.")
end

-- Called right before the tool is unloaded.
renoise.tool().tool_will_unload_observable:add_notifier(on_tool_shutdown)

Some important notifiers include:

• tool_finished_loading_observable: Fired when the tool has been successfully loaded.
• tool_will_unload_observable: Fired just before the tool is disabled or reloaded.
• app_new_document_observable: Fired after a new song has been loaded.
• app_release_document_observable: Fired before the current song is closed.
• app_will_save_document_observable Fired just before the song is saved.
• app_idle_observable: Fired periodically, useful for low-priority background tasks.

Preferences

Tools can have preferences that are saved and loaded by Renoise. To use them, we first need to create a renoise.Document object which holds the options that we want to store.

Fields in a Renoise Document are defined as Observable types. This is especially handy for settings dialogs, as UI widgets can be directly bound to these observable properties. The UI will automatically update the document, and vice-versa.

Let's see an example of setting up an options object for a tool. Our goal is to have a few settings managed by a Document and a dialog to change them. The tool will be able to randomize the song's BPM and track count.

We will also define a menu entry to open our tool's settings dialog. See the sections on Menu Entries and Custom GUIs for more details.

-- Create a new renoise.Document by supplying a table of default values.
-- Each field will be wrapped in an Observable type (e.g., ObservableBoolean).
-- * a boolean for whether the tool should randomize the BPM
-- * a boolean for randomizing tracks
-- * an integer for the maximum number of tracks
local options = renoise.Document.create("RandomizerToolPreferences") {
  randomize_bpm = true,
  randomize_tracks = false,
  max_tracks = 16
}

-- Once we have our options, we assign the document to our tool's preferences.
renoise.tool().preferences = options

-- Define a randomizer function.
-- When called, it will set a random BPM and add or remove tracks.
local function randomize_song()
  local song = renoise.song()
  -- Use .value to access the underlying value of an Observable
  if options.randomize_bpm.value then
    -- Set BPM to a value between 60 and 180
    song.transport.bpm = 60 + math.random() * 120
  end
  
  if options.randomize_tracks.value then
    -- Figure out how many tracks we want based on the max_tracks option
    local target_count = 1 + math.floor(math.random() * options.max_tracks.value)
    local current_count = song.sequencer_track_count

    if current_count < target_count then
      -- Insert new tracks if there aren't enough
      for i = 1, target_count - current_count do
        song:insert_track_at(current_count)
      end
    else
      -- Remove tracks if there are too many
      for i = 1, current_count - target_count do
        song:delete_track_at(song.sequencer_track_count)
      end
    end
  end
end

-- Define a function to show a custom dialog for our options.
function show_options()
  local vb = renoise.ViewBuilder()

  local dialog_content = vb:column {
    margin = renoise.ViewBuilder.DEFAULT_DIALOG_MARGIN,
    views = {
      -- Add randomize BPM option
      vb:row {
        views = {
          -- Bind our observable value directly to this checkbox
          vb:checkbox {
            bind = options.randomize_bpm
          },
          vb:text {
            text = "Randomize BPM"
          }
        }
      },
      -- Add randomize tracks option
      vb:row {
        views = {
          -- Same for the randomize_tracks boolean
          vb:checkbox {
            bind = options.randomize_tracks
          },
          vb:text {
            text = "Randomize Tracks"
          },
        }
      },
      -- Add max tracks row
      vb:row {
        views = {
          -- For max_tracks, create a valuebox and bind it.
          -- Restrict it to a range of [1..16].
          vb:valuebox {
            min = 1,
            max = 16,
            bind = options.max_tracks
          },
          vb:text {
            text = "Tracks Max"
          }
        }
      },
      -- Add some space
      vb:space{ 
        height = renoise.ViewBuilder.DEFAULT_DIALOG_SPACING
      }, 
      -- Add a button that will execute the randomization
      vb:button {
        text = "Randomize Now",
        notifier = randomize_song
      }
    }
  }
  
  renoise.app():show_custom_dialog(
    "Randomizer Options", dialog_content
  )
end

-- Finally, add a menu entry to open our options dialog.
renoise.tool():add_menu_entry {
  name = "Main Menu:Tools:Randomizer Options...",
  invoke = show_options
}

As you can see, all we had to do was assign our observables to the bind property of the UI controls. Renoise handles the synchronization between the UI and the document automatically.

preferences.xml

When you assign a document to renoise.tool().preferences, Renoise automatically saves its state to a preferences.xml file inside your tool's folder. As long as you use simple data types, you don't have to worry about serialization.

Try restarting Renoise to see that the values you've set in your dialog persist between sessions.

Complex Documents

For more complex applications, or if you prefer an object-oriented approach, you can create a class that inherits from renoise.Document.DocumentNode and register properties in its constructor.

You could rewrite the document creation from the example above like this:

---@class RandomizerToolPreferences : renoise.Document.DocumentNode
---@field randomize_bpm renoise.Document.ObservableBoolean
---@field randomize_tracks renoise.Document.ObservableBoolean
---@field max_tracks renoise.Document.ObservableNumber
class "RandomizerToolPreferences" (renoise.Document.DocumentNode)

function RandomizerToolPreferences:__init()
  renoise.Document.DocumentNode.__init(self)
  -- Register observable properties which will make up our Document
  self:add_property("randomize_bpm", true)
  self:add_property("randomize_tracks", false)
  self:add_property("max_tracks", 16)
end

---@type RandomizerToolPreferences
local options = RandomizerToolPreferences()

renoise.tool().preferences = options

This approach allows you to build more structured and complex preference documents. See the complete Document API for more details on what you can store and how to manage it.

File IO & Bits

The Renoise API uses Lua's standard io library to read or write external files.

To access the raw bits and bytes of some data, for example, to read or write binary file streams, you can use the bit library. It's built into the Renoise API, so there's no need to require it.

See the LuaJIT bit library documentation for more info and examples.

-- Reading integer numbers or raw bytes from a file

local function read_word(file)
  local bytes = file:read(2)
  if (not bytes or #bytes < 2) then 
    return nil 
  else
    -- little-endian
    return bit.bor(bytes:byte(1),
      bit.lshift(bytes:byte(2), 8))
  end
end

local function read_dword(file)
  local bytes = file:read(4)
  if (not bytes or #bytes < 4) then 
    return nil 
  else
    -- little-endian
    return bit.bor(bytes:byte(1),
      bit.lshift(bytes:byte(2), 8),
      bit.lshift(bytes:byte(3), 16),
      bit.lshift(bytes:byte(4), 24))  
  end   
end

-- and so on (adapt as needed to deal with endianness!) ...

local file, err = io.open("some_binary_file.bin", "rb")
if not file then
  print("Could not open file: " .. tostring(err))
  return
end

local bytes = file:read(512)

if (not bytes or #bytes < 512) then 
  print("unexpected end of file")
else
  for i = 1, #bytes do
    print(bytes:byte(i))
  end
end
    
print(read_word(file) or "unexpected end of file")
print(read_dword(file) or "unexpected end of file")

file:close()

Sockets

The Renoise API allows you to create network sockets. This can be used to communicate with other devices and applications via UDP and TCP, for example, to send or receive OSC messages.

See the renoise.Socket API for more details.

HTTP GET Client

This example creates a TCP socket, connects to a web server, and sends a simple HTTP GET request.

-- Connection will give up after 2 seconds
local connection_timeout = 2000

local client, socket_error = renoise.Socket.create_client(
  "www.renoise.com", 80, renoise.Socket.PROTOCOL_TCP, connection_timeout)
   
if socket_error then 
  renoise.app():show_warning(socket_error)
  return
end

-- Request the root document
local succeeded, socket_error = 
  client:send("GET / HTTP/1.0\r\nHost: www.renoise.com\r\n\r\n")

if (socket_error) then 
  renoise.app():show_warning(socket_error)
  return
end

-- Loop until we get no more data from the server.
-- Note: A robust implementation should parse the HTTP header
-- and use the "Content-Length" to determine when to stop.
local receive_succeeded = false
local receive_content = ""

while (true) do
  -- Timeout for receiving data is 500ms
  local receive_timeout = 500
  
  local message, socket_error = 
    client:receive("*line", receive_timeout)
    
  if (message) then 
    receive_content = receive_content .. message .. "\n"
  else
    if (socket_error == "timeout" or 
        socket_error == "disconnected") 
    then
      -- Could retry on timeout, but we'll just stop in this example.
      receive_succeeded = true
      break
    else
      renoise.app():show_warning(
        "'socket receive' failed with the error: " .. socket_error)
      break
    end
  end
end
  
-- Close the connection if it was not already closed by the server
if (client and client.is_open) then
  client:close()
end

-- Show what we've got
if (receive_succeeded and #receive_content > 0) then
  renoise.app():show_prompt(
    "HTTP GET Response", 
    receive_content, 
    {"OK"}
  )
else
  renoise.app():show_prompt(
    "HTTP GET Response", 
    "Socket receive timeout or no content.", 
    {"OK"}
  ) 
end

Echo UDP Server (using a table as notifier)

local server, socket_error = renoise.Socket.create_server(
  "localhost", 1025, renoise.Socket.PROTOCOL_UDP)
   
if socket_error then 
  renoise.app():show_warning(
     "Failed to start the echo server: " .. socket_error)
else
  server:run {
    ---@param socket_error string
    socket_error = function(socket_error)
      renoise.app():show_warning(socket_error)
    end,
    
    ---@param socket renoise.Socket.SocketClient
    socket_accepted = function(socket)
      print(("client %s:%d connected"):format(
        socket.peer_address, socket.peer_port))
    end,
  
    ---@param socket renoise.Socket.SocketClient
    ---@param message string
    socket_message = function(socket, message)
      print(("client %s:%d sent '%s'"):format(
        socket.peer_address, socket.peer_port,  message))
      -- Simply send the message back      
      socket:send(message)
    end    
  }
end
-- This server will run and echo messages as long as the script is active.

Echo TCP Server (using a class as notifier)

This example allows any address to connect by not specifying an address in create_server.

class "EchoServer"
  function EchoServer:__init(port)
    -- Create a server socket
    local server, socket_error = renoise.Socket.create_server(
      "localhost", port, renoise.Socket.PROTOCOL_TCP)
     
    if socket_error then 
      renoise.app():show_warning(
        "Failed to start the echo server: " .. socket_error)
    else
      -- Start running
      self.server = server
      self.server:run(self)
    end
  end

  ---@param socket_error string
  function EchoServer:socket_error(socket_error)
    renoise.app():show_warning(socket_error)
  end
  
  ---@param socket renoise.Socket.SocketClient
  function EchoServer:socket_accepted(socket)
    print(("client %s:%d connected"):format(
      socket.peer_address, socket.peer_port))
  end

  ---@param message string
  ---@param socket renoise.Socket.SocketClient
  function EchoServer:socket_message(socket, message)
    print(("client %s:%d sent '%s'"):format(
      socket.peer_address, socket.peer_port,  message))
    -- Simply send the message back      
    socket:send(message)
  end
  
-- Create and run the echo server on port 1025
local echo_server = EchoServer(1025)

-- The server will run as long as the script is active or the
-- echo_server object is garbage collected.

MIDI

The Renoise API allows you to access raw MIDI input and output devices from within your tool. You can use this to add features like bi-directional MIDI controller support.

See the renoise.Midi API for more details.

MIDI Input Listener (Function Callback)

-- NOTE: The MIDI device will be closed when this local variable gets garbage
-- collected. Make it global or assign it to a table that is held globally
-- to keep it active.
local midi_device = nil

local inputs = renoise.Midi.available_input_devices()
if not table.is_empty(inputs) then
  -- Use the first available device in this example
  local device_name = inputs[1]
  
  local function midi_callback(message)
    assert(#message == 3)
    assert(message[1] >= 0 and message[1] <= 0xff)
    assert(message[2] >= 0 and message[2] <= 0xff)    
    assert(message[3] >= 0 and message[3] <= 0xff)
    
    print(("%s: got MIDI %X %X %X"):format(device_name, 
      message[1], message[2], message[3]))
  end

  -- The sysex callback is an optional second argument.
  midi_device = renoise.Midi.create_input_device(
    device_name, midi_callback)
  
  -- To stop listening, call: midi_device:close()
end

MIDI Input and SysEx Listener (Class Callbacks)

class "MidiDumper"
  function MidiDumper:__init(device_name)
    self.device_name = device_name
    self.device = nil
  end
  
  function MidiDumper:start()
    self.device = renoise.Midi.create_input_device(
      self.device_name, 
      { self, self.midi_callback }, 
      { self, self.sysex_callback }
    )
  end
  
  function MidiDumper:stop()
    if self.device then 
      self.device:close()
      self.device = nil
    end
  end
  
  function MidiDumper:midi_callback(message)
    print(("%s: MidiDumper got MIDI %X %X %X"):format(
      self.device_name, message[1], message[2], message[3]))
  end

  function MidiDumper:sysex_callback(message)
    print(("%s: MidiDumper got SYSEX with %d bytes"):format(
      self.device_name, #message))
  end
  
-- NOTE: The MIDI device will be closed when this dumper object gets garbage
-- collected. Make it global or assign it to a table that is held globally
-- to keep it active.
local midi_dumper = nil
  
local inputs = renoise.Midi.available_input_devices()

if not table.is_empty(inputs) then
  -- Use the first available device in this example
  local device_name = inputs[1]

  midi_dumper = MidiDumper(device_name)
  -- This will dump MIDI messages until midi_dumper:stop() is called
  -- or the MidiDumper object is garbage collected.
  midi_dumper:start()  
end

MIDI Output

local outputs = renoise.Midi.available_output_devices()
if not table.is_empty(outputs) then
  local device_name = outputs[1]
  local midi_device = renoise.Midi.create_output_device(device_name)
  
  -- Note On
  midi_device:send({ 0x90, 0x10, 0x7F })
  -- SysEx (MMC Start)
  midi_device:send({ 0xF0, 0x7F, 0x00, 0x06, 0x02, 0xF7 })
 
  -- We no longer need the device in this example, so close it.
  midi_device:close()  
end

OSC

The Renoise API allows you to create sockets and provides tools to send and receive Open Sound Control (OSC) data. This enables you to connect your tools to other OSC servers and clients, offering an alternative to MIDI for controlling and interacting with devices like a monome.

See the renoise.Osc and renoise.Socket APIs for more details.

OSC Server (Receiving OSC)

This example creates a UDP server that listens for OSC messages on port 8008.

-- Create some shortcuts
local OscMessage = renoise.Osc.Message
local OscBundle = renoise.Osc.Bundle

-- Open a socket connection to listen for messages
local server, socket_error = renoise.Socket.create_server(
  "localhost", 8008, renoise.Socket.PROTOCOL_UDP)
   
if (socket_error) then 
  renoise.app():show_warning(("Failed to start the " .. 
    "OSC server. Error: '%s'"):format(socket_error))
  return
end

server:run {
  socket_message = function(socket, data)
    -- Decode the binary data to an OSC message or bundle
    local message_or_bundle, osc_error = renoise.Osc.from_binary_data(data)
    
    -- Show what we've got
    if (message_or_bundle) then
      if (type(message_or_bundle) == "Message") then
        print(("Got OSC message: '%s'"):format(tostring(message_or_bundle)))

      elseif (type(message_or_bundle) == "Bundle") then
        print(("Got OSC bundle: '%s'"):format(tostring(message_or_bundle)))
      end
      
      -- Send a reply back to the client
      local reply_message = OscMessage("/renoise/reply", {
        { tag = "s", value = "Thank you for the message!" }
      })
      socket:send(reply_message:to_binary_data())
      
    else
      print(("Got invalid OSC data, or data which is not " .. 
        "OSC data at all. Error: '%s'"):format(osc_error))
    end
  end    
}

-- To shut down the server at any time, call:
-- server:close()

OSC Client (Sending OSC)

This example creates a UDP client to send OSC messages to a server on port 8008.

-- Create some shortcuts
local OscMessage = renoise.Osc.Message
local OscBundle = renoise.Osc.Bundle

-- Create a client to send messages to the server
local client, socket_error = renoise.Socket.create_client(
  "localhost", 8008, renoise.Socket.PROTOCOL_UDP)
   
if (socket_error) then 
  renoise.app():show_warning(("Failed to start the " .. 
    "OSC client. Error: '%s'"):format(socket_error))
  return
end

-- Construct and send a simple message
client:send(
  OscMessage("/transport/start"):to_binary_data()
)

-- Construct and send a message with arguments
client:send(
  OscMessage("/transport/bpm", { 
    { tag = "f", value = 127.5 } 
  }):to_binary_data()
)

-- Construct and send a bundle of messages
local message1 = OscMessage("/some/message")
local message2 = OscMessage("/another/one", { 
  { tag = "b", value = "with some blob data" },
  { tag = "s", value = "and a string" } 
})

client:send(
  OscBundle(os.clock(), { message1, message2 }):to_binary_data()
)

-- Close the client when done
client:close()

SQLite Databases

The Renoise API allows you to create or load SQLite databases. This can be used to either efficiently deal with large data blobs within your tools or to read existing database files from other applications.

See renoise.SQLite for more info.

A quick example on how to open and read from an existing database file:

-- create a new database (rwc = read/write/create)
local db, status, error = renoise.SQLite.open("./some_test.db", "rwc")
-- NB: use renoise.SQLite.open() to create a in-memory db instead
print("Create:", db.is_open, db.error_code, db.error_message)

local sql = [[
  CREATE TABLE numbers(num1,num2,str);
  INSERT INTO numbers VALUES(1,11,"ABC");
  INSERT INTO numbers VALUES(2,22,"DEF");
  INSERT INTO numbers VALUES(3,33,"UVW");
  INSERT INTO numbers VALUES(4,44,"XYZ");
]]

print("Exec:", db:execute(sql))
print("Changes:", db.changes, db.total_changes, db.error_message)

-- read from an existing db using a prepared statement
local db, status, error = renoise.SQLite.open("./test.db", "ro") -- read-only
print("Open:", db.is_open, db.error_code, db.error_message)

local stm = db:prepare("SELECT * from numbers")
print("Read:", stm.columns, stm.unames)

for k in stm:rows() do
 rprint(k) 
end

Renoise Lua API Overview

The API files in this documentation folder will list all available Lua functions and classes that can be accessed from scripts in Renoise. If you are familiar with Renoise, the names of the classes, functions and properties should be self explanitory.

A note about the general API design:

• Whatever you do with the API, you should never be able to fatally crash Renoise. If you manage to do this, then please file a bug report in our forums so we can fix it. All errors, as stupid they might be, should always result in a clean error message from Lua.

• The Renoise Lua API also allows global File IO and external program execution (via os.execute()) which can obviously be hazardous. Please be careful with these, as you would with programming in general...

Some notes about the documentation, and a couple of tips:

• All classes, functions in the API, are nested in the namespace (Lua table) renoise. E.g: to get the application object, you will have to type renoise.app()

• The API is object-oriented, and thus split into classes. The references will first note the class name (e.g. renoise.Application), then list its Constants, Properties, Functions and Operators. All properties and functions are always listed with their full path to make it clear where they belong and how to access them.

• Nearly all functions are actually methods, so you have to invoke them via the colon operator : E.g. renoise.app():show_status("Status Message") If you're new to Lua, this takes a while to get used to. Don't worry, it'll make sense sooner or later. ;)

• Properties are syntactic sugar for get/set functions. song().comments will invoke a function which returns comments. But not all properties have setters, and thus can only be used as read-only getters. Those are marked as **READ-ONLY**.

• All exposed objects are read-only (you can not add new fields, properties). In contrast, the classes are not. This means you can extend the API classes with your own helper functions, if needed, but can not add new properties to objects. Objects, like for example the result of song(), are read-only to make it easier to catch typos. song().transport.bmp = 80 will fire an error, because there is no such property 'bmp.' You probably meant song().transport.bpm = 80 here. If you need to store data somewhere, do it in your own tables, objects instead of using the Renoise API objects.

• some_property, _observable means, that there is also an observer object available for the property. An observable object allows you to attach notifiers (global functions or methods) that will be called as soon as a value has changed. Please see Renoise.Document.API for more info about observables and related classes.

A small example using bpm:

renoise.song().transport.bpm_observable:add_notifier(function()
  print("bpm changed")
end)

-- will print "bpm changed", but only if the bpm was not 120 before
renoise.song().transport.bpm = 120

The above notifier is called when anything changes the bpm, including your script, other scripts, or anything else in Renoise (you've automated the BPM in the song, entered a new BPM value in Renoise's GUI, whatever...)

Lists like renoise.song().tracks[] can also have notifiers. But these will only fire when the list layout has changed: an element was added, removed or elements in the list changed their order. They will not fire when the list values changed. Attach notifiers to the list elements to get such notifications.

• Can't remember what the name of function XYZ was? In the scripting terminal you can list all methods/properties of API objects (or your own class objects) via the global function oprint(some_object) - e.g. oprint(renoise.song()). To dump the renoise module/class layout, use rprint(renoise).

renoise

Holds all renoise related API functions and classes.

• Constants
  • API_VERSION : number
  • RENOISE_VERSION : string
• Functions
  • ViewBuilder()
  • app()
  • song()
  • tool()

Constants

API_VERSION : number

Currently 6.2. Any changes in the API which are not backwards compatible, will increase the internal API's major version number (e.g. from 1.4 -> 2.0). All other backwards compatible changes, like new functionality, new functions and classes which do not break existing scripts, will increase only the minor version number (e.g. 1.0 -> 1.1).

RENOISE_VERSION : string

Renoise Version "Major.Minor.Revision[AlphaBetaRcVersion][Demo]"

Functions

ViewBuilder()

->renoise.ViewBuilder

Construct a new viewbuilder instance you can use to create views.

app()

->renoise.Application

Global access to the Renoise Application.

song()

->renoise.Song?

Global access to the Renoise Song.

NB: The song instance changes when a new song is loaded or created in Renoise, so tools can not memorize the song instance globally once, but must instead react on the application's new_document_observable observable.

tool()

->renoise.ScriptingTool

Global access to the Renoise Scripting Tool (your XRNX tool).

This is only valid when getting called from a tool and not when e.g. using the scripting terminal and editor in Renoise.

renoise.Application

The Renoise application.

• Properties
  • log_filename : string
  • current_song : renoise.Song
  • recently_loaded_song_files : string[]
  • recently_saved_song_files : string[]
  • installed_tools : table<string, string>
  • installed_tools_observable : renoise.Document.Observable
  • audio_plugin_effects_observable : renoise.Document.Observable
  • audio_plugin_instruments_observable : renoise.Document.Observable
  • key_modifier_states : table<string, string>
  • key_modifier_flags : ModifierFlags
  • window : renoise.ApplicationWindow
  • theme : renoise.ApplicationTheme
  • theme_observable : renoise.Document.Observable
  • active_clipboard_index : 1 | 2 | 3 | 4
• Functions
  • show_message(self, message : string)
  • show_error(self, message : string)
  • show_warning(self, message : string)
  • show_status(self, message : string)
  • show_prompt(self, title : string, message : string, button_labels : string[]?)
  • show_custom_prompt(self, title : string, content_view : renoise.Views.View, button_labels : string[], key_handler : KeyHandler``?, key_handler_options : KeyHandlerOptions``?, focus_handler : FocusHandler``?)
  • show_custom_dialog(self, title : DialogTitle, content_view : renoise.Views.View, key_handler : KeyHandler``?, key_handler_options : KeyHandlerOptions``?, focus_handler : FocusHandler``?)
  • show_menu(self, dialog : renoise.Dialog, menu_entries : DialogMenuEntry[], below_view : renoise.Views.View``?)
  • prompt_for_path(self, title : DialogTitle)
  • prompt_for_filename_to_read(self, file_extensions : string[], title : DialogTitle)
  • prompt_for_multiple_filenames_to_read(self, file_extensions : string[], title : DialogTitle)
  • prompt_for_filename_to_write(self, file_extension : string, title : DialogTitle)
  • open_url(self, url : string)
  • open_path(self, file_path : string)
  • install_tool(self, file_path : string)
  • uninstall_tool(self, file_path : string)
  • new_song(self)
  • new_song_no_template(self)
  • load_song(self, filename : string)
  • load_track_device_chain(self, filename : string)
  • load_track_device_preset(self, filename : string)
  • load_instrument(self, filename : string)
  • load_instrument_multi_sample(self, filename : string)
  • load_instrument_device_chain(self, filename : string)
  • load_instrument_device_preset(self, filename : string)
  • load_instrument_modulation_set(self, filename : string)
  • load_instrument_phrase(self, filename : string)
  • load_instrument_sample(self, filename : string)
  • load_theme(self, filename : string)
  • save_song(self)
  • save_song_as(self, filename : string)
  • save_track_device_chain(self, filename : string)
  • save_instrument(self, filename : string)
  • save_instrument_multi_sample(self, filename : string)
  • save_instrument_device_chain(self, filename : string)
  • save_instrument_modulation_set(self, filename : string)
  • save_instrument_phrase(self, filename : string)
  • save_instrument_sample(self, filename : string)
  • save_theme(self, filename : string)
• Structs
• DialogMenuEntry
  • Properties
    • name : string
    • invoke : fun()
    • active : boolean``?
    • selected : boolean``?
• KeyEvent
  • Properties
    • name : string
    • modifiers : ModifierStates
    • modifier_flags : ModifierFlags
    • character : string``?
    • note : integer``?
    • state : "pressed" | "released"
    • repeated : boolean``?
  • Aliases
    • ModifierFlags
    • ModifierStates
• KeyHandlerOptions
  • Properties
    • send_key_repeat : boolean``?
    • send_key_release : boolean``?
  • Aliases
    • DialogTitle
    • FocusHandler
    • KeyHandler
    • ModifierFlags
    • ModifierStates

Properties

log_filename : string

READ-ONLY Access to the application's full log filename and path. Will already be opened for writing, but you nevertheless should be able to read from it.

current_song : renoise.Song

READ-ONLY Get the apps main document, the song. The global "renoise.song()" function is, in fact, a shortcut to this property.

recently_loaded_song_files : string[]

READ-ONLY List of recently loaded song files.

recently_saved_song_files : string[]

READ-ONLY List of recently saved song files.

installed_tools : table<string, string>

READ-ONLY Returns information about all currently installed tools.

installed_tools_observable : renoise.Document.Observable

Fired when the list of installed tools changed.

audio_plugin_effects_observable : renoise.Document.Observable

Fired when the list of available audio plugin effects changed, for example when scanning for new plugins in the preferences. Use the component's available_plugins or available_devices properties to access currently available devices which are supported by the component such as the track device chains.

audio_plugin_instruments_observable : renoise.Document.Observable

Fired when the list of available audio plugin instruments changed, for example when scanning for new plugins in the preferences.

key_modifier_states : table<string, string>

Deprecated. READ-ONLY Use key_modifier_flags instead

key_modifier_flags : ModifierFlags

READ-ONLY Access keyboard modifier states.

window : renoise.ApplicationWindow

READ-ONLY Access to the application's window.

theme : renoise.ApplicationTheme

READ-ONLY Access to the application's color theme.

theme_observable : renoise.Document.Observable

Fired, when any theme color changed. e.g. when a new theme got loaded or when theme colors got edited in the theme preferences.

active_clipboard_index : 1 | 2 | 3 | 4

Range: (1 - 4) Get or set globally used clipboard "slots" in the application.

Functions

show_message(self, message : string)

Shows an info message dialog to the user.

show_error(self, message : string)

Shows an error dialog to the user.

show_warning(self, message : string)

Shows a warning dialog to the user.

show_status(self, message : string)

Shows a message in Renoise's status bar to the user.

show_prompt(self, title : string, message : string, button_labels : string[]?)

->label : string

Opens a modal dialog with a title, text and custom button labels. Returns the pressed button label or an empty string when canceled.

show_custom_prompt(self, title : string, content_view : renoise.Views.View, button_labels : string[], key_handler : KeyHandler?, key_handler_options : KeyHandlerOptions?, focus_handler : FocusHandler?)

->label : string

Opens a modal dialog with a title, custom content and custom button labels. See: renoise.ViewBuilder for more info about custom views.

show_custom_dialog(self, title : DialogTitle, content_view : renoise.Views.View, key_handler : KeyHandler?, key_handler_options : KeyHandlerOptions?, focus_handler : FocusHandler?)

->renoise.Dialog

Shows a non modal dialog (a floating tool window) with custom content. When no key_handler is provided, the Escape key is used to close the dialog. See: renoise.ViewBuilder for more info about custom views.

show_menu(self, dialog : renoise.Dialog, menu_entries : DialogMenuEntry[], below_view : renoise.Views.View?)

Shows a custom context menu on top of the given dialog.

When specifying a view, the menu will be shown below the given view instance. The view instance must be part of the dialog that shows the menu and must be visible. By default the menu will be shown at the current mouse cursor position.

prompt_for_path(self, title : DialogTitle)

->path : string

Opens a modal dialog to query an existing directory from the user.

prompt_for_filename_to_read(self, file_extensions : string[], title : DialogTitle)

->path : string

Opens a modal dialog to query a filename and path to read from a file.

prompt_for_multiple_filenames_to_read(self, file_extensions : string[], title : DialogTitle)

->paths : string[]

Same as 'prompt_for_filename_to_read' but allows the user to select more than one file.

prompt_for_filename_to_write(self, file_extension : string, title : DialogTitle)

->path : string

Open a modal dialog to get a filename and path for writing. When an existing file is selected, the dialog will ask whether or not to overwrite it, so you don't have to take care of this on your own.

open_url(self, url : string)

Opens the default internet browser with the given URL. The URL can also be a file that browsers can open (like xml, html files...).

open_path(self, file_path : string)

Opens the default file browser (explorer, finder...) with the given path.

install_tool(self, file_path : string)

Install order update a tool. Any errors are shown to the user during installation. Installing an already existing tool will upgrade the tool without confirmation. Upgraded tools will automatically be re-enabled, if necessary.

uninstall_tool(self, file_path : string)

Uninstall an existing tool. Any errors are shown to the user during uninstallation.

new_song(self)

Create a new song document (will ask the user to save changes if needed). The song is not created immediately, but soon after the call was made and the user did not aborted the operation. In order to continue execution with the new song, attach a notifier to 'renoise.app().new_document_observable' See: renoise.ScriptingTool for more info.

new_song_no_template(self)

Create a new song document, avoiding template XRNS songs (when present) to be loaded. The song is not created immediately, but soon after the call was made and the user did not aborted the operation. In order to continue execution with the new song, attach a notifier to 'renoise.app().new_document_observable' See: renoise.ScriptingTool for more info.

load_song(self, filename : string)

Load a new song document from the given filename (will ask to save changes if needed, any errors are shown to the user). Just like new_song(), the song is not loaded immediately, but soon after the call was made. See 'renoise.app():new_song()' for details.

load_track_device_chain(self, filename : string)

->success : boolean

Load a track device chains into the currently selected track. Any errors during the export are shown to the user.

load_track_device_preset(self, filename : string)

->success : boolean

Load a track device devices into the currently selected track. When no device is selected a new device will be created. Any errors during the export are shown to the user.

load_instrument(self, filename : string)

->success : boolean

Load an instrument into the currently selected instrument. Any errors during the export are shown to the user.

load_instrument_multi_sample(self, filename : string)

->success : boolean

Load an instrument multi sample into the currently selected instrument. Any errors during the export are shown to the user.

load_instrument_device_chain(self, filename : string)

->success : boolean

Load an instrument device chain into the currently selected instrument's device chain. When no device chain is selected, a new one will be created. Any errors during the export are shown to the user.

load_instrument_device_preset(self, filename : string)

->success : boolean

Load an instrument device into the currently selected instrument's device chain's device. When no device is selected, a new one will be created. Any errors during the export are shown to the user.

load_instrument_modulation_set(self, filename : string)

->success : boolean

Load an instrument modulation chain into the currently selected instrument's modulation chain. When no device is selected, a new one will be created. Any errors during the export are shown to the user.

load_instrument_phrase(self, filename : string)

->success : boolean

Load an instrument phrase into the currently selected instrument's phrases. When no phrase is selected, a new one will be created. Any errors during the export are shown to the user.

load_instrument_sample(self, filename : string)

->success : boolean

Load an instrument sample into the currently selected instrument's sample lists. When no sample is selected, a new one will be created. Any errors during the export are shown to the user.

load_theme(self, filename : string)

->success : boolean

Load a new theme file and apply it. Any errors during the export are shown to the user.

save_song(self)

Quicksave or save the current song under a new name. Any errors during the export are shown to the user.

save_song_as(self, filename : string)

Save the current song under a new name. Any errors during the export are shown to the user.

save_track_device_chain(self, filename : string)

->success : boolean

Save a currently selected track device chain to a file with the given name. When no device chain is selected an error is raised. returns success.

save_instrument(self, filename : string)

->success : boolean

Save a currently selected instrument to a file with the given name. When no instruemnt is selected an error is raised. returns success.

save_instrument_multi_sample(self, filename : string)

->success : boolean

Save a currently selected instrument multi sample file to a file with the given name. When no instrument is selected an error is raised. returns success.

save_instrument_device_chain(self, filename : string)

->success : boolean

Save a currently selected instrument's device chain to a file with the given name. When no chain is selected an error is raised. returns success.

save_instrument_modulation_set(self, filename : string)

->success : boolean

Save a currently selected instrument's modulation set to a file with the given name. When no modulation is selected an error is raised. returns success.

save_instrument_phrase(self, filename : string)

->success : boolean

Save a currently selected instrument's phrase to a file with the given name. When no phrase is selected an error is raised. returns success.

save_instrument_sample(self, filename : string)

->success : boolean

Save a currently selected instrument's sample to a file with the given name. When no sample is selected an error is raised. returns success.

save_theme(self, filename : string)

->success : boolean

Save a current theme to a file with the given name. returns success.

Structs

DialogMenuEntry

Defines a custom menu entry, shown in custom dialog windows.

Separating entries: To divide entries into groups prepend one or more dashes to the name:

---First Group Item
Regular item

To create sub menus, define entries with a common path, using a colon as separator:

Main Menu Item
Sub Menu:Sub Menu Item 1
Sub Menu:Sub Menu Item 2

To insert a script menu entry into an existing context menu, see ToolMenuEntry.

Properties

name : string

Name and optional path of the menu entry

invoke : fun()

A function that is called as soon as the entry is clicked

active : boolean?

Default: true. When false, the action will not be invoked and will be "greyed out".

selected : boolean?

Default: false. When true, the entry will be marked as "this is a selected option"

KeyEvent

Properties

name : string

name of the key, like 'esc' or 'a'

modifiers : ModifierStates

Deprecated. Use modifier_flags instead READ-ONLY the held down modifiers as a string

modifier_flags : ModifierFlags

READ-ONLY the held down modifiers as flags

character : string?

possible character representation of the key

note : integer?

virtual keyboard piano key value (starting from 0)

state : "pressed" | "released"

only present if send_key_release was set to true

repeated : boolean?

only present if send_key_repeat was set to true

Aliases

ModifierFlags

{ alt : boolean, control : boolean, meta : boolean, shift : boolean }

The currently pressed/release key's modifiers as platform independent flags. On macOS "control" is their "Command" key and the "meta" keyboard is the "Control" key. On Windows the "meta" key is the "Windows" key and on Linux the "Super" key.

ModifierStates

string

Deprecated. Use ModifierFlags instead.

The modifier keys will be provided as a string. Possible keys are dependent on the platform

• Windows : "shift", "alt", "control", "winkey"
• Linux : "shift", "alt", "control", "meta"
• Mac : "shift", "option", "control", "command". If multiple modifiers are held down, the string will be formatted as " + " Their order will correspond to the following precedence shift + alt/option + control + winkey/meta/command If no modifier is pressed, this will be an empty string.

KeyHandlerOptions

Properties

send_key_repeat : boolean?

Default: true

send_key_release : boolean?

Default: false

Aliases

DialogTitle

string

The title that shows up at the title-bar of the dialog.

FocusHandler

(dialogs : renoise.Dialog, focused : boolean) -> KeyEvent?

Optional focus change notifier for a custom dialog. Will be called when the dialog gains of loses key focus. You maybe want to initialize your dloag's (modifier) keyboard states here.

KeyHandler

(dialog : renoise.Dialog, key_event : KeyEvent) -> KeyEvent?

Optional keyhandler to process key events on a custom dialog. When returning the passed key from the key-handler function, the key will be passed back to Renoise's key event chain, in order to allow processing global Renoise key-bindings from your dialog. This will not work for modal dialogs. This also only applies to global shortcuts in Renoise, because your dialog will steal the focus from all other Renoise views such as the Pattern Editor, etc.

ModifierFlags

{ alt : boolean, control : boolean, meta : boolean, shift : boolean }

The currently pressed/release key's modifiers as platform independent flags. On macOS "control" is their "Command" key and the "meta" keyboard is the "Control" key. On Windows the "meta" key is the "Windows" key and on Linux the "Super" key.

ModifierStates

string

Deprecated. Use ModifierFlags instead.

The modifier keys will be provided as a string. Possible keys are dependent on the platform

• Windows : "shift", "alt", "control", "winkey"
• Linux : "shift", "alt", "control", "meta"
• Mac : "shift", "option", "control", "command". If multiple modifiers are held down, the string will be formatted as " + " Their order will correspond to the following precedence shift + alt/option + control + winkey/meta/command If no modifier is pressed, this will be an empty string.

renoise.ApplicationTheme

Application's theme colors and other general color theme properties.

Note: All properties and functions of the app theme are read-only, so the theme can't be modified here. Use the app's renoise.Application:load_theme function to load and apply new themes instead.

Accessing colors and theme properties can be useful in custom viewbuilder widgets.

• Properties
  • colors : { [ThemeColor]: RGBColor }
  • knob_shade : number
  • knob_shade_observable : renoise.Document.Observable
  • body_shade : number
  • body_shade_observable : renoise.Document.Observable
  • contrast : number
  • contrast_observable : renoise.Document.Observable
  • texture_set : string
  • texture_set_observable : renoise.Document.Observable
• Functions
  • color(self, color_name : ThemeColor)
• Aliases
  • RGBColor
  • ThemeColor

Properties

colors : { [ThemeColor]: RGBColor }

READ-ONLY Get all theme colors in a flat list of RGBColors. Color table keys are string identifiers as used in the theme XML file, but in lower case.

Note that if you only need to access a single color from the theme, use renoise.app().theme.color(color_name) instead.

To get notified of color changes, use renoise.app().theme_observable

knob_shade : number

READ-ONLY Get theme's knob shade setting. Range: (1 - 2)

knob_shade_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

body_shade : number

READ-ONLY Get theme's body shade setting. Range: (1 - 2)

body_shade_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

contrast : number

READ-ONLY Get theme's contrast setting. Range: (-0.5 - 0.5)

contrast_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

texture_set : string

READ-ONLY Get theme's texture set name

texture_set_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

Functions

color(self, color_name : ThemeColor)

->RGBColor

Get a single color from the theme using a color identifier as used in the theme XML file - but in lower case.

e.g. to access the button background color from the theme, use renoise.app().theme.color("button_back")

To get notified of color changes, use renoise.app().theme_observable

-- The application theme's colors
color_name:
    | "main_back"
    | "main_font"
    | "alternate_main_back"
    | "alternate_main_font"
    | "body_back"
    | "body_font"
    | "strong_body_font"
    | "button_back"
    | "button_font"
    | "button_highlight_font"
    | "selected_button_back"
    | "selected_button_font"
    | "selection_back"
    | "selection_font"
    | "standby_selection_back"
    | "standby_selection_font"
    | "midi_mapping_back"
    | "midi_mapping_font"
    | "tooltip_back"
    | "tooltip_font"
    | "valuebox_back"
    | "valuebox_font"
    | "valuebox_font_icons"
    | "scrollbar"
    | "slider"
    | "folder"
    | "pattern_default_back"
    | "pattern_default_font"
    | "pattern_default_font_volume"
    | "pattern_default_font_panning"
    | "pattern_default_font_pitch"
    | "pattern_default_font_delay"
    | "pattern_default_font_global"
    | "pattern_default_font_other"
    | "pattern_default_font_dspfx"
    | "pattern_default_font_unused"
    | "pattern_highlighted_back"
    | "pattern_highlighted_font"
    | "pattern_highlighted_font_volume"
    | "pattern_highlighted_font_panning"
    | "pattern_highlighted_font_pitch"
    | "pattern_highlighted_font_delay"
    | "pattern_highlighted_font_global"
    | "pattern_highlighted_font_other"
    | "pattern_highlighted_font_dspfx"
    | "pattern_highlighted_font_unused"
    | "pattern_playposition_back"
    | "pattern_playposition_font"
    | "pattern_centerbar_back"
    | "pattern_centerbar_font"
    | "pattern_centerbar_back_standby"
    | "pattern_centerbar_font_standby"
    | "pattern_selection"
    | "pattern_standby_selection"
    | "pattern_mute_state"
    | "automation_grid"
    | "automation_line_edge"
    | "automation_line_fill"
    | "automation_point"
    | "automation_marker_play"
    | "automation_marker_single"
    | "automation_marker_pair"
    | "automation_marker_diamond"
    | "vumeter_meter"
    | "vumeter_meter_low"
    | "vumeter_meter_middle"
    | "vumeter_meter_high"
    | "vumeter_peak"
    | "vumeter_back_normal"
    | "vumeter_back_clipped"
    | "default_color_01"
    | "default_color_02"
    | "default_color_03"
    | "default_color_04"
    | "default_color_05"
    | "default_color_06"
    | "default_color_07"
    | "default_color_08"
    | "default_color_09"
    | "default_color_10"
    | "default_color_11"
    | "default_color_12"
    | "default_color_13"
    | "default_color_14"
    | "default_color_15"
    | "default_color_16"

Aliases

RGBColor

{ 1 : integer, 2 : integer, 3 : integer }

A table of 3 bytes (ranging from 0 to 255) representing the red, green and blue channels of a color. {0xFF, 0xFF, 0xFF} is white {165, 73, 35} is the red from the Renoise logo

ThemeColor

"alternate_main_back" | "alternate_main_font" | "automation_grid" | "automation_line_edge" | "automation_line_fill" | "automation_marker_diamond" | "automation_marker_pair" | "automation_marker_play" | "automation_marker_single" | "automation_point" | "body_back" | "body_font" | "button_back" | "button_font" | "button_highlight_font" | "default_color_01" | "default_color_02" | "default_color_03" | "default_color_04" | "default_color_05" | "default_color_06" | "default_color_07" | "default_color_08" | "default_color_09" | "default_color_10" | "default_color_11" | "default_color_12" | "default_color_13" | "default_color_14" | "default_color_15" | "default_color_16" | "folder" | "main_back" | "main_font" | "midi_mapping_back" | "midi_mapping_font" | "pattern_centerbar_back" | "pattern_centerbar_back_standby" | "pattern_centerbar_font" | "pattern_centerbar_font_standby" | "pattern_default_back" | "pattern_default_font" | "pattern_default_font_delay" | "pattern_default_font_dspfx" | "pattern_default_font_global" | "pattern_default_font_other" | "pattern_default_font_panning" | "pattern_default_font_pitch" | "pattern_default_font_unused" | "pattern_default_font_volume" | "pattern_highlighted_back" | "pattern_highlighted_font" | "pattern_highlighted_font_delay" | "pattern_highlighted_font_dspfx" | "pattern_highlighted_font_global" | "pattern_highlighted_font_other" | "pattern_highlighted_font_panning" | "pattern_highlighted_font_pitch" | "pattern_highlighted_font_unused" | "pattern_highlighted_font_volume" | "pattern_mute_state" | "pattern_playposition_back" | "pattern_playposition_font" | "pattern_selection" | "pattern_standby_selection" | "scrollbar" | "selected_button_back" | "selected_button_font" | "selection_back" | "selection_font" | "slider" | "standby_selection_back" | "standby_selection_font" | "strong_body_font" | "tooltip_back" | "tooltip_font" | "valuebox_back" | "valuebox_font" | "valuebox_font_icons" | "vumeter_back_clipped" | "vumeter_back_normal" | "vumeter_meter" | "vumeter_meter_high" | "vumeter_meter_low" | "vumeter_meter_middle" | "vumeter_peak"

-- The application theme's colors
ThemeColor:
    | "main_back"
    | "main_font"
    | "alternate_main_back"
    | "alternate_main_font"
    | "body_back"
    | "body_font"
    | "strong_body_font"
    | "button_back"
    | "button_font"
    | "button_highlight_font"
    | "selected_button_back"
    | "selected_button_font"
    | "selection_back"
    | "selection_font"
    | "standby_selection_back"
    | "standby_selection_font"
    | "midi_mapping_back"
    | "midi_mapping_font"
    | "tooltip_back"
    | "tooltip_font"
    | "valuebox_back"
    | "valuebox_font"
    | "valuebox_font_icons"
    | "scrollbar"
    | "slider"
    | "folder"
    | "pattern_default_back"
    | "pattern_default_font"
    | "pattern_default_font_volume"
    | "pattern_default_font_panning"
    | "pattern_default_font_pitch"
    | "pattern_default_font_delay"
    | "pattern_default_font_global"
    | "pattern_default_font_other"
    | "pattern_default_font_dspfx"
    | "pattern_default_font_unused"
    | "pattern_highlighted_back"
    | "pattern_highlighted_font"
    | "pattern_highlighted_font_volume"
    | "pattern_highlighted_font_panning"
    | "pattern_highlighted_font_pitch"
    | "pattern_highlighted_font_delay"
    | "pattern_highlighted_font_global"
    | "pattern_highlighted_font_other"
    | "pattern_highlighted_font_dspfx"
    | "pattern_highlighted_font_unused"
    | "pattern_playposition_back"
    | "pattern_playposition_font"
    | "pattern_centerbar_back"
    | "pattern_centerbar_font"
    | "pattern_centerbar_back_standby"
    | "pattern_centerbar_font_standby"
    | "pattern_selection"
    | "pattern_standby_selection"
    | "pattern_mute_state"
    | "automation_grid"
    | "automation_line_edge"
    | "automation_line_fill"
    | "automation_point"
    | "automation_marker_play"
    | "automation_marker_single"
    | "automation_marker_pair"
    | "automation_marker_diamond"
    | "vumeter_meter"
    | "vumeter_meter_low"
    | "vumeter_meter_middle"
    | "vumeter_meter_high"
    | "vumeter_peak"
    | "vumeter_back_normal"
    | "vumeter_back_clipped"
    | "default_color_01"
    | "default_color_02"
    | "default_color_03"
    | "default_color_04"
    | "default_color_05"
    | "default_color_06"
    | "default_color_07"
    | "default_color_08"
    | "default_color_09"
    | "default_color_10"
    | "default_color_11"
    | "default_color_12"
    | "default_color_13"
    | "default_color_14"
    | "default_color_15"
    | "default_color_16"

renoise.ApplicationWindow

Application window and general UI properties of the Renoise app.

• Constants
  • UpperFrame
  • MiddleFrame
  • LowerFrame
  • DiskBrowserCategory
  • InstrumentBoxSlotSize
  • MixerFader
• Properties
  • fullscreen : boolean
  • is_maximized : boolean
  • is_minimized : boolean
  • lock_keyboard_focus : boolean
  • sample_record_dialog_is_visible : boolean
  • disk_browser_is_visible : boolean
  • disk_browser_is_visible_observable : renoise.Document.Observable
  • disk_browser_category : renoise.ApplicationWindow.DiskBrowserCategory
  • disk_browser_category_observable : renoise.Document.Observable
  • instrument_box_is_visible : boolean
  • instrument_box_is_visible_observable : renoise.Document.Observable
  • instrument_box_slot_size : renoise.ApplicationWindow.InstrumentBoxSlotSize
  • instrument_box_slot_size_observable : renoise.Document.Observable
  • instrument_editor_is_detached : boolean
  • instrument_editor_is_detached_observable : renoise.Document.Observable
  • instrument_properties_is_visible : boolean
  • instrument_properties_is_visible_observable : renoise.Document.Observable
  • instrument_properties_show_volume_transpose : boolean
  • instrument_properties_show_trigger_options : boolean
  • instrument_properties_show_scale_options : boolean
  • instrument_properties_show_plugin : boolean
  • instrument_properties_show_plugin_program : boolean
  • instrument_properties_show_midi : boolean
  • instrument_properties_show_midi_program : boolean
  • instrument_properties_show_macros : boolean
  • instrument_properties_show_phrases : boolean
  • sample_properties_is_visible : boolean
  • sample_properties_is_visible_observable : renoise.Document.Observable
  • mixer_view_is_detached : boolean
  • mixer_view_is_detached_observable : renoise.Document.Observable
  • upper_frame_is_visible : boolean
  • upper_frame_is_visible_observable : renoise.Document.Observable
  • active_upper_frame : renoise.ApplicationWindow.UpperFrame
  • active_upper_frame_observable : renoise.Document.Observable
  • active_middle_frame : renoise.ApplicationWindow.MiddleFrame
  • active_middle_frame_observable : renoise.Document.Observable
  • lower_frame_is_visible : boolean
  • lower_frame_is_visible_observable : renoise.Document.Observable
  • active_lower_frame : renoise.ApplicationWindow.LowerFrame
  • active_lower_frame_observable : renoise.Document.Observable
  • right_frame_is_visible : boolean
  • right_frame_is_visible_observable : renoise.Document.Observable
  • pattern_matrix_is_visible : boolean
  • pattern_matrix_is_visible_observable : renoise.Document.Observable
  • pattern_advanced_edit_is_visible : boolean
  • pattern_advanced_edit_is_visible_observable : renoise.Document.Observable
  • mixer_view_post_fx : boolean
  • mixer_view_post_fx_observable : renoise.Document.Observable
  • mixer_fader_type : renoise.ApplicationWindow.MixerFader
  • mixer_fader_type_observable : renoise.Document.Observable
• Functions
  • maximize(self)
  • minimize(self)
  • restore(self)
  • select_preset(self, preset_index : integer)

Constants

UpperFrame

{
    UPPER_FRAME_TRACK_SCOPES: integer = 1,
    UPPER_FRAME_MASTER_SPECTRUM: integer = 2,
}

MiddleFrame

{
    MIDDLE_FRAME_PATTERN_EDITOR: integer = 1,
    MIDDLE_FRAME_MIXER: integer = 2,
    MIDDLE_FRAME_INSTRUMENT_PHRASE_EDITOR: integer = 3,
    MIDDLE_FRAME_INSTRUMENT_SAMPLE_KEYZONES: integer = 4,
    MIDDLE_FRAME_INSTRUMENT_SAMPLE_EDITOR: integer = 5,
    MIDDLE_FRAME_INSTRUMENT_SAMPLE_MODULATION: integer = 6,
    MIDDLE_FRAME_INSTRUMENT_SAMPLE_EFFECTS: integer = 7,
    MIDDLE_FRAME_INSTRUMENT_PLUGIN_EDITOR: integer = 8,
    MIDDLE_FRAME_INSTRUMENT_MIDI_EDITOR: integer = 9,
}

LowerFrame

{
    LOWER_FRAME_TRACK_DSPS: integer = 1,
    LOWER_FRAME_TRACK_AUTOMATION: integer = 2,
}

DiskBrowserCategory

{
    DISK_BROWSER_CATEGORY_SONGS: integer = 1,
    DISK_BROWSER_CATEGORY_INSTRUMENTS: integer = 2,
    DISK_BROWSER_CATEGORY_SAMPLES: integer = 3,
    DISK_BROWSER_CATEGORY_OTHER: integer = 4,
}

InstrumentBoxSlotSize

{
    INSTRUMENT_BOX_SLOT_SIZE_SMALL: integer = 1,
    INSTRUMENT_BOX_SLOT_SIZE_MEDIUM: integer = 2,
    INSTRUMENT_BOX_SLOT_SIZE_LARGE: integer = 3,
}

MixerFader

{
    MIXER_FADER_TYPE_24DB: integer = 1,
    MIXER_FADER_TYPE_48DB: integer = 2,
    MIXER_FADER_TYPE_96DB: integer = 3,
    MIXER_FADER_TYPE_LINEAR: integer = 4,
}

Properties

fullscreen : boolean

Get/set if the application is running fullscreen.

is_maximized : boolean

READ-ONLY. Window status flag.

is_minimized : boolean

READ-ONLY. Window status flag.

lock_keyboard_focus : boolean

When true, the middle frame views (like the pattern editor) will stay focused unless alt or middle mouse is clicked.

sample_record_dialog_is_visible : boolean

Dialog for recording new samples, floating above the main window.

disk_browser_is_visible : boolean

Diskbrowser Panel.

disk_browser_is_visible_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

disk_browser_category : renoise.ApplicationWindow.DiskBrowserCategory

disk_browser_category_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

instrument_box_is_visible : boolean

InstrumentBox

instrument_box_is_visible_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

instrument_box_slot_size : renoise.ApplicationWindow.InstrumentBoxSlotSize

InstrumentBox slot size

instrument_box_slot_size_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

instrument_editor_is_detached : boolean

Instrument Editor detaching.

instrument_editor_is_detached_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

instrument_properties_is_visible : boolean

InstrumentProperties (below InstrumentBox)

instrument_properties_is_visible_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

instrument_properties_show_volume_transpose : boolean

instrument_properties_show_trigger_options : boolean

instrument_properties_show_scale_options : boolean

instrument_properties_show_plugin : boolean

instrument_properties_show_plugin_program : boolean

instrument_properties_show_midi : boolean

instrument_properties_show_midi_program : boolean

instrument_properties_show_macros : boolean

instrument_properties_show_phrases : boolean

sample_properties_is_visible : boolean

SampleProperties (below SampleNavigator)

sample_properties_is_visible_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

mixer_view_is_detached : boolean

Mixer View detaching.

mixer_view_is_detached_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

upper_frame_is_visible : boolean

Frame with the scopes/master spectrum...

upper_frame_is_visible_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

active_upper_frame : renoise.ApplicationWindow.UpperFrame

active_upper_frame_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

active_middle_frame : renoise.ApplicationWindow.MiddleFrame

Frame with the pattern editor, mixer...

active_middle_frame_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

lower_frame_is_visible : boolean

Frame with the DSP chain view, automation, etc.

lower_frame_is_visible_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

active_lower_frame : renoise.ApplicationWindow.LowerFrame

active_lower_frame_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

right_frame_is_visible : boolean

Frame with Disk Browser and Instrument Box.

right_frame_is_visible_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

pattern_matrix_is_visible : boolean

Pattern matrix, visible in pattern editor and mixer only...

pattern_matrix_is_visible_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

pattern_advanced_edit_is_visible : boolean

Pattern advanced edit, visible in pattern editor only...

pattern_advanced_edit_is_visible_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

mixer_view_post_fx : boolean

Mixer views Pre/Post volume setting.

mixer_view_post_fx_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

mixer_fader_type : renoise.ApplicationWindow.MixerFader

Mixer fader type setting.

mixer_fader_type_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

Functions

maximize(self)

Expand the window over the entire screen, without hiding menu bars, docks and so on.

minimize(self)

Minimize the window to the dock or taskbar, depending on the OS.

restore(self)

"un-maximize" or "un-minimize" the window, or just bring it to front.

select_preset(self, preset_index : integer)

Select/activate one of the global view presets, to memorize/restore the user interface layout.

renoise.AudioDevice

Audio DSP device in tracks or sample device chains.

• Properties
  • name : string
  • short_name : string
  • display_name : string
  • display_name_observable : renoise.Document.Observable
  • is_active : boolean
  • is_active_observable : renoise.Document.Observable
  • is_maximized : boolean
  • is_maximized_observable : renoise.Document.Observable
  • active_preset : integer
  • active_preset_observable : renoise.Document.Observable
  • active_preset_data : string
  • presets : string[]
  • is_active_parameter : renoise.DeviceParameter
  • parameters : renoise.DeviceParameter[]
  • external_editor_available : boolean
  • external_editor_visible : boolean
  • device_path : string
• Functions
  • preset(self, index : integer)
  • parameter(self, index : integer)

Properties

name : string

READ-ONLY

short_name : string

READ-ONLY

display_name : string

Configurable device display name. When empty name is displayed.

display_name_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

is_active : boolean

!active = bypassed

is_active_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

is_maximized : boolean

Maximize state in DSP chain.

is_maximized_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

active_preset : integer

0 when none is active or available

active_preset_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

active_preset_data : string

raw serialized data in XML format of the active preset

presets : string[]

READ-ONLY preset names

is_active_parameter : renoise.DeviceParameter

READ-ONLY

parameters : renoise.DeviceParameter[]

READ-ONLY

external_editor_available : boolean

READ-ONLY Returns whether or not the device provides its own custom GUI (only available for some plugin devices)

external_editor_visible : boolean

true to show the editor, false to close it

device_path : string

READ-ONLY Returns a string that uniquely identifies the device, from available_devices. The string can be passed into: renoise.song().tracks[]:insert_device_at()

Functions

preset(self, index : integer)

->preset_name : string

Access to a single preset name by index. Use properties 'presets' to iterate over all presets and to query the presets count. comment

parameter(self, index : integer)

->renoise.DeviceParameter

Access to a single parameter by index. Use properties 'parameters' to iterate over all parameters and to query the parameter count.

renoise.DeviceParameter

A single parameter within an audio DSP effect (renoise.AudioDevice)

• Constants
  • Polarity
• Properties
  • name : string
  • name_observable : renoise.Document.ObservableString
  • polarity : renoise.DeviceParameter.Polarity
  • value_min : number
  • value_max : number
  • value_quantum : number
  • value_default : number
  • time_quantum : number
  • is_automatable : boolean
  • is_automated : boolean
  • is_automated_observable : renoise.Document.Observable
  • is_midi_mapped : boolean
  • is_midi_mapped_observable : renoise.Document.Observable
  • show_in_mixer : boolean
  • show_in_mixer_observable : renoise.Document.Observable
  • value : number
  • value_observable : renoise.Document.Observable
  • value_string : string
  • value_string_observable : renoise.Document.Observable
• Functions
  • record_value(self, value : number)

Constants

Polarity

{
    POLARITY_UNIPOLAR: integer = 1,
    POLARITY_BIPOLAR: integer = 2,
}

Properties

name : string

READ-ONLY

name_observable : renoise.Document.ObservableString

polarity : renoise.DeviceParameter.Polarity

READ-ONLY

value_min : number

READ-ONLY

value_max : number

READ-ONLY

value_quantum : number

READ-ONLY

value_default : number

READ-ONLY

time_quantum : number

READ-ONLY

is_automatable : boolean

READ-ONLY

is_automated : boolean

READ-ONLY Is automated. Not valid for parameters of instrument devices.

is_automated_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

is_midi_mapped : boolean

READ-ONLY Parameter has a custom MIDI mapping in the current song.

is_midi_mapped_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

show_in_mixer : boolean

Show in mixer. Not valid for parameters of instrument devices.

show_in_mixer_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

value : number

value in Range: (value_min - value_max)

value_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

value_string : string

value_string_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

Functions

record_value(self, value : number)

Set a new value and write automation when the MIDI mapping "record to automation" option is set. Only works for parameters of track devices, not for instrument devices.

renoise.Dialog

A custom dialog created via the scripting API. Dialogs can be created via renoise.app():show_custom_dialog.

See create custom views on top of the renoise.ViewBuilder docs on how to create views for the dialog.

• Properties
  • visible : boolean
  • focused : boolean
• Functions
  • show(self)
  • close(self)

Properties

visible : boolean

READ-ONLY Check if a dialog is alive and visible.

focused : boolean

READ-ONLY Check if a dialog is visible and is the key window.

Functions

show(self)

Bring an already visible dialog to front and make it the key window.

close(self)

Close a visible dialog.

renoise.Document

renoise.Document classes are wrappers for Renoise's internal document classes.

Please note: the Lua wrappers are not really "the Lua way" of solving and expressing things. e.g: there's no support for mixed types in lists, tuples at the moment.

Documents can be serialized from/to XML, just like Renoise's internal document and are observable.

An empty document (node) object can be created via renoise.Document.create("MyDoc"){}

Such document objects can then be extended with the document's add_property function. Existing properties can also be removed again with the remove_property function.

examples:

-- Creates an empty document, using "MyDoc" as the model name (a type name)
local my_document = renoise.Document.create("MyDoc"){ }
-- adds a number to the document with the initial value 1
my_document:add_property("value1", 1)
-- adds a string
my_document:add_property("value2", "bla")
-- create another document and adds it
local node = renoise.Document.create("MySubDoc"){ }
node:add_property("another_value", 1)
-- add another already existing node
my_document:add_property("nested_node", node)
-- removes a previously added node
my_document:remove_property(node)
-- access properties
local value1 = my_document.value1
value1 = my_document:property("value1")

As an alternative to renoise.Document.create, you can also inherit from renoise.Document.DocumentNode in order to create your own document classes. This is especially recommended when dealing with more complex docs, because you can also use additional methods to deal with your properties, the data.

examples:

class "MyDocument" (renoise.Document.DocumentNode)
  function MyDocument:__init()
    -- important! call super first
    renoise.Document.DocumentNode.__init(self)
    -- add properties to construct the document model
    self:add_property("age", 1)
    self:add_property("name", renoise.Document.ObservableString("value"))
    -- other doc renoise.Document.DocumentNode object
    self:add_property("sub_node", MySubNode())
    -- list of renoise.Document.DocumentNode objects
    self:add_property("doc_list", renoise.Document.DocumentList())
    -- or the create() way:
    self:add_properties {
      something = "else"
    }
  end

Instantiating such custom document objects can then be done by simply calling the constructor:

my_document = MyDocument()
-- do something with my_document, load/save, add/remove more properties

• Functions
  • create(model_name : string)
    • examples:
    • examples:
  • instantiate(model_name : string)
• Aliases
  • DocumentMember
  • ListElementAdded
  • ListElementChange
  • ListElementRemoved
  • ListElementsSwapped
  • ListNotifierFunction
  • ListNotifierMemberContext
  • NotifierFunction
  • NotifierMemberContext
  • ObservableProperties
  • ObservableTypes

Functions

create(model_name : string)

->(properties : ObservableProperties) -> renoise.Document.DocumentNode

Create an empty DocumentNode or a DocumentNode that is modeled after the passed key value table. "model_name" will be used to identify the documents type when loading/saving. It also allows you to instantiate new document objects (see renoise.Document.instantiate).

examples:

my_document = renoise.Document.create("MyDoc") {
  age = 1,
  name = "bla", -- implicitly specify a property type
  is_valid = renoise.Document.ObservableBoolean(false), -- or explicitly
  age_list = {1, 2, 3},
  another_list = renoise.Document.ObservableNumberList(),
  sub_node = {
    sub_value1 = 2,
    sub_value2 = "bla2"
  }
}

This will create a document node which is !modeled! after the the passed table. The table is not used internally by the document after construction, and will only be referenced to construct new instances. Also note that you need to assign values for all passed table properties in order to automatically determine it's type, or specify the types explicitly -> renoise.Document.ObservableXXX().

The passed name ("MyDoc" in the example above) is used to identify the document when loading/saving it (loading a XML file which was saved with a different model will fail) and to generally specify the "type".

Additionally, once "create" is called, you can use the specified model name to create new instances.

examples:

-- create a new instance of "MyDoc"
my_other_document = renoise.Document.instantiate("MyDoc")

instantiate(model_name : string)

->renoise.Document.DocumentNode

Create a new instance of the given document model. Given model_name must have been registered with renoise.Document.create before.

Aliases

DocumentMember

renoise.Document.DocumentList | renoise.Document.DocumentNode | renoise.Document.Observable | renoise.Document.ObservableList

Track changes to document properties or general states by attaching listener functions to it.

ListElementAdded

{ index : integer, type : "insert" }

ListElementChange

ListElementAdded | ListElementRemoved | ListElementsSwapped

ListElementRemoved

{ index : integer, type : "removed" }

ListElementsSwapped

{ index1 : integer, index2 : integer, type : "swapped" }

ListNotifierFunction

(change : ListElementChange)

ListNotifierMemberContext

table | userdata

NotifierFunction

fun()

NotifierMemberContext

table | userdata

ObservableProperties

table<string, ObservableTypes | renoise.Document.DocumentList | renoise.Document.DocumentNode>

ObservableTypes

boolean | string | number | boolean[] | number[] | string[]

renoise.Document.DocumentList

A document list is a document sub component which may contain other document nodes in an observable list.

example:

-- our goal here is to have a document that contains a list of documents
-- which can loaded as preferences for our tool
--
-- define a class model for our complex type for document items in the list
-- so that Renoise knows how to load it later our entries will have
renoise.Document.create("Entry") {
  name = renoise.Document.ObservableString(),
  path = renoise.Document.ObservableString(),
}

-- create new entry instances with the given data
function create_entry(name, path)
  local entry = renoise.Document.instantiate("Entry")
  entry.name.value = name
  entry.path.value = path
  return entry
end

-- define a class model for our preferences which is using a list of entries
renoise.Document.create("MyPreferences") {
  list = renoise.Document.DocumentList()
}

-- assign a fresh instance of our main document as preferences
local preferences = renoise.Document.instantiate("MyPreferences")
renoise.tool().preferences = preferences

-- insert elements into the list using :insert(index, element)
-- we call our helper to create an instance of Entry
preferences.list:insert(1, create_entry("some name", "some/path"))

-- access entries by using :property(index)
print(preferences.list:property(1).name)

-- get the size of the list (you can use :size() as well)
print(#preferences.list)

-- loop over the list to print all entries
for i = 1, #preferences.list do
  local entry = preferences.list:property(i)
  print(i)
  print(entry.name)
  print(entry.path)
end

-- try reloading your tool to see the list get bigger

• Functions
  • size(self)
  • property(self, index : integer)
  • find(self, start_pos : integer, value : renoise.Document.DocumentNode)
  • insert(self, pos : integer, value : renoise.Document.DocumentNode)
  • remove(self, pos : integer)
  • swap(self, pos1 : integer, pos2 : integer)
  • has_notifier(self, notifier : ListNotifierFunction)
  • add_notifier(self, notifier : ListNotifierFunction)
  • remove_notifier(self, notifier : ListNotifierFunction | ListNotifierMemberContext)
• Aliases
  • ListElementAdded
  • ListElementChange
  • ListElementRemoved
  • ListElementsSwapped
  • ListNotifierFunction
  • ListNotifierMemberContext

Functions

size(self)

->integer

Returns the number of entries of the list.

property(self, index : integer)

->renoise.Document.DocumentNode?

List item access by index. returns nil for non existing items.

find(self, start_pos : integer, value : renoise.Document.DocumentNode)

->integer?

Find a value in the list by comparing the list values with the passed value. The first successful match is returned. When no match is found, nil is returned.

insert(self, pos : integer, value : renoise.Document.DocumentNode)

->renoise.Document.DocumentNode

Insert a new item to the end of the list when no position is specified, or at the specified position. Returns the newly created and inserted Observable.

remove(self, pos : integer)

Removes an item (or the last one if no index is specified) from the list.

swap(self, pos1 : integer, pos2 : integer)

Swaps the positions of two items without adding/removing the items.

With a series of swaps you can move the item from/to any position.

has_notifier(self, notifier : ListNotifierFunction)

Checks if the given function, method was already registered as notifier.

add_notifier(self, notifier : ListNotifierFunction)

Register a function or method as a notifier, which will be called as soon as the document lists layout changed. The passed notifier can either be a function or a table with a function and some context (an "object") -> method.

remove_notifier(self, notifier : ListNotifierFunction | ListNotifierMemberContext)

Unregister a previously registered list notifier. When only passing an object, all notifier functions that match the given object will be removed. This will not fire errors when no methods for the given object are attached. Trying to unregister a function or method which wasn't registered, will resolve into an error.

Aliases

ListElementAdded

{ index : integer, type : "insert" }

ListElementChange

ListElementAdded | ListElementRemoved | ListElementsSwapped

ListElementRemoved

{ index : integer, type : "removed" }

ListElementsSwapped

{ index1 : integer, index2 : integer, type : "swapped" }

ListNotifierFunction

(change : ListElementChange)

ListNotifierMemberContext

table | userdata

renoise.Document.DocumentNode

A document node is a sub component in a document which contains other documents or observables.

• Functions
  • __init(self)
  • has_property(self, property_name : string)
  • property(self, property_name : string)
  • add_property(self, name : string, value : renoise.Document.DocumentNode)
  • add_properties(self, properties : ObservableProperties)
  • remove_property(self, value : DocumentMember)
  • save_as(self, file_name : string)
  • load_from(self, file_name : string)
  • to_string(self)
  • from_string(self, string : string)
• Aliases
  • DocumentMember
  • ListElementAdded
  • ListElementChange
  • ListElementRemoved
  • ListElementsSwapped
  • ListNotifierFunction
  • ListNotifierMemberContext
  • NotifierFunction
  • NotifierMemberContext
  • ObservableProperties
  • ObservableTypes

Functions

__init(self)

Base constructor, only necessary to be called in your custom class constructor, when inheriting from renoise.Document.DocumentNode.

has_property(self, property_name : string)

->boolean

Check if the given property exists.

property(self, property_name : string)

->DocumentMember?

Access a property by name. Returns the property, or nil when there is no such property.

add_property(self, name : string, value : renoise.Document.DocumentNode)

->renoise.Document.DocumentNode

Add a new property. Name must be unique: overwriting already existing properties with the same name is not allowed and will fire an error. If you want to replace a property, remove it first, then add it again.

add_properties(self, properties : ObservableProperties)

Add a batch of properties in one go, similar to renoise.Document.create.

remove_property(self, value : DocumentMember)

Remove a previously added property. Property must exist.

In order to remove a value by it's key, use my_document:remove_property(my_document["some_member"])

save_as(self, file_name : string)

->success : boolean, error : string?

Save the whole document tree to an XML file. Overwrites all contents of the file when it already exists.

load_from(self, file_name : string)

->success : boolean, error : string?

Load the document tree from an XML file. This will NOT create new properties, except for list items, but will only assign existing property values in the document node with existing property values from the XML. This means: nodes that only exist in the XML will silently be ignored. Nodes that only exist in the document, will not be altered in any way. The loaded document's type must match the document type that saved the XML data. A document's type is specified in the renoise.Document.create() function as "model_name". For classes which inherit from renoise.Document.DocumentNode it's the class name.

to_string(self)

->string

Serialize the whole document tree to a XML string.

from_string(self, string : string)

->success : boolean, error : string?

Parse document tree from the given string data. See renoise.Document.DocumentNode:load_from for details about how properties are parsed and errors are handled.

Aliases

DocumentMember

renoise.Document.DocumentList | renoise.Document.DocumentNode | renoise.Document.Observable | renoise.Document.ObservableList

Track changes to document properties or general states by attaching listener functions to it.

ListElementAdded

{ index : integer, type : "insert" }

ListElementChange

ListElementAdded | ListElementRemoved | ListElementsSwapped

ListElementRemoved

{ index : integer, type : "removed" }

ListElementsSwapped

{ index1 : integer, index2 : integer, type : "swapped" }

ListNotifierFunction

(change : ListElementChange)

ListNotifierMemberContext

table | userdata

NotifierFunction

fun()

NotifierMemberContext

table | userdata

ObservableProperties

table<string, ObservableTypes | renoise.Document.DocumentList | renoise.Document.DocumentNode>

ObservableTypes

boolean | string | number | boolean[] | number[] | string[]

renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

• Functions
  • has_notifier(self, notifier : NotifierFunction)
  • add_notifier(self, notifier : NotifierFunction)
    • examples:
  • remove_notifier(self, notifier : NotifierFunction | NotifierMemberContext)
• Aliases
  • NotifierFunction
  • NotifierMemberContext

Functions

has_notifier(self, notifier : NotifierFunction)

->boolean

Checks if the given function, method was already registered as notifier.

add_notifier(self, notifier : NotifierFunction)

Register a function or method as a notifier, which will be called as soon as the observable's value changed. The passed notifier can either be a function or a table with a function and some context (an "object") -> method.

examples:

renoise.song().transport.bpm_observable:add_notifier(function()
  print("BPM changed")
end)

local my_context = { bpm_changes = 0, something_else = "bla" }
renoise.song().transport.bpm_observable:add_notifier({
  my_context,
  function(context)
    context.bpm_changes = context.bpm_changes + 1;
    print(("#BPM changes: %s"):format(context.bpm_changes));
  end
})

remove_notifier(self, notifier : NotifierFunction | NotifierMemberContext)

Unregister a previously registered notifier. When only passing an object, all notifier functions that match the given object will be removed. This will not fire errors when no methods for the given object are attached. Trying to unregister a function or method which wasn't registered, will resolve into an error.

Aliases

NotifierFunction

fun()

NotifierMemberContext

table | userdata

renoise.Document.ObservableBang

Observable without a value which sends out notifications when "banging" it.

• Functions
  • has_notifier(self, notifier : NotifierFunction)
  • add_notifier(self, notifier : NotifierFunction)
    • examples:
  • remove_notifier(self, notifier : NotifierFunction | NotifierMemberContext)
  • bang(self)
• Aliases
  • NotifierFunction
  • NotifierMemberContext

Functions

has_notifier(self, notifier : NotifierFunction)

->boolean

Checks if the given function, method was already registered as notifier.

add_notifier(self, notifier : NotifierFunction)

Register a function or method as a notifier, which will be called as soon as the observable's value changed. The passed notifier can either be a function or a table with a function and some context (an "object") -> method.

examples:

renoise.song().transport.bpm_observable:add_notifier(function()
  print("BPM changed")
end)

local my_context = { bpm_changes = 0, something_else = "bla" }
renoise.song().transport.bpm_observable:add_notifier({
  my_context,
  function(context)
    context.bpm_changes = context.bpm_changes + 1;
    print(("#BPM changes: %s"):format(context.bpm_changes));
  end
})

remove_notifier(self, notifier : NotifierFunction | NotifierMemberContext)

Unregister a previously registered notifier. When only passing an object, all notifier functions that match the given object will be removed. This will not fire errors when no methods for the given object are attached. Trying to unregister a function or method which wasn't registered, will resolve into an error.

bang(self)

fire a notification, calling all registered notifiers.

Aliases

NotifierFunction

fun()

NotifierMemberContext

table | userdata

renoise.Document.ObservableBoolean

• Properties
  • value : boolean
• Functions
  • has_notifier(self, notifier : NotifierFunction)
  • add_notifier(self, notifier : NotifierFunction)
    • examples:
  • remove_notifier(self, notifier : NotifierFunction | NotifierMemberContext)
  • to_string(self)
  • from_string(self, string : any)
• Aliases
  • NotifierFunction
  • NotifierMemberContext

Properties

value : boolean

Read/write access to the value of an observable.

Functions

has_notifier(self, notifier : NotifierFunction)

->boolean

Checks if the given function, method was already registered as notifier.

add_notifier(self, notifier : NotifierFunction)

Register a function or method as a notifier, which will be called as soon as the observable's value changed. The passed notifier can either be a function or a table with a function and some context (an "object") -> method.

examples:

renoise.song().transport.bpm_observable:add_notifier(function()
  print("BPM changed")
end)

local my_context = { bpm_changes = 0, something_else = "bla" }
renoise.song().transport.bpm_observable:add_notifier({
  my_context,
  function(context)
    context.bpm_changes = context.bpm_changes + 1;
    print(("#BPM changes: %s"):format(context.bpm_changes));
  end
})

remove_notifier(self, notifier : NotifierFunction | NotifierMemberContext)

Unregister a previously registered notifier. When only passing an object, all notifier functions that match the given object will be removed. This will not fire errors when no methods for the given object are attached. Trying to unregister a function or method which wasn't registered, will resolve into an error.

to_string(self)

->string

Serialize an object to a string.

from_string(self, string : any)

->string

Assign the object's value from a string - when possible. Errors are silently ignored.

Aliases

NotifierFunction

fun()

NotifierMemberContext

table | userdata

renoise.Document.ObservableBooleanList

A observable list of boolean values.

• Functions
  • to_string(self)
  • from_string(self, string : any)
  • size(self)
  • has_notifier(self, notifier : ListNotifierFunction)
  • add_notifier(self, notifier : ListNotifierFunction)
  • remove_notifier(self, notifier : ListNotifierFunction | ListNotifierMemberContext)
  • property(self, index : integer)
  • find(self, start_pos : integer, value : boolean)
  • insert(self, pos : integer, value : boolean)
  • remove(self, pos : integer)
  • swap(self, pos1 : integer, pos2 : integer)
• Aliases
  • ListElementAdded
  • ListElementChange
  • ListElementRemoved
  • ListElementsSwapped
  • ListNotifierFunction
  • ListNotifierMemberContext

Functions

to_string(self)

->string

Serialize an object to a string.

from_string(self, string : any)

->string

Assign the object's value from a string - when possible. Errors are silently ignored.

size(self)

->integer

Returns the number of entries of the list.

has_notifier(self, notifier : ListNotifierFunction)

Checks if the given function, method was already registered as notifier.

add_notifier(self, notifier : ListNotifierFunction)

Register a function or method as a notifier, which will be called as soon as the observable lists layout changed. The passed notifier can either be a function or a table with a function and some context (an "object") -> method.

remove_notifier(self, notifier : ListNotifierFunction | ListNotifierMemberContext)

Unregister a previously registered list notifier. When only passing an object, all notifier functions that match the given object will be removed. This will not fire errors when no methods for the given object are attached. Trying to unregister a function or method which wasn't registered, will resolve into an error.

property(self, index : integer)

->renoise.Document.ObservableBoolean?

List item access by index. returns nil for non existing items.

find(self, start_pos : integer, value : boolean)

->integer?

Find a value in the list by comparing the list values with the passed value. The first successful match is returned. When no match is found, nil is returned.

insert(self, pos : integer, value : boolean)

->renoise.Document.ObservableBoolean

Insert a new item to the end of the list when no position is specified, or at the specified position. Returns the newly created and inserted Observable.

remove(self, pos : integer)

Removes an item (or the last one if no index is specified) from the list.

swap(self, pos1 : integer, pos2 : integer)

Swaps the positions of two items without adding/removing the items.

With a series of swaps you can move the item from/to any position.

Aliases

ListElementAdded

{ index : integer, type : "insert" }

ListElementChange

ListElementAdded | ListElementRemoved | ListElementsSwapped

ListElementRemoved

{ index : integer, type : "removed" }

ListElementsSwapped

{ index1 : integer, index2 : integer, type : "swapped" }

ListNotifierFunction

(change : ListElementChange)

ListNotifierMemberContext

table | userdata

renoise.Document.ObservableList

Track changes to document lists by attaching listener functions to it. NB: Notifiers will not broadcast changes made to list items, but only changes to the lists layout (items got added, removed, swapped).

• Functions
  • size(self)
  • has_notifier(self, notifier : ListNotifierFunction)
  • add_notifier(self, notifier : ListNotifierFunction)
  • remove_notifier(self, notifier : ListNotifierFunction | ListNotifierMemberContext)
• Aliases
  • ListElementAdded
  • ListElementChange
  • ListElementRemoved
  • ListElementsSwapped
  • ListNotifierFunction
  • ListNotifierMemberContext

Functions

size(self)

->integer

Returns the number of entries of the list.

has_notifier(self, notifier : ListNotifierFunction)

Checks if the given function, method was already registered as notifier.

add_notifier(self, notifier : ListNotifierFunction)

Register a function or method as a notifier, which will be called as soon as the observable lists layout changed. The passed notifier can either be a function or a table with a function and some context (an "object") -> method.

remove_notifier(self, notifier : ListNotifierFunction | ListNotifierMemberContext)

Unregister a previously registered list notifier. When only passing an object, all notifier functions that match the given object will be removed. This will not fire errors when no methods for the given object are attached. Trying to unregister a function or method which wasn't registered, will resolve into an error.

Aliases

ListElementAdded

{ index : integer, type : "insert" }

ListElementChange

ListElementAdded | ListElementRemoved | ListElementsSwapped

ListElementRemoved

{ index : integer, type : "removed" }

ListElementsSwapped

{ index1 : integer, index2 : integer, type : "swapped" }

ListNotifierFunction

(change : ListElementChange)

ListNotifierMemberContext

table | userdata

renoise.Document.ObservableNumber

• Properties
  • value : number
• Functions
  • has_notifier(self, notifier : NotifierFunction)
  • add_notifier(self, notifier : NotifierFunction)
    • examples:
  • remove_notifier(self, notifier : NotifierFunction | NotifierMemberContext)
  • to_string(self)
  • from_string(self, string : any)
• Aliases
  • NotifierFunction
  • NotifierMemberContext

Properties

value : number

Read/write access to the value of an Observable.

Functions

has_notifier(self, notifier : NotifierFunction)

->boolean

Checks if the given function, method was already registered as notifier.

add_notifier(self, notifier : NotifierFunction)

Register a function or method as a notifier, which will be called as soon as the observable's value changed. The passed notifier can either be a function or a table with a function and some context (an "object") -> method.

examples:

renoise.song().transport.bpm_observable:add_notifier(function()
  print("BPM changed")
end)

local my_context = { bpm_changes = 0, something_else = "bla" }
renoise.song().transport.bpm_observable:add_notifier({
  my_context,
  function(context)
    context.bpm_changes = context.bpm_changes + 1;
    print(("#BPM changes: %s"):format(context.bpm_changes));
  end
})

remove_notifier(self, notifier : NotifierFunction | NotifierMemberContext)

Unregister a previously registered notifier. When only passing an object, all notifier functions that match the given object will be removed. This will not fire errors when no methods for the given object are attached. Trying to unregister a function or method which wasn't registered, will resolve into an error.

to_string(self)

->string

Serialize an object to a string.

from_string(self, string : any)

->string

Assign the object's value from a string - when possible. Errors are silently ignored.

Aliases

NotifierFunction

fun()

NotifierMemberContext

table | userdata

renoise.Document.ObservableNumberList

A observable list of number values.

• Functions
  • to_string(self)
  • from_string(self, string : any)
  • size(self)
  • has_notifier(self, notifier : ListNotifierFunction)
  • add_notifier(self, notifier : ListNotifierFunction)
  • remove_notifier(self, notifier : ListNotifierFunction | ListNotifierMemberContext)
  • property(self, index : integer)
  • find(self, start_pos : integer, value : number)
  • insert(self, pos : integer, value : number)
  • remove(self, pos : integer)
  • swap(self, pos1 : integer, pos2 : integer)
• Aliases
  • ListElementAdded
  • ListElementChange
  • ListElementRemoved
  • ListElementsSwapped
  • ListNotifierFunction
  • ListNotifierMemberContext

Functions

to_string(self)

->string

Serialize an object to a string.

from_string(self, string : any)

->string

Assign the object's value from a string - when possible. Errors are silently ignored.

size(self)

->integer

Returns the number of entries of the list.

has_notifier(self, notifier : ListNotifierFunction)

Checks if the given function, method was already registered as notifier.

add_notifier(self, notifier : ListNotifierFunction)

Register a function or method as a notifier, which will be called as soon as the observable lists layout changed. The passed notifier can either be a function or a table with a function and some context (an "object") -> method.

remove_notifier(self, notifier : ListNotifierFunction | ListNotifierMemberContext)

Unregister a previously registered list notifier. When only passing an object, all notifier functions that match the given object will be removed. This will not fire errors when no methods for the given object are attached. Trying to unregister a function or method which wasn't registered, will resolve into an error.

property(self, index : integer)

->renoise.Document.ObservableNumber?

List item access by index. returns nil for non existing items.

find(self, start_pos : integer, value : number)

->integer?

Find a value in the list by comparing the list values with the passed value. The first successful match is returned. When no match is found, nil is returned.

insert(self, pos : integer, value : number)

->renoise.Document.ObservableNumber

Insert a new item to the end of the list when no position is specified, or at the specified position. Returns the newly created and inserted Observable.

remove(self, pos : integer)

Removes an item (or the last one if no index is specified) from the list.

swap(self, pos1 : integer, pos2 : integer)

Swaps the positions of two items without adding/removing the items. With a series of swaps you can move the item from/to any position.

Aliases

ListElementAdded

{ index : integer, type : "insert" }

ListElementChange

ListElementAdded | ListElementRemoved | ListElementsSwapped

ListElementRemoved

{ index : integer, type : "removed" }

ListElementsSwapped

{ index1 : integer, index2 : integer, type : "swapped" }

ListNotifierFunction

(change : ListElementChange)

ListNotifierMemberContext

table | userdata

renoise.Document.ObservableString

• Properties
  • value : string
• Functions
  • has_notifier(self, notifier : NotifierFunction)
  • add_notifier(self, notifier : NotifierFunction)
    • examples:
  • remove_notifier(self, notifier : NotifierFunction | NotifierMemberContext)
  • to_string(self)
  • from_string(self, string : any)
• Aliases
  • NotifierFunction
  • NotifierMemberContext

Properties

value : string

Read/write access to the value of an Observable.

Functions

has_notifier(self, notifier : NotifierFunction)

->boolean

Checks if the given function, method was already registered as notifier.

add_notifier(self, notifier : NotifierFunction)

Register a function or method as a notifier, which will be called as soon as the observable's value changed. The passed notifier can either be a function or a table with a function and some context (an "object") -> method.

examples:

renoise.song().transport.bpm_observable:add_notifier(function()
  print("BPM changed")
end)

local my_context = { bpm_changes = 0, something_else = "bla" }
renoise.song().transport.bpm_observable:add_notifier({
  my_context,
  function(context)
    context.bpm_changes = context.bpm_changes + 1;
    print(("#BPM changes: %s"):format(context.bpm_changes));
  end
})

remove_notifier(self, notifier : NotifierFunction | NotifierMemberContext)

Unregister a previously registered notifier. When only passing an object, all notifier functions that match the given object will be removed. This will not fire errors when no methods for the given object are attached. Trying to unregister a function or method which wasn't registered, will resolve into an error.

to_string(self)

->string

Serialize an object to a string.

from_string(self, string : any)

->string

Assign the object's value from a string - when possible. Errors are silently ignored.

Aliases

NotifierFunction

fun()

NotifierMemberContext

table | userdata

renoise.Document.ObservableStringList

A observable list of string values.

• Functions
  • to_string(self)
  • from_string(self, string : any)
  • size(self)
  • has_notifier(self, notifier : ListNotifierFunction)
  • add_notifier(self, notifier : ListNotifierFunction)
  • remove_notifier(self, notifier : ListNotifierFunction | ListNotifierMemberContext)
  • property(self, index : integer)
  • find(self, start_pos : integer, value : number)
  • insert(self, pos : integer, value : number)
  • remove(self, pos : integer)
  • swap(self, pos1 : integer, pos2 : integer)
• Aliases
  • ListElementAdded
  • ListElementChange
  • ListElementRemoved
  • ListElementsSwapped
  • ListNotifierFunction
  • ListNotifierMemberContext

Functions

to_string(self)

->string

Serialize an object to a string.

from_string(self, string : any)

->string

Assign the object's value from a string - when possible. Errors are silently ignored.

size(self)

->integer

Returns the number of entries of the list.

has_notifier(self, notifier : ListNotifierFunction)

Checks if the given function, method was already registered as notifier.

add_notifier(self, notifier : ListNotifierFunction)

Register a function or method as a notifier, which will be called as soon as the observable lists layout changed. The passed notifier can either be a function or a table with a function and some context (an "object") -> method.

remove_notifier(self, notifier : ListNotifierFunction | ListNotifierMemberContext)

Unregister a previously registered list notifier. When only passing an object, all notifier functions that match the given object will be removed. This will not fire errors when no methods for the given object are attached. Trying to unregister a function or method which wasn't registered, will resolve into an error.

property(self, index : integer)

->renoise.Document.ObservableString?

List item access by index. returns nil for non existing items.

find(self, start_pos : integer, value : number)

->integer?

Find a value in the list by comparing the list values with the passed value. The first successful match is returned. When no match is found, nil is returned.

insert(self, pos : integer, value : number)

->renoise.Document.ObservableString

Insert a new item to the end of the list when no position is specified, or at the specified position. Returns the newly created and inserted Observable.

remove(self, pos : integer)

Removes an item (or the last one if no index is specified) from the list.

swap(self, pos1 : integer, pos2 : integer)

Swaps the positions of two items without adding/removing the items. With a series of swaps you can move the item from/to any position.

Aliases

ListElementAdded

{ index : integer, type : "insert" }

ListElementChange

ListElementAdded | ListElementRemoved | ListElementsSwapped

ListElementRemoved

{ index : integer, type : "removed" }

ListElementsSwapped

{ index1 : integer, index2 : integer, type : "swapped" }

ListNotifierFunction

(change : ListElementChange)

ListNotifierMemberContext

table | userdata

renoise.Document.Serializable

• Functions
  • to_string(self)
  • from_string(self, string : any)

Functions

to_string(self)

->string

Serialize an object to a string.

from_string(self, string : any)

->string

Assign the object's value from a string - when possible. Errors are silently ignored.

renoise.EffectColumn

A single effect column in a pattern line.

Access effect column properties either by values (numbers) or by strings. The string representation uses exactly the same notation as you see them in Renoise's pattern or phrase editor.

• Properties
  • is_empty : boolean
  • is_selected : boolean
  • number_value : integer
  • number_string : string
  • amount_value : integer
  • amount_string : string
• Functions
  • clear(self)
  • copy_from(self, other : renoise.EffectColumn)

Properties

is_empty : boolean

READ-ONLY True, when all effect column properties are empty.

is_selected : boolean

READ-ONLY True, when this column is selected in the pattern or phrase editor.

number_value : integer

0-65535 in the form 0x0000xxyy where xx=effect char 1 and yy=effect char 2

number_string : string

Range: ('00' - 'ZZ')

amount_value : integer

Range: (0 - 255)

amount_string : string

Range: ('00' - 'FF')

Functions

clear(self)

Clear the effect column.

copy_from(self, other : renoise.EffectColumn)

Copy the column's content from another column.

renoise.GroupTrack

Group track component of a Renoise song.

• Properties
  • type : renoise.Track.TrackType
  • name : string
  • name_observable : renoise.Document.Observable
  • color : RGBColor
  • color_observable : renoise.Document.Observable
  • color_blend : integer
  • color_blend_observable : renoise.Document.Observable
  • mute_state : renoise.Track.MuteState
  • mute_state_observable : renoise.Document.Observable
  • solo_state : boolean
  • solo_state_observable : renoise.Document.Observable
  • prefx_volume : renoise.DeviceParameter
  • prefx_panning : renoise.DeviceParameter
  • prefx_width : renoise.DeviceParameter
  • postfx_volume : renoise.DeviceParameter
  • postfx_panning : renoise.DeviceParameter
  • collapsed : boolean
  • collapsed_observable : renoise.Document.Observable
  • group_parent : renoise.GroupTrack
  • available_output_routings : string[]
  • output_routing : string
  • output_routing_observable : renoise.Document.Observable
  • output_delay : number
  • output_delay_observable : renoise.Document.Observable
  • max_effect_columns : integer
  • min_effect_columns : integer
  • max_note_columns : integer
  • min_note_columns : integer
  • visible_effect_columns : integer
  • visible_effect_columns_observable : renoise.Document.Observable
  • visible_note_columns : integer
  • visible_note_columns_observable : renoise.Document.Observable
  • volume_column_visible : boolean
  • volume_column_visible_observable : renoise.Document.Observable
  • panning_column_visible : boolean
  • panning_column_visible_observable : renoise.Document.Observable
  • delay_column_visible : boolean
  • delay_column_visible_observable : renoise.Document.Observable
  • sample_effects_column_visible : boolean
  • sample_effects_column_visible_observable : renoise.Document.Observable
  • available_devices : string[]
  • available_device_infos : AudioDeviceInfo[]
  • devices : renoise.AudioDevice[]
  • devices_observable : renoise.Document.ObservableList
  • members : renoise.Track[]
  • group_collapsed : boolean
• Functions
  • insert_device_at(self, device_path : string, device_index : integer)
  • delete_device_at(self, device_index : any)
  • swap_devices_at(self, device_index1 : integer, device_index2 : integer)
  • device(self, device_index : integer)
  • mute(self)
  • unmute(self)
  • solo(self)
  • column_is_muted(self, column_index : integer)
  • column_is_muted_observable(self, column_index : integer)
  • set_column_is_muted(self, column_index : integer, muted : boolean)
  • column_name(self, column_index : integer)
  • column_name_observable(self, column_index : integer)
  • set_column_name(self, column_index : integer, name : string)
  • swap_note_columns_at(self, column_index1 : integer, column_index2 : integer)
  • swap_effect_columns_at(self, column_index1 : integer, column_index2 : integer)
• Structs
• AudioDeviceInfo
  • Properties
    • path : string
    • name : string
    • short_name : string
    • favorite_name : string
    • is_favorite : boolean
    • is_bridged : boolean
  • Aliases
    • RGBColor

Properties

type : renoise.Track.TrackType

READ-ONLY

name : string

Name, as visible in track headers

name_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

color : RGBColor

A table of 3 bytes (ranging from 0 to 255) representing the red, green and blue channels of a color. {0xFF, 0xFF, 0xFF} is white {165, 73, 35} is the red from the Renoise logo

color_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

color_blend : integer

Range: (0 - 100) Color blend in percent

color_blend_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

mute_state : renoise.Track.MuteState

Mute and solo states. Not available for the master track.

mute_state_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

solo_state : boolean

solo_state_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

prefx_volume : renoise.DeviceParameter

READ-ONLY

prefx_panning : renoise.DeviceParameter

READ-ONLY

prefx_width : renoise.DeviceParameter

READ-ONLY

postfx_volume : renoise.DeviceParameter

READ-ONLY

postfx_panning : renoise.DeviceParameter

READ-ONLY

collapsed : boolean

Collapsed/expanded visual appearance.

collapsed_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

group_parent : renoise.GroupTrack

READ-ONLY

available_output_routings : string[]

READ-ONLY

output_routing : string

One of available_output_routings

output_routing_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

output_delay : number

Range: (-100.0-100.0) in ms

output_delay_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

max_effect_columns : integer

READ-ONLY 8 OR 0 depending on the track type

min_effect_columns : integer

READ-ONLY 1 OR 0 depending on the track type

max_note_columns : integer

READ-ONLY 12 OR 0 depending on the track type

min_note_columns : integer

READ-ONLY 1 OR 0 depending on the track type

visible_effect_columns : integer

1-8 OR 0-8, depending on the track type

visible_effect_columns_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

visible_note_columns : integer

0 OR 1-12, depending on the track type

visible_note_columns_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

volume_column_visible : boolean

volume_column_visible_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

panning_column_visible : boolean

panning_column_visible_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

delay_column_visible : boolean

delay_column_visible_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

sample_effects_column_visible : boolean

sample_effects_column_visible_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

available_devices : string[]

READ-ONLY FX devices this track can handle.

available_device_infos : AudioDeviceInfo[]

READ-ONLY Array of tables containing information about the devices.

devices : renoise.AudioDevice[]

READ-ONLY List of audio DSP FX.

devices_observable : renoise.Document.ObservableList

Track changes to document lists by attaching listener functions to it. NB: Notifiers will not broadcast changes made to list items, but only changes to the lists layout (items got added, removed, swapped).

members : renoise.Track[]

READ-ONLY All member tracks of this group, including subgroups and their tracks.

group_collapsed : boolean

Collapsed/expanded visual appearance of whole group.

Functions

insert_device_at(self, device_path : string, device_index : integer)

->renoise.AudioDevice

Insert a new device at the given position. device_path must be one of renoise.Track.available_devices.

delete_device_at(self, device_index : any)

Delete an existing device in a track. The mixer device at index 1 can not be deleted from any track.

swap_devices_at(self, device_index1 : integer, device_index2 : integer)

Swap the positions of two devices in the device chain. The mixer device at index 1 can not be swapped or moved.

device(self, device_index : integer)

->renoise.AudioDevice

Access to a single device by index. Use property devices to iterate over all devices and to query the device count.

mute(self)

Uses default mute state from the prefs. Not for the master track.

unmute(self)

solo(self)

column_is_muted(self, column_index : integer)

->boolean

Note column mutes. Only valid within (1-track.max_note_columns)

column_is_muted_observable(self, column_index : integer)

->renoise.Document.Observable

set_column_is_muted(self, column_index : integer, muted : boolean)

column_name(self, column_index : integer)

->string

Note column names. Only valid within (1-track.max_note_columns)

column_name_observable(self, column_index : integer)

->renoise.Document.Observable

set_column_name(self, column_index : integer, name : string)

swap_note_columns_at(self, column_index1 : integer, column_index2 : integer)

Swap the positions of two note or effect columns within a track.

swap_effect_columns_at(self, column_index1 : integer, column_index2 : integer)

Structs

AudioDeviceInfo

Audio device info

Properties

path : string

The device's path used by renoise.Track:insert_device_at

name : string

The device's name

short_name : string

The device's name as displayed in shortened lists

favorite_name : string

The device's name as displayed in favorites

is_favorite : boolean

true if the device is a favorite

is_bridged : boolean

true if the device is a bridged plugin

Aliases

RGBColor

{ 1 : integer, 2 : integer, 3 : integer }

A table of 3 bytes (ranging from 0 to 255) representing the red, green and blue channels of a color. {0xFF, 0xFF, 0xFF} is white {165, 73, 35} is the red from the Renoise logo

renoise.Instrument

• Constants
  • Tab
  • PhrasePlaybackMode
  • Layer
  • OverlapMode
  • NUMBER_OF_MACROS : integer
  • MAX_NUMBER_OF_PHRASES : integer
• Properties
  • active_tab : renoise.Instrument.Tab
  • active_tab_observable : renoise.Document.Observable
  • name : string
  • name_observable : renoise.Document.Observable
  • comments : string[]
  • comments_observable : renoise.Document.Observable
  • comments_assignment_observable : renoise.Document.Observable
  • show_comments_after_loading : boolean
  • show_comments_after_loading_observable : renoise.Document.Observable
  • macros_visible : boolean
  • macros_visible_observable : renoise.Document.Observable
  • macros : renoise.InstrumentMacro[]
  • pitchbend_macro : renoise.InstrumentMacro
  • modulation_wheel_macro : renoise.InstrumentMacro
  • channel_pressure_macro : renoise.InstrumentMacro
  • volume : number
  • volume_observable : renoise.Document.Observable
  • transpose : integer
  • transpose_observable : renoise.Document.Observable
  • trigger_options : renoise.InstrumentTriggerOptions
  • sample_mapping_overlap_mode : renoise.Instrument.OverlapMode
  • sample_mapping_overlap_mode_observable : renoise.Document.Observable
  • phrase_editor_visible : boolean
  • phrase_editor_visible_observable : renoise.Document.Observable
  • phrase_playback_mode : renoise.Instrument.PhrasePlaybackMode
  • phrase_playback_mode_observable : renoise.Document.Observable
  • phrase_program : integer
  • phrase_program_observable : renoise.Document.Observable
  • phrases : renoise.InstrumentPhrase[]
  • phrases_observable : renoise.Document.ObservableList
  • phrase_mappings : renoise.InstrumentPhraseMapping[]
  • phrase_mappings_observable : renoise.Document.ObservableList
  • samples : renoise.Sample[]
  • samples_observable : renoise.Document.ObservableList
  • sample_mappings : renoise.SampleMapping[]
  • sample_mappings_observable : renoise.Document.ObservableList
  • sample_modulation_sets : renoise.SampleModulationSet[]
  • sample_modulation_sets_observable : renoise.Document.ObservableList
  • sample_device_chains : renoise.SampleDeviceChain[]
  • sample_device_chains_observable : renoise.Document.ObservableList
  • midi_input_properties : renoise.InstrumentMidiInputProperties
  • midi_output_properties : renoise.InstrumentMidiOutputProperties
  • plugin_properties : renoise.InstrumentPluginProperties
• Functions
  • clear(self)
  • copy_from(self, instrument : renoise.Instrument)
  • macro(self, index : integer)
  • insert_phrase_at(self, index : integer)
  • delete_phrase_at(self, index : integer)
  • phrase(self, index : integer)
  • can_insert_phrase_mapping_at(self, index : integer)
  • insert_phrase_mapping_at(self, index : integer, phrase : renoise.InstrumentPhrase)
  • delete_phrase_mapping_at(self, index : integer)
  • phrase_mapping(self, index : integer)
  • insert_sample_at(self, index : integer)
  • delete_sample_at(self, index : integer)
  • swap_samples_at(self, index1 : integer, index2 : integer)
  • sample(self, index : integer)
  • sample_mapping(self, layer : renoise.Instrument.Layer, index : integer)
  • insert_sample_modulation_set_at(self, index : integer)
  • delete_sample_modulation_set_at(self, index : integer)
  • swap_sample_modulation_sets_at(self, index1 : any, index2 : any)
  • sample_modulation_set(self, index : integer)
  • insert_sample_device_chain_at(self, index : integer)
  • delete_sample_device_chain_at(self, index : integer)
  • swap_sample_device_chains_at(self, index1 : integer, index2 : integer)
  • sample_device_chain(self, index : integer)

Constants

Tab

{
    TAB_SAMPLES: integer = 1,
    TAB_PLUGIN: integer = 2,
    TAB_EXT_MIDI: integer = 3,
}

PhrasePlaybackMode

{
    PHRASES_OFF: integer = 1,
    PHRASES_PLAY_SELECTIVE: integer = 2,
    PHRASES_PLAY_KEYMAP: integer = 3,
}

Layer

{
    LAYER_NOTE_DISABLED: integer = 0,
    LAYER_NOTE_ON: integer = 1,
    LAYER_NOTE_OFF: integer = 2,
}

OverlapMode

{
    OVERLAP_MODE_ALL: integer = 0,
    OVERLAP_MODE_CYCLED: integer = 1,
    OVERLAP_MODE_RANDOM: integer = 2,
}

NUMBER_OF_MACROS : integer

MAX_NUMBER_OF_PHRASES : integer

Properties

active_tab : renoise.Instrument.Tab

Currently active tab in the instrument GUI (samples, plugin or MIDI).

active_tab_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

name : string

Instrument's name.

name_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

comments : string[]

Instrument's comment list. See renoise.song().comments for more info on how to get notified on changes and how to change it.

comments_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

comments_assignment_observable : renoise.Document.Observable

Notifier which is called as soon as any paragraph in the comments change.

show_comments_after_loading : boolean

Set this to true to show the comments dialog after loading a song

show_comments_after_loading_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

macros_visible : boolean

Macro parameter pane visibility in the GUI.

macros_visible_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

macros : renoise.InstrumentMacro[]

READ-ONLY Macro parameters. Array with size Instrument.NUMBER_OF_MACROS.

pitchbend_macro : renoise.InstrumentMacro

Access the MIDI pitch-bend macro

modulation_wheel_macro : renoise.InstrumentMacro

Access the MIDI modulation-wheel macro

channel_pressure_macro : renoise.InstrumentMacro

Access the MIDI channel pressure macro

volume : number

Range: (0 - math.db2lin(6))

volume_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

transpose : integer

Range: (-120 - 120). Global relative pitch in semi tones. Applied to all samples, MIDI and plugins in the instrument.

transpose_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

trigger_options : renoise.InstrumentTriggerOptions

Global trigger options (quantization and scaling options).

sample_mapping_overlap_mode : renoise.Instrument.OverlapMode

Sample mapping's overlap trigger mode.

sample_mapping_overlap_mode_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

phrase_editor_visible : boolean

Phrase editor pane visibility in the GUI.

phrase_editor_visible_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

phrase_playback_mode : renoise.Instrument.PhrasePlaybackMode

Phrase playback.

phrase_playback_mode_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

phrase_program : integer

Phrase playback program: 0 = Off, 1-126 = specific phrase, 127 = keymap.

phrase_program_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

phrases : renoise.InstrumentPhrase[]

READ-ONLY Phrases.

phrases_observable : renoise.Document.ObservableList

Track changes to document lists by attaching listener functions to it. NB: Notifiers will not broadcast changes made to list items, but only changes to the lists layout (items got added, removed, swapped).

phrase_mappings : renoise.InstrumentPhraseMapping[]

READ-ONLY Phrase mappings.

phrase_mappings_observable : renoise.Document.ObservableList

Track changes to document lists by attaching listener functions to it. NB: Notifiers will not broadcast changes made to list items, but only changes to the lists layout (items got added, removed, swapped).

samples : renoise.Sample[]

READ-ONLY Samples slots.

samples_observable : renoise.Document.ObservableList

Track changes to document lists by attaching listener functions to it. NB: Notifiers will not broadcast changes made to list items, but only changes to the lists layout (items got added, removed, swapped).

sample_mappings : renoise.SampleMapping[]

READ-ONLY Sample mappings (key/velocity to sample slot mappings). sample_mappings[LAYER_NOTE_ON/OFF][]. Sample mappings also can be accessed via ---@field samples[].sample_mapping

sample_mappings_observable : renoise.Document.ObservableList

Track changes to document lists by attaching listener functions to it. NB: Notifiers will not broadcast changes made to list items, but only changes to the lists layout (items got added, removed, swapped).

sample_modulation_sets : renoise.SampleModulationSet[]

READ-ONLY Sample modulation sets.

sample_modulation_sets_observable : renoise.Document.ObservableList

Track changes to document lists by attaching listener functions to it. NB: Notifiers will not broadcast changes made to list items, but only changes to the lists layout (items got added, removed, swapped).

sample_device_chains : renoise.SampleDeviceChain[]

READ-ONLY Sample device chains.

sample_device_chains_observable : renoise.Document.ObservableList

Track changes to document lists by attaching listener functions to it. NB: Notifiers will not broadcast changes made to list items, but only changes to the lists layout (items got added, removed, swapped).

midi_input_properties : renoise.InstrumentMidiInputProperties

READ-ONLY MIDI input properties.

midi_output_properties : renoise.InstrumentMidiOutputProperties

READ-ONLY MIDI output properties.

plugin_properties : renoise.InstrumentPluginProperties

READ-ONLY Plugin properties.

Functions

clear(self)

Reset, clear all settings and all samples.

copy_from(self, instrument : renoise.Instrument)

Copy all settings from the other instrument, including all samples.

macro(self, index : integer)

->instrument_macro : renoise.InstrumentMacro

Range: (1 - renoise.Instrument.NUMBER_OF_MACROS) Access a single macro by index. See also property macros.

insert_phrase_at(self, index : integer)

->new_phrase : renoise.InstrumentPhrase

Insert a new phrase behind the given phrase index (1 for the first one).

delete_phrase_at(self, index : integer)

Delete a new phrase at the given phrase index.

phrase(self, index : integer)

->renoise.InstrumentPhrase

Access a single phrase by index. Use properties 'phrases' to iterate over all phrases and to query the phrase count.

can_insert_phrase_mapping_at(self, index : integer)

->boolean

Returns true if a new phrase mapping can be inserted at the given phrase mapping index (see See renoise.song().instruments[].phrase_mappings). Passed phrase must exist and must not have a mapping yet. Phrase note mappings may not overlap and are sorted by note, so there can be max 119 phrases per instrument when each phrase is mapped to a single key only. To make up room for new phrases, access phrases by index, adjust their note_range, then call 'insert_phrase_mapping_at' again.

insert_phrase_mapping_at(self, index : integer, phrase : renoise.InstrumentPhrase)

->new_mapping : renoise.InstrumentPhraseMapping

Insert a new phrase mapping behind the given phrase mapping index. The new phrase mapping will by default use the entire free (note) range between the previous and next phrase (if any). To adjust the note range of the new phrase change its 'new_phrase_mapping.note_range' property.

delete_phrase_mapping_at(self, index : integer)

Delete a new phrase mapping at the given phrase mapping index.

phrase_mapping(self, index : integer)

->renoise.InstrumentPhraseMapping

Access to a phrase note mapping by index. Use property 'phrase_mappings' to iterate over all phrase mappings and to query the phrase (mapping) count.

insert_sample_at(self, index : integer)

->new_sample : renoise.Sample

Insert a new empty sample. returns the new renoise.Sample object. Every newly inserted sample has a default mapping, which covers the entire key and velocity range, or it gets added as drum kit mapping when the instrument used a drum-kit mapping before the sample got added.

delete_sample_at(self, index : integer)

Delete an existing sample.

swap_samples_at(self, index1 : integer, index2 : integer)

Swap positions of two samples.

sample(self, index : integer)

->renoise.Sample

Access to a single sample by index. Use properties 'samples' to iterate over all samples and to query the sample count.

sample_mapping(self, layer : renoise.Instrument.Layer, index : integer)

->renoise.SampleMapping

Access to a sample mapping by index. Use property 'sample_mappings' to iterate over all sample mappings and to query the sample (mapping) count.

insert_sample_modulation_set_at(self, index : integer)

->new_sample_modulation_set : renoise.SampleModulationSet

Insert a new modulation set at the given index

delete_sample_modulation_set_at(self, index : integer)

Delete an existing modulation set at the given index.

swap_sample_modulation_sets_at(self, index1 : any, index2 : any)

Swap positions of two modulation sets.

sample_modulation_set(self, index : integer)

->renoise.SampleModulationSet

Access to a single sample modulation set by index. Use property 'sample_modulation_sets' to iterate over all sets and to query the set count.

insert_sample_device_chain_at(self, index : integer)

->new_sample_device_chain : renoise.SampleDeviceChain

Insert a new sample device chain at the given index.

delete_sample_device_chain_at(self, index : integer)

Delete an existing sample device chain at the given index.

swap_sample_device_chains_at(self, index1 : integer, index2 : integer)

Swap positions of two sample device chains.

sample_device_chain(self, index : integer)

->renoise.SampleDeviceChain

Access to a single device chain by index. Use property 'sample_device_chains' to iterate over all chains and to query the chain count.

renoise.InstrumentDevice

Deprecated. Use renoise.InstrumentPluginDevice instead.

• Properties
  • name : string
  • short_name : string
  • presets : string[]
  • active_preset : integer
  • active_preset_observable : renoise.Document.Observable
  • active_preset_data : string
  • parameters : renoise.DeviceParameter[]
  • external_editor_available : boolean
  • external_editor_visible : boolean
  • device_path : string
• Functions
  • preset(self, index : integer)
  • parameter(self, index : integer)

Properties

name : string

READ-ONLY Device name.

short_name : string

READ-ONLY

presets : string[]

READ-ONLY

active_preset : integer

Preset handling. 0 when when none is active (or available)

active_preset_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

active_preset_data : string

raw XML data of the active preset

parameters : renoise.DeviceParameter[]

READ-ONLY

external_editor_available : boolean

READ-ONLY Returns whether or not the plugin provides its own custom GUI.

external_editor_visible : boolean

When the plugin has no custom GUI, Renoise will create a dummy editor for it which lists the plugin parameters. set to true to show the editor, false to close it

device_path : string

READ-ONLY Returns a string that uniquely identifies the plugin The string can be passed into: renoise.InstrumentPluginProperties:load_plugin()

Functions

preset(self, index : integer)

->string

Access to a single preset name by index. Use properties 'presets' to iterate over all presets and to query the presets count.

parameter(self, index : integer)

->renoise.DeviceParameter

Access to a single parameter by index. Use properties 'parameters' to iterate over all parameters and to query the parameter count.

renoise.InstrumentMacro

• Properties
  • name : string
  • name_observable : renoise.Document.Observable
  • value : number
  • value_observable : renoise.Document.Observable
  • value_string : string
  • value_string_observable : renoise.Document.Observable
  • mappings : renoise.InstrumentMacroMapping[]
  • mappings_observable : renoise.Document.ObservableList
• Functions
  • mapping(self, index : integer)

Properties

name : string

Macro name as visible in the GUI when mappings are presents.

name_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

value : number

Range: (0 - 1)

value_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

value_string : string

Range: (0 - 100)

value_string_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

mappings : renoise.InstrumentMacroMapping[]

READ-ONLY Macro mappings, target parameters

mappings_observable : renoise.Document.ObservableList

Track changes to document lists by attaching listener functions to it. NB: Notifiers will not broadcast changes made to list items, but only changes to the lists layout (items got added, removed, swapped).

Functions

mapping(self, index : integer)

->renoise.InstrumentMacroMapping

Access to a single attached parameter mapping by index. Use property 'mappings' to query mapping count.

renoise.InstrumentMacroMapping

• Constants
  • Scaling
• Properties
  • parameter : renoise.DeviceParameter
  • parameter_min : number
  • parameter_min_observable : renoise.Document.Observable
  • parameter_max : number
  • parameter_max_observable : renoise.Document.Observable
  • parameter_scaling : renoise.InstrumentMacroMapping.Scaling
  • parameter_scaling_observable : renoise.Document.Observable

Constants

Scaling

{
    SCALING_LOG_FAST: integer = 1,
    SCALING_LOG_SLOW: integer = 2,
    SCALING_LINEAR: integer = 3,
    SCALING_EXP_SLOW: integer = 4,
    SCALING_EXP_FAST: integer = 5,
}

Properties

parameter : renoise.DeviceParameter

READ-ONLY Linked parameter. Can be a sample FX- or modulation parameter. Never nil.

parameter_min : number

Range: (0 - 1)

parameter_min_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

parameter_max : number

Range: (0 - 1)

parameter_max_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

parameter_scaling : renoise.InstrumentMacroMapping.Scaling

Scaling which gets applied within the min/max range to set the dest value.

parameter_scaling_observable : renoise.Document.Observable

Track changes to document properties or general states by attaching listener functions to it.

renoise.InstrumentMidiInputProperties

• Properties
  • device_name : string
  • device_name_observable : renoise.Document.Observable
  • channel : integer
  • channel_observable : renoise.Document.Observable
  • note_range : integer[]
  • note_range_observable : renoise.Document.Observable
  • assigned_track : integer
  • assigned_track_observable : renoise.Document.Observable

Properties

device_name : string

When setting new devices, device names must be one of renoise.Midi.available_input_devices. Devices are automatically opened when needed. To close a device, set its name to "", e.g. an empty string.

device_name_observable : renoise.Document.Observable