- NAME
- VERSION
- SYNOPSIS
- DESCRIPTION
- METHODS
  - new
  - ok, msg, data, ptr
  - open_virtual_port
  - open_port
  - get_ports_by_name
  - open_port_by_name
  - close_port
  - get_port_count
  - get_port_name
  - get_current_api
  - set_callback 🐉
  - cancel_callback
  - ignore_types
  - get_message
  - send_message
  - send_event
- TODO
  - Deprecate the dragon
  - Deprecate _skip_free
- SEE ALSO
- AUTHOR
- CONTRIBUTING
- BUGS AND SUPPORT
- COPYRIGHT
- LICENSE

# 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.