renoise.Song Song

Renoise’s main document - the song.

Constants
- MAX_NUMBER_OF_INSTRUMENTS : integer
- SubColumnType
Properties
Functions
- is_undo_redoing (self)
- can_undo (self) -> boolean
- undo (self)
- can_redo (self) -> boolean
- redo (self)
- describe_undo (self, string)
- describe_batch_undo (self, string, number?)
- insert_track_at (self, integer) -> renoise.Track
- delete_track_at (self, integer)
- swap_tracks_at (self, integer, integer)
- track (self, integer) -> renoise.Track
- select_previous_track (self)
- select_next_track (self)
- insert_group_at (self, integer) -> renoise.GroupTrack
- add_track_to_group (self, integer, integer)
- remove_track_from_group (self, integer)
- delete_group_at (self, integer)
- insert_instrument_at (self, integer) -> renoise.Instrument
- delete_instrument_at (self, integer)
- swap_instruments_at (self, integer, integer)
- instrument (self, integer) -> renoise.Instrument
- capture_instrument_from_pattern (self)
- capture_nearest_instrument_from_pattern (self)
- pattern (self, integer) -> renoise.Pattern
- render (self, RenderOptions, string, ()) -> boolean, string
- cancel_rendering (self)
- trigger_pattern_line (self, integer)
- trigger_instrument_note_on (self, integer, integer, integer | integer[]?, number?)
- trigger_instrument_note_off (self, integer, integer, integer | integer[]?)
- trigger_sample_note_on (self, integer, integer, integer, integer?, number?, boolean?)
- trigger_sample_note_off (self, integer, integer, integer, integer?)
- load_midi_mappings (self, string) -> boolean, string
- save_midi_mappings (self, string) -> boolean, string
- clear_midi_mappings (self)
Structs
- PatternSelection
  - Properties
- PhraseSelection
  - Properties
- RenderOptions
  - Properties
    - start_pos : renoise.SongPos
    - end_pos : renoise.SongPos
    - sample_rate : 192000 | 22050 | 44100 | 48000 | 88200 | 96000
    - bit_depth : 16 | 24 | 32
    - interpolation : "default" | "precise"
    - priority : "high" | "low" | "realtime"

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`

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

artist : `string`

Song Comments

artist_observable : `renoise.Document.Observable`

READ-ONLY

name : `string`

name_observable : `renoise.Document.Observable`

READ-ONLY

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`

READ-ONLY

comments_assignment_observable : `renoise.Document.Observable`

Notifier is called as soon as any paragraph in the comments change. READ-ONLY

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`

READ-ONLY

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`

True while rendering is in progress. READ-ONLY

rendering_progress : `number`

The current render progress amount Range: (0.0 - 1.0) READ-ONLY

transport : `renoise.Transport`

READ-ONLY

sequencer : `renoise.PatternSequencer`

READ-ONLY

pattern_iterator : `renoise.PatternIterator`

READ-ONLY

sequencer_track_count : `integer`

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

send_track_count : `integer`

number of send tracks in song. READ-ONLY

instruments : `renoise.Instrument[]`

Instrument arrays READ-ONLY

instruments_observable : `renoise.Document.ObservableList`

READ-ONLY

patterns : `renoise.Pattern[]`

Pattern arrays READ-ONLY

patterns_observable : `renoise.Document.ObservableList`

READ-ONLY

tracks : `renoise.Track[]`

Track array READ-ONLY

tracks_observable : `renoise.Document.ObservableList`

READ-ONLY

selected_instrument : `renoise.Instrument`

Selected in the instrument box. READ-ONLY

selected_instrument_observable : `renoise.Document.Observable`

READ-ONLY

selected_instrument_index : `integer`

Selected instrument index in the instrument box. Note, Renoise displays zero-based indices here but this value starts from one.

selected_instrument_index_observable : `renoise.Document.Observable`

READ-ONLY

selected_phrase : `renoise.InstrumentPhrase`

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

selected_phrase_observable : `renoise.Document.Observable`

READ-ONLY

selected_phrase_index : `integer`

Selected phrase index the instrument’s phrase map piano view.

selected_sample : `renoise.Sample`

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

selected_sample_observable : `renoise.Document.Observable`

READ-ONLY

selected_sample_index : `integer`

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`

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

selected_sample_modulation_set_observable : `renoise.Document.Observable`

READ-ONLY

selected_sample_modulation_set_index : `integer`

Selected modulation set index in the instrument’s modulation view.

selected_sample_device_chain : `renoise.SampleDeviceChain`

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

selected_sample_device_chain_observable : `renoise.Document.Observable`

READ-ONLY

selected_sample_device_chain_index : `integer`

Selected chain index in the instrument’s effects view.

selected_sample_device : `renoise.AudioDevice`

Selected in the sample effect mixer. READ-ONLY

selected_sample_device_observable : `renoise.Document.Observable`

READ-ONLY

selected_sample_device_index : `integer`

Selected device index in the sample effect mixer.

selected_track : `renoise.Track`

Selected in the pattern editor or mixer. READ-ONLY

selected_track_observable : `renoise.Document.Observable`

READ-ONLY

selected_track_index : `integer`

Selected track index in the pattern editor or mixer.

selected_track_index_observable : `renoise.Document.Observable`

READ-ONLY

selected_track_device : `renoise.AudioDevice`

Selected in the track DSP chain editor. READ-ONLY

selected_track_device_observable : `renoise.Document.Observable`

READ-ONLY

selected_track_device_index : `integer`

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

selected_automation_parameter_observable : `renoise.Document.Observable`

READ-ONLY

selected_automation_device : `renoise.AudioDevice`

Parent device of ‘selected_automation_parameter’. READ-ONLY

selected_automation_device_observable : `renoise.Document.Observable`

READ-ONLY

selected_pattern : `renoise.Pattern`

The currently edited pattern. READ-ONLY

selected_pattern_observable : `renoise.Document.Observable`

READ-ONLY

selected_pattern_index : `integer`

The currently edited pattern index.

selected_pattern_index_observable : `renoise.Document.Observable`

READ-ONLY

selected_pattern_track : `renoise.PatternTrack`

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

selected_pattern_track_observable : `renoise.Document.Observable`

READ-ONLY

selected_sequence_index : `integer`

The currently edited sequence position.

selected_sequence_index_observable : `renoise.Document.Observable`

READ-ONLY

selected_line : `renoise.PatternLine`

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

selected_line_index : `integer`

selected_note_column : `renoise.NoteColumn`

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

selected_note_column_index : `integer`

selected_effect_column : `renoise.EffectColumn`

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

selected_effect_column_index : `integer`

selected_sub_column_type : `renoise.Song.SubColumnType`

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

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`

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

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`

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

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`

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

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`

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

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 : ())

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