MIDI¶

MIDI input via embedded RtMidi: parsed message types and the MidiIn receiver. See the MIDI Guide for usage.

nanosynth.midi ¶

MIDI input support via embedded RtMidi.

Provides parsed MIDI message types and a MidiIn class for receiving MIDI input from hardware controllers.

This module requires the _midi C extension (built by default with NANOSYNTH_EMBED_MIDI=ON). If unavailable, importing this module raises ImportError.

Basic usage::

from nanosynth.midi import MidiIn, NoteOn

midi = MidiIn(port=0)
midi.on_note_on(lambda msg: print(f"Note {msg.note} vel {msg.velocity}"))
# ...
midi.close()

# Or as context manager:
with MidiIn(port=0) as midi:
    midi.on_cc(lambda msg: print(f"CC {msg.control} = {msg.value}"))
    input("Press Enter to quit...")

NoteOn `dataclass` ¶

MIDI Note On message.

NoteOff `dataclass` ¶

MIDI Note Off message.

ControlChange `dataclass` ¶

MIDI Control Change (CC) message.

PitchBend `dataclass` ¶

MIDI Pitch Bend message.

Value range is 0--16383, with 8192 as center (no bend).

MidiIn ¶

MIDI input port.

Args: port: Port to open. None opens a virtual port, int opens by index, str matches by name.

Raises: ImportError: If the _midi C extension is not available. RuntimeError: If the requested port cannot be opened.

close ¶

close() -> None

Close the MIDI input port.

on_note_on ¶

on_note_on(callback: Callable[[NoteOn], None]) -> None

Register a handler for Note On messages.

on_note_off ¶

on_note_off(callback: Callable[[NoteOff], None]) -> None

Register a handler for Note Off messages.

on_cc ¶

on_cc(callback: Callable[[ControlChange], None]) -> None

Register a handler for Control Change messages.

on_pitch_bend ¶

on_pitch_bend(
    callback: Callable[[PitchBend], None],
) -> None

Register a handler for Pitch Bend messages.

off_note_on ¶

off_note_on(callback: Callable[[NoteOn], None]) -> None

Remove a Note On handler.

off_note_off ¶

off_note_off(callback: Callable[[NoteOff], None]) -> None

Remove a Note Off handler.

off_cc ¶

off_cc(callback: Callable[[ControlChange], None]) -> None

Remove a Control Change handler.

off_pitch_bend ¶

off_pitch_bend(
    callback: Callable[[PitchBend], None],
) -> None

Remove a Pitch Bend handler.

list_ports `staticmethod` ¶

list_ports() -> list[str]

Return a list of available MIDI input port names.

midi_note_map ¶

midi_note_map(
    midi_in: MidiIn,
    server: Server,
    synthdef_name: str,
    **fixed_params: float,
) -> Callable[[], None]

Map MIDI note-on to synth creation and note-off to gate release.

Creates a synth for each note-on with freq derived from the MIDI note number. On note-off, sends gate=0 to the corresponding synth.

Args: midi_in: The MidiIn instance to listen on. server: The Server to create synths on. synthdef_name: Name of the SynthDef to instantiate. **fixed_params: Additional fixed parameters for all synths.

Returns: A cleanup function that removes the handlers.

midi_cc_map ¶

midi_cc_map(
    midi_in: MidiIn,
    server: Server,
    synth: Synth | int,
    cc_map: dict[int, str],
    *,
    range_min: float = 0.0,
    range_max: float = 1.0,
) -> Callable[[], None]

Map MIDI CC numbers to synth parameters.

Each CC value (0--127) is linearly scaled to [range_min, range_max] and sent as the mapped parameter name.

Args: midi_in: The MidiIn instance to listen on. server: The Server for parameter updates. synth: Target synth (Synth proxy or node ID). cc_map: Mapping of CC number to parameter name. range_min: Output range minimum. range_max: Output range maximum.

Returns: A cleanup function that removes the handler.