Core

A main include file

NANOSECONDS_IN_SECOND

An amount of nanoseconds in a second

QUEUE_TEMPO

A constant that defines the beat tempo in microseconds

QUEUE_STATUS_PPQ

A constant that defines the base resolution of the ticks (pulses per quarter note)

void init_midi_port(MIDI_port **current_midi_port)

Allocates memory for a MIDI_port instance

Parameters
  • current_midi_port – a double pointer used to allocate memory for a MIDI_port instance

Since

v0.1

void print_midi_port(MIDI_port *current_midi_port)

Prints a name of snd_seq_client_info_t and snd_seq_port_info_t containers

Parameters
  • current_midi_port – a MIDI_port instance to display

Since

v0.1

void free_midi_message(MIDI_message *msg)

Deallocates memory for MIDI_message instance

Parameters
Since

v0.1

void init_amidi_data_instance(Alsa_MIDI_data **amidi_data)

Allocates memory for an instance of Alsa_MIDI_data or throws an error

Parameters
  • amidi_data – a double pointer used to allocate memory for a Alsa_MIDI_data instance

Since

v0.1

void assign_midi_queue(MIDI_in_data *input_data)

Creates an assigns a MIDI message queue for a MIDI_in_data instance

Parameters
  • input_data – a pointer containing a MIDI_in_data instance for creating a GAsyncQueue instance.

Since

v0.1

void assign_midi_data(MIDI_in_data *input_data, Alsa_MIDI_data *amidi_data)

Assign Alsa_MIDI_data instance to MIDI_in_data instance

Parameters
Since

v0.1

void set_MIDI_in_callback(MIDI_in_data *input_data, MIDI_callback callback, void *user_data)

Sets a callback for MIDI input events.

Parameters
  • input_dataMIDI_in_data instance

  • callbackMIDI_callback instance

  • user_data – an optional pointer to additional data that is passed to the callback function whenever it is called.

Since

v0.1

void enqueue_error(MIDI_in_data *input_data, char *etype, char *msg)

Add an error_message instance to MIDI_in_data instance

Parameters
  • input_data – a MIDI_in_data instance containing a queue to send an error to

  • etype – error type string, for example, “V0001”, “S0001”

  • msg – error message

Since

v0.1

void assign_error_queue(MIDI_in_data *input_data)

Create an error queue, add to MIDI_in_data instance

Parameters
  • input_data – a MIDI_in_data instance to add an error queue to

Since

v0.1

int init_amidi_data(Alsa_MIDI_data *amidi_data, mp_type_t port_type)

Fill Alsa_MIDI_data struct instance

Parameters
  • amidi_dataAlsa_MIDI_data instance to initialize

  • port_type – a port type to use, supports all values for mp_type_t

Returns

0 on success, -1 when port_type is not mp_type_t.MP_IN, mp_type_t.MP_VIRTUAL_IN, mp_type_t.MP_OUT, mp_type_t.MP_VIRTUAL_OUT.

Since

v0.1

int init_seq(Alsa_MIDI_data *amidi_data, const char *client_name, mp_type_t port_type)

Creates a seq instance, assigns it to Alsa_MIDI_data

Parameters
  • amidi_dataAlsa_MIDI_data instance

  • client_name – client name string

  • port_type – a port type for a sequencer, supports all values for mp_type_t

Returns

0 on success, -1 on error.

Since

v0.1

int start_input_seq(Alsa_MIDI_data *amidi_data, const char *queue_name, RMR_Port_config *port_config)

Creates a named input queue, sets its tempo and other parameters.

Parameters
  • amidi_dataAlsa_MIDI_data instance

  • queue_name – a name for a new named queue

  • port_config – an instance of port configuration: RMR_Port_config

Returns

0 or -1 when an error happens

Since

v0.1

int prepare_output(int is_virtual, Alsa_MIDI_data *amidi_data, const char *port_name)

Creates a MIDI event parser, a virtual port for virtual mode and allocates a buffer for normal mode.

TODO pick a new name, considering calls to snd_midi_event_new, snd_midi_event_init, snd_seq_create_simple_port (virtual mode) and malloc for amidi_data->buffer (normal mode).

Parameters
  • is_virtual – should the function create normal output port or a virtual one?

  • amidi_dataAlsa_MIDI_data instance

  • port_name – a name to set for a new virtual output port

Returns

0 on success, -1 on an error

Since

v0.1

unsigned int port_info(int *seq, int *pinfo, unsigned int type, int port_number)

This function is used to count or get the pinfo structure for a given port number.

Parameters
  • snd_seq_t – Alsa’s snd_seq_t instance

  • pinfo – Alsa’s snd_seq_port_info_t instance

  • type – Alsa MIDI port capabilities SND_SEQ_PORT_CAP_READ | SND_SEQ_PORT_CAP_SUBS_READ or SND_SEQ_PORT_CAP_WRITE | SND_SEQ_PORT_CAP_SUBS_WRITE

  • port_number – use -1 for counting ports and a port number to get port info (in that case a function returns 1).

TODO do we query a client number, not a port number? We are using snd_seq_query_next_client.

Returns

port count (or the amount of ports) when a negative port_number value is provided, 1 when a port ID is provided and the port is found, 0 when a port ID is not found

unsigned int get_midi_port_count(Alsa_MIDI_data *amidi_data, unsigned int type)

Counts midi ports for input and output types

Parameters
  • amidi_dataAlsa_MIDI_data instance

  • type – Alsa MIDI port capabilities, like “SND_SEQ_PORT_CAP_READ | SND_SEQ_PORT_CAP_SUBS_READ” or “SND_SEQ_PORT_CAP_WRITE | SND_SEQ_PORT_CAP_SUBS_WRITE

Returns

MIDI port count

Since

v0.1

void get_port_descriptor_by_id(MIDI_port *port, Alsa_MIDI_data *amidi_data, unsigned int port_number, unsigned int type)

Updates a port pointer to MIDI_port instance from a selected port_number.

Parameters
  • port – a pointer to update

  • amidi_dataAlsa_MIDI_data instance

  • port_number – a port number

  • type – Alsa MIDI port capabilities SND_SEQ_PORT_CAP_READ | SND_SEQ_PORT_CAP_SUBS_READ or SND_SEQ_PORT_CAP_WRITE | SND_SEQ_PORT_CAP_SUBS_WRITE

Since

v0.1

void deallocate_input_thread(struct MIDI_in_data *input_data)

Free an Alsa MIDI event parser, reset its value in MIDI_in_data instance, set current MIDI_in_data thread to dummy_thread_id

Parameters
Since

v0.1

void *alsa_MIDI_handler(void *ptr)

A start routine for alsa_MIDI_handler.

Parameters
Since

v0.1

int open_virtual_port(Alsa_MIDI_data *amidi_data, const char *port_name, MIDI_in_data *input_data)

Opens a MIDI port with a given name, creates a thread and queues for it.

Parameters
  • amidi_dataAlsa_MIDI_data instance

  • port_name – a char array pointer pointing to a port name string

  • input_data – a MIDI_in_data instance

Returns

0 on success

Since

v0.1

int send_midi_message(Alsa_MIDI_data *amidi_data, const unsigned char *message, int size)

Sends a MIDI message using a provided Alsa_MIDI_data instance

Parameters
  • amidi_dataAlsa_MIDI_data instance

  • message – a MIDI message to be sent

  • size – a size of MIDI message in bytes

Returns

0 on success, -1 on an error

Since

v0.1

int find_midi_port(Alsa_MIDI_data *amidi_data, MIDI_port *port, mp_type_t port_type, const char *substr)

Finds a MIDI port (port) by a given substring. Matches a substring in MIDI_port.client_info_name attribute.

Parameters
  • amidi_dataAlsa_MIDI_data instance

  • portMIDI_port instance

  • port_type – a port type for a sequencer, supports all values for mp_type_t, distinguishes only between “input” and “output”, so a virtual input will still be “an input”

  • substr – a port substring

Returns

1 when a port was found, -1 on an error, -2 when an invalid port type was provided

Since

v0.1

int open_port(mp_type_t port_type, unsigned int port_number, const char *port_name, Alsa_MIDI_data *amidi_data, MIDI_in_data *input_data)

Opens a MIDI port by its number. Converted from two RtMIDI methods, initially accepted boolean pointing if it’s input.

TODO read all calls in a function and decide if it really makes sense for port_type not to be inverted.

Parameters
  • port_type – a port type for a opening, supports all values for mp_type_t, currently expects MP_IN or MP_VIRTUAL_IN in input context

  • port_number – number of a port to look for

  • port_name – a name of a port to set using snd_seq_port_info_set_name()

  • amidi_dataAlsa_MIDI_data instance

  • input_data – a MIDI_in_data instance

Returns

0 on success, -1 on an error

Since

v0.1

void close_port(Alsa_MIDI_data *amidi_data, MIDI_in_data *input_data, int mode)

Closes input or output port, works for both virtual and not ports

Parameters
  • amidi_dataAlsa_MIDI_data instance

  • input_dataMIDI_in_data instance

  • mode – accepts SND_SEQ_OPEN_INPUT or SND_SEQ_OPEN_OUTPUT

Since

v0.1

int destroy_midi_output(Alsa_MIDI_data *amidi_data, MIDI_in_data *input_data)

Destroys a MIDI output port: closes a port connection and performs a cleanup.

Parameters
Returns

0 on success

Since

v0.1

int destroy_midi_input(Alsa_MIDI_data *amidi_data, MIDI_in_data *input_data)

Destroys a MIDI input port: closes a port connection, shuts the input thread down, performs cleanup / deallocations.

Parameters
Returns

0 on success

Since

v0.1

void set_port_name(Alsa_MIDI_data *amidi_data, const char *port_name)

Set the name of a port_info container in Alsa SEQ interface port information container, update a port info value for an amidi_data.vport value.

Parameters
  • amidi_data – Alsa_MIDI_data instance

  • port_name – a new name for Alsa seq port

Since

v0.1

void set_client_name(Alsa_MIDI_data *amidi_data, const char *client_name)

Set name for a amidi_data.seq snd_seq_t instance.

Parameters
  • amidi_dataAlsa_MIDI_data instance

  • client_name – a new name for Alsa seq client

Since

v0.1

int prepare_input_data_with_queues(MIDI_in_data **input_data)

Allocates memory for MIDI_in_data instance. Assigns two queues: one for MIDI messages and one for errors.

Parameters
  • input_data – a double pointer used to allocate memory for a MIDI_in_data instance

Returns

0 on success

Since

v0.1

int start_virtual_output_port(Alsa_MIDI_data **amidi_data, RMR_Port_config *port_config)

A wrapper function for a initializing a virtual output MIDI port.

Parameters
Returns

0 on success

Since

v0.1

int start_output_port(Alsa_MIDI_data **amidi_data, RMR_Port_config *port_config)

A wrapper function for starting a non-virtual output port.

Parameters
Returns

0 on success

Since

v0.1

int start_virtual_input_port(Alsa_MIDI_data **amidi_data, RMR_Port_config *port_config)

A wrapper function for opening a virtual input port

Parameters
Returns

0 on success

Since

v0.1

int start_input_port(Alsa_MIDI_data **amidi_data, RMR_Port_config *port_config)

A wrapper function for starting a non-virtual input port.

Parameters
Returns

0 on success

Since

v0.1

int reset_port_config(RMR_Port_config *port_config, mp_type_t port_type)

Fills RMR_Port_config attributes.

A port type is set first, then a queue tempo and ppq you can change. “client_name”, “port_name” and “queue_name” are set as “N/A” and then changed to default values needed for a certain port type.

Parameters
  • port_config – an instance of port configuration: RMR_Port_config

  • port_type – a port type for a sequencer, supports all values for mp_type_t

Returns

0 on success

Since

v0.1.3

int setup_port_config(RMR_Port_config **port_config, mp_type_t port_type)

Allocates memory for an instance of RMR_Port_config, sets default values for it

Parameters
  • port_config – an instance of port configuration: RMR_Port_config

  • port_type – a port type for a sequencer, supports all values for mp_type_t

Returns

0 on success

Since

v0.1.3

int destroy_port_config(RMR_Port_config *port_config)

Deallocates an instance of RMR_Port_config

Parameters
Returns

0 on success

Since

v0.1.3

int start_port(Alsa_MIDI_data **amidi_data, RMR_Port_config *port_config)

A wrapper for in, out, virtual in and virtual out MIDI port initialization. TODO add Port_config input.

Parameters
Returns

0 on success

Since

v0.1

int get_full_port_name(char *port_name, unsigned int port_number, mp_type_t port_type, Alsa_MIDI_data *amidi_data)

Finds a complete port name, including both client info and port info. A rewrite of both RtMIDI’s getPortName functions.

While this output format might look unusual, it provides info about two Alsa containers: “client info” and “port info”, in that order. It shows names and IDs.

Parameters
  • port_name – a const char pointer pointing to a string to be filled

  • port_number – a number of a port to look for

  • port_type – supports all values for mp_type_t, used to select SND_SEQ_PORT_CAP_READ | SND_SEQ_PORT_CAP_SUBS_READ or SND_SEQ_PORT_CAP_WRITE | SND_SEQ_PORT_CAP_SUBS_WRITE port capabilities

  • amidi_data – a double pointer to Alsa_MIDI_data instance

Returns

0 on success, -1 when port_name is a null pointer, -2 when incorrect value was passed for port_type argument, -3 when port wasn’t found.

Since

v0.1