/ 
MIDI-RtMidi-FFI-0.03-TRIAL
River stage one • 1 direct dependent • 1 total dependent
/ MIDI::RtMidi::FFI::Device

NAME

MIDI::RtMidi::FFI::Device - OO interface for MIDI::RtMidi::FFI

VERSION

version 0.03

SYNOPSIS

use MIDI::RtMidi::FFI::Device;

my $device = MIDI::RtMidi::FFI::Device->new;
$device->open_virtual_port( 'perl-rtmidi' );
$device->send_event( note_on => 0x40, 0x5a );
sleep 1;
$device->send_event( note_off => 0x40, 0x5a );

DESCRIPTION

MIDI::RtMidi::FFI::Device is an OO interface for MIDI::RtMidi::FFI to help you manage devices, ports and MIDI events.

METHODS

new

my $device = MIDI::RtMidi::FFI::Device->new( %attributes );

Returns a new MIDI::RtMidi::FFI::Device object. Valid attributes:

  • type - Device type : 'in' or 'out' (defaults to 'out')

  • api - MIDI API to use. This should be a RtMidiApi constant. By default the device should use the first compiled API available. See search order notes in Using Simultaneous Multiple APIs on the RtMidi website.

  • api_name - MIDI API to use by name. One of 'alsa', 'jack', 'core', 'winmm' or 'dummy'.

  • name - Device name

  • queue_size_limit - (Type 'in' only) The buffer size to allocate for queueing incoming messages (defaults to 1024)

  • bufsize - (Type 'in' only) An alias for queue_size_limit.

  • ignore_sysex - (Type 'in' only) Ignore incoming SYSEX messages (defaults to true)

  • ignore_timing - (Type 'in' only) Ignore incoming timing messages (defaults to true)

  • ignore_sensing - (Type 'in' only) Ignore incoming active sensing messages (defaults to true)

ok, msg, data, ptr

warn $device->msg unless $device->ok;

Getters for RtMidiWrapper device struct members

open_virtual_port

$device->open_virtual_port( $name );

Open a virtual device port.

This method will not work on Windows.

open_port

$device->open_port( $port, $name );

Open a port.

get_ports_by_name

$device->get_ports_by_name( $name );
$device->get_ports_by_name( qr/name/ );

Returns a list of ports matching the supplied name criteria.

open_port_by_name

$device->open_port_by_name( $name );
$device->open_port_by_name( qr/name/ );
$device->open_port_by_name( [ $name, $othername, qr/anothername/ ] );

Opens the first port found matching the supplied name criteria.

close_port

$device->close_port();

Closes the currently open port

get_port_count

$device->get_port_count();

Return the number of available MIDI ports to connect to.

get_port_name

$self->get_port_name( $port );

Returns the name of the supplied port number.

get_current_api

$self->get_current_api();

Returns the MIDI API in use for the device.

This is a RtMidiApi constant.

set_callback 🐉

Here be dragons.

$device->set_callback( sub {
    my ( $ts, $msg, $data );
    # handle $msg here
}, $data );

Type 'in' only. Sets a callback to be executed when an incoming message is received. Your callback receives the timestamp of the event, the message, and optionally some data you set while defining the callback. This data should be a simple scalar string, not a reference or other data structure.

In my experience, receiving a message on your device while a callback is in progress results in a crash.

Depending on the message rate your application expects, this may be OK.

cancel_callback

$device->cancel_callback();

Type 'in' only. Removes the callback from your device.

ignore_types

$device->ignore_types( $ignore_sysex, $ignore_timing, $ignore_sensing );
$device->ignore_types( (1)x3 );

Type 'in' only. Set message types to ignore.

get_message

$device->get_message();

Type 'in' only. Gets the next message from the queue, if available.

get_event

$device->get_event();

Type 'in' only. Gets the next message from the queue, if available, as a decoded MIDI::Event.

send_message

$device->send_message( $msg );

Type 'out' only. Sends a message to the open port.

send_event

$device->send_event( @event );
$device->send_event( note_on => 0x40, 0x5a );

Type 'out' only. Sends a MIDI::Event encoded message to the open port.

NOTE: The dtime and channel values should be omitted from the message.

TODO

Deprecate the dragon

The callback mechanism for handling incoming events is useful. It would be nice if it were more robust.

SEE ALSO

RtMidi

MIDI::RtMidi::FFI

MIDI::Event

AUTHOR

John Barrett, <john@jbrt.org>

CONTRIBUTING

https://github.com/jbarrett/MIDI-RtMidi-FFI

All comments and contributions welcome.

BUGS AND SUPPORT

Please direct all requests to https://github.com/jbarrett/MIDI-RtMidi-FFI/issues

COPYRIGHT

Copyright 2019-2021 John Barrett.

LICENSE

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