MIDI byte <-> sequencer event coder. More...

Functions
int	snd_midi_event_new (size_t bufsize, snd_midi_event_t **rdev)
	Creates a MIDI event parser.

void	snd_midi_event_free (snd_midi_event_t *dev)
	Frees a MIDI event parser.

void	snd_midi_event_no_status (snd_midi_event_t *dev, int on)
	Enables/disables MIDI command merging.

void	snd_midi_event_reset_encode (snd_midi_event_t *dev)
	Resets MIDI encode parser.

void	snd_midi_event_reset_decode (snd_midi_event_t *dev)
	Resets MIDI decode parser.

void	snd_midi_event_init (snd_midi_event_t *dev)
	Resets MIDI encode/decode parsers.

int	snd_midi_event_resize_buffer (snd_midi_event_t *dev, size_t bufsize)
	Resizes the MIDI message encoding buffer.

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.

int	snd_midi_event_encode_byte (snd_midi_event_t dev, int c, snd_seq_event_t ev)
	Encodes byte to sequencer event.

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.

Detailed Description

MIDI byte <-> sequencer event coder.

Author: Takashi Iwai tiwai.nosp@m.@sus.nosp@m.e.de; Jaroslav Kysela perex.nosp@m.@per.nosp@m.ex.cz

Date: 2000-2001

Function Documentation

◆ snd_midi_event_decode()

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

◆ snd_midi_event_encode()

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

◆ 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

◆ snd_midi_event_free()

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

◆ snd_midi_event_init()

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

◆ snd_midi_event_new()

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

◆ snd_midi_event_no_status()

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.

◆ snd_midi_event_reset_decode()

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

◆ snd_midi_event_reset_encode()

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

◆ snd_midi_event_resize_buffer()

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

Functions

Detailed Description

Function Documentation

◆ snd_midi_event_decode()

◆ snd_midi_event_encode()

◆ snd_midi_event_encode_byte()

◆ snd_midi_event_free()

◆ snd_midi_event_init()

◆ snd_midi_event_new()

◆ snd_midi_event_no_status()

◆ snd_midi_event_reset_decode()

◆ snd_midi_event_reset_encode()

◆ snd_midi_event_resize_buffer()