
              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 31 Aug 1998):
=========================================

* Allows scheduling and routing of both real-time events and events with a
  midi tick timestamp. The sequencer uses tempo (us/beat) and specified PPQ
  resolution (ticks/beat) to calculate the ticks from time.

* 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 driver for the system clock (100Hz) is provided
  (snd-seq-systimer). 

* The time and song position for the queues are maintained by a software
  timer. It can be started and stopped by sending SND_SEQ_EVENT_START and
  SND_SEQ_EVENT_STOP messages to the timer port (client 0, port 0).

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

* proc interface (/proc/asound/sequencer-*) to see what clients have
  registered, get memory status info, queue status etc.

* Muliple independent queues can be used to run different time/tempo
  independend application. (ie. multi-user sequencing)

* Included sample clients (in the test/seq/ directory):

  - readtime    : display information on the sequencer timer.

  - 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

  - kernel_client_midi
                : a kernel API test which implements a MIDI driver (similar
                  like the usertest2 driver)

  - kernel_client_midi2
                : registers a MIDI driver using the midisynth mid-level
                  driver. 


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

- Compile the sequencer:
     (directory alsa-driver/kernel/seq) 
     $ make
- make sure ALSA is loaded
- load the sequencer (need root privileges)
     $ insmod snd-seq.o
- load the timer (need root privileges)
     $ insmod snd-seq-systimer.o

- Compile the clients:
     (directory alsa-driver/test/seq)
     $ make

- 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..)
     $ playfile pick_up_the_pieces.mid
 
- Have fun. 
     


Todo:
=====

Many things.... 

- kill some bugs
- work out client & port registration/lookup
- add system announcements
- add open on demand for midisynth
- clean events on client termination
- 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/

