.TH alSeqPlayer 3P local "Silicon Graphics, Inc."

.SH NAME
.upperok
alSeqPlayer \- Ultra 64 MIDI sequence player routines.

.SH SYNOPSIS
.nf
\f3
.Op c
#include <libaudio.h>
.sp .8v

void    alSeqpNew(ALSeqPlayer *seqp, ALSeqpConfig *config);
void    alSeqpDelete(ALSeqPlayer *seqp);
void    alSeqpSetSeq(ALSeqPlayer *seqp, ALSeq *seq);
ALSeq   *alSeqpGetSeq(ALSeqPlayer *seqp);
void    alSeqpSetBank(ALSeqPlayer *seqp, ALBank *b);
s32     alSeqpGetState(ALSeqPlayer *seqp);
void    alSeqpPlay(ALSeqPlayer *seqp);
void    alSeqpStop(ALSeqPlayer *seqp);
void    alSeqpSetTempo(ALSeqPlayer *seqp, s32 tempo);
s32     alSeqpGetTempo(ALSeqPlayer *seqp);
s16     alSeqpGetVol(ALSeqPlayer *seqp);
void    alSeqpSetVol(ALSeqPlayer *seqp, s16 vol);

void    alSeqpSetChlProgram(ALSeqPlayer *seqp, u8 chan, u8 prog);
s32     alSeqpGetChlProgram(ALSeqPlayer *seqp, u8 chan);
void    alSeqpSetChlFXMix(ALSeqPlayer *seqp, u8 chan, u8 fxmix);
u8      alSeqpGetChlFXMix(ALSeqPlayer *seqp, u8 chan);
void    alSeqpSetChlVol(ALSeqPlayer *seqp, u8 chan, u8 vol);
u8      alSeqpGetChlVol(ALSeqPlayer *seqp, u8 chan);
void    alSeqpSetChlPan(ALSeqPlayer *seqp, u8 chan, ALPan pan);
ALPan   alSeqpGetChlPan(ALSeqPlayer *seqp, u8 chan);
void    alSeqpSetChlPriority(ALSeqPlayer *seqp, u8 chan, u8 priority);
u8      alSeqpGetChlPriority(ALSeqPlayer *seqp, u8 chan);

void    alSeqpSendMidi(ALSeqPlayer *seqp, s32 ticks, u8 status, 
                       u8 byte1, u8 byte2);

void    alSeqpLoop(ALSeqPlayer *seqp, ALSeqMarker *start, 
                   ALSeqMarker *end, s32 count);

.Op
\f1
.fi
.SH DESCRIPTION
The Ultra 64 Audio Library supports playback of MIDI sequences using either
the Type 0 MIDI Sequence Player, whose routines start with 
.I alSeqp,
or the Compressed MIDI Sequence Player, whose routines start with 
.I alCSP. 
This man page details the Type 0 MIDI Sequence Player. For details
of the Compressed MIDI Sequence Player, see the man page for 
.I alCSeqPlayer.
The principle differences between the two MIDI players are the handling of
loops, and the compression of data. Details are discussed in the Nintendo 64
Programming Manual's chapters, Audio Library and Audio Formats.

.PP
The sequence player handles the playback of the sequence, but
the actual sequence data is handled by a Sequence 
(see
.I alSeq).
.PP
To use the Sequence Player, you must first initialize an ALSeqPlayer
structure to represent it. This is accomplished with a call to 
.I alSeqpNew.
.PP
After initializing the ALSeqPlayer structure, you must set the bank and the 
sequence with calls to 
.I alSeqpSetBank
and 
.I alSeqpSetSeq
respectively. 
.PP
To start the sequence player playing call
.I alSeqpPlay.
To stop the sequence player call
.I alSeqpStop. 
The sequence player can only have one target sequence at a time. You must 
stop a sequence before setting and playing a new sequence. You should not 
attempt to switch banks while a sequence is playing. You can use
.B alCSPGetState
to determine if the sequence player is fully stopped. When you call 
.I alSeqpStop,
all processing of the sequence will stop and all notes will be turned off.
.PP
When a sequence is stopped it will not "rewind" but will remain pointing to
its current location. This allows you to restart a sequence from where it
was stopped with a call to
.I alSeqpPlay.
Sustained notes that were cut off by a call to
.I alSeqpStop
will not be restarted, only new notes will be processed.
.PP
If you want to rewind the sequence or relocate to another point in the
sequence, you can create an ALSeqMarker at the desired location using the call 
.I alSeqNewMarker,
and then call
.I alSeqSetLoc
to rewind or relocate the sequence.  Note that these calls do not affect
the channel playback state so care should be taken to make sure that the
channel parameters (eg. program, vol, pan, etc.) are set to appropriate 
values for the given sequence location.

Channel parameters can be set with their individual calls or by sending the
appropriate midi data using
.I alSeqpSendMidi.
Music can be created in realtime and played back with
.I alSeqpSendMidi.

A single loop can be created by calling 
.I alSeqpLoop.
You must first create and set a begining and end loop. Looping of individual
tracks is not supported by the sequence player. (For more involved looping see
the compressed MIDI sequence player. 
.I alCSeqPlayer)



.SH SEE ALSO
.IR alSeq (3P),
.IR alSeqpNew (3P),
.IR alSeqpDelete (3P),
.IR alSeqpSetSeq (3P),
.IR alSeqpGetSeq (3P),
.IR alSeqpPlay (3P),
.IR alSeqpStop (3P),
.IR alSeqpSetBank (3P),
.IR alSeqpSetTempo (3P),
.IR alSeqpGetTempo (3P),
.IR alSeqpGetVol (3P),
.IR alSeqpSetVol (3P),
.IR alSeqpSetChlProgram (3P),
.IR alSeqpGetChlProgram (3P),
.IR alSeqpSetChlFXMix (3P),
.IR alSeqpGetChlFXMix (3P),
.IR alSeqpSetChlPan (3P),
.IR alSeqpGetChlPan (3P),
.IR alSeqpSetChlVol (3P),
.IR alSeqpGetChlVol (3P),
.IR alSeqpSetChlPriority (3P),
.IR alSeqpGetChlPriority (3P),
.IR alSeqpSendMidi (3P)