
              Advanced Linux Sound Architecture (ALSA) - Sequencer
              ====================================================
              http://www.inter.nl.net/users/F.K.W.van.de.Pol/alsa/

By Frank van de Pol, F.K.W.van.de.Pol@Inter.nl.net

ALSA Sequencer 
==============

This directory contains a prototype for the ALSA Sequencer. Beware that this
is *development* code. My motivation for writing this prototype is to get a
proof of concept and feasibility for this project. The eventually
(hopefully) working prototype can be used for discussing sequencer APIs.

Current status (last updated 9 Jul 1998):
=========================================

* Allows scheduling and routing of real-time events. No support for song
  timestamps and tempos yet. There is only one timing queue.

* Both user-land and kernel clients can connect, send events, receive events
  and communicate directly with the sequencer (ioctl()). Reads and writes
  for user-land clients can be batched, blocking io and select() is
  supported. Kernel clients can directly enqueue data to the priority queue
  and use a call-back for incoming data.

* A simple timer for the system clock (100Hz) is provided. The timer is
  started and stopped by sending SND_SEQ_EVENT_START and SND_SEQ_EVENT_STOP
  messages to the timer (client 0, port 0).

* Support for fixed length events and variable length events (used for
  system exclusive data)

* proc interface (/proc/sound/sndseq) to see what clients have registered.

* Included sample clients:

  - readtime    : display current sequencer time

  - usertest1   : decoding of received events to text

  - usertest2   : a simple user-land driver that plays received events to
                  the MIDI output port (/dev/sndmidi00). It uses Round-Robin
                  scheduling to get reasonable performance. Tested with a
                  Gravis Ultrasound MAX card and external Yamaha XG 
                  synthesizer.
                  It supports the following events:
                    - SND_SEQ_EVENT_NOTEON
                    - SND_SEQ_EVENT_NOTEOFF
                    - SND_SEQ_EVENT_PGMCHANGE
                    - SND_SEQ_EVENT_PITCHBEND
                    - SND_SEQ_EVENT_CONTROLLER
                    - SND_SEQ_EVENT_START       (send real-time start)
                    - SND_SEQ_EVENT_STOP        (send real-time stop)
                    - SND_SEQ_EVENT_CONTINUE    (send real-time continue)
                    - SND_SEQ_EVENT_SYSEX

  - playmidi    : a player for standard midi files (SMF). It is based on the
                  readmidi library, so only type 0 midi files are supported. 
                  Output is send to client 1 (hard coded), so either
                  usertest1 or usertest2 should be started first.

  - kernel-client1 
                : a test for the kernel API, just bounces events to next
                  client


Installation:
=============

- edit Makefile and let TOPDIR point to the source directory of the ALSA
  driver.
- Compile the sequencer and clients: 
     $ make
- make sure ALSA is loaded
- load the sequencer (as root)
     $ insmod snd-seq.o
- load the timer (as root)
     $ insmod snd-systimer.o

- run the clients
     start our synth driver:
     $ usertest2 (preferably as root)

     and in some other session start playback of a MIDI file (make sure your
     synth gear is switched on and the faders on your mixing desk are open..)
     $ cd playfile
     $ playfile pick_up_the_pieces.mid
 
- Have fun. 
     


Todo:
=====

Many things.... 

- add multiple queues
- add ticks/tempo timing stuff
- kill some bugs
- work out client & port registration/lookup
- add synchronization
- add more clients



References on the web:
======================

ALSA:            http://alsa.jcu.cz/
ALSA Sequencer:  http://www.inter.nl.net/users/F.K.W.van.de.Pol/alsa/

