renoise.Song

Renoise's main document - the song.

Constants
- SubColumnType
- MAX_NUMBER_OF_INSTRUMENTS : integer
Properties
Functions
Local 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, Pattern, and Track 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`[]

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`[]

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`

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 Currently 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`

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`

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`

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`

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`

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`

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`

selected_device : `renoise.AudioDevice`

selected_device_observable : `renoise.Document.Observable`

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

selected_device_index : `integer`

selected_parameter : `renoise.DeviceParameter`

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'. not settable.

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

selection_in_phrase : `PhraseSelection?`

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

Functions

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 : `any`)

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")

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.

cancel_rendering(self)

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

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.