Source code for audiofm

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Six-operator FM synthesis that plays the classic six-operator voice format.

`Synth` is an audio source with a pool of voices: press and release notes on
it and play it like any other source. `Patch` is one voice, with every
parameter as an attribute, and reads and writes the 155-byte single voice and
the 4104-byte 32-voice bank that the format's instruments and editors
exchange.
"""

from __future__ import annotations
from types import TracebackType
from typing import Self, Sequence

__version__: str
"""The audiodsp release this module came from."""
__revision__: str
"""Which source this build was made from, from `git describe`: a release tag,
or the nearest one and the commit. "unknown" when the build had no git."""

FRAMES: int
"""Frames in one block: 256."""
MAX_VOICES: int
"""The most voices a `Synth` can have: 64."""

[docs] class Operator: """One of a `Patch`'s six operators, read and written in place. Every value is the format's own whole number. Setting one outside its range raises `ValueError`. """ @property def number(self) -> int: """Which operator this is, 1 to 6.""" @property def enabled(self) -> bool: """False mutes the operator without changing its settings. Not part of the 155 bytes `Patch.pack` writes.""" @enabled.setter def enabled(self, value: bool) -> None: ... rates: tuple[int, int, int, int] """The envelope's four rates, 0 to 99. Higher is faster.""" levels: tuple[int, int, int, int] """The envelope's four levels, 0 to 99. The fourth is where a released note falls to.""" breakpoint: int """The key keyboard level scaling turns on, 0 to 99. 39 is middle C.""" left_depth: int """Level scaling below the breakpoint, 0 to 99.""" right_depth: int """Level scaling above the breakpoint, 0 to 99.""" left_curve: int """0 falls linearly, 1 falls exponentially, 2 rises exponentially, 3 rises linearly.""" right_curve: int """As `left_curve`, above the breakpoint.""" rate_scaling: int """How much faster the envelope runs on higher keys, 0 to 7.""" amp_mod: int """How far the LFO moves this operator's level, 0 to 3.""" velocity: int """How much key velocity changes the level, 0 to 7.""" level: int """Output level, 0 to 99.""" fixed: bool """True plays a fixed frequency instead of a ratio of the key's.""" coarse: int """The frequency ratio, 0 to 31, where 0 is one half; as a fixed frequency, 0 to 3 picks 1, 10, 100 or 1000 Hz.""" fine: int """Adds 0 to 99 percent to the ratio, or moves a fixed frequency up to nearly ten times.""" detune: int """0 to 14, where 7 is in tune."""
[docs] class Patch: """One voice: six operators, the algorithm that wires them, and the rest. A new patch is the initial voice: operator 1 alone, a sine at full level. """ def __init__(self) -> None: ... @property def operators(self) -> tuple[Operator, Operator, Operator, Operator, Operator, Operator]: """The six operators. ``operators[0]`` is operator 1.""" @property def algorithm(self) -> int: """How the six operators are wired, 1 to 32.""" @algorithm.setter def algorithm(self, value: int) -> None: ... @property def name(self) -> str: """Up to ten ASCII characters.""" @name.setter def name(self, value: str) -> None: ... pitch_rates: tuple[int, int, int, int] """The pitch envelope's four rates, 0 to 99.""" pitch_levels: tuple[int, int, int, int] """The pitch envelope's four levels, 0 to 99. 50 is no change.""" feedback: int """How much the feedback operator feeds itself, 0 to 7.""" key_sync: bool """True restarts every operator's phase on each note.""" lfo_speed: int """0 to 99.""" lfo_delay: int """How long the LFO waits after a note before fading in, 0 to 99.""" lfo_pitch_depth: int """Vibrato depth, 0 to 99.""" lfo_amp_depth: int """Tremolo depth, 0 to 99.""" lfo_key_sync: bool """True restarts the LFO on each note.""" lfo_wave: int """0 triangle, 1 saw down, 2 saw up, 3 square, 4 sine, 5 sample and hold.""" lfo_pitch_sens: int """How far `lfo_pitch_depth` moves the pitch, 0 to 7.""" transpose: int """0 to 48 semitones, where 24 is no change."""
[docs] def pack(self) -> bytes: """The voice as 155 bytes, in the single-voice parameter order."""
[docs] @staticmethod def unpack(data: bytes) -> Patch: """A patch from 155 voice bytes, or from a 163-byte single-voice system exclusive message. Values past a parameter's range are clamped. Raises: ValueError: the length is neither, or a message's header or checksum is wrong. """
[docs] @staticmethod def bank(data: bytes) -> list[Patch]: """The 32 voices of a bank. Args: data: The 4104-byte system exclusive message, checked against its checksum, or its 4096 data bytes alone. Raises: ValueError: the length is neither, or the header or checksum is wrong. """
[docs] @staticmethod def pack_bank(patches: Sequence[Patch]) -> bytes: """Up to 32 patches as a 4104-byte bank message. Missing slots get the initial voice."""
[docs] class Synth: """A polyphonic source that plays a `Patch`. Play it like any audio sample, or put it in a mixer. A new note takes a free voice, else the oldest released one, else the oldest held one. Args: voices: How many notes can sound at once, 1 to `MAX_VOICES`. sample_rate: Frames per second, 1000 or more. channel_count: 1, or 2 for the same signal on both channels. patch: The `Patch` to play. A new initial voice if not given. Raises: ValueError: an argument is out of range. TypeError: ``patch`` is not a `Patch`. """ def __init__(self, voices: int = 16, sample_rate: int = 48000, channel_count: int = 1, patch: Patch | None = None) -> None: ...
[docs] def deinit(self) -> None: """Silence every voice and release the synth."""
def __enter__(self) -> Self: ... def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None: ... @property def sample_rate(self) -> int: ... @property def bits_per_sample(self) -> int: ... @property def channel_count(self) -> int: ...
[docs] def press(self, note: int, velocity: int = 100) -> None: """Start `note`, 0 to 127, at `velocity`, 0 to 127. The patch is read now, so edits to it reach the next note, never a sounding one."""
[docs] def release(self, note: int) -> None: """Release every voice holding `note`."""
[docs] def release_all(self) -> None: """Release every held note, as if every key came up."""
@property def patch(self) -> Patch: """The patch new notes play.""" @patch.setter def patch(self, value: Patch) -> None: ... @property def pitch_bend(self) -> float: """-1.0 to 1.0, clamped, scaled by `bend_range`.""" @pitch_bend.setter def pitch_bend(self, value: float) -> None: ... @property def bend_range(self) -> int: """How many semitones a full `pitch_bend` moves, 0 to 24. The default is 2.""" @bend_range.setter def bend_range(self, value: int) -> None: ... @property def mod_wheel(self) -> float: """0.0 to 1.0, clamped. Adds LFO pitch and amplitude depth on top of the patch's own, up to full depth.""" @mod_wheel.setter def mod_wheel(self, value: float) -> None: ... @property def sustain(self) -> bool: """The sustain pedal. Lifting it releases the notes it held.""" @sustain.setter def sustain(self, value: bool) -> None: ... @property def voices(self) -> int: """How many notes can sound at once.""" @property def active(self) -> int: """How many voices are sounding, releases included."""