/ 
MIDI-RtMidi-FFI-0.01
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.01

SYNOPSIS

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

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

  • 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)

  • _skip_free - A hack to prevent memory errors when a device is being cleaned up. Skips free() (defaults to false)

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.

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 => 0, 0, 0x40, 0x5a );

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

TODO

Deprecate the dragon

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

Deprecate _skip_free

I've found this is only required for certain builds of librtmidi v3.0.0, but not requiring it at all would be better.

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 John Barrett.

LICENSE

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