✒ Udated Api Docs For Renoise 2.7 + How To Upgrade Old Scripts

We’ve increased the renoise.API version with the 2.7 release, which means that old scripts from Renoise 2.6 will no longer work in Renoise 2.7. Such renoise.API changes will not necessary happen with every new Renoise release, but now happened because we changed far too much in the instrument and sample bindings to make those fully backwards compatible.

Most scripts will still work though, will not need any changes, beside of updating the in its manifest.xml. If a tool does not mess with instruments and samples its very very likely that this is the only thing you need to change for Renoise 2.7. See below for some tips how to check/update your tools for 2.7.

That we need to upgrade old tools to make them work now sucks, but unfortunately there’s no way to automatically detect if a script will work or not with the new API. At some time we should make this easier, and add a tools auto-updating mechanism to Renoise, so you don’t have to update tools manually with every release, but scripting had not much priority in this release, so we have to postpone this to another release (or write a tool which updates other tools ;) )

Update documentation:

You’ll find the updated API docs attached. In the attached zip is also a diff which highlights changes made from 2.6 to 2.7. Both can also be viewed online (see links below).

Text Version:
1777 LUA_API_Documentation_27.zip

HTML Version:
1816 LUA_API_Documentation_27_HTML.zip

Online diff of 26->2.7 API changes : https://code.google.com/p/xrnx/source/detail?r=931
Browse updated online Docs here: https://code.google.com/p/xrnx/source/browse/trunk/Documentation

API changes:

New features/changed features overview:

  • CHANGED aligner/rack:resize is redundant now.
    The function is still present, but deprecated and will do nothing. We did not removed it to make upgrading to 2.7 a bit easier. rack views did only auto expand in API_VERSION 1, will now expand and shrink automatically - always. Aligner views will now always be automatically resized with its parent. This was not always the case in the previous API version.

  • CHANGED sample buffers and sample lists may be read-only now with the slicing:
    If you are modifying sample data, or create new sample buffers, first check if a sample is an alias -> renoise.song().instruments[].samples[].is_slice_alias. If a sample is a slice alias, then you can either change the master sample: instruments[].samples[1] (which will wipe all slices though), or should bail out and not modify anything in your tool.

Sliced sample lists are also read-only (you can’t insert/delete/reorder samples). Test #samples[1].slice_markers > 1) to find out if sample is sliced.

(see renoise.SampleBuffer for more details please)

  • CHANGED sample_buffer.prepare_sample_data_changes MUST be called before sample_buffer.finalize_sample_data_changes is called:

– change sample data

to ensure undo/redo works (see renoise.SampleBuffer for more details please)

  • REMOVED renoise.song().instruments[].split_map[] (replaced with the new sample mapping bindings)

  • context menu identifiers: REMOVED “Instrument Box Samples”, ADDED “Sample List” (new sample list view context menu) and “Sample Mappings” (sample key zone right-click menu)

  • NEW sample slices and new sample mappings can be fully accessed via the API (see renoise.Instrument and renoise.Sample docs)

  • NEW global rawequal() can now compare Lua class and Renoise API objects object identity (rawequal(renoise.song().track[1], renoise.song().track[1] -> true)

  • NEW multiline_text.edit_mode and text.edit_mode (set focus/edit mode for text fields)

  • NEW renoise.app().window.mixer_view_post_fx, observable

  • NEW renoise.song().tracks[].devices[].parameters[].is_midi_mapped, _observable (true when a parameter has a custom MIDI mapping)

  • NEW nearly every list property in the song (like renoise.song.tracks[]) has a function which accesses only one item by index: (-> renoise.song:track()). This merely is a performance optimization help for tools. If you only need one single item from a list, this avoids that the whole list is loaded/put on the stack, but only the item you need. Most likely is relevant with pattern lines and pattern line columns, else will hardly make a difference but was added to keep things consistent.

Dealing with multiple Script Versions on http://tools.renoise.com

It will be possible to upload multiple version of your scripts for multiple API/Renoise versions. So we can see at a glance which tools are available for which version of Renoise. This currently does not work, but WILL work soon. We’ll let you know here. Till we’ve updated the tools page, use the XRNX forum for new tool announcements and test please.

Let us know if you have any questions please.

Hi Taktik!

number of revision

kpanic@hpinux:~/.renoise/V2.7.0/Scripts$ svn up
At revision 931.

Error message:

Failed to initialize custom MIDI actions from the user preferences: ‘/home/kpanic/.renoise/V2.7.0/Scripts/GlobalMidiActions.lua’.

The script either contains errors or the file is out of date, was written for an older version of Renoise.

In case it’s out of date, use the applications default MIDI mapping script at ‘/usr/local/share/renoise-2.7.0/Scripts/GlobalMidiActions.lua’ as new template, remove the file, or fix the errors listed below.

Script Error:
no static ‘MIDDLE_FRAME_INSTRUMENT_EDITOR’ in class ‘ApplicationWindow’
stack traceback:
[C]: ?
GlobalMidiActions.lua:1986: in main chunk

no local changes

kpanic@hpinux:~/.renoise/V2.7.0/Scripts$ svn diff GlobalMidiActions.lua

thanks for renoise 2.7.0b1!

Thanks. Updated/fixed in r932.

Small bump for an updated HTML version of the 2.7 API docs (thanks to conner_bw):

HTML Version:
1816 LUA_API_Documentation_27_HTML.zip

Just a small question to be sure: Since Renoise 2.7 allows renaming of devices i did fear at first that i have to update quite a bit in my scripts, but from my tests it seems that scripts always get the real device names. Am i right with this assumption or is there something further to lookout for regarding the names?

Yes, “renoise.song().tracks[].devices[].name” is not the custom name, but the something like an identifier. Actually we forgot to publish the custom name as well.
Will add a “renoise.song().tracks[].devices[].display_name, observable” and also allow changing it from scripts.

Perfect, all good then with my scripts for now.

Great that you implemented pre/post fx observable :slight_smile: Integrated this into FaderPort driver today !

Have a question:

Since the automation editor allows higher resolution automation points I was wondering if it was possible for
scripts to insert points at intermediate positions, too. Right now it seems that the “time” parameter
is limited to pattern lines.

Yes, this is possible. See Renoise.Song.API.lua / renoise.PatternTrackAutomation Docs for details please.

oki, I see. It’s done via x/256 fractions. Thank you

– General remarks: Automation “time” is specified in lines + optional 1/256
– line fraction for the sub line grid. The sub line grid has 256 units per
– line. All times are internally quantized to this sub line grid.
– For example a time of 1.5 means: line 1 with a note column delay of 128