✒ Lua Api Changes For 2.8 & How To Upgrade Tools

Lua API changes:

[luabox]

REMOVED

– unused and confusing property
renoise.song().instruments[].samples[].base_note, observable
– is now ‘plugin_path’
renoise.song().instruments[].plugin_properties.plugin_name
– is now 'groove

renoise.song().transport.shuffle_


CHANGED

– some 'device_path’s have changed. See ‘tracks[].available_devices’
– for the actual native device paths
renoise.song().tracks[]:insert_device_at(device_path, device_index)

– volume/panning effect number/amount notation: from hex to 0-Z
renoise.song()patterns[].tracks[].lines[].note_columns[].volume_value
Old -> [number, 0-254, 255==Empty]
New -> [number, 0-127, 255==Empty when column value is <= 0x80 or is 0xFF,
i.e. is used to specify volume]
[number, 0-65535 in the form 0x0000xxyy where
xx=effect char 1 and yy=effect char 2,
when column value is > 0x80, i.e. is used to specify an effect]

renoise.song().patterns[].tracks[].lines[].note_columns[].volume_string
Old -> [string, ‘00’ - ‘FE’ or ‘…’]
New -> [string, ‘00’ - ‘ZF’ or ‘…’]

renoise.song().patterns[].tracks[].lines[].note_columns[].panning_value
Old -> [number, 0-254, 255==Empty]
New -> [number, 0-127, 255==Empty when column value is <= 0x80 or is 0xFF,
i.e. is used to specify pan]
[number, 0-65535 in the form 0x0000xxyy where
xx=effect char 1 and yy=effect char 2,
when column value is > 0x80, i.e. is used to specify an effect]

renoise.song().patterns[].tracks[].lines[].note_columns[].panning_string
Old -> [string, ‘00’ - ‘FE’ or ‘…’]
New -> [string, ‘00’ - ‘ZF’ or ‘…’]

renoise.song().patterns[].tracks[].lines[].effect_columns[].number_value
Old -> [number, 0-255]
New -> [number, 0-65535 in the form 0x0000xxyy where xx=effect char 1 and yy=effect char 2]

renoise.song().patterns[].tracks[].lines[].effect_columns[].number_string
Old -> [string, ‘00’ - ‘FF’]
New -> [string, ‘00’ - ‘ZZ’]
[/luabox]

Lua API additions:

[luabox]
– a file rename, which works across different devices as well
os.move(src, dest)

– extended disk browser flag
renoise.app().window.disk_browser_is_expanded, _observable

– track groups and collapsing
renoise.Track.TRACK_TYPE_GROUP
renoise.song().tracks[].collapsed, _observable
renoise.song().tracks[].group_parent
renoise.song().tracks[].available_device_infos[]
renoise.song().tracks[].members[]
renoise.song().tracks[].group_collapsed
renoise.song():insert_group_at(int index)
renoise.song():add_track_to_group(int track_index, int group_index)
renoise.song():delete_group_at(int index)

– get selected column (volume/pan/…) within a track
renoise.Song.SUB_COLUMN_NOTE
renoise.Song.SUB_COLUMN_INSTRUMENT
renoise.Song.SUB_COLUMN_VOLUME
renoise.Song.SUB_COLUMN_PANNING
renoise.Song.SUB_COLUMN_DELAY
renoise.Song.SUB_COLUMN_EFFECT_NUMBER
renoise.Song.SUB_COLUMN_EFFECT_AMOUNT
renoise.song().selected_sub_column_type

– get/set selection in the pattern
renoise.song().selection_in_pattern

– pattern aliases
renoise.song().patterns[].tracks[].is_alias
renoise.song().patterns[].tracks[].alias_pattern_index , _observable

– few more pattern sequence tools, sections & selection
renoise.song().sequencer:sort()
renoise.song().sequencer:sequence_is_start_of_section(sequence_index)
renoise.song().sequencer:set_sequence_is_start_of_section(sequence_index)
renoise.song().sequencer:sequence_is_start_of_section_observable(sequence_index)
renoise.song().sequencer:sequence_section_name(sequence_index)
renoise.song().sequencer:set_sequence_section_name(sequence_index, string)
renoise.song().sequencer:sequence_section_name_observable(sequence_index)
renoise.song().sequencer:sequence_is_part_of_section(sequence_index)
renoise.song().sequencer:sequence_is_end_of_section(sequence_index)
renoise.song().sequencer:sequence_sections_changed_observable()
renoise.song().sequencer:track_sequence_slot_is_selected(track_index, sequence_index)
renoise.song().sequencer:set_track_sequence_slot_is_selected(
renoise.song().sequencer.selection_range[], _observable

– device path accessors (to clone/copy a device)
renoise.song().tracks[].devices[].device_path

– instrument MIDI input properties
renoise.song().instruments[].midi_input_properties

– instrument sample envelopes
renoise.InstrumentEnvelope.PLAYMODE_POINTS = 1
renoise.InstrumentEnvelope.PLAYMODE_LINEAR = 2
renoise.InstrumentEnvelope.PLAYMODE_CUBIC = 3

renoise.InstrumentEnvelope.LOOP_MODE_OFF = 1
renoise.InstrumentEnvelope.LOOP_MODE_FORWARD = 2
renoise.InstrumentEnvelope.LOOP_MODE_REVERSE = 3
renoise.InstrumentEnvelope.LOOP_MODE_PING_PONG = 4

renoise.InstrumentEnvelope.MAX_NUMBER_OF_POINTS = 6
renoise.InstrumentEnvelope.MAX_NUMBER_OF_POINTS = 1000

renoise.InstrumentEnvelope.MIN_FADE_AMOUNT = 0
renoise.InstrumentEnvelope.MAX_FADE_AMOUNT = 4095

renoise.song().instruments[].sample_envelopes

renoise.song().instruments[].sample_envelopes.XXX:clear_points()
renoise.song().instruments[].sample_envelopes.XXX:copy_points_from(other_envelope object)
renoise.song().instruments[].sample_envelopes.XXX:has_point_at(time)
renoise.song().instruments[].sample_envelopes.XXX:add_point_at(time, value)
renoise.song().instruments[].sample_envelopes.XXX:remove_point_at(time)
renoise.song().instruments[].sample_envelopes.XXX.enabled, _observable
renoise.song().instruments[].sample_envelopes.XXX.play_mode, _observable
renoise.song().instruments[].sample_envelopes.XXX.length, _observable
renoise.song().instruments[].sample_envelopes.XXX.loop_mode, _observable
renoise.song().instruments[].sample_envelopes.XXX.loop_start, _observable
renoise.song().instruments[].sample_envelopes.XXX.loop_end, _observable
renoise.song().instruments[].sample_envelopes.XXX.sustain_enabled, _observable
renoise.song().instruments[].sample_envelopes.XXX.sustain_position, _observable
renoise.song().instruments[].sample_envelopes.XXX.fade_amount, _observable
renoise.song().instruments[].sample_envelopes.XXX.points, _observable
renoise.song().instruments[].sample_envelopes.XXX.points[].time
renoise.song().instruments[].sample_envelopes.XXX.points[].value

renoise.InstrumentEnvelopeLfo.MODE_OFF = 1
renoise.InstrumentEnvelopeLfo.MODE_SIN = 2
renoise.InstrumentEnvelopeLfo.MODE_SAW = 3
renoise.InstrumentEnvelopeLfo.MODE_PULSE = 4
renoise.InstrumentEnvelopeLfo.MODE_RANDOM = 5

renoise.InstrumentEnvelopeLfo.MIN_FREQUENCY = 0
renoise.InstrumentEnvelopeLfo.MAX_FREQUENCY = 127

renoise.InstrumentEnvelopeLfo.MIN_AMOUNT = 0
renoise.InstrumentEnvelopeLfo.MAX_AMOUNT = 127

renoise.InstrumentEnvelopeLfo.MIN_PHASE = 0
renoise.InstrumentEnvelopeLfo.MAX_PHASE = 180

renoise.song().instruments[].sample_envelopes.XXX.lfo:init()
renoise.song().instruments[].sample_envelopes.XXX.lfo:copy_from(other_lfo)
renoise.song().instruments[].sample_envelopes.XXX.lfo.mode, _observable
renoise.song().instruments[].sample_envelopes.XXX.lfo.phase, _observable
renoise.song().instruments[].sample_envelopes.XXX.lfo.frequency, _observable
renoise.song().instruments[].sample_envelopes.XXX.lfo.amount, _observable

renoise.InstrumentEnvelopeFollower.MIN_ATTACK = 1
renoise.InstrumentEnvelopeFollower.MAX_ATTACK = 180

renoise.InstrumentEnvelopeFollower.MIN_RELEASE = 1
renoise.InstrumentEnvelopeFollower.MAX_RELEASE = 127

renoise.InstrumentEnvelopeFollower.MIN_AMOUNT = -127
renoise.InstrumentEnvelopeFollower.MAX_AMOUNT = 127

renoise.song().instruments[].sample_envelopes.XXX.follower:init()
renoise.song().instruments[].sample_envelopes.XXX.follower:copy_from(other_follower)
renoise.song().instruments[].sample_envelopes.XXX.follower.enabled, _observable
renoise.song().instruments[].sample_envelopes.XXX.follower.attack, _observable
renoise.song().instruments[].sample_envelopes.XXX.follower.release, _observable
renoise.song().instruments[].sample_envelopes.XXX.follower.amount, _observable
renoise.song().instruments[].sample_envelopes:init()
renoise.song().instruments[].sample_envelopes:copy_from(other_sample_envelopes)
renoise.song().instruments[].sample_envelopes.volume
renoise.song().instruments[].sample_envelopes.pan
renoise.song().instruments[].sample_envelopes.pitch
renoise.song().instruments[].sample_envelopes.cutoff
renoise.song().instruments[].sample_envelopes.resonance
renoise.song().instruments[].sample_envelopes.filter_type, _observable

renoise.song().instruments[].sample_envelopes.volume/pan/pitch:init()
renoise.song().instruments[].sample_envelopes.volume/pan/pitch:copy_from(other_envelope object)
renoise.song().instruments[].sample_envelopes.volume/pan/pitch.lfo1
renoise.song().instruments[].sample_envelopes.volume/pan/pitch.lfo2
renoise.song().instruments[].sample_envelopes.cutoff/resonance:init()
renoise.song().instruments[].sample_envelopes.cutoff/resonance:copy_from(other_envelope object)

renoise.song().instruments[].sample_envelopes.cutoff/resonance.lfo
renoise.song().instruments[].sample_envelopes.cutoff/resonance.follower

renoise.song().instruments[].midi_input_properties.device_name, _observable
renoise.song().instruments[].midi_input_properties.channel, _observable
renoise.song().instruments[].midi_input_properties.assigned_track, _observable

renoise.song().instruments[].plugin_properties.available_plugin_infos[]
renoise.song().instruments[].plugin_properties.plugin_device.device_path
[/luabox]

Updated documentation files:

Renoise 2.8 comes with the updated API reference. You will find it it in the “Scripting Tool & Editor”'s “Resource Scripts” node.
A pretty HTML API reference is available too: https://xrnx.googlecode.com/files/XrnxStarterPack280.zip

How to upgrade your Tools to Renoise 2.8 (API_VERSION 3):

Renoise will try to automatically upgrade old tools when possible. It does so by checking if any of the changed or removed API functions (see list above) are present. If they are present, the tool can’t be auto-upgraded and will be disabled.

The auto-upgrader can’t deeply check how the API is used by your script. It only does a raw text search, so even if upgrading succeeded there is a chance your tool might still not work. Even when upgrading succeeded, please do test all your tools in Renoise 2.8 and provide new versions to your users.

A few tips on how to get your tools ready for Renoise 2.8:

  • First open the manifest.xml file of your tool and set to 3 (Renoise 2.7’s was 2)
  • remove the node from the manifest XML (if it was autoupgraded)
  • Check/search for any of the changed API function listed above and fix/replace them
  • Open Renoise and check if your tool was disabled by Renoise. This will happen when auto-upgrading failed. You can enable it again in the “Tool Browser”.
  • Test the tool, verify the changes you’ve made to the Lua file

Looks good! :)

I especially like the addition of API access to instrument envelopes.

ReSynth3 is definitely on the cards.

If you were an Alpha tester, we could have enjoyed ReSynth3 today :ph34r:

Thanks a lot for awesome updates. The DSP improvements will open up lots of new possibilities, given this means that the dsp name string (or something) corresponds to .available_devices.

EDIT: Confirmed. I love you :)

Apologies if this is painfully obvious, but how do I see the lua api changes from within the scripting terminal and editor window. I only see the 2.7 api inside of 2.8. http://code.google.com/p/xrnx/ seems to only have a 2.7 starter pack.

Btw,the aliases are great.

Embarassing, the 2.8 api seems to be packaged right in Resource Scripts. My bad.

do you have a Windows/Linux path for that?
OSX is Renoise_Reg_Intel64.app/Contents/Resources/Scripts/Documentation/*

XRNX repository is now up to date as well. And the XRNX started pack contains a pretty HTML API reference as well: https://xrnx.googlecode.com/files/XrnxStarterPack280.zip

missing from this list is:
renoise.song().instruments[].samples[].autofade, _observable

Will it be possible to code a basic arpeggiator / transgater within resynth, based on point-based volume envelopes (for the transgater) and pitch envelopes (for the arp itself) ?

That make a good standalone tool, besides dblue’s automation envelopes from note’s script, there is no script dealing with generating envelopes!