xLib

• Index

Contents

• Functions
• Tables
• Fields

Modules

• xAudioDevice
• xAudioDeviceAutomation
• xAutomation
• xBlockLoop
• xColumns
• xCursorPos
• xEffectColumn
• xEnvelope
• xInstrument
• xKeyZone
• xLFO
• xLib
• xLine
• xLineAutomation
• xLinePattern
• xMatrixSelection
• xMessage
• xMidiCommand
• xMidiInput
• xMidiIO
• xMidiMessage
• xNoteCapture
• xNoteColumn
• xOscClient
• xOscDevice
• xOscMessage
• xOscPattern
• xOscRouter
• xOscValue
• xParameter
• xParameterAutomation
• xPatternPos
• xPatternSelection
• xPatternSequencer
• xPersistentSettings
• xPhrase
• xPhraseManager
• xPhraseSelection
• xPlayPos
• xRule
• xRules
• xRuleset
• xSample
• xSampleBuffer
• xSampleBufferOperation
• xSampleDeviceChain
• xSampleMapping
• xScale
• xSequencerSelection
• xSongPos
• xStreamBuffer
• xStreamPos
• xTrack
• xTransport
• xValue
• xVoiceManager
• xVoiceRunner
• xVoiceSorter

Module xSongPos

Static methods for working with renoise.SongPos (or alike).

Three options are designed to deal with song boundaries, pattern-loop and block-loop boundaries. By default, they are set to settings which mimic the behavior in Renoise when playing/manipulating the playback position. You can specify alternative settings either by supplying them as a secondary argument (the 'args' table), or by defining alternative values for xSongPos.DEFAULT_XX

Note also that anything relating to beats and bars depend on the currently set transport options. If you want to override these values with your own ones, they can be supplied via the secondary argument (beatsperbar and linesperbeat, respectively).

Note: throughout, the class accepts not only an instance of renoise.SongPos as argument, but also "SongPos-alike" objects - tables that contain a line and sequence property.

Functions

create (pos)	[Static] Create a native SongPos object
create_from_beats (beats, args)	Convert a number (number of beats) into a SongPos
get_number_of_beats (pos, args)	Figure out the position in beats (identical to e.g.
get_defaults ()	For convenience, return default settings
set_defaults (val)	For convenience, apply default settings
apply_to_edit_pos (pos)	Apply a position to the "transport.edit_pos" NB: take care - the property might not be updated immediately
normalize (pos, args)	[Class] Normalize the position, takes us from an 'imaginary' position to one that respect the actual pattern length/sequence plus loops
increase_by_lines (num_lines, pos, args)	[Class] Increase position by X number of lines
decrease_by_lines (num_lines, pos, args)	[Class] Subtract a number of lines from position
next_beat (pos, args)	[Class] Set to the next beat position
previous_beat (pos, args)	[Class] Set to the previous beat position
next_bar (pos, args)	[Class] Set to the next bar position NB: bars are based on position in beats and use metronomebeatsper_bar as basis
previous_bar (pos, args)	[Class] Set to the previous bar position NB: bars are based on position in beats and use metronomebeatsper_bar as basis
next_block (pos, args)	[Class] Set to the next block position
previous_block (pos, args)	[Class] Set to the next block position
next_pattern (pos, args)	[Class] Set to the beginning of next pattern
previous_pattern (pos, args)	[Class] Set to the beginning of pattern, or previous pattern
enforce_boundary (direction, pos, args)	[Static] Restrict the position to boundaries (sequence, loop)
enforce_block_boundary (pos, line_delta, boundary)	[Static] Restrict position to boundaries (block-loop)
within_bounds (pos)	Check if position is within bounds of the song Note: this method only verifies the line-index for the last pattern
get_last_line_in_song ()	Get the last line in the last pattern
get_line_diff (pos1, pos2)	[Static] Get the difference in lines between two song-positions
_init_args (args)	Apply default boundary-values

Tables

OUT_OF_BOUNDS	How to deal with sequence (song) boundaries CAP: do not exceed, cap at beginning/end LOOP: going past the end will take us to the start, and vice versa NULL: going past the end or start will return nil ALLOW: allow out-of-bounds values (when outside bounds, will keep the sequence index but line index will be higher than pattern length, or set to a negative value)
LOOP_BOUNDARY	How to deal with loop boundaries HARD: always stay within loop, no matter the position SOFT: only stay within loop when playback takes us there NONE: continue past loop boundary (ignore)
BLOCK_BOUNDARY	How to deal with block-loop boundaries HARD: always stay within loop, no matter the position SOFT: only stay within loop when playback takes us there NONE: continue past loop boundary (ignore)

Fields

DEFAULT_BOUNDS_MODE	Provide fallback values
BEATS_PER_BAR	If defined, these values are used when calculating beats and bars.

Functions

create (pos)

[Static] Create a native SongPos object

Parameters:

• pos , renoise.SongPos or alike

Returns:

renoise.SongPos

create_from_beats (beats, args)

Convert a number (number of beats) into a SongPos

Parameters:

• beats (number)
• args , table (xSongPos-options - see description of class)

Returns:

renoise.SongPos or nil

get_number_of_beats (pos, args)

Figure out the position in beats (identical to e.g. "editposbeats")

Parameters:

• pos (SongPos)
• args , table (xSongPos-options - see description of class)

Returns:

renoise.SongPos or nil

get_defaults ()

For convenience, return default settings

set_defaults (val)

For convenience, apply default settings

Parameters:

• val

apply_to_edit_pos (pos)

Apply a position to the "transport.edit_pos" NB: take care - the property might not be updated immediately

Parameters:

• pos (SongPos, or SongPos-alike object)

normalize (pos, args)

[Class] Normalize the position, takes us from an 'imaginary' position to one that respect the actual pattern length/sequence plus loops

Parameters:

• pos
• args

Returns:

SongPos

increase_by_lines (num_lines, pos, args)

[Class] Increase position by X number of lines

Parameters:

• num_lines (number)
• pos (SongPos)
• args , table (xSongPos-options - see description of class)

Returns:

1. SongPos or nil
2. number, lines travelled or nil

decrease_by_lines (num_lines, pos, args)

[Class] Subtract a number of lines from position

Parameters:

• num_lines , int
• pos (SongPos)
• args , table (xSongPos-options - see description of class)

Returns:

1. SongPos or nil
2. number, lines travelled or nil

next_beat (pos, args)

[Class] Set to the next beat position

Parameters:

• pos (SongPos)
• args , table (xSongPos-options - see description of class)

Returns:

1. SongPos or nil
2. number, lines travelled or nil

previous_beat (pos, args)

[Class] Set to the previous beat position

Parameters:

• pos (SongPos)
• args , table (xSongPos-options - see description of class)

Returns:

number, lines travelled

next_bar (pos, args)

[Class] Set to the next bar position NB: bars are based on position in beats and use metronomebeatsper_bar as basis

Parameters:

• pos (SongPos)
• args , table (xSongPos-options - see description of class)

Returns:

1. xSongPos or nil
2. number, lines travelled or nil

previous_bar (pos, args)

[Class] Set to the previous bar position NB: bars are based on position in beats and use metronomebeatsper_bar as basis

Parameters:

• pos (SongPos)
• args , table (xSongPos-options - see description of class)

Returns:

1. SongPos or nil
2. number, lines travelled or nil

next_block (pos, args)

[Class] Set to the next block position

Parameters:

• pos (SongPos)
• args , table (xSongPos-options - see description of class)

Returns:

1. SongPos or nil
2. number, lines travelled or nil

previous_block (pos, args)

[Class] Set to the next block position

Parameters:

• pos (SongPos)
• args , table (xSongPos-options - see description of class)

Returns:

1. SongPos or nil
2. number, lines travelled or nil

next_pattern (pos, args)

[Class] Set to the beginning of next pattern

Parameters:

• pos (SongPos)
• args , table (xSongPos-options - see description of class)

Returns:

1. SongPos or nil
2. number, lines travelled or nil

previous_pattern (pos, args)

[Class] Set to the beginning of pattern, or previous pattern

Parameters:

• pos (SongPos)
• args , table (xSongPos-options - see description of class)

Returns:

number, lines travelled

enforce_boundary (direction, pos, args)

[Static] Restrict the position to boundaries (sequence, loop)

Parameters:

• direction , string ("increase" or "decrease")
• pos , SongPos
• args , table (xSongPos-options - see description of class)

Returns:

sequence,line,done sequence, int or nil line, int or nil done (bool), true when boundary was "enforced" (capped/nullified/allowed)

enforce_block_boundary (pos, line_delta, boundary)

[Static] Restrict position to boundaries (block-loop)

Parameters:

• pos , SongPos
• line_delta , int - #lines to add/subtract, negative when decreasing
• boundary ], xSongPos.BLOCK_BOUNDARY

Returns:

line, int

within_bounds (pos)

Check if position is within bounds of the song Note: this method only verifies the line-index for the last pattern

Parameters:

• pos , SongPos

Returns:

boolean

get_last_line_in_song ()

Get the last line in the last pattern

Returns:

SongPos

get_line_diff (pos1, pos2)

[Static] Get the difference in lines between two song-positions

Parameters:

• pos1 (SongPos)
• pos2 (SongPos)

Returns:

int

_init_args (args)

Apply default boundary-values

Parameters:

• args , table (xSongPos-options - see description of class)

Tables

OUT_OF_BOUNDS

How to deal with sequence (song) boundaries CAP: do not exceed, cap at beginning/end LOOP: going past the end will take us to the start, and vice versa NULL: going past the end or start will return nil ALLOW: allow out-of-bounds values (when outside bounds, will keep the sequence index but line index will be higher than pattern length, or set to a negative value)

Fields:

• CAP
• LOOP
• NULL
• ALLOW

LOOP_BOUNDARY

How to deal with loop boundaries HARD: always stay within loop, no matter the position SOFT: only stay within loop when playback takes us there NONE: continue past loop boundary (ignore)

Fields:

• HARD
• SOFT
• NONE

BLOCK_BOUNDARY

How to deal with block-loop boundaries HARD: always stay within loop, no matter the position SOFT: only stay within loop when playback takes us there NONE: continue past loop boundary (ignore)

Fields:

• HARD
• SOFT
• NONE

Fields

DEFAULT_BOUNDS_MODE

Provide fallback values

BEATS_PER_BAR

If defined, these values are used when calculating beats and bars.
When not, LINESPERBEAT will use transport.lpb while BEATSPERBAR will use transport.metronomebeatsper_bar