Module `xVoiceRunner`

This class converts pattern-tracks into 'voice-runs' - small note sequences .

About

xVoiceRunner provides a highly configurable method for extracting pattern data.

Functions

reset ()	reset variables to initial state before starting to process
purge_voices ()	prepare for next pattern by removing all terminated voices/voice-runs
collect (ptrack_or_phrase, collect_mode, selection, trk_idx, seq_idx)	gather voice-runs according to the specified settings
collect_at_cursor ()	select the voice-run directly below the cursor position
collect_above_cursor ()	select the voice-run directly above the cursor position
collect_below_cursor ()	select the voice-run directly below the cursor position
detect_run_condition (notecol, col_idx, vol_visible, pan_visible, from_pattern)	detect what action to take on a given note-column
detect_run_length (ptrack_or_phrase, col_idx, start_line, end_line, vol_visible, pan_visible)	check when a voice-run ends by examining the pattern-track
resolve_notecol (col_idx, line_idx)	get a specific note-column and its index
merge_columns (ptrack_or_phrase, selection, trk_idx, seq_idx)	merge columns: rightmost notes in selection overrides earlier ones
shorten_run (voice_run, num_lines)	if voice-run is longer than num_lines, shorten it (remove lines/note-columns, update #lines, set to implied off)
write (ptrack_or_phrase, selection, trk_idx)	write the current voice-runs to the provided pattern-track
get_voice_run_selection (vrun, trk_idx, col_idx)	Static Methods
has_room (voice_runs, line_start, col_idx, num_lines)	figure out if a given range contains any voice-runs
in_range (voice_runs, line_start, line_end, args)	collect runs that are triggered during a particular range of lines
get_runs_on_line (voice_runs, line_idx)	collect runs that begin on a specific line
create_voice (voice_run, col_idx, run_idx, line_idx)	create a voice table (to ensure correct variable types...)
get_initial_notecol (voice_run)	Voice-run methods
get_open_run (run_col, line_start)	Voice-run (column methods)
get_higher_notes_in_column (run_col, note_val)	find occurrences of notes which are higher than the specified one (NB: will only look for the initial note)
get_most_recent_run_index (run_col, line_idx)	find the index of the most recent run at the provided line
get_high_low_note_values (run_col, line_start, line_end)	check the lowest/highest note-values for a given column
get_column_start_end_line (run_col)	retrieve the first and last line in column
get_final_notecol_info (voice_run, respect_visibility, vol_visible, pan_visible)
get_notecol_info (notecol, respect_visibility, vol_visible, pan_visible)	obtain a bunch of useful info about a note-column
terminate_note (notecol, reveal_subcolumns, vol_visible, pan_visible, dly_visible, track_or_phrase)	terminate the note by whichever means

Tables

self.voice_runs

table of xNoteColumns, active voice from trigger to (implied) release table = { [column_index] = { -- pairs

[voice_run_index] = {             -- pairs
  [number_of_lines] = int or nil  -- always set, including trailing blank space
  [implied_noteoff] = bool or nil -- set when switching note/instr while having an active (non-offed) voice - see also split_on_note_xx options
  [open_ended] = bool or nil      -- set when voice extends beyond selection/pattern boundary
  [orphaned] = bool or nil        -- set on data with no prior voice (such as when we stop at note-off, note-cut...)
  [actual_noteoff_col] = xNoteColumn or nil -- set when note-off/cut is explicit
  [single_line_trigger] = bool or nil -- set when Cx on same line as note (only possible when stop_at_note_cut is true)
  [__skip_run] = bool or nil -- true when the whitelist tell us to ignore this note
  [line_idx] =                    -- xNoteColumn
  [line_idx] =                    -- xNoteColumn
  [line_idx] =                    -- etc...

self.unique_notes

table, keep track of unique note/instrument combinations table{

[note_value] = {
  [instrument_value] = true
}

]

Fields

self.split_at_note	bool, split a voice-run when note switches
self.split_at_note_change	bool, split a voice-run when note switches
self.split_at_instrument_change	bool, split a voice-run when instrument switches
self.link_ghost_notes	bool, stop voice-run when encountering a NOTE-OFF
self.link_ghost_notes	bool, stop voice-run when encountering a NOTE-OFF
self.stop_at_note_off	bool, stop voice-run when encountering a NOTE-OFF
self.stop_at_note_cut	bool, stop voice-run when encountering a NOTE-OFF
self.remove_orphans	bool, remove orphaned runs as they are encountered
self.wrap_around_jump	bool, decide whether 'next/previous' jumps will wrap in pattern
self.compact_columns	bool, compact runs when collecting (remove empty columns)
self.whitelist	table{[note_value]}, decides which notes to collect (optional)
self.low_column	int, remember the collected columns indices (used for clearing leftovers on output)

Functions

reset ()

reset variables to initial state before starting to process

purge_voices ()

prepare for next pattern by removing all terminated voices/voice-runs

collect (ptrack_or_phrase, collect_mode, selection, trk_idx, seq_idx)

gather voice-runs according to the specified settings

Parameters:

ptrack_or_phrase (renoise.PatternTrack or renoise.InstrumentPhrase)
collect_mode (xVoiceRunner.COLLECT_MODE)
selection (table), xPatternSelection
trk_idx (int)
seq_idx (int)

collect_at_cursor ()

select the voice-run directly below the cursor position

Returns:

table or nil

collect_above_cursor ()

select the voice-run directly above the cursor position

Returns:

table or nil

collect_below_cursor ()

select the voice-run directly below the cursor position

Returns:

table or nil

detect_run_condition (notecol, col_idx, vol_visible, pan_visible, from_pattern)

detect what action to take on a given note-column

Parameters:

notecol
col_idx
vol_visible
pan_visible
from_pattern

Returns:

xVoiceRunner.CONDITIONS.XX

detect_run_length (ptrack_or_phrase, col_idx, start_line, end_line, vol_visible, pan_visible)

check when a voice-run ends by examining the pattern-track

Parameters:

ptrack_or_phrase , renoise.PatternTrack
col_idx (int)
start_line (int), the line where the voice got triggered
end_line (int), iterate until this
vol_visible (bool)
pan_visible (bool)

Returns:

int, line index

resolve_notecol (col_idx, line_idx)

get a specific note-column and its index

Parameters:

col_idx (int)
line_idx (int)

Returns:

xNoteColumn or nil
int (run index) or nil

merge_columns (ptrack_or_phrase, selection, trk_idx, seq_idx)

merge columns: rightmost notes in selection overrides earlier ones

Parameters:

ptrack_or_phrase
selection
trk_idx
seq_idx

shorten_run (voice_run, num_lines)

if voice-run is longer than num_lines, shorten it (remove lines/note-columns, update #lines, set to implied off)

Parameters:

voice_run
num_lines

write (ptrack_or_phrase, selection, trk_idx)

write the current voice-runs to the provided pattern-track

Parameters:

ptrack_or_phrase (renoise.PatternTrack or renoise.InstrumentPhrase)
selection (table)
trk_idx (int)

get_voice_run_selection (vrun, trk_idx, col_idx)

Static Methods

Parameters:

vrun (table)
trk_idx (number)
col_idx (number)

Returns:

table, pattern selection spanning the provided voice-run

has_room (voice_runs, line_start, col_idx, num_lines)

figure out if a given range contains any voice-runs

Parameters:

voice_runs (table)
line_start (int)
col_idx (int)
num_lines (int)

Returns:

bool, true when no runs
table, voice-runs in range

in_range (voice_runs, line_start, line_end, args)

collect runs that are triggered during a particular range of lines

Parameters:

voice_runs (table)
line_start (int)
line_end (int)
args (table) excludecolumns (table) restricttocolumn (int) includebefore (bool), include runs that started before linestart includeafter (bool), include runs that continue beyond lineend matchedcolumns (table), set when called recursively

Returns:

table
matched_columns

get_runs_on_line (voice_runs, line_idx)

collect runs that begin on a specific line

Parameters:

voice_runs (table)
line_idx (int)

Returns:

table - see xVoiceRunner.create_voice()

create_voice (voice_run, col_idx, run_idx, line_idx)

create a voice table (to ensure correct variable types...)

Parameters:

voice_run (table)
col_idx (number)
run_idx (number)
line_idx (number)

Returns:

table

get_initial_notecol (voice_run)

Voice-run methods

Parameters:

voice_run , table

Returns:

int, note value or nil
int, line index

get_open_run (run_col, line_start)

Voice-run (column methods) retrieve the previous run if it overlaps with the provided line

Parameters:

run_col (table)
line_start (int)

Returns:

int or nil

get_higher_notes_in_column (run_col, note_val)

find occurrences of notes which are higher than the specified one (NB: will only look for the initial note)

Parameters:

run_col (table)
note_val (int)

Returns:

int, run index or nil
int, line index or nil

get_most_recent_run_index (run_col, line_idx)

find the index of the most recent run at the provided line

Parameters:

run_col (table)
line_idx (int)

Returns:

int or nil

get_high_low_note_values (run_col, line_start, line_end)

check the lowest/highest note-values for a given column

Parameters:

run_col (table), required
line_start (int)
line_end (int)

Returns:

int, low note-value or nil
int, high note-value or nil

get_column_start_end_line (run_col)

retrieve the first and last line in column

Parameters:

run_col (table), "voice-run column"

Returns:

notecol

get_final_notecol_info (voice_run, respect_visibility, vol_visible, pan_visible)

Parameters:

voice_run , table
respect_visibility (bool)
vol_visible (bool)
pan_visible (bool)

Returns:

notecol

get_notecol_info (notecol, respect_visibility, vol_visible, pan_visible)

obtain a bunch of useful info about a note-column

Parameters:

notecol (renoise.NoteColumn or xNoteColumn)
respect_visibility (bool)
vol_visible (bool)
pan_visible (bool)

terminate_note (notecol, reveal_subcolumns, vol_visible, pan_visible, dly_visible, track_or_phrase)

terminate the note by whichever means

Parameters:

notecol (renoise.NoteColumn or xNoteColumn)
reveal_subcolumns (boolean)
vol_visible (boolean)
pan_visible (boolean)
dly_visible (boolean)
track_or_phrase (renoise.PatternTrack or renoise.InstrumentPhrase)

Tables

self.voice_runs

table of xNoteColumns, active voice from trigger to (implied) release table = { [column_index] = { -- pairs

[voice_run_index] = {             -- pairs
  [number_of_lines] = int or nil  -- always set, including trailing blank space
  [implied_noteoff] = bool or nil -- set when switching note/instr while having an active (non-offed) voice - see also split_on_note_xx options
  [open_ended] = bool or nil      -- set when voice extends beyond selection/pattern boundary
  [orphaned] = bool or nil        -- set on data with no prior voice (such as when we stop at note-off, note-cut...)
  [actual_noteoff_col] = xNoteColumn or nil -- set when note-off/cut is explicit
  [single_line_trigger] = bool or nil -- set when Cx on same line as note (only possible when stop_at_note_cut is true)
  [__skip_run] = bool or nil -- true when the whitelist tell us to ignore this note
  [line_idx] =                    -- xNoteColumn
  [line_idx] =                    -- xNoteColumn
  [line_idx] =                    -- etc...
 }

} }

self.unique_notes

table, keep track of unique note/instrument combinations table{

[note_value] = {
  [instrument_value] = true
}

]

Fields

self.split_at_note: bool, split a voice-run when note switches
self.split_at_note_change: bool, split a voice-run when note switches
self.split_at_instrument_change: bool, split a voice-run when instrument switches
self.link_ghost_notes: bool, stop voice-run when encountering a NOTE-OFF
self.link_ghost_notes: bool, stop voice-run when encountering a NOTE-OFF
self.stop_at_note_off: bool, stop voice-run when encountering a NOTE-OFF
self.stop_at_note_cut: bool, stop voice-run when encountering a NOTE-OFF
self.remove_orphans: bool, remove orphaned runs as they are encountered
self.wrap_around_jump: bool, decide whether 'next/previous' jumps will wrap in pattern
self.compact_columns: bool, compact runs when collecting (remove empty columns)
self.whitelist: table{[note_value]}, decides which notes to collect (optional)
self.low_column: int, remember the collected columns indices (used for clearing leftovers on output)

xLib

Contents

Modules

Module xVoiceRunner

About

Functions

Tables

Fields

Functions

Parameters:

Returns:

Returns:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Tables

Fields

Module `xVoiceRunner`