Banks API

The bankfiles module defines FluidPatcher’s declarative data model. It turns YAML bank files into structured Python objects that can be validated, inspected, modified, and written back to disk.

Advanced users and UI authors can use these classes directly to build interactive editors, patch designers, or controller-driven workflows.

The Bank Class

fluidpatcher.bankfiles.Bank

Parsed representation of a FluidPatcher bank YAML document.

Attributes:
  • root (dict) –

    Raw root-level configuration data.

  • patch (dict) –

    Raw dictionary of patches (unmerged).

  • patches (list[str]) –

    Patch names in declaration order.

  • soundfonts (list[SFPreset]) –

    Dynamic list of soundfont files required by patches.

Users don't instantiate Bank objects directly. They are created by FluidPatcher.load_bank and a reference stored at FluidPatcher.bank.

fp = FluidPatcher()
fp.bank

Root vs Patch Data

Bank files are split into two conceptual areas:

  • Root level — settings outside the patches block

  • Patch level — settings within a named entry under patches

The root and patch attributes provide direct access to these two areas of the parsed bank data, allowing them to be queried or modified independently.

Indexing the Bank object by patch name returns a merged view combining root and patch data using the following rules:

  • SoundFont presets fall back to root values
  • Lists (messages, rules) concatenate root + patch
  • Dictionaries (sequences, arpeggios, etc.) merge, with patch values overriding root values

This merged view is computed dynamically and does not modify the underlying bank structure. It should be treated as read-only; edits should instead be made via the root and patch mappings.

Modifying Banks Programmatically

Banks are mutable, and are designed to support interactive workflows such as:

  • Changing a patch’s SoundFont preset
  • Inserting or removing MIDI rules
  • Adjusting controller mappings
  • Writing the modified bank back to disk

Example: change the program on channel 1 for a patch:

fp.bank.patch["My Patch"][1] = SFPreset("piano.sf2", 0, 4)

Mutating Objects and Serialization

When bank objects are loaded from YAML, they retain their original serialized representation to support consistent round-trip loading and saving. Bank object attributes can be edited in-place, but if dumped to file they appear in their original form.

To update an object's YAML representation, it must replaced with a new instance. Most bank object types (except SFPreset) provide a copy() method to simplify this. copy() creates a new object using the original parameters as defaults, with any provided keyword arguments overriding selected fields.

rule = fp.bank.patch["My Patch"]["rules"][2]

fp.bank.patch["My Patch"]["rules"][2] = rule.copy(
    chan=3,
    val="0-127=50-80"
)

This pattern preserves round-trip fidelity while supporting safe, incremental edits.

Tip

Replace edited objects with copies to persist them to disk.

Bank Object Types

fluidpatcher.bankfiles.SFPreset

SoundFont preset reference

Attributes:
  • file (str) –

    Path to the .sf2 file

  • bank (int) –

    SoundFont bank index

  • prog (int) –

    Program index

Represents a single SoundFont program selection. These objects correspond to YAML entries such as:

1: piano.sf2:000:004

They are lightweight and effectively immutable, making them safe to replace programmatically.

fluidpatcher.bankfiles.MidiMessage

Description of a single MIDI message

Attributes:
  • type (str) –

    Message type (“note”, “ctrl”, “sysex”, ...)

  • chan (int) –

    Channel number (where applicable)

  • num (int) –

    Note/controller number (where applicable)

  • val (int) –

    Value (velocity, CC value, pitch bend, etc.)

Represents a MIDI message that can be sent when loading a bank, applying a patch, or from a Sequence.

Supported features include:

  • Channel messages (note, CC, program change, etc.)
  • System realtime messages and SysEx
  • Shorthand aliases (nt, cc, pc)
  • Scientific pitch notation (C#4)

Example:

msg = MidiMessage(type="cc", chan=1, num=7, val=100)
fp.bank.patch["My Patch"]["messages"].append(msg)

fluidpatcher.bankfiles.MidiRule

A mapping that describes how to match incoming MIDI messages and what events they should trigger.

Attributes:
  • type (str) –

    Matching message type

  • totype (str) –

    Resulting message type (default: self.type)

  • chan (Route) –

    Channel range/transform (optional)

  • num (Route) –

    Parameter range/transform (optional)

  • val (Route) –

    Value range/transform (optional)

  • **pars (dict) –

    additional parameters for custom functionality

A declarative routing directive connecting incoming MIDI messages to synth events or programmatic actions.

Rules can:

  • Filter by type, channel, controller, or value
  • Remap ranges (e.g. slider → effect parameter)
  • Translate between message types
  • Trigger players, counters, or actions

fluidpatcher.bankfiles.Route

An object that expresses MIDI parameter ranges/transforms.

Attributes:
  • min (int | float) –

    minimum value to match

  • max (int | float) –

    maximum value to match

  • mul (int | float) –

    multiplier to apply to values

  • add (int | float) –

    amount to add to values

  • tomin (int | float) –

    minimum of target range for values

  • tomax (int | float) –

    maximum of target range for values

from_affine(min, max, mul, add) classmethod

Creates a Route using an affine transform

Parameters:
  • min (int | float) –

    minimum value to match

  • max (int | float) –

    maximum value to match

  • mul (int | float) –

    multiplier to apply to values

  • add (int | float) –

    amount to add to values

from_ranges(min=None, max=None, tomin=None, tomax=None) classmethod

Creates a Route based on from-to ranges

Parameters:
  • min (int | float, default: None ) –

    minimum value to match

  • max (int | float, default: None ) –

    maximum value to match

  • tomin (int | float, default: None ) –

    minimum of target range for values

  • tomax (int | float, default: None ) –

    maximum of target range for values

The chan, num, and val attributes of a MidiRule are converted to Route objects on creation. A Route instance can be used to modify one of these attributes after creating the rule.

fluidpatcher.bankfiles.Sequence

Step-sequenced event container

Attributes:
  • events (list) –

    Parsed events grouped by pattern

  • order (list) –

    Playback order of patterns (default: [1])

  • tempo (int) –

    Beats per minute (default: 120)

  • tdiv (int) –

    Beat divisor (default: 8)

  • swing (float) –

    Timing swing ratio (default: 0.5)

  • groove (int | list) –

    Beat accent pattern (default: [1, 1])

A step-sequenced event container supporting:

  • Pattern-based sequencing
  • Multi-track layouts
  • Groove patterns
  • Text or structured event syntax

fluidpatcher.bankfiles.Arpeggio

Patterned arpeggiation definition

Attributes:
  • style (str) –

    Pattern type

  • tempo (int) –

    Beats per minute (default: 120)

  • tdiv (int) –

    Beat divisor (default: 8)

  • swing (float) –

    Timing swing ratio (default: 0.5)

  • groove (int | list) –

    Beat accent pattern (default: [1, 1])

Defines a patterned arpeggiation behavior. Arpeggios are triggered by incoming notes and can be reassigned or modified per patch.

fluidpatcher.bankfiles.MidiLoop

Looping MIDI event generator

Attributes:
  • beats (int) –

    Loop length in beats

  • tempo (int) –

    Beats per minute (default: 120)

A looping MIDI recorder/player used for live looping and overdubbing.

fluidpatcher.bankfiles.MidiFile

MIDI file playback directive

Attributes:
  • file (str) –

    Path to a .mid file

  • tempo (int) –

    Beats per minute (default: 120)

  • barlength (int) –

    Ticks per musical measure (default: 1)

  • jumps (list[str]) –

    List of bar jumps as [from]>[to] (default: [])

  • shift (int) –

    Channel shift amount (default: 0)

  • mask (list[str]) –

    Ignored message types (default: [])

MIDI file playback directive supporting:

  • Jump points
  • Tempo matching
  • Note shifting to avoid collisions

fluidpatcher.bankfiles.LadspaEffect

LADSPA audio effect declaration

Attributes:
  • lib (str) –

    LADSPA library basename

  • plugin (str) –

    Plugin label (default: '')

  • audio (list[str]) –

    Audio port names (default: ['Input', 'Output'])

  • vals (dict) –

    Initial values for control ports (default: {})

  • chan (list[int]) –

    Input channel routing (default: [])

Defines a LADSPA plugin instance and routing.

Effects are declarative:

  • Applying a patch rebuilds the FX chain as needed
  • Parameter changes can be driven by MidiRule mappings

fluidpatcher.bankfiles.Counter

State storing object that responds to messages/rules

Attributes:
  • min/max (float) –

    range for values

  • startval (float) –

    Initial value for counter (default: self.min)

  • wrap (bool) –

    wrap values if True, else clamp to range (default: False)

A persistent state container used by routing rules.

Counters enable:

  • Toggle behavior
  • Stepped parameter changes
  • Stateful controller logic

Summary

The bankfiles module defines everything that can appear in a bank.

Key takeaways:

  • YAML is parsed into validated Python objects
  • Banks are mutable and round-trippable
  • Patch access returns merged views, not copies
  • Use the copy() method to save edited objects to disk

If FluidPatcher is the engine, bankfiles is the language it speaks.