Module: Musa::Extension::Matrix

Defined in:: lib/musa-dsl/matrix/matrix.rb

Overview

Note:

These refinements must be activated with using Musa::Extension::Matrix in the scope where you want to use them.

Refinements for Array and Matrix classes to support musical structure conversions.

These refinements add methods to convert between matrix representations and Musa's P (point sequence) format, which is used extensively in the DSL for representing musical gestures and trajectories.

Background

In Musa DSL, musical gestures are often represented as sequences of points in multidimensional space, where dimensions can represent time, pitch, velocity, or other musical parameters. The P format provides a compact representation suitable for sequencer playback and transformation.

Matrix to P Conversion

A matrix of points (rows = time steps, columns = parameters) can be converted to P format where:

One dimension represents time (usually the first column)
Other dimensions represent musical parameters
Each P is an array extended with P module
The P contains alternating values (arrays extended with V) and durations (numbers): [value1, duration1, value2, duration2, ..., valueN].extend(P)

Use Cases

Converting recorded MIDI data to playable sequences
Transforming algorithmic compositions from matrix form to time-based sequences
Merging fragmented musical gestures that share connection points
Decomposing complex trajectories into simpler monotonic segments

Methods Added

Array

Array#indexes_of_values - Creates a hash mapping values to their indices
Array#to_p - Converts an array of matrices to P sequences
Array#condensed_matrices - Condenses matrices that share common boundary rows

Matrix

Matrix#to_p - Converts a matrix to P format (see examples in module documentation)
Matrix#_rows - Provides direct access to internal rows array (private API)

Examples:

Basic matrix conversion

using Musa::Extension::Matrix

# Matrix: [time, pitch]
matrix = Matrix[[0, 60], [1, 62], [2, 64]]
p_sequences = matrix.to_p(time_dimension: 0)
# Returns an array with one P:
#   [[60], 1, [62], 1, [64]].extend(P)
# Where [60], [62], [64] are arrays extended with V module

Multi-dimensional musical parameters

using Musa::Extension::Matrix

# Matrix: [time, pitch, velocity]
matrix = Matrix[[0, 60, 100], [0.5, 62, 110], [1, 64, 120]]
p_sequences = matrix.to_p(time_dimension: 0, keep_time: false)
# Returns an array with one P:
#   [[60, 100], 0.5, [62, 110], 0.5, [64, 120]].extend(P)
# Time dimension removed, used only for duration calculation

Condensing connected matrices

using Musa::Extension::Matrix

# Two phrases that connect at [1, 62]
phrase1 = Matrix[[0, 60], [1, 62]]
phrase2 = Matrix[[1, 62], [2, 64], [3, 65]]

[phrase1, phrase2].to_p(time_dimension: 0)
# Returns an array with one P (merged):
#   [[60], 1, [62], 1, [64], 1, [65]].extend(P)
# Both phrases merged into one continuous sequence