/ 
MIDI-Stream-0.002
/ MIDI::Stream::Decoder

NAME

MIDI::Stream::Decoder - MIDI bytestream decoder

VERSION

version 0.002

SYNOPSIS

Using a callback for event-driven operation:

use MIDI::Stream::Decoder;

my $decoder = MIDI::Stream::Decoder->new(
    retain_events => false,
    callback => sub( $event ) {
        # Handle MIDI::Stream::Event $event
    }
);

# Callbacks can respond to individual event types
$decoder->attach_callback(
    [ qw/ note_off note_on / ] => sub( $event ) {
        # Handle MIDI::Stream::Event::Note $event
    }
);

# Your favourite MIDI input library goes here ...
while ( my $msg = await $some_midi_device->receive ) {
    $decoder->decode( $msg );
}

Procedural approach:

use MIDI::Stream::Decoder;

my $decoder = MIDI::Stream::Decoder->new(
    retain_events => true,
);

while ( my $msg = $some_midi_device->receive ) {
    if ( $decoder->decode( $msg ) ) {
        my @events = $decoder->events;
        # Handle MIDI::Stream::Event @events
    }
}

DESCRIPTION

MIDI::Stream::Decoder provides realtime MIDI stream decoding facilities. It supports running-status, 14-bit CC, and all basic channel, system common, and realtime messages.

MIDI::Stream::Decoder is a stateful class. A new instance should be created for each target MIDI port, device or stream.

Two main modes of operation are provided, a procedural mode where events are retrieved by-hand, and an event-driven mode where events are passed to callbacks as they arrive. Callbacks receive a MIDI::Stream::Event instance.

METHODS

new

my $decoder = MIDI::Stream::Decoder->new( %options );

Returns a new decoder instance. Options:

retain_events

Store decoded events for later retrieval. This should be set to true if using the procedural interface, or wish to hold events in memory for any other purpose. Retaining events is not required for the callback interface.

The default value is true.

enable_14bit_cc

Enable decoding of 14-bit CC values for the lower 32 CCs. This option will combine CC MSB/LSB values to a single 14-bit value, assigned to the lower (MSB) CC.

The default value is false.

round_tempo

This module will use the timing of incoming clock events to derive a tempo, or BPM. This option will force tempo to be rounded to the nearest whole number.

The default value is false.

clock_samples

The number of clock events to sample when deriving tempo.

The default value is 24.

clock_ppqn

The PPQN value of the incoming clock. This is probably 24.

The default value is 24.

decode

my $pending_count = $decoder->decode( $midi_bytes );
$decoder->decode( $midi_bytes );

Decodes any MIDI messages in the passed string. Returns the number of pending events if retain_events is enabled. Any callbacks associated with the decoded events will be invoked.

attach_callback

$decoder->attach_callback( $event, $callback );

$decoder->attach_callback(
    control_change => sub( $event ) {
        ...
        $decoder->stop;
    }
);

$decoder->attach_callback(
    [ qw/ note_on note_off / ] => sub( $event ) {
        ...
        $decoder->continue;
    }
);

Attaches the given callback to the specified event type. Multiple event types may be bound by setting $event to be an arrayref of event types.

Any number of callbacks may be attached to an event. They will be executed in the order they were attached. Should you wish to stop processing further callbacks for the given event, your callback should return $decoder->stop.

A special event 'all' will respond to all event types. These callbacks will be called before the global callback, if one was passed to the constructor. If set, the global callback will always be called no matter the return value of attached event callbacks.

cancel_event_callback

$decoder->cancel_event_callback( $event );

Cancels the callbacks associated with the given event name. As with attach_callback, $event may be an arrayref of event names.

cancel_callback

Cancels the global callback, the one passed in the constructor parameter 'callback'.

NB This operation cannot be undone!

events

Return all pending events. This clears the event queue.

fetch_one_event

Returns the next pending event from the event queue.

tempo

Return the current tempo/BPM, based on incoming clock events.

AUTHOR

John Barrett <john@jbrt.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by John Barrett.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.