subsequence.definitions

The API reference for Definitions and load_definitions.

Definitions

class Definitions(
    notes: typing.Dict[str, int] = dict(),
    cc: typing.Dict[str, int] = dict(),
    channels: typing.Dict[str, int] = dict(),
    programs: typing.Dict[str, int] = dict(),
    nrpn: typing.Dict[str, int] = dict(),
)

The name-to-number tables read from a project definitions file.

One plain dict per section, always present — an absent or null section is an empty dict. The dicts merge directly into the existing parameters: notes into drum_note_map=, cc into cc_name_map=, nrpn into nrpn_name_map=, while channels values feed channel= and programs values feed p.program_change().

The dataclass is frozen (attributes cannot be reassigned) but the dicts themselves are ordinary mutable dicts, so they can be merged and extended freely.

Example

defs = subsequence.load_definitions("project.yaml")
defs.channels["birds"]      # 3
defs.notes                  # {"ride_edge_soft": 53, ...}

Members: cc, channels, notes, nrpn, programs

Definitions.notes

Definitions.notes: typing.Dict[str, int] = dataclasses.field(default_factory=dict)

Definitions.cc

Definitions.cc: typing.Dict[str, int] = dataclasses.field(default_factory=dict)

Definitions.channels

Definitions.channels: typing.Dict[str, int] = dataclasses.field(default_factory=dict)

Definitions.programs

Definitions.programs: typing.Dict[str, int] = dataclasses.field(default_factory=dict)

Definitions.nrpn

Definitions.nrpn: typing.Dict[str, int] = dataclasses.field(default_factory=dict)

load_definitions

load_definitions(path: typing.Union[str, pathlib.Path]) -> Definitions

Load and validate a project definitions file.

Reads the YAML file at path and returns a Definitions whose notes / cc / channels / programs / nrpn dicts merge straight into pattern parameters. See the module docstring for the file format, the value ranges, and the shared-vocabulary contract with the Subsample sampler.

Validation is strict inside the sections listed above and lenient outside them: unknown top-level sections are ignored, while a bad name, a non-whole number (including YAML true/false), or an out-of-range value is rejected with an error naming the file, section, and entry.

Parameters

• path: The definitions file, as a path string or pathlib.Path.

Returns

• A Definitions with one name-to-number dict per section.

Raises

• ValueError: If the file is missing, unreadable, or not valid YAML; if the top level or a consumed section is not a mapping; or if a name or value inside a consumed section is invalid. File-system and YAML errors are wrapped so this is the only error type raised.

Example

defs = subsequence.load_definitions("project.yaml")

@comp.pattern(channel=defs.channels["kit"], drum_note_map=defs.notes)
def kit (p):
        p.hit("ride_edge_soft", beats=[1, 3])