Renoise Lua API 6.2 changes
Backwards Compatibility
The update mostly contains new functionality and thus is fully backwards compatible with API 6.1, apart from some minor compatibility changes due to the new LuaJIT interpreter. See below for more details.
LuaJIT
Renoise now uses LuaJIT, which is in general compatible with Lua 5.1. Using LuaJIT instead of the Standard Lua 5.1 brings substantial speed improvements for number crunching operations in Renoise tools. However, most tools won’t see a general speed increase as they primarily will spend time in Renoise’s internal functions.
Lua 5.1 Compatibility
- arg: LuaJIT does not set the magic
argvarargs variable, which already was deprected in Lua 5.1. Replace it withlocal arg = {...}instead. See luaargvs{...} on stackoverflow
- goto is a keyword (and new feature) in LuaJIT and thus can not be used as a variable name anymore.
LuaJIT Extensions
The LuaJIT FFI extension is disabled in Renoise. It’s far too easy to corrupt the application’s memory or cause other bad crashes with it.
However, JIT and other LuaJIT extensions are available in Renoise.
Changes in Renoise App, Song & Tool
See also raw API definition changes on github.
renoise.Application
New
---**READ-ONLY** Access keyboard modifier states.
@field key_modifier_flags ModifierFlags
---**READ-ONLY** Access to the application's color theme.
@field theme renoise.ApplicationTheme
---Fired, when *any* theme color changed. e.g. when a new theme got loaded
---or when theme colors got edited in the theme preferences.
@field theme_observable renoise.Document.Observable
---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:
---```md
------First Group Item
---Regular item
---```
---
---To create sub menus, define entries with a common path,
---using a colon as separator:
---```md
---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`.
---@see ToolMenuEntry
---
@class DialogMenuEntry
---Name and optional path of the menu entry
@field name string
---A function that is called as soon as the entry is clicked
@field invoke fun()
---Default: true.
---When false, the action will not be invoked and will be "greyed out".
@field active boolean?
---Default: false.
---When true, the entry will be marked as "this is a selected option"
@field selected boolean?
---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.
---@param dialog renoise.Dialog
---@param menu_entries DialogMenuEntry[]
---@param below_view? renoise.Views.View
function renoise.Application:show_menu(dialog, menu_entries, below_view) end
Changed
---Deprecated. Use `key_modifier_flags` instead
@field key_modifier_states table<string, string>
---Optional focus change notifier for a custom dialogs.
---Will be called when the dialog gains of loses key focus.
---You maybe want to initialize your dloag's (modifier) keyboard states here.
@alias FocusHandler fun(dialogs: renoise.Dialog, focused: boolean) : KeyEvent?
renoise.ApplicationWindow
New
---Disk Browser view as part of the *right frame* in the UI.
---To hide the entire frame, use `right_frame_is_visible` property.
@field disk_browser_category renoise.ApplicationWindow.DiskBrowserCategory
@field disk_browser_categorye_observable renoise.Document.Observable
---InstrumentProperties (below InstrumentBox)
@field instrument_properties_is_visible boolean
@field instrument_properties_is_visible_observable renoise.Document.Observable
@field instrument_properties_show_volume_transpose boolean
@field instrument_properties_show_trigger_options boolean
@field instrument_properties_show_scale_options boolean
@field instrument_properties_show_plugin boolean
@field instrument_properties_show_plugin_program boolean
@field instrument_properties_show_midi boolean
@field instrument_properties_show_midi_program boolean
@field instrument_properties_show_macros boolean
@field instrument_properties_show_phrases boolean
---
---SampleProperties (below SampleNavigator)
@field sample_properties_is_visible boolean
@field sample_properties_is_visible_observable renoise.Document.Observable
---Frame with Disk Browser and Instrument Box.
@field right_frame_is_visible boolean
@field right_frame_is_visible_observable renoise.Document.Observable
renoise.Song
New
---**READ-ONLY** The currently edited line in the currently edited phrase.
---Nil when no phrase is selected.
@field selected_phrase_line renoise.PatternLine?
---The currently edited line index in the currently edited phrase.
---0 when no phrase is selected.
@field selected_phrase_line_index integer
---**READ-ONLY** The currently edited column in the selected line in the
---currently edited phrase. Nil when no phrase is selected or when an effect
---column is selected.
@field selected_phrase_note_column renoise.NoteColumn?
---The currently edited column index in the selected line in the currently
---edited phrase. 0 when no phrase is selected or when an effect column
---is selected.
@field selected_phrase_note_column_index integer
---**READ-ONLY** The currently edited column in the selected line
---in the currently edited phrase. Nil when no phrase is selected or when
---a note column is selected.
@field selected_phrase_effect_column renoise.EffectColumn?
---The currently edited effect column index in the selected line in
---the currently edited phrase. 0 when no phrase is selected or when
---a note column is selected.
@field selected_phrase_effect_column_index integer
---**READ-ONLY** The currently edited sub column type within the selected
---note/effect column in the current phrase. 0 when no phrase is selected.
@field selected_phrase_sub_column_type renoise.Song.SubColumnType
---Same as `describe_undo`, but additionally this tries to merge the
---following changes to the document with the last one, if the description
---matches the last description and the given timeout was not reached
---since the last describe_batch_undo call.
---
---Calls to `describe_undo` from other tools, or from Renoise internally,
---will cancel batches and split the undo action.
---
---Batches can be useful to combine multiple changes in the document
---into a single undo/redo step, when the changes happen asynchroniously,
---for example a process
---sliced action (via Lua coroutines).
---@param description string
---@param timeout_ms number? Default: 2000
function renoise.Song:describe_batch_undo(description, timeout_ms) end
---True while an undo/redo action is invoked. This may be useful to check
---in notifiers, to figure out if the document currently changes because
---of an undo/redo operation.
function renoise.Song:is_undo_redoing() end
---Trigger the given pattern line index in the current pattern for
---preview purposes.
---This works similar to the Renoise `PlayCurrentLine` keyboard shortcut,
---but does now advance the playback position.
---
---If you want to preview a single track's note only, mute other tracks
---before triggering the pattern line. To stop the preview,
---invoke `stop` from the transport.
---
---Transport playback must be stopped for this to work.
---If it's not, an error is thrown.
---
---This is evaluated from the GUI thread, not a real-time thread, so
---timing will be a little bit wonky.
---Don't try to use this as a custom sequencer!
---
---@param line_index integer line index in current pattern.
function renoise.Song:trigger_pattern_line(line_index) end
---Trigger instrument playback with the specified note or a table
---of notes (a chord) and volume for preview purposes on the
---given track index.
---
---Send tracks can not play notes. When specifying a send track,
---notes will play on the master track instead.
---
---This is evaluated from the GUI thread, not a real-time thread,
---so timing will be a little bit wonky.
--- Only use this to **preview instruments** from tools and
---not as a sequencer.
---
---@param instrument_index integer The instrument to trigger.
---@param track_index integer The track to play the instrument on.
--- A single note or a table of notes in Range: (0 - 119). Default: 48.
---@param note (integer|(integer[]))?
---@param volume number? Volume in Range: (0 - 1). Default: 1.0.
function renoise.Song:trigger_instrument_note_on(
instrument_index, track_index, note, volume) end
---Stop instrument playback which previously got started via
---`trigger_instrument_note_on`.
---@param instrument_index integer The instrument to trigger.
---@param track_index integer The track to play the instrument on.
--- A single note or a table of notes in Range: (0 - 119). Default: 48.
---@param note (integer|(integer[]))?
function renoise.Song:trigger_instrument_note_off(
instrument_index, track_index, note) end
---Trigger a sample with the specified note and volume for
---preview purposes on the given track. This directly triggers
---the sample, bypassing the instrument's keyzone.
---
---Only use this to **preview samples** from tools and not
---as a sequencer.
---See also `trigger_instrument_note_on`.
---
---@param instrument_index integer The instrument to trigger.
---@param sample_index integer The sample to trigger.
---@param track_index integer The track to play the instrument on.
---@param note integer? A single note in Range: (0 - 119). Default: 48.
---@param volume number? Volume in Range: (0 - 1). Default 1.0
---Default: false.
---When true and a selection is set, play the selection instead of the whole
---sample. Also disables looping.
---@param use_selection boolean?
function renoise.Song:trigger_sample_note_on(
instrument_index, sample_index,
track_index, note, volume, use_selection) end
---Stops sample playback that previously got triggered
---via `trigger_sample_note_on`.
---@param instrument_index integer The instrument to trigger.
---@param sample_index integer The sample to trigger.
---@param track_index integer The track to play the instrument on.
---@param note integer? A single note in Range: (0 - 119). Default: 48.
function renoise.Song:trigger_sample_note_off(
instrument_index, sample_index, track_index, note) end
renoise.Instrument
New
---When true, act as MTS ESP client. Disables custom tunings.
@field mts_esp_tuning boolean
@field mts_esp_tuning_observable renoise.Document.Observable
---Array of custom pitch values relative to 1/1, used as custom tuning
---values for instrument sample playback. The root key is assumed
---to be middle C (48 in Renoise),
---The scale will be repeated, so only one octave of values should
---be defined. An octave may contain more or less than 12 notes.
---
---When set mts_esp_tuning is disabled. Set an empty table to disable
---custom tuning using default 12-ET tuning instead.
---
---Use property `tuning_name` to give your custom tuning a name.
---
---### examples:
---```lua
----- Andreas Werckmeister's temperament III (the most famous one, 1681)
---local well_tempered_tuning = {
--- 256/243, 1.117403, 32/27, 1.252827, 4/3, 1024/729,
--- 1.494927, 128/81, 1.670436, 16/9, 1.879241, 2/1
---}
---instrument.tuning = well_tempered_tuning
---```
@field tuning number[]
@field tuning_observable renoise.Document.Observable
---Name, as displayed in the UI for a custom tuning or a tuning
---loaded from a file.
@field tuning_name string
@field tuning_name_observable renoise.Document.Observable
renoise.InstrumentPhrase
New
---playback mode
@field playback_mode renoise.InstrumentPhrase.PlaybackMode
@field playback_mode_observable renoise.Document.Observable
---
---**READ-ONLY** Phrase script properties. Only used when `playback_mode` is
---set to `renoise.InstrumentPhrase.PLAY_SCRIPT`
@field script renoise.InstrumentPhraseScript
---
renoise.InstrumentPhraseScript
New
See API Docs.
renoise.SampleBuffer
Changed
---When param `undo_redo_enabled` is false, no undo/redo data is
---generated for the following changes. When undefined or true,
---the global "Enable Undo/Redo in Sample Editor" option is applied.
---@param undo_redo_enabled boolean?
function renoise.SampleBuffer:prepare_sample_data_changes(
undo_redo_enabled) end
renoise.DeviceParameter
New
---Fired when the device parameter name did change.
@field name_observable renoise.Document.ObservableString
renoise.Transport
New
---Transport Sync modes
---@enum renoise.Transport.SyncMode
renoise.Transport = {
SYNC_MODE_INTERNAL = 1,
SYNC_MODE_MIDI_CLOCK = 2,
SYNC_MODE_ABLETON_LINK = 3,
SYNC_MODE_JACK = 4
}
---Note: `SYNC_MODE_JACK` only is available on Linux. Trying to enable it on
---other platforms will fire an error.
@field sync_mode renoise.Transport.SyncMode
@field sync_mode_observable renoise.Document.Observable
---Get notified of loop block changes.
@field loop_block_enabled_observable renoise.Document.Observable
---Change metronome volume
@field metronome_volume number Range: (0 - math.db2lin(6))
@field metronome_volume_observable renoise.Document.Observable
---*READ-ONLY* true when sample sample dialog is visible and recording started.
@field sample_recording Boolean
---Sample recording pattern quantization On/Off.
@field sample_recording_sync_enabled boolean
@field sample_recording_sync_enabled_observable renoise.Document.Observable
---Start a new sample recording when the sample dialog is visible.
function renoise.Transport:start_sample_recording() end
---Stop sample recording when the sample dialog is visible and running
function renoise.Transport:stop_sample_recording() end
Changed
---Deprecated. Use `start_sample_recording` or `stop_sample_recording` instead.
function renoise.Transport:start_stop_sample_recording() end
renoise.Tool
New
---Invoked just before the application document (song) is saved.
---This is the last chance to make any changes that should be part of
---the saved song. You could for example write your tool data to
---`renoise.song().tool_data` here.
@field app_will_save_document_observable renoise.Document.Observable
renoise.ApplicationTheme
New
Read-only access to Renoise theme colors.
See API Docs.
Libraries
renoise.SQLite
New
Lua SQLite2 bindings to read from or write to in-memory or file SQLite databases. See API Docs.
Views
renoise.Views.View
New
---The dimensions of a view has to be larger than 0.
---For nested views you can also specify relative size, for
---example `vb:text { size = { width = "80%", height = 20}}`.
---The percentage values are relative to the view's parent size
---and will automatically update when the parent view's size
---changes.
@alias ViewSize {width: ViewDimension, height: ViewDimension }|
{ [1]:ViewDimension, [2]:ViewDimension }
---**Deprecated.** Use property `size` instead.
@field width ViewDimension
---**Deprecated.** Use property `size` instead.
@field height ViewDimension
@field size ViewSize
---Horizontal (x) or Vertical (y) position of a view within its
---parent view.
@alias ViewPosition integer
---The position of a view within its parent view.
---Only the `stack` layouts allows to freely position child
---views. Other layout views will automatically set the origin,
---but the origin then still can be read in for example mouse
---handlers.
@alias ViewOrigin { x: ViewPosition, y: ViewPosition }|
{ [1]:ViewPosition, [2]:ViewPosition }
---The cursor cursor for this view which appears on mouse hover.
---Using a "none" shape will use use underlying view's cursor or
---the default cursor.
@alias ViewCursorShape
---|"none"
---|"empty"
---|"default"
---|"change_value"
---|"edit_text"
---|"pencil"
---|"marker"
---|"crosshair"
---|"move"
---|"erase"
---|"play"
---|"drag"
---|"drop"
---|"nodrop"
---|"busy"
---|"resize_vertical"
---|"resize_horizontal"
---|"resize_edge_vertical"
---|"resize_edge_horizontal"
---|"resize_edge_diagonal_left"
---|"resize_edge_diagonal_right"
---|"extend_left"
---|"extend_right"
---|"extend_top"
---|"extend_bottom"
---|"extend_left_alias"
---|"extend_right_alias"
---|"extend_top_alias"
---|"extend_bottom_alias"
---|"zoom_vertical"
---|"zoom_horizontal"
---|"zoom"
---Event type of a `MouseEvent`.
@alias MouseEventType
---|"enter"
---|"exit"
---|"move"
---|"down"
---|"up"
---|"double"
---|"drag"
---|"wheel"
---Mouse button of a `MouseEvent` of type
---"up"|"down"|"double"|"drag".
@alias MouseEventButton
---|"left"
---|"right"
---|"middle"
---Mouse wheel direction in a `MouseEvent` of type "wheel".
@alias MouseEventWheelDirection
---|"up"
---|"down"
---|"left"
---|"right"
---Mouse event as passed to a layout view's "mouse_handler"
---function.
@class MouseEvent
---Mouse event type. Only enabled types are passed to the
---handler.
@field type MouseEventType
---For "up"|"down"|"double"|"drag" events, the mouse button
---which got pressed, nil for all other events.
@field button MouseEventButton?
---For "wheel" events, the wheel's direction, nil for all other
---events.
@field direction MouseEventWheelDirection?
---Mouse cursor position in relative coordinates to the layout.
@field position { x: number, y: number }
---Currently pressed (held down) keyboard modifier buttons.
@field modifier_flags { shift: boolean, control: boolean,
alt: boolean, meta: boolean }
---Currently pressed (held down) mouse buttons.
@field button_flags { left: boolean, right: boolean,
middle: boolean }
---List of sub views and possible layout subview's subviews,
---that are located below the mouse cursor. In other words: all
---views that are located below the mouse cursor.
---The list is orderd by containing the top-most visible view
---first, so you usually will need to check the first table
---entry only.
---
---NB: Only views that got created with the same view builder
---instance as the layout, and only subviews with valid
---viewbuilder "id"s will show up here!
@field hover_views { id: string, view: renoise.Views.View }[]
@alias MouseHandlerNotifierFunction fun(event: MouseEvent):
MouseEvent?
@alias MouseHandlerNotifierMemberFunction fun(
self: NotifierMemberContext, event: MouseEvent): MouseEvent?
@alias MouseHandlerNotifierMethod1 {[1]:NotifierMemberContext,
[2]:MouseHandlerNotifierMemberFunction}
@alias MouseHandlerNotifierMethod2 {[1]:MouseHandlerNotifierMemberFunction,
[2]:NotifierMemberContext}
---Optional mouse event handler for a view. return nil when the
---event got handled to stop propagating the event. return the
---event instance, as passed, to pass it to the next view in the
---view hirarchy.
@alias MouseHandler MouseHandlerNotifierFunction|
MouseHandlerNotifierMethod1|MouseHandlerNotifierMethod2
---The mouse event types that should be passed to your
---`mouse_handler` function.
---By default: `{ "down", "up", "double" }`
---Avoid adding event types that you don't use, especially
---"move" events as they do create quite some overhead. Also
---note that when enabling "drag", sub view controls can no
---longer handle drag events, even when you pass back the event
---in the handler, so only enable it when you want to completely
---override mouse drag behavior of *all* your content views.
@alias MouseEventTypes (MouseEventType[])
@field origin ViewOrigin
@field cursor ViewCursorShape
---Add a new child view to this view.
---@param child renoise.Views.View
function View:add_view(child) end
---Remove a child view from this view.
---@param child renoise.Views.View
function View:remove_view(child) end
---Swap position of two child views in this view. With a series
---of swaps views can be moved to any position in the parent.
---@param child1 renoise.Views.View
---@param child2 renoise.Views.View
function View:swap_views(child1, child2) end
Changed
---Deprecated. Use `add_view` instead
---@param child renoise.Views.View
function View:add_child(child) end
---Deprecated. Use `remove_view` instead
---@param child renoise.Views.View
function View:remove_child(child) end
---Deprecated. Use `swap_views` instead
---@param child1 renoise.Views.View
---@param child2 renoise.Views.View
function View:swap_childs(child1, child2) end
---### examples:
---```lua
-----Use the `views` property to specify child views in the viewbuilder:
---vb:row {
--- views = {
--- vb:button {
--- text = "Some Button"
--- }
--- }
---}
---
-----Previously it was possible to specify `views` as table array members,
-----which still is supported, but deprecated:
---vb:row {
--- vb:button {
--- text = "Some Button"
--- }
---}
@property views
renoise.Viewbuilder
New
---@see renoise.Views.Stack
---@param properties StackViewProperties?
---@return renoise.Views.Stack
function renoise.ViewBuilder:stack(properties) end
---@see renoise.Views.Canvas
---@param properties CanvasViewProperties?
---@return renoise.Views.Canvas
function renoise.ViewBuilder:canvas(properties) end
---@see renoise.Views.TextLink
---@param properties TextLinkViewProperties?
---@return renoise.Views.TextLink
function renoise.ViewBuilder:link(properties) end
---@see renoise.Views.ScrollBar
---@param properties ScrollBarProperties?
---@return renoise.Views.ScrollBar
function renoise.ViewBuilder:scrollbar(properties) end
renoise.Views.Bitmap
New
@field color BitmapColor
@field mode
---"custom_color" # Recolor the bitmap using a custom color set by the `color'
--- property. Use bitmaps with an alpha channel, such as PNG
--- bitmaps, for custom colored bitmaps.
renoise.Views.Button
New
--Setup the buttons text's or bitmap's alignment within the button.
@alias ButtonAlignment
---| "left" # aligned to the left
---| "right" # aligned to the right
---| "center" # center (default)
---When set, the unpressed button's background will be drawn in
---the specified color.
---A text color is automatically selected unless explicitly set,
---to make sure its always visible.
---Set color {0,0,0} to enable the theme colors for the button again.
@alias ButtonColor RGBColor|ThemeColor
---When set, the unpressed button's background text or bitmap will
---be drawn in the specified color.
---Set color {0,0,0} to enable the theme colors for the button again.
@alias ButtonSecondaryColor RGBColor|ThemeColor
---Get/set the style a button should be displayed with.
@alias ButtonStyle
---| "normal" # (Default)
---| "rounded" # rounded corners on all sides
---| "rounded_left" # rounded left side
---| "rounded_right" # rounded right side
---| "rounded_top" # rounded left side
---| "rounded_bottom" # rounded right side
@field align ButtonAlignment
@field font TextFontStyle
@field color ButtonColor
@field secondary_color ButtonSecondaryColor
@field style ButtonStyle
renoise.Views.Text
New
@alias TextFontStyle
---| "code" # monospace code font
---When set, the text will be drawn in the specified color.
---Set style to something else than "custom" or color to `{0, 0, 0}`
---to enable the default theme color for the text again.
@alias TextColor RGBColor|ThemeColor
---Setup the texts's orientation (writing direction).
@alias TextOrientation
---| "horizontal" # Draw from left to right (Default)
---| "horizontal-rl" # Draw from right to left
---| "vertical" # Draw from bottom to top
---| "vertical-tb" # Draw from top to bottom
@field color TextColor
@field orientation TextOrientation
renoise.Views.MultiLineText
New
---**READ-ONLY** The currently selected text, if any.
---Newlines (Windows, Mac or Unix styled) will use the unix newline format.
@alias TextMultilineSelectedString string
@field selected_text TextMultilineSelectedString
renoise.Views.MultiLineTextField
New
@field selected_text TextMultilineSelectedString
renoise.Views.Aligner
New
---ALigners can have custom backgrounds and mouse handlers now.
@field background ViewBackgroundStyle?
@field mouse_handler MouseHandler?
@field mouse_events MouseEventTypes?
@field views AlignerChildViews?
Changed
---**DEPRECATED** Use `background` property instead.
@field style ViewBackgroundStyle ####
renoise.Views.Rack
New
---Racks can have custom backgrounds and mouse handlers now.
@field background ViewBackgroundStyle?
@field mouse_handler MouseHandler?
@field mouse_events MouseEventTypes?
@field views RackChildViews?
Changed
**DEPRECATED** Use `background` property instead.
@field style ViewBackgroundStyle ####
renoise.Views.Stack
New
A Stack has no content on its own. It only stacks it’s child views.
The position of the child views in the stack can be freely set by using
the origin property of the views
See API Docs.
renoise.Views.ScrollBar
New
A special slider alike control to scroll through some content.
See API Docs.
Renoise.Views.TextLink
New
Shows a text string which is highlighted when hovering with the mouse,
and which can be clicked to perform some action.
To create a hyperlink alike text, add a notifier which opens an url via:
renoise.app():open_url("https://some.url.com")
See API Docs.
Renoise.Views.Canvas
New
A canvas view lets you draw and handle mouse events in a completely
customisable way.
Note: The content is cached in a texture and not hardware accelerated, so
it’s not suitable for animations, but for static content such as custom
backgrounds or bitmap-like views
See API Docs.