subsequence.groove

The API reference for Groove.

Groove

class Groove(
    offsets: typing.List[float],
    grid: float = 0.25,
    velocities: typing.Optional[typing.List[float]] = None,
)

A timing/velocity template applied to quantised grid positions.

A groove is a repeating pattern of per-step timing offsets and optional velocity adjustments aligned to a rhythmic grid. Apply it as a post-build transform with p.groove(template) to give a pattern its characteristic feel - swing, shuffle, MPC-style pocket, or anything extracted from an Ableton .agr file.

The offsets repeat from the start of the piece, not from the start of each pattern, so the same groove given to parts of different lengths keeps them in one feel.

Parameters

• offsets: Timing offset per grid slot, in beats. Repeats cyclically. Positive values delay the note; negative values push it earlier.
• grid: Grid size in beats (0.25 = 16th notes, 0.5 = 8th notes).
• velocities: Optional velocity scale per grid slot (1.0 = unchanged). Repeats cyclically alongside offsets.

Example:

# Ableton-style 57% swing on 16th notes
groove = Groove.swing(percent=57)

# Custom groove with timing and velocity
groove = Groove(
        grid=0.25,
        offsets=[0.0, +0.02, 0.0, -0.01],
        velocities=[1.0, 0.7, 0.9, 0.6],
)

Members: from_agr, grid, offsets, swing, velocities

Groove.offsets

Groove.offsets: typing.List[float]

Groove.grid

Groove.grid: float = 0.25

Groove.velocities

Groove.velocities: typing.Optional[typing.List[float]] = None

Groove.swing

staticmethod Groove.swing(
    percent: float = 57.0,
    grid: float = 0.25,
) -> 'Groove'

Create a swing groove from a percentage.

50% is straight (no swing). 67% is approximately triplet swing. 57% is a moderate shuffle - the Ableton default.

Applied, a note moves by whole pulses (24 to a beat), so percentages that round to the same pulse sound the same: on sixteenths 55–62 all sound as about 58%. PatternBuilder.swing lists the steps for sixteenths and eighths.

Parameters

• percent: Swing amount (50–75 is the useful range).
• grid: Grid size in beats (0.25 = 16ths, 0.5 = 8ths).

Groove.from_agr

staticmethod Groove.from_agr(
    path: str,
    grid: typing.Optional[float] = None,
) -> 'Groove'

Import timing and velocity data from an Ableton .agr groove file.

An .agr file is an XML document containing a MIDI clip whose note positions encode the groove's rhythmic feel. This method reads those note start times and velocities and converts them into the Groove dataclass format (per-step offsets and velocity scales).

Without grid=, the grid is inferred as clip length / note count - which assumes the clip plays exactly one note per grid cell (the standard shape for a groove clip). A clip with rests or chords breaks that assumption: pass grid= explicitly (e.g. grid=0.25 for a 16th-note groove) and empty cells keep a neutral offset. A clip whose notes cannot be assigned one-per-cell raises rather than importing a wrong feel.

What is extracted:

• Time attribute of each MidiNoteEvent → timing offsets relative to ideal grid positions.
• Velocity attribute of each MidiNoteEvent → velocity scaling (normalised to the highest velocity in the file).
• TimingAmount from the Groove element → pre-scales the timing offsets (100 = full, 70 = 70% of the groove's timing).
• VelocityAmount from the Groove element → pre-scales velocity deviation (100 = full groove velocity, 0 = no velocity changes).

The resulting Groove reflects the file author's intended strength. Use strength= when applying to further adjust.

What is NOT imported:

RandomAmount (use p.randomize() separately for random jitter) and QuantizationAmount (not applicable - Subsequence notes are already grid-quantised by construction).

Other MidiNoteEvent fields (Duration, VelocityDeviation, OffVelocity, Probability) are also ignored.

Parameters

• path: Path to the .agr file.
• grid: Grid size in beats (0.25 = 16th notes). None (default) infers it from the clip, assuming one note per cell.