subsequence.forms

The API reference for Section and Form.

Section

class Section(
    name: str,
    bars: int,
    energy: float = 0.5,
    key: typing.Optional[str] = None,
    scale: typing.Optional[str] = None,
)

One section of a form — the payload home.

Attributes

• name: The section name ("verse").
• bars: Length in bars (≥ 1).
• energy: The section's energy level (0.0–1.0; the arranging dial). Read by p.energy and min_energy= gating; a composition.energy() dict overrides it (the dict is the later, performance-level dial).
• key: Optional key override — re-anchors key-relative content (degrees, romans, generated material, and key-relative section progressions bound with section_chords) to this section's tonic. Absolute content (note names, MIDI pitches, frozen chords) is never moved, and chord-relative content (ChordTone, Approach) tracks the sounding chord rather than the key — see the three-intent model in the docs. The live graph engine (harmony(style=...)) stays in the composition key by design (a stateful walk does not transpose mid-stream).
• scale: Optional scale/mode override (e.g. "minor") — moves the mode as well as the tonic, so a section can genuinely change to the relative or parallel minor. Falls back to the form's scale, then the composition's.

Members: bars, energy, key, name, scale

Section.name

Section.name: str

Section.bars

Section.bars: int

Section.energy

Section.energy: float = 0.5

Section.key

Section.key: typing.Optional[str] = None

Section.scale

Section.scale: typing.Optional[str] = None

Form

class Form(
    sections: typing.Iterable[typing.Any],
    key: typing.Optional[str] = None,
    scale: typing.Optional[str] = None,
)

A frozen sequence of Sections — the editable, bindable form value.

List-friendly: the constructor coerces ("name", bars) tuples, so Form([("verse", 8), ("chorus", 8)]) and Form([Section("verse", 8), Section("chorus", 8)]) are the same value. Repetition is Python list arithmetic before construction.

A form may carry its own key/scale — the form tier of the key-source chain (Section.key overrides it; it overrides the composition key). A whole AABA in one key with one section borrowing another is Form([...], key="A") plus a Section(..., key="F").

Coerce any iterable of Sections / (name, bars) tuples.

Members: bars, describe, insert, key, replace, scale, sections, with_energy

Form.sections

Form.sections: typing.Tuple[Section, ...]

Form.key

Form.key: typing.Optional[str] = None

Form.scale

Form.scale: typing.Optional[str] = None

Form.bars

property Form.bars: int

Total length in bars.

Form.replace

Form.replace(
    slot: int,
    section: typing.Optional[Section] = None,
    **changes: typing.Any,
) -> Form

Replace the section at a 1-based slot — whole, or by field.

form.replace(3, bars=16) stretches slot 3; form.replace(3, Section("drop", 16, energy=1.0)) swaps it out.

Form.insert

Form.insert(slot: int, section: typing.Any) -> Form

Insert a section at a 1-based slot (existing sections shift right).

slot may be len(form) + 1 to append.

Form.with_energy

Form.with_energy(energies: typing.Dict[str, float]) -> Form

Set the energy payload on named sections — {"chorus": 0.9}.

Every section whose name appears in the mapping takes the new value; naming a section the form does not contain raises. Energy ramps ((start, end) tuples) live in composition.energy(), not in the payload — a Section carries one number.

Form.describe

Form.describe() -> str

A readable one-section-per-line summary.