renoise.Song

Renoise's main document - the song.

Constants
- SubColumnType
- MAX_NUMBER_OF_INSTRUMENTS : integer
Properties
Functions
Structs
PatternSelection
- Properties
PhraseSelection
- Properties
RenderOptions
- Properties

Constants

SubColumnType

{
    SUB_COLUMN_NOTE: integer = 1,
    SUB_COLUMN_INSTRUMENT: integer = 2,
    SUB_COLUMN_VOLUME: integer = 3,
    SUB_COLUMN_PANNING: integer = 4,
    SUB_COLUMN_DELAY: integer = 5,
    SUB_COLUMN_SAMPLE_EFFECT_NUMBER: integer = 6,
    SUB_COLUMN_SAMPLE_EFFECT_AMOUNT: integer = 7,
    SUB_COLUMN_EFFECT_NUMBER: integer = 8,
    SUB_COLUMN_EFFECT_AMOUNT: integer = 9,
}

MAX_NUMBER_OF_INSTRUMENTS : `integer`

Properties

file_name : `string`

READ-ONLY When the song is loaded from or saved to a file, the absolute path and name to the XRNS file, otherwise an empty string.

artist : `string`

Song Comments

artist_observable : `renoise.Document.Observable`

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

name : `string`

name_observable : `renoise.Document.Observable`

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

comments : `string`[]

Note: All property tables of basic types in the API are temporary copies. In other words comments = { "Hello", "World" } will work, comments[1] = "Hello"; renoise.song().comments[2] = "World" will not work.

comments_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).

comments_assignment_observable : `renoise.Document.Observable`

READ-ONLY Notifier 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.

tool_data : `string?`

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 across 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.

rendering : `boolean`

READ-ONLY True while rendering is in progress.

rendering_progress : `number`

Range: (0.0 - 1.0)

transport : `renoise.Transport`

READ-ONLY

sequencer : `renoise.PatternSequencer`

READ-ONLY

pattern_iterator : `renoise.PatternIterator`

READ-ONLY

sequencer_track_count : `integer`

READ-ONLY number of normal playback tracks (non-master or sends) in song.

send_track_count : `integer`

-READ-ONLY number of send tracks in song.

instruments : `renoise.Instrument`[]

READ-ONLY Instrument arrays

instruments_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).

patterns : `renoise.Pattern`[]

READ-ONLY Pattern arrays

patterns_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).

tracks : `renoise.Track`[]

READ-ONLY Track array

tracks_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).

selected_instrument : `renoise.Instrument`

READ-ONLY Selected in the instrument box.

selected_instrument_observable : `renoise.Document.Observable`

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

selected_instrument_index : `integer`

READ-ONLY Selected instrument index in the instrument box.

selected_instrument_index_observable : `renoise.Document.Observable`

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

selected_phrase : `renoise.InstrumentPhrase`

READ-ONLY Selected phrase the instrument's phrase map piano view.

selected_phrase_observable : `renoise.Document.Observable`

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

selected_phrase_index : `integer`

READ-ONLY Selected phrase index the instrument's phrase map piano view.

selected_sample : `renoise.Sample`

READ-ONLY Selected in the instrument's sample list. Only nil when no samples are present in the selected instrument.

selected_sample_observable : `renoise.Document.Observable`

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

selected_sample_index : `integer`

READ-ONLY Selected sample index in the instrument's sample list. Only 0 when no samples are present in the selected instrument.

selected_sample_modulation_set : `renoise.SampleModulationSet`

READ-ONLY Selected in the instrument's modulation view.

selected_sample_modulation_set_observable : `renoise.Document.Observable`

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

selected_sample_modulation_set_index : `integer`

READ-ONLY Selected modulation set index in the instrument's modulation view.

selected_sample_device_chain : `renoise.SampleDeviceChain`

READ-ONLY Selected in the instrument's effects view.

selected_sample_device_chain_observable : `renoise.Document.Observable`

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

selected_sample_device_chain_index : `integer`

READ-ONLY Selected chain index in the instrument's effects view.

selected_sample_device : `renoise.AudioDevice`

READ-ONLY Selected in the sample effect mixer.

selected_sample_device_observable : `renoise.Document.Observable`

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

selected_sample_device_index : `integer`

READ-ONLY Selected device index in the sample effect mixer.

selected_track : `renoise.Track`

READ-ONLY Selected in the pattern editor or mixer.

selected_track_observable : `renoise.Document.Observable`

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

selected_track_index : `integer`

READ-ONLY Selected track index in the pattern editor or mixer.

selected_track_index_observable : `renoise.Document.Observable`

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

selected_track_device : `renoise.AudioDevice`

READ-ONLY Selected in the track DSP chain editor.

selected_track_device_observable : `renoise.Document.Observable`

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

selected_track_device_index : `integer`

READ-ONLY Selected device index in the track DSP chain editor.

selected_device : `renoise.AudioDevice`

Deprecated. READ-ONLY Use 'selected_track_device' instead.

selected_device_observable : `renoise.Document.Observable`

Deprecated. Use 'selected_track_device_observable' instead.

selected_device_index : `integer`

Deprecated. READ-ONLY Use 'selected_track_device_index' instead.

selected_parameter : `renoise.DeviceParameter`

Deprecated. READ-ONLY Use 'selected_automation_parameter' instead.

selected_parameter_observable : `renoise.Document.Observable`

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

selected_automation_parameter : `renoise.DeviceParameter`

Selected parameter in the automation editor. When setting a new parameter, parameter must be automateable and must be one of the currently selected track device chain.

selected_automation_parameter_observable : `renoise.Document.Observable`

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

selected_automation_device : `renoise.AudioDevice`

READ-ONLY Parent device of 'selected_automation_parameter'.

selected_automation_device_observable : `renoise.Document.Observable`

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

selected_pattern : `renoise.Pattern`

READ-ONLY The currently edited pattern.

selected_pattern_observable : `renoise.Document.Observable`

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

selected_pattern_index : `integer`

READ-ONLY The currently edited pattern index.

selected_pattern_index_observable : `renoise.Document.Observable`

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

selected_pattern_track : `renoise.PatternTrack`

READ-ONLY The currently edited pattern track object. and selected_track_observable for notifications.

selected_pattern_track_observable : `renoise.Document.Observable`

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

selected_sequence_index : `integer`

The currently edited sequence position.

selected_sequence_index_observable : `renoise.Document.Observable`

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

selected_line : `renoise.PatternLine`

READ-ONLY The currently edited line in the edited pattern.

selected_line_index : `integer`

selected_note_column : `renoise.NoteColumn`

READ-ONLY The currently edited column in the selected line in the edited sequence/pattern. Nil when an effect column is selected.

selected_note_column_index : `integer`

selected_effect_column : `renoise.EffectColumn`

READ-ONLY The currently edited column in the selected line in the edited sequence/pattern. Nil when a note column is selected.

selected_effect_column_index : `integer`

selected_sub_column_type : `renoise.Song.SubColumnType`

READ-ONLY The currently edited sub column type within the selected note/effect column.

selection_in_pattern : `PatternSelection?`

Read/write access to the selection in the pattern editor.

Line indexes are valid from 1 to patterns[].number_of_lines Track indexes are valid from 1 to #tracks Column indexes are valid from 1 to (tracks[].visible_note_columns + tracks[].visible_effect_columns)

When setting the selection, all members are optional. Combining them in various different ways will affect how specific the selection is. When selection_in_pattern returns nil or is set to nil, no selection is present.

examples:
renoise.song().selection_in_pattern = {}
  --> clear
renoise.song().selection_in_pattern = { start_line = 1, end_line = 4 }
  --> select line 1 to 4, first to last track
renoise.song().selection_in_pattern =
  { start_line = 1, start_track = 1, end_line = 4, end_track = 1 }
  --> select line 1 to 4, in the first track only

selected_phrase_line : `renoise.PatternLine`

READ-ONLY The currently edited line in the currently edited phrase. Nil when no phrase is selected.

selected_phrase_line_index : `integer`

The currently edited line index in the currently edited phrase. 0 when no phrase is selected.

selected_phrase_note_column : `renoise.NoteColumn`

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.

selected_phrase_note_column_index : `integer`

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.

selected_phrase_effect_column : `renoise.EffectColumn`

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.

selected_phrase_effect_column_index : `integer`

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.

selected_phrase_sub_column_type : `renoise.Song.SubColumnType`

READ-ONLY The currently edited sub column type within the selected note/effect column in the current phrase. 0 when no phrase is selected.

selection_in_phrase : `PhraseSelection?`

Same as selection_in_pattern but for the currently selected phrase (if any).

Functions

is_undo_redoing(self)

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.

can_undo(self)

->boolean

Test if something in the song can be undone.

undo(self)

Undo the last performed action. Will do nothing if nothing can be undone.

can_redo(self)

->boolean

Test if something in the song can be redone.

redo(self)

Redo a previously undo action. Will do nothing if nothing can be redone.

describe_undo(self, description : `string`)

When modifying the song, Renoise will automatically add descriptions for undo/redo by looking at what first changed (a track was inserted, a pattern line changed, and so on). When the song is changed from an action in a menu entry callback, the menu entry's label will automatically be used for the undo description. If those auto-generated names do not work for you, or you want to use something more descriptive, you can, before changing anything in the song, give your changes a custom undo description (like: "Generate Synth Sample")

describe_batch_undo(self, description : `string`, timeout_ms : `number?`)

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 udo/redo step, when the changes happen asynchroniously, for example a process sliced action (via Lua coroutines).

insert_track_at(self, index : `integer`)

->renoise.Track

Insert a new track at the given index. Inserting a track behind or at the Master Track's index will create a Send Track. Otherwise, a regular track is created.

delete_track_at(self, index : `integer`)

Delete an existing track. The Master track can not be deleted, but all Sends can. Renoise needs at least one regular track to work, thus trying to delete all regular tracks will fire an error.

swap_tracks_at(self, index1 : `integer`, index2 : `integer`)

Swap the positions of two tracks. A Send can only be swapped with a Send track and a regular track can only be swapped with another regular track. The Master can not be swapped at all.

track(self, index : `integer`)

->renoise.Track

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

select_previous_track(self)

Set the selected track to prev relative to the current track. Takes care of skipping over hidden tracks and wrapping around at the edges.

select_next_track(self)

Set the selected track to next relative to the current track. Takes care of skipping over hidden tracks and wrapping around at the edges.

insert_group_at(self, index : `integer`)

->renoise.GroupTrack

Insert a new group track at the given index. Group tracks can only be inserted before the Master track.

add_track_to_group(self, track_index : `integer`, group_index : `integer`)

Add track at track_index to group at group_index by first moving it to the right spot to the left of the group track, and then adding it. If group_index is not a group track, a new group track will be created and both tracks will be added to it.

remove_track_from_group(self, track_index : `integer`)

Removes track from its immediate parent group and places it outside it to the left. Can only be called for tracks that are actually part of a group.

delete_group_at(self, group_index : `integer`)

Delete the group with the given index and all its member tracks. Index must be that of a group or a track that is a member of a group.

insert_instrument_at(self, index : `integer`)

->renoise.Instrument

Insert a new instrument at the given index. This will remap all existing notes in all patterns, if needed, and also update all other instrument links in the song. Can't have more than MAX_NUMBER_OF_INSTRUMENTS in a song.

delete_instrument_at(self, index : `integer`)

Delete an existing instrument at the given index. Renoise needs at least one instrument, thus trying to completely remove all instruments is not allowed. This will remap all existing notes in all patterns and update all other instrument links in the song.

swap_instruments_at(self, index1 : `integer`, index2 : `integer`)

Swap the position of two instruments. Will remap all existing notes in all patterns and update all other instrument links in the song.

instrument(self, index : `integer`)

->renoise.Instrument

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

capture_instrument_from_pattern(self)

Captures the current instrument (selects the instrument) from the current note column at the current cursor pos. Changes the selected instrument accordingly, but does not return the result. When no instrument is present at the current cursor pos, nothing will be done.

capture_nearest_instrument_from_pattern(self)

Tries to captures the nearest instrument from the current pattern track, starting to look at the cursor pos, then advancing until an instrument is found. Changes the selected instrument accordingly, but does not return the result. When no instruments (notes) are present in the current pattern track, nothing will be done.

pattern(self, index : `integer`)

->renoise.Pattern

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

render(self, options : `RenderOptions`, filename : `string`, rendering_done_callback : fun())

->success : boolean, error : string

Start rendering a section of the song or the whole song to a WAV file.

Rendering job will be done in the background and the call will return back immediately, but the Renoise GUI will be blocked during rendering. The passed rendering_done_callback function is called as soon as rendering is done, e.g. successfully completed.

While rendering, the rendering status can be polled with the song().rendering and song().rendering_progress properties, for example, in idle notifier loops. If starting the rendering process fails (because of file IO errors for example), the render function will return false and the error message is set as the second return value. On success, only a single true value is returned.

To render only specific tracks or columns, mute the undesired tracks/columns before starting to render.

Parameter file_name must point to a valid, maybe already existing file. If it already exists, the file will be silently overwritten. The renderer will automatically add a ".wav" extension to the file_name, if missing.

Parameter rendering_done_callback is ONLY called when rendering has succeeded. You can do something with the file you've passed to the renderer here, like for example loading the file into a sample buffer.

cancel_rendering(self)

When rendering (see rendering, renoise.song().rendering_progress), the current render process is canceled. Otherwise, nothing is done.

trigger_pattern_line(self, line_index : `integer`)

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!

trigger_instrument_note_on(self, instrument_index : `integer`, track_index : `integer`, note : `integer` | `integer`[]`?`, volume : `number?`)

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.

trigger_instrument_note_off(self, instrument_index : `integer`, track_index : `integer`, note : `integer` | `integer`[]`?`)

Stop instrument playback which previously got started via trigger_instrument_note_on.

trigger_sample_note_on(self, instrument_index : `integer`, sample_index : `integer`, track_index : `integer`, note : `integer?`, volume : `number?`, use_selection : `boolean?`)

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.