✒ Lua API version 6 to 6.1 changes

Renoise Tool Development
1

Renoise.API.lua

-- Bumped to 6.1
renoise.API_VERSION 
  -> [number]

Renoise.Document.API.lua

-- Serialize the whole document tree to a XML string. 
doc:to_string()
  -> [string]
-- Parse document tree from the given string data. See doc:load_from for details
-- about how properties are parsed and errors are handled.
doc:from_string(string)
  -> [boolean, error_String]

Renoise.ScriptingTool.API.lua

-- Invoked when the tool finished loading/initializing and no errors happened. When
-- the tool has preferences, they are loaded here as well when the notification fires,
-- but 'renoise.song()' may not yet be available.
-- See also 'renoise.tool().app_new_document_observable'.
renoise.tool().tool_finished_loading_observable
  -> [renoise.Document.Observable object]

-- Invoked right before a tool gets unloaded: either because it got disabled, reloaded
-- or the application exists. You can cleanup resources or connections to other devices
-- here if necessary.
renoise.tool().tool_will_unload_observable
  -> [renoise.Document.Observable object]

Renoise.Song.API.lua

song

-- Inject/fetch custom XRNX scripting tool data into the song. Can only be called
-- from scripts that are running in Renoise scripting tool bundles; attempts to
-- access the data from e.g. the scripting terminal will result in an error.
-- Returns nil when no data is present.
--
-- Each tool gets it's own data slot in the song, which is resolved by the tool's
-- bundle id, so this data is unique for every tool and persistent accross tools
-- with the same bundle id (but possibly different versions).
-- If you want to store renoise.Document data in here, you can use the
-- renoise.Document's 'to_string' and 'from_string' functions to serialize the data.
-- Alternatively, write your own serializers for your custom data.
renoise.song().tool_data
  -> [string or nil]

instruments

-- Valid object for successfully loaded plugins, otherwise nil. Alias plugin
-- instruments of FX will return the resolved device, will link to the device
-- the alias points to.
-- The observable is fired when the device changes: when a plugin gets loaded or
-- unloaded or a plugin alias is assigned or unassigned.
renoise.song().instruments[].plugin_properties.plugin_device, _observable
 -> [renoise.InstrumentPluginDevice object or renoise.AudioDevice object or nil]

-- Valid for loaded and unloaded plugins.
renoise.song().instruments[].plugin_properties.alias_instrument_index, _observable
  -> [read-only, number or 0 (when no alias instrument is set)]
renoise.song().instruments[].plugin_properties.alias_fx_track_index, _observable
  -> [read-only, number or 0 (when no alias FX is set)]
renoise.song().instruments[].plugin_properties.alias_fx_device_index, _observable
  -> [read-only, number or 0 (when no alias FX is set)]

-- Valid for loaded and unloaded plugins. target instrument index or 0 of the 
-- plugin's MIDI output (when present)
renoise.song().instruments[].plugin_properties.midi_output_routing_index, _observable
  -> [read-only, number. 0 when no routing is set]

sample_modulation_sets

-- DEPRECATED: use 'is_active' instead
renoise.song().instruments[].sample_modulation_sets[].devices[].enabled, _observable
  -> [boolean]
-- Enable/bypass the device.
renoise.song().instruments[].sample_modulation_sets[].devices[].is_active, _observable
  -> [boolean, not active = bypassed]

-- Maximize state in modulation chain.
renoise.song().instruments[].sample_modulation_sets[].devices[].is_maximized, _observable
  -> [boolean]

-- Scaling mode.
renoise.song().instruments[].sample_modulation_sets[].devices[].scaling, _observable
  -> [enum = SCALING]
-- Delay.
renoise.song().instruments[].sample_modulation_sets[].devices[].delay
-> [renoise.DeviceParameter object, 0-1]

device_names

-- The device name as displayed in browser when paths are hidden or in the mixer
renoise.song().tracks[].devices[].short_name
  -> [read-only, string]

renoise.song().instruments[].sample_modulation_sets[].devices[].short_name
  -> [read-only, string]

renoise.song().instruments[].plugin_properties.plugin_device.short_name
  -> [read-only, string]

Renoise.ViewBuilder.API.lua

-- Get/set inc/dec step amounts when clicking the <> buttons.
-- First value is the small step (applied on left clicks), second value is the
-- big step (applied on right clicks)
valuebox.steps
  -> [{1=Number,2=Number}]

slider.steps
  -> [{1=Number,2=Number}]

-- Get/set the default value (applied on double-click).
slider.default
  -> [number]

minislider.default
   -> [number]
 
rotary.default
  -> [number]
8 Likes
4

This is great!

What does this exactly mean:

-- Inject/fetch custom XRNX scripting tool data into the song. Can only be called
-- from scripts that are running in Renoise scripting tool bundles; attempts to
-- access the data from e.g. the scripting terminal will result in an error.
-- Returns nil when no data is present.

Tools only with the namespace com.renoise are allowed to store data here? Or any namespace? So accessing renoise.song().tool_data automatically maps to the appropriate song xml node using the bundle id, correct?

5

Yes, exactly. Each tool loads/saves its own data in the song as the tool data in the song in memorized per tool id under the hood. A tool can also not access other tool’s data.

3 Likes
6

@taktik Is it possible that in the tool section of renoise.com api version 6.1 will then show “renoise 3.2”? Also the order of the uploads does not seem to have any effect on the tools’ page.

7

– Get/set the default value (applied on double-click).
slider.default
→ [number]

minislider.default
→ [number]

rotary.default
→ [number]

That’s so much better!! It was a bit annoying having to have all sliders/knobs default to 0. This simplifies it a lot!

1 Like
8

@taktik Thank you very much for continuing to improve the API! You have made me happy the whole year! For my part, I will continue to report if I find something wrong in the code. Please keep looking at possible improvements. I am using the API a lot lately. So this makes me very happy.

I know that there are still essential things missing in the modulation_set section, among other access details to certain panels that I miss.

Finding small errors is tedious, but very annoying when you intend to build a tool. I realize that maintaining an API like this is a huge job. Thanks a lot!

.default_value is quite a blessing.

I still miss the sliders with the panning style: slider.style

slider.style
→ [string]
– normal
– panning (or centered)
– inverse (maybe this also?)

Thank you very much for attending us!

1 Like