ALSA project - the C library reference: Sequencer event <-> MIDI byte stream coder

ALSA project - the C library reference

- Main Page
- Related Pages
- Modules
- Data Structures
- Files
- Examples

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Typedefs | Functions
Sequencer event <-> MIDI byte stream coder
MIDI Sequencer

## Typedefs
typedef struct snd_midi_event | snd_midi_event_t

## Functions
int | snd_midi_event_new (size_t bufsize, snd_midi_event_t **rdev)
| Creates a MIDI event parser. More...
int | snd_midi_event_resize_buffer (snd_midi_event_t *dev, size_t bufsize)
| Resizes the MIDI message encoding buffer. More...
void | snd_midi_event_free (snd_midi_event_t *dev)
| Frees a MIDI event parser. More...
void | snd_midi_event_init (snd_midi_event_t *dev)
| Resets MIDI encode/decode parsers. More...
void | snd_midi_event_reset_encode (snd_midi_event_t *dev)
| Resets MIDI encode parser. More...
void | snd_midi_event_reset_decode (snd_midi_event_t *dev)
| Resets MIDI decode parser. More...
void | snd_midi_event_no_status (snd_midi_event_t *dev, int on)
| Enables/disables MIDI command merging. More...
long | snd_midi_event_encode (snd_midi_event_t *dev, const unsigned char *buf, long count, snd_seq_event_t *ev)
| Encodes bytes to sequencer event. More...
int | snd_midi_event_encode_byte (snd_midi_event_t *dev, int c, snd_seq_event_t *ev)
| Encodes byte to sequencer event. More...
long | snd_midi_event_decode (snd_midi_event_t *dev, unsigned char *buf, long count, const snd_seq_event_t *ev)
| Decodes sequencer event to MIDI byte stream. More...

## Detailed Description

Sequencer event <-> MIDI byte stream coder

## Typedef Documentation

typedef struct snd_midi_event snd_midi_event_t

container for sequencer midi event parsers

## Function Documentation

long snd_midi_event_decode | ( | snd_midi_event_t * | dev,
|  | unsigned char * | buf,
|  | long | count,
|  | const snd_seq_event_t * | ev
| ) |  |

Decodes sequencer event to MIDI byte stream.

Parameters

  [in] | dev | MIDI event parser.
  [out] | buf | Buffer for the resulting MIDI byte stream.
  [in] | count | Number of bytes in buf.
  [in] | ev | The sequencer event to decode.

Returns
  The number of bytes written to buf, or a negative error code.

This function tries to decode the sequencer event into one or more MIDI messages, and writes the raw MIDI byte(s) into buf.

The generated MIDI messages may use running status, unless disabled with snd_midi_event_no_status.

The required buffer size for a sequencer event it as most 12 bytes, except for System Exclusive events (ev->type == SND_SEQ_EVENT_SYSEX) which can have any length (as specified by ev->data.ext.len).

The following sequencer events correspond to MIDI messages:

- SND_SEQ_EVENT_NOTEOFF
- SND_SEQ_EVENT_NOTEON
- SND_SEQ_EVENT_KEYPRESS
- SND_SEQ_EVENT_CONTROLLER
- SND_SEQ_EVENT_PGMCHANGE
- SND_SEQ_EVENT_CHANPRESS
- SND_SEQ_EVENT_PITCHBEND
- SND_SEQ_EVENT_SYSEX
- SND_SEQ_EVENT_QFRAME
- SND_SEQ_EVENT_SONGPOS
- SND_SEQ_EVENT_SONGSEL
- SND_SEQ_EVENT_TUNE_REQUEST
- SND_SEQ_EVENT_CLOCK
- SND_SEQ_EVENT_START
- SND_SEQ_EVENT_CONTINUE
- SND_SEQ_EVENT_STOP
- SND_SEQ_EVENT_SENSING
- SND_SEQ_EVENT_RESET
- SND_SEQ_EVENT_CONTROL14
- SND_SEQ_EVENT_NONREGPARAM
- SND_SEQ_EVENT_REGPARAM

Errors:
  -EINVAL
    ev is not a valid sequencer event.
  -ENOENT
    The sequencer event does not correspond to one or more MIDI messages.
  -ENOMEM

    The MIDI message(s) would not fit into count bytes.

Conforming to:
  LSB 3.2

See Also
  snd_midi_event_reset_decode, snd_midi_event_no_status

long snd_midi_event_encode | ( | snd_midi_event_t * | dev,
|  | const unsigned char * | buf,
|  | long | count,
|  | snd_seq_event_t * | ev
| ) |  |

Encodes bytes to sequencer event.

Parameters

  [in] | dev | MIDI event parser.
  [in] | buf | Buffer containing bytes of a raw MIDI stream.
  [in] | count | Number of bytes in buf.
  [out] | ev | Sequencer event.

Returns
  The number of bytes consumed, or a negative error code.

This function tries to use up to count bytes from the beginning of the buffer to encode a sequencer event. If a complete MIDI message has been encoded, the sequencer event is written to ev; otherwise, ev->type is set to SND_SEQ_EVENT_NONE, and further bytes are required to complete a message.

The buffer in dev is used to hold any bytes of a not-yet-complete MIDI message. If a System Exclusive message is larger than the buffer, the message is split into multiple parts, and a sequencer event is returned at the end of each part.

Any bytes that are not part of a valid MIDI message are silently ignored, i.e., they are consumed without signaling an error.

When this function returns a system exclusive sequencer event (ev->type is SND_SEQ_EVENT_SYSEX), the data pointer (ev->data.ext.ptr) points into the MIDI event parser's buffer. Therefore, the sequencer event can only be used as long as that buffer remains valid, i.e., until the next call to snd_midi_event_encode, snd_midi_event_encode_byte, snd_midi_event_resize_buffer, snd_midi_event_init, snd_midi_event_reset_encode, or snd_midi_event_free for that MIDI event parser.

This function can generate any sequencer event that corresponds to a MIDI message, i.e.:

- SND_SEQ_EVENT_NOTEOFF
- SND_SEQ_EVENT_NOTEON
- SND_SEQ_EVENT_KEYPRESS
- SND_SEQ_EVENT_CONTROLLER
- SND_SEQ_EVENT_PGMCHANGE
- SND_SEQ_EVENT_CHANPRESS
- SND_SEQ_EVENT_PITCHBEND
- SND_SEQ_EVENT_SYSEX
- SND_SEQ_EVENT_QFRAME
- SND_SEQ_EVENT_SONGPOS
- SND_SEQ_EVENT_SONGSEL
- SND_SEQ_EVENT_TUNE_REQUEST
- SND_SEQ_EVENT_CLOCK
- SND_SEQ_EVENT_START
- SND_SEQ_EVENT_CONTINUE
- SND_SEQ_EVENT_STOP
- SND_SEQ_EVENT_SENSING
- SND_SEQ_EVENT_RESET

Some implementations may also be able to generate the following events for a sequence of controller change messages:

- SND_SEQ_EVENT_CONTROL14
- SND_SEQ_EVENT_NONREGPARAM
- SND_SEQ_EVENT_REGPARAM

Conforming to:
  LSB 3.2

See Also
  snd_midi_event_new, snd_midi_event_reset_encode, snd_midi_event_encode_byte

int snd_midi_event_encode_byte | ( | snd_midi_event_t * | dev,
|  | int | c,
|  | snd_seq_event_t * | ev
| ) |  |

Encodes byte to sequencer event.

Parameters

  [in] | dev | MIDI event parser.
  [in] | c | A byte of a raw MIDI stream.
  [out] | ev | Sequencer event.

Returns
  1 if a sequenver event has been completed, 0 if more bytes are required to complete an event, or a negative error code.

This function tries to use the byte c to encode a sequencer event. If a complete MIDI message has been encoded, the sequencer event is written to ev; otherwise, further bytes are required to complete a message.

See also the description of snd_midi_event_encode.

Conforming to:
  LSB 3.2

See Also
  snd_midi_event_new, snd_midi_event_reset_encode, snd_midi_event_encode

void snd_midi_event_free | ( | snd_midi_event_t * | dev | ) |

Frees a MIDI event parser.

Parameters

  dev | MIDI event parser.

Frees a MIDI event parser.

Conforming to:
  LSB 3.2

void snd_midi_event_init | ( | snd_midi_event_t * | dev | ) |

Resets MIDI encode/decode parsers.

Parameters

  dev | MIDI event parser.

This function resets both encoder and decoder of the MIDI event parser.

See Also
  snd_midi_event_reset_encode, snd_midi_event_reset_decode

Conforming to:
  LSB 3.2

int snd_midi_event_new | ( | size_t | bufsize,
|  | snd_midi_event_t ** | rdev
| ) |  |

Creates a MIDI event parser.

Parameters

  [in] | bufsize | Size of the buffer used for encoding; this should be large enough to hold the largest MIDI message to be encoded.
  [out] | rdev | The new MIDI event parser.

Returns
  Zero on success, otherwise a negative error code.

This function creates and initializes a MIDI parser object that can be used to convert a MIDI byte stream to sequencer events (encoding) and/or to convert sequencer events to a MIDI byte stream (decoding).

Errors:
  -ENOMEM

    Out of memory.

Conforming to:
  LSB 3.2

void snd_midi_event_no_status | ( | snd_midi_event_t * | dev,
|  | int | on
| ) |  |

Enables/disables MIDI command merging.

Parameters

  dev | MIDI event parser.
  on | 0 to enable MIDI command merging, 1 to always write the command byte.

This function enables or disables MIDI command merging (running status).

When MIDI command merging is not disabled, snd_midi_event_decode is allowed to omit any status byte that is identical to the previous status byte.

void snd_midi_event_reset_decode | ( | snd_midi_event_t * | dev | ) |

Resets MIDI decode parser.

Parameters

  dev | MIDI event parser.

This function resets the MIDI decoder of the parser dev. The next decoded message does not use running status from before the call to snd_midi_event_reset_decode.

Conforming to:
  LSB 3.2

void snd_midi_event_reset_encode | ( | snd_midi_event_t * | dev | ) |

Resets MIDI encode parser.

Parameters

  dev | MIDI event parser.

This function resets the MIDI encoder of the parser dev. Any partially encoded MIDI message is dropped, and running status state is cleared.

Conforming to:
  LSB 3.2

int snd_midi_event_resize_buffer | ( | snd_midi_event_t * | dev,
|  | size_t | bufsize
| ) |  |

Resizes the MIDI message encoding buffer.

Parameters

  dev | MIDI event parser.
  bufsize | The new buffer size.

Returns
  Zero on success, otherwise a negative error code.

This function resizes the buffer that is used to hold partially encoded MIDI messages.

If there is a partially encoded message in the buffer, it is dropped.

Errors:
  -ENOMEM

    Out of memory.

See Also
  snd_midi_event_encode, snd_midi_event_reset_encode