Advanced Linux Sound Architecture

SEQUENCER

3.1 Events

Messaging between clients is performed by sending events from one client to another. These events contain high-level MIDI oriented messages or sequencer specific messages.

3.1.1 Structure of an event

An event, as stored within the sequencer's queues consists of:

Internal pointer to next event. This are actually 2 pointers: the left and right child for the priority queue. If the event is stored in a FIFO only one pointer (left) is used, the other is set to NULL. These pointers are hidden for clients. (8 bytes)
Type of the event. (2 bytes)
- 1 byte for event type id
- 1 byte for event flags
  - time stamp "real time"/"song ticks"
  - time mode "absolute"/"relative to current time"
Timestamp of the event (8 bytes)
Source address of the event. (4 bytes)
Destination address of the event. (4 bytes)
The actual event data. (8 bytes)

The event as seen by the clients starts with the event type, the internal pointers are not presented to the clients.

The complete event can be stored in one cell. Memory allocation is handled by the sequencer's own memory manager.

Implementation of an event:

	/* sequencer event */
typedef struct snd_seq_event_t {
	snd_seq_event_type	type;	/* event type */
	unsigned char		flags;	/* event flags */
	char			unused1,
				unused2;
	
	/* schedule time */
	union {
		snd_seq_tick_time_t tick;
		snd_seq_real_time_t real;
	} time;
			
	snd_seq_addr_t	source;	/* source address */
	snd_seq_addr_t	dest;	/* destination address */
	
			
	union {			/* event data... */
		snd_seq_ev_note	 note;
		snd_seq_ev_ctrl  control;
		snd_seq_ev_raw8	 raw8;
		snd_seq_ev_raw32 raw32;		
		snd_seq_ev_ext	 ext;
	} data;
} snd_seq_event_t;

3.1.2 Time stamp

The timestamp of the event can either specified in 'real time' or in 'song ticks'. Which format is used is determined by the event flags.

	typedef struct {
	        int     sec;            /* seconds */
	        int     nsec;           /* nanoseconds */
	} snd_seq_real_time_t;

	typedef unsigned int snd_seq_tick_time_t;       /* midi ticks */



        /* schedule time */
        union {
                snd_seq_tick_time_t tick;
                snd_seq_real_time_t real;
        } time;

Note that the time format used for real time events is very similar to timeval struct used for unix system time.

The 'absurd' resolution of the timestamps allows us to perform very accurate conversions between songposition and real time. Round-off errors can be neglected.

If a timestamp with a relative timestamp is delivered to to ALSA the specified timestamp will be used as an offset to the current time of the queue the event is send into. At that point the timestamp of the event will be converted into an absolute timestamp.

An client that relies on these relative timestamps is the MIDI input port. As each sequencer queue has it's own clock the only way to deliver events at the right time is by using the relative timestamp format. When the event arrives at the queue it is normalised to absolute format.

3.1.3 Source / destination address

To identify the source and destination of an event the addressing field contains the following information:

Sequencer queue: 0..15:
- 0..15 = destination queue
- 255 = broadcast to all queues
Client number: 0..255:
- 0..191 = destination client
- 192..254 = multicasts to groups of clients/ports/channels
- 255 = broadcast to all clients (only for dest)
Port within client: 0..254:
- 0..254 = destination port
- 255 = broadcast to all ports
Channel within client: 0..15:
- 0..15 = destination channel
- 255 = broadcast to all channels

A total of 4 bytes are needed for specifying a full address.

Version 0.036, April 2nd, 1999	Usage:
Copyright (c) 1998 by Frank van de Pol, Netherlands	Advanced Linux Sound Architecture