renoise.Song
Renoise's main document - the song.
- Constants
- Properties
- artist :
string
- artist_observable :
renoise.Document.Observable
- comments :
string
[] - comments_assignment_observable :
renoise.Document.Observable
- comments_observable :
renoise.Document.ObservableList
- file_name :
string
- instruments :
renoise.Instrument
[] - instruments_observable :
renoise.Document.ObservableList
- name :
string
- name_observable :
renoise.Document.Observable
- pattern_iterator :
renoise.PatternIterator
- patterns :
renoise.Pattern
[] - patterns_observable :
renoise.Document.ObservableList
- rendering :
boolean
- rendering_progress :
number
- selected_automation_device :
renoise.AudioDevice
- selected_automation_device_observable :
renoise.Document.Observable
- selected_automation_parameter :
renoise.DeviceParameter
- selected_automation_parameter_observable :
renoise.Document.Observable
- selected_device :
renoise.AudioDevice
- selected_device_index :
integer
- selected_device_observable :
renoise.Document.Observable
- selected_effect_column :
renoise.EffectColumn
- selected_effect_column_index :
integer
- selected_instrument :
renoise.Instrument
- selected_instrument_index :
integer
- selected_instrument_index_observable :
renoise.Document.Observable
- selected_instrument_observable :
renoise.Document.Observable
- selected_line :
renoise.PatternLine
- selected_line_index :
integer
- selected_note_column :
renoise.NoteColumn
- selected_note_column_index :
integer
- selected_parameter :
renoise.DeviceParameter
- selected_parameter_observable :
renoise.Document.Observable
- selected_pattern :
renoise.Pattern
- selected_pattern_index :
integer
- selected_pattern_index_observable :
renoise.Document.Observable
- selected_pattern_observable :
renoise.Document.Observable
- selected_pattern_track :
renoise.PatternTrack
- selected_pattern_track_observable :
renoise.Document.Observable
- selected_phrase :
renoise.InstrumentPhrase
- selected_phrase_index :
integer
- selected_phrase_observable :
renoise.Document.Observable
- selected_sample :
renoise.Sample
- selected_sample_device :
renoise.AudioDevice
- selected_sample_device_chain :
renoise.SampleDeviceChain
- selected_sample_device_chain_index :
integer
- selected_sample_device_chain_observable :
renoise.Document.Observable
- selected_sample_device_index :
integer
- selected_sample_device_observable :
renoise.Document.Observable
- selected_sample_index :
integer
- selected_sample_modulation_set :
renoise.SampleModulationSet
- selected_sample_modulation_set_index :
integer
- selected_sample_modulation_set_observable :
renoise.Document.Observable
- selected_sample_observable :
renoise.Document.Observable
- selected_sequence_index :
integer
- selected_sequence_index_observable :
renoise.Document.Observable
- selected_sub_column_type :
renoise.Song.SubColumnType
- selected_track :
renoise.Track
- selected_track_device :
renoise.AudioDevice
- selected_track_device_index :
integer
- selected_track_device_observable :
renoise.Document.Observable
- selected_track_index :
integer
- selected_track_index_observable :
renoise.Document.Observable
- selected_track_observable :
renoise.Document.Observable
- selection_in_pattern :
PatternSelection``?
- selection_in_phrase :
PhraseSelection``?
- send_track_count :
integer
- sequencer :
renoise.PatternSequencer
- sequencer_track_count :
integer
- show_comments_after_loading :
boolean
- show_comments_after_loading_observable :
renoise.Document.Observable
- tool_data :
string``?
- tracks :
renoise.Track
[] - tracks_observable :
renoise.Document.ObservableList
- transport :
renoise.Transport
- artist :
- Functions
- add_track_to_group(self, track_index :
integer
, group_index :integer
) - can_redo(self)
- can_undo(self)
- cancel_rendering(self)
- capture_instrument_from_pattern(self)
- capture_nearest_instrument_from_pattern(self)
- clear_midi_mappings(self)
- delete_group_at(self, group_index :
integer
) - delete_instrument_at(self, index :
integer
) - delete_track_at(self, index :
integer
) - describe_undo(self, description :
any
) - insert_group_at(self, index :
integer
) - insert_instrument_at(self, index :
integer
) - insert_track_at(self, index :
integer
) - instrument(self, index :
integer
) - load_midi_mappings(self, filename :
string
) - pattern(self, index :
integer
) - redo(self)
- remove_track_from_group(self, track_index :
integer
) - render(self, options :
RenderOptions
, filename :string
, rendering_done_callback : fun()) - save_midi_mappings(self, filename :
string
) - select_next_track(self)
- select_previous_track(self)
- swap_instruments_at(self, index1 :
integer
, index2 :integer
) - swap_tracks_at(self, index1 :
integer
, index2 :integer
) - track(self, index :
integer
) - undo(self)
- add_track_to_group(self, track_index :
- Local Structs
- PatternSelection
- PhraseSelection
- RenderOptions
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
artist : string
Song Comments
artist_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_assignment_observable : renoise.Document.Observable
READ-ONLY Notifier is called as soon as any paragraph in the comments change.
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).
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.
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).
name : string
name_observable : renoise.Document.Observable
Track changes to document properties or general states by attaching listener functions to it.
pattern_iterator : renoise.PatternIterator
READ-ONLY
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).
rendering : boolean
READ-ONLY True while rendering is in progress.
rendering_progress : number
Range: (0.0 - 1.0)
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_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_device : renoise.AudioDevice
selected_device_index : integer
selected_device_observable : renoise.Document.Observable
Track changes to document properties or general states by attaching listener functions to it.
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_instrument : renoise.Instrument
READ-ONLY Selected in the instrument box.
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_instrument_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_parameter : renoise.DeviceParameter
selected_parameter_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_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_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_phrase : renoise.InstrumentPhrase
READ-ONLY Currently selected phrase the instrument's phrase map piano view.
selected_phrase_index : integer
selected_phrase_observable : renoise.Document.Observable
Track changes to document properties or general states by attaching listener functions to it.
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_device : renoise.AudioDevice
READ-ONLY Selected in the sample effect mixer.
selected_sample_device_chain : renoise.SampleDeviceChain
READ-ONLY Selected in the instrument's effects view.
selected_sample_device_chain_index : integer
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_index : integer
selected_sample_device_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_index : integer
selected_sample_modulation_set_observable : renoise.Document.Observable
Track changes to document properties or general states by attaching listener functions to it.
selected_sample_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_sub_column_type : renoise.Song.SubColumnType
READ-ONLY The currently edited sub column type within the selected note/effect column.
selected_track : renoise.Track
READ-ONLY Selected in the pattern editor or mixer.
selected_track_device : renoise.AudioDevice
READ-ONLY Selected in the track DSP chain editor.
selected_track_device_index : integer
selected_track_device_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_observable : renoise.Document.Observable
Track changes to document properties or general states by attaching listener functions to it.
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).
send_track_count : integer
-READ-ONLY number of send tracks in song.
sequencer : renoise.PatternSequencer
READ-ONLY
sequencer_track_count : integer
READ-ONLY number of normal playback tracks (non-master or sends) in song.
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.
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).
transport : renoise.Transport
READ-ONLY
Functions
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.
can_redo(self)
->
boolean
Test if something in the song can be redone.
can_undo(self)
->
boolean
Test if something in the song can be undone.
cancel_rendering(self)
When rendering (see rendering, renoise.song().rendering_progress), the current render process is canceled. Otherwise, nothing is done.
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.
clear_midi_mappings(self)
clear all MIDI mappings in the song
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.
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.
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.
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_group_at(self, index : integer
)
Insert a new group track at the given index. Group tracks can only be inserted before the Master track.
insert_instrument_at(self, index : integer
)
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.
insert_track_at(self, index : integer
)
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.
instrument(self, index : integer
)
Access to a single instrument by index. Use properties 'instruments' to iterate over all instruments and to query the instrument count.
load_midi_mappings(self, filename : string
)
->
success : boolean
, error : string
Load all global MIDI mappings in the song into a XRNM file. Returns true when loading/saving succeeded, else false and the error message.
pattern(self, index : integer
)
Access to a single pattern by index. Use properties 'patterns' to iterate over all patterns and to query the pattern count.
redo(self)
Redo a previously undo action. Will do nothing if nothing can be redone.
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.
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
andsong().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 singletrue
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.
save_midi_mappings(self, filename : string
)
->
success : boolean
, error : string
Save all global MIDI mappings in the song into a XRNM file. Returns true when loading/saving succeeded, else false and the error message.
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.
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.
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.
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
)
Access to a single track by index. Use properties 'tracks' to iterate over all tracks and to query the track count.
undo(self)
Undo the last performed action. Will do nothing if nothing can be undone.
Local Structs
PatternSelection
Selection range in the current pattern
Properties
end_column : integer
?
End column index within end_track
end_line : integer
?
End pattern line index
end_track : integer
?
End track index
start_column : integer
?
Start column index within start_track
start_line : integer
?
Start pattern line index
start_track : integer
?
Start track index
PhraseSelection
Selection range in the current phrase
Properties
end_column : integer
?
End column index within end_track
end_line : integer
?
End pattern line index
start_column : integer
?
Start column index within start_track
start_line : integer
?
Start pattern line index
RenderOptions
Properties
bit_depth : 16
| 24
| 32
by default 32.
end_pos : renoise.SongPos
by default the song end.
interpolation : "default"
| "precise"
by default "default".
priority : "high"
| "low"
| "realtime"
by default "high".
sample_rate : 192000
| 22050
| 44100
| 48000
| 88200
| 96000
by default the players current rate.
start_pos : renoise.SongPos
by default the song start.