NAME
MIDI::RtMidi::FFI::Device::In - OO interface for MIDI::RtMidi::FFI input devices
VERSION
version 0.10
SYNOPSIS
DESCRIPTION
METHODS
See MIDI::RtMidi::FFI::Device for documentation methods common to all device types.
new
Construct new instance.
my $midiin = MIDI::RtMidi::FFI::Device::In->new( %options );See global device options in "new" in MIDI::RtMidi::FFI::Device.
ignore_sysex
Ignore incoming SysEx messages. Default: true
ignore_timing
Ignore incoming timing messages. Default: true
ignore_sensing
Ignore incoming active sensing messages. Default: true
enable_14bit_cc
Enable decoding of MSB/LSB pairs for lower 32 CCs to 14-bit values. Default: false
retain_events
Retain decoded events. Calling "decode" or "get_message_decoded" will clear events from the queue as they are retrieved.
If you intend to use callbacks to retrieve MIDI events or data, consider disabling this option to save memory. All pending events may be retrieved with:
my @events = $midiin->decoder->events();Default: true.
queue_size_limit
Buffer size for incoming messages. Default: 4096 bytes
bufsize
An alias for queue_size_limit.
remap_event_names
If true, decoded incoming events will use "EVENTS" in MIDI::Event namesMIDI::Event for backwards compatibility. If false, MIDI::Stream event names will be used.
Default: true.
bufsize
Read-only accessor for bufsize/queue_size_limit parameter.
set_callback
$device->set_callback( sub( $dt, $msg ) {
# handle $msg here
} );Sets a callback to be executed when an incoming MIDI message is received. Your callback receives the time which has elapsed since the previous event in seconds, alongside the MIDI message.
NB As a callback may occur at any point in your program's flow, the program should probably not be doing much when it occurs. That is, programs handling RtMidi callbacks should be asleep the callback is triggered. See "get_fh" for an approach to integrating rtmidi into event loops.
See the examples included with this dist for some ideas on how to incorporate callbacks into your program.
set_callback_decoded
$device->set_callback_decoded( sub( $dt, $msg, $event ) {
# handle $msg / $event here
} );Same as "set_callback", though also attempts to decode the message, and pass that to the callback as an array ref. The original message is also sent in case this fails.
See "remap_event_names" - a constructor option which sets event names for incoming events.
cancel_callback
$device->cancel_callback();Removes the callback from your device.
get_fh
# Future::AsyncAwait style ...
my $fh = $midi_in->get_fh;
my $size = $midi_in->bufsize;
my $decoder = MIDI::Stream::Decoder->new(
callback => sub( $event ) { # Handle $event here }
);
while ( my $bytes = await Future::IO->read( $fh, $size ) ) {
$decoder->decode( $bytes );
}This uses the rtmidi callback mechanism to write MIDI bytes to a pipe as the arrive. This method returns the other end of the pipe as a nonblocking IO::Handle instance, which can be handed to the event loop of your choice.
NB This receives raw MIDI bytes, not decoded events with timestamps. This cannot be used in conjunction with "set_callback" or "set_callback_decoded".
ignore_types
$device->ignore_types( $ignore_sysex, $ignore_timing, $ignore_sensing );
$device->ignore_types( (1)x3 );Type 'in' only. Set message types to ignore.
ignore_sysex
$device->ignore_sysex( 1 );
$device->ignore_sysex( 0 );Type 'in' only. Set whether or not to ignore sysex messages.
ignore_timing
$device->ignore_timing( 1 );
$device->ignore_timing( 0 );Type 'in' only. Set whether or not to ignore clock/timing messages.
ignore_sensing
$device->ignore_sensing( 1 );
$device->ignore_sensing( 0 );Type 'in' only. Set whether or not to ignore active sensing messages.
get_message
$device->get_message();Type 'in' only. Gets the next message from the queue, if available.
get_message_decoded
$device->get_message_decoded();Type 'in' only. Gets the next message from the queue, if available, decoded as an event. See "decode_message" for what to expect from incoming events.
get_event
Alias for "get_message_decoded".
decode_message
my $event = $device->decode_message( $msg );Decodes the passed MIDI byte string with MIDI::Stream::Decoder.
decode
Alias for "decode_message"
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.