\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename ossmodule.texi
@settitle Python OSS Module
@setchapternewpage odd
@c %**end of header

@ifinfo

********************************************************************
Python OSS Module -- A Python interface to the Open Sound System API
********************************************************************

Public Domain 1997 Timothy Butler

THIS DOCUMENT IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

@end ifinfo

@titlepage
@title Python OSS Module
@subtitle A Python interface to the Open Sound System API
@subtitle July 1997
@author Timothy Butler


@c  The following two commands
@c  start the copyright page.
@page
@vskip 0pt plus 1filll
Public Domain 1997 Timothy Butler

THIS DOCUMENT IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

@end titlepage

@node Top, Introduction, (dir), (dir)

@menu
* Introduction::                
* Mixer Programming::           
* Sequencer Programming::       
* Audio Programming::           
* Miscellaneous ::              
* Variable Index::              
* Function Index::              

 --- The Detailed Node Listing ---

Introduction

* Essential References::        
* Obtaining the oss Module::    
* Installation::                
* Feedback::                    
* Design and Implementation::   
* Future Development::          

Essential References

* Installation::                
* Design and Implementation::   

Installation

* Linking into the Interpreter::  
* Building a Shared Library::   

Building a Shared Library 

* Design and Implementation::   

Mixer Programming

* Channel Identifiers::         
* mixer Objects::               

Channel Identifiers

* Channel Numbers::             
* Channel Labels::              

mixer Objects

* mixer Instantiation::         
* mixer Methods::               

Sequencer Programming

* sequencer Objects::           
* synth_info Objects::          
* midi_info Objects::           

sequencer Objects

* sequencer Instantiation::     
* sequencer Methods::           

sequencer Methods

* synth_info Objects::          
* midi_info Objects::          

synth_info Objects

* synth_info Instantiation::    
* synth_info Members::          

midi_info Objects

* midi_info Instantiation::     
* midi_info Members::           

midi_info Members

* Audio Programming::                       

Audio Programming

* Audio Formats::               
* audio Objects::               

audio Objects

* audio Instantiation::         
* audio Methods::               

Miscellaneous 

* Sound Card ID Numbers::       
@end menu

@node Introduction, Mixer Programming, Top, Top
@chapter Introduction

The @b{oss} module provides access to the Open Sound System from the
Python programming language.  The Open Sound System is a UNIX device
driver that allows you to record and play digitized audio, control input
and output volume levels, select recording sources, and generate
synthesizer commands and midi bytes controlled by a low-level sequencer.
It runs on FreeBSD, Linux, BSD/OS, Solaris, and other operating systems.

Python is an interpreted, interactive, object-oriented, extensible,
and way-cool programming language.  An interactive programming environment
extended with objects to control your sound card can be a powerful and
fun combination.

@menu
* Essential References::        
* Obtaining the oss Module::    
* Installation::                
* Feedback::                    
* Design and Implementation::   
* Future Development::          
@end menu

@node Essential References, Obtaining the oss Module, Introduction, Introduction
@section Essential References

This manual does not cover all of the details you need to program 
the Open Sound System. You should consult the following resources 
to learn about the Open Sound System.

@table @asis
@item Open Sound System
http://www.4front-tech.com/oss.html

@item Open Sound System (OSS) Free
http://www.4front-tech.com/usslite/

@item OSS Programmer's Guide
http://www.4front-tech.com/pguide/index.html

@item OSS documentation (contains link to valuable "Hackers Guide to VoxWare")
http://www.4front-tech.com/usslite/docs.html

@end table

You can find more information about Python at 

@table @asis
@item Python Home Page
http://www.python.org
@end table

@menu
* Installation::                
* Design and Implementation::   
@end menu

@node Obtaining the oss Module, Installation, Essential References, Introduction
@section Obtaining the oss Module

You can download the oss Module from
@example
    http://www.indra.com/~tim/ossmodule
@end example

@node Installation, Feedback, Obtaining the oss Module, Introduction
@section Installation

The @b{oss} module consists entirely of a single C language source file,
@file{ossmodule.c}.  You must either 

@enumerate

@item
compile and link the module into the Python interpreter or

@item
create and install a shared library in a directory named by your
@code{PYTHONPATH}.

@end enumerate

@menu
* Linking into the Interpreter::  
* Building a Shared Library::   
@end menu

@node Linking into the Interpreter, Building a Shared Library, Installation, Installation
@subsection Linking into the Interpreter

@enumerate

@item Copy @file{ossmodule.c} into Python's @file{Modules} directory.
@example
    > cp ossmodule.c Python-1.4/Modules
@end example

@item Edit @file{Modules/Setup} and add an entry for the @b{oss} module.

@example
    oss ossmodule.c -I/usr/include/machine -I/usr/include/sys
@end example

You may need to add or change the C preprocessor's search directories so
it can find @file{soundcard.h} on your system.

You can also create a shared library this way if you place the module
line in the @code{*shared*} section of the @file{Setup} file.  Read the
comments in the @file{Setup} file for details.

@item Recompile, test, and install the Python interpreter
@example
    > cd Python-1.4
    > make

    > ./python
    >> import oss

    >make bininstall
@end example
        
@end enumerate

@node Building a Shared Library,  , Linking into the Interpreter, Installation
@subsection Building a Shared Library 

You can use the @file{Makefile} provided with the @b{oss} module
distribution to compile a shared library.  You will have to edit the
@file{Makefile} to match your system.  Copy the resulting shared library
to a directory named by your @code{PYTHONPATH}.

@enumerate

@end enumerate



@menu
* Design and Implementation::   
@end menu

@node Feedback, Design and Implementation, Installation, Introduction
@section Feedback

Please email bug reports and comments concerning the @b{oss} module to
@code{tim@@netbox.com}.

I am not qualified to answer questions about the OSS itself.  Part of
the reason I wrote the @b{oss} module was to create an environment where
I could experiment with and learn about the OSS.

If you can't get your sound card to work in the first place
I can't help;  but you might check out the resources listed above.
@xref{Essential References}.

@node Design and Implementation, Future Development, Feedback, Introduction
@section Design and Implementation

The C language header file, @file{sys/soundcard.h}, defines the OSS API.
Most of the API consists of macros which define operations and arguments
for the @code{ioctl()} system call. 

The @b{oss} module implements only the bare minimum to use the API
including:

@table @b

@item Sound device objects.
Represent devices such as a mixer, sequencer, and digital audio
devices. The sound device objects in the @b{oss}
module store a file descriptor and their methods typically involve
little more than a call to @code{ioctl()} with the proper arguments.

@item Functions that open and return sound device objects.

@item Module-level variables holding macro "constants". 
Bitmasks or device numbers that are ultimately provided as arguments to
the @code{ioctl()} calls. Many module-level variables exist in the
@b{oss} module which correspond to the exact same names of macro
constants in @file{soundcard.h}.  For example the value of
@code{oss.SOUND_MIXER_NRDEVICES} is the same as
@code{SOUND_MIXER_NRDEVICES} in @file{soundcard.h}.

@item "Structure" objects. 
Hold read-only information about system capabilities.

@end table


The API operations, such as @code{SOUND_MIXER_READ_RECMASK}, typically
translate into methods of sound device objects, such as
@code{mixer.read_recmask()}.  The correspondence should be clear from the
documentation if not from the names.

None of the objects provided by the @b{oss} module can serve as base classes.

Not every name and data structure provided by @file{soundcard.h} is
available through the @b{oss} module. The @b{oss} module provides only
the interface that is described in the official OSS API documentation.
Many parts of @file{soundcard.h} are either unsupported, obsolete, not
portable, or undocumented.

The MIDI interface and the /dev/sndstat objects are not provided because
these interfaces are simply read and write operations.
 
The @b{oss} module was developed using the OSSFree implementation under
FreeBSD. Your mileage may vary.

@node Future Development,  , Design and Implementation, Introduction
@section Future Development

I would like to stick as close as possible to the OSS API as opposed to
implementing old or undocumented features.  So far, I have provided
that part of the API provided implemented by OSSFree.  I may add
features of the commercial version as an option.

As a separate project I'd like to add a layer on top of the @b{oss}
module (called "possum") that provides graphical interfaces to the sound
devices.  MIDI protocol support would be handy also.


@node Mixer Programming, Sequencer Programming, Introduction, Top
@chapter Mixer Programming

@menu
* Channel Identifiers::         
* mixer Objects::               
@end menu

@node Channel Identifiers, mixer Objects, Mixer Programming, Mixer Programming
@section Channel Identifiers

@menu
* Channel Numbers::             
* Channel Labels::              
@end menu

@node Channel Numbers, Channel Labels, Channel Identifiers, Channel Identifiers
@subsection Channel Numbers

Mixer channels are identified by channel numbers stored in these
module-level variables. Each channel number variable has a corresponding
"MASK" variable has a single bit set shifted left by the channel number.

@vtable @code

@item SOUND_MIXER_NRDEVICES
number of channels known to OSS [0,30] 

@item  SOUND_MIXER_VOLUME 
@itemx SOUND_MASK_VOLUME 
 master output level     
	
@item  SOUND_MIXER_BASS
@itemx SOUND_MASK_BASS
bass level of all output channels  

@item  SOUND_MIXER_TREBLE
@itemx SOUND_MASK_TREBLE
treble level of all output channels

@item  SOUND_MIXER_SYNTH
@itemx SOUND_MASK_SYNTH
level of synthesizer (e.g. FM, wave-table)

@item  SOUND_MIXER_PCM
@itemx SOUND_MASK_PCM
output level for audio device (/dev/dsp, /dev/audio) 

@item  SOUND_MIXER_SPEAKER
@itemx SOUND_MASK_SPEAKER
volume of PC speaker signal routed through card 

@item  SOUND_MIXER_LINE
@itemx SOUND_MASK_LINE
level for line-in jack

@item  SOUND_MIXER_MIC
@itemx SOUND_MASK_MIC
input level from microphone jack

@item  SOUND_MIXER_CD
@itemx SOUND_MASK_CD
input level from CD

@item  SOUND_MIXER_IMIX
@itemx SOUND_MASK_IMIX
output (headphone jack) vol for rec monitor (rec only)

@item  SOUND_MIXER_ALTPCM
@itemx SOUND_MASK_ALTPCM
volume of alternative CODEC device

@item  SOUND_MIXER_RECLEV
@itemx SOUND_MASK_RECLEV
global recording level (rec only)

@item  SOUND_MIXER_IGAIN
@itemx SOUND_MASK_IGAIN
??

@item  SOUND_MIXER_OGAIN
@itemx SOUND_MASK_OGAIN
??

@item  SOUND_MIXER_LINE1
@itemx SOUND_MASK_LINE1
vendor specific

@item  SOUND_MIXER_LINE2
@itemx SOUND_MASK_LINE2
vendor specific

@item  SOUND_MIXER_LINE3
@itemx SOUND_MASK_LINE3
vendor specific


@end vtable

@node Channel Labels,  , Channel Numbers, Channel Identifiers
@subsection Channel Labels

Two module-level lists, @code{SOUND_DEVICE_LABELS} and
@code{SOUND_DEVICE_NAMES}, store strings that can be used to name
channels. These lists can be indexed by channel number
(e.g. @code{SOUND_DEVICE_LABELS[SOUND_MIXER_VOLUME]}).

@vtable @code

@item SOUND_DEVICE_LABELS
channel names that are suitable for user presentation.
@item SOUND_DEVICE_NAMES 
lowercase fixed-size names without spaces.

@end vtable

@node mixer Objects,  , Channel Identifiers, Mixer Programming
@section mixer Objects

A mixer object controls the volume levels of input and output channels.
A mixer object also selects input sources from the microphone, line, and
CD inputs.

Read and write operations on a mixer's file descriptor are undefined and
there are no @code{read()} or @code{write()} methods on a mixer.
    
@menu
* mixer Instantiation::         
* mixer Methods::               
@end menu

@node mixer Instantiation, mixer Methods, mixer Objects, mixer Objects
@subsection mixer Instantiation

Create an mixer object using the module function @code{open_mixer()}.
The same mixer device may be opened more than once.
An open mixer object will be closed before it is deleted.

@defun open_mixer (filename, flags) 
        
Create, open, and return a new mixer object.
@table @var
@item filename
 defaults to @code{"/dev/mixer"}.
@item flags 
defaults to @code{FCNTL.O_RDWR}.
@end table

@end defun


@node mixer Methods,  , mixer Instantiation, mixer Objects
@subsection mixer Methods

@defmethod mixer fileno ()
Return the file number associated with this mixer.
@end defmethod

@defmethod mixer close ()
Free the resources associated with this mixer.

Called on deletion if not called explicitly.  Do not call any
methods of a closed mixer.
@end defmethod
    
@defmethod mixer devmask ()
Return a bitmask of available mixer channels.
@end defmethod

@defmethod mixer recmask ()
Return a bitmask of channels that may be used as recording sources.
@end defmethod

@defmethod mixer stereodevs ()
Return a bitmask of stereo channels.
@end defmethod

@defmethod mixer caps ()
Return a bitmask describing the general capabilities of a mixer.

Currently, the module-level constant mask @code{SOUND_CAP_EXCL_INPUT} is
the only mixer capability defined. 

@vtable @code
@item SOUND_CAP_EXCL_INPUT
If this bit is set to 1, then only one mixer channel can be selected at
the same time.
@end vtable

@end defmethod

@defmethod mixer read_recsrc ()
Return a bitmask of active recording sources.
@end defmethod


@defmethod mixer write_recsrc (mask)
Select recording source channels with a bitmask.
	
If @var{mask} is zero, then the mic input will be used.
@end defmethod

@defmethod mixer read_channel (channel_num)
Return the level (volume) of a channel.

The volume is returned as a tuple, ( @var{left}, @var{right} ),
representing the level of both stereo channels.  For mono devices, only
@var{left} is valid, (the right channel value is set to the left).
	
Levels are between 0 (off) and 100 (maximum), inclusive.

@end defmethod

@defmethod mixer write_channel (channel_num, level)
Set the level (volume) of a channel.

@var{level} may be either a single integer or a tuple
(@var{left}, @var{right}) with values from 0 (off) to 100
(maximum), inclusive.
	
If @var{level} is a single integer, it is applied to just a mono
channel or both sides of a stereo channel.
	
If @var{level} is a tuple, then each side of a stereo channel will
be assigned its own level. Mono-devices use the left value
of a tuple.
	
@code{write_channel()} returns a tuple that represents the new
level(s) of a channel.  Because some mixers will quantize
levels with only 3 to 8 bits, the new levels may @emph{not} be
exactly the same as what was requested. See the OSS
developer's guide for details.
@end defmethod

@c *************************************************************************
@node Sequencer Programming, Audio Programming, Mixer Programming, Top
@chapter Sequencer Programming

@menu
* sequencer Objects::           
* synth_info Objects::          
* midi_info Objects::           
@end menu

@node sequencer Objects, synth_info Objects, Sequencer Programming, Sequencer Programming
@section sequencer Objects

The sequencer object controls the on-board synthesizer using MIDI-like
commands and allows I/O through MIDI ports.


Synthesizers accept commands that resemble MIDI commands but otherwise
have nothing to do with the MIDI capabilities of a soundcard. For
example, some synthesizer methods are called @code{note_on()} and
@code{chn_pressure()} but these do not send bytes out the MIDI
port. Instead, they only mimic similar effects with the synthesizers.

MIDI I/O support consists entirely of simple commands to read and
write individual bytes through specific MIDI ports. MIDI input is not
implemented in this version.
    
Read and write operations on a mixer's file descriptor are undefined and
there are no @code{read()} or @code{write()} methods on a mixer.

Many methods of a sequencer generate an @dfn{event} (synthesizer command
or a MIDI byte) that is written immediately to a buffer in the @b{oss}
module.  As the buffer fills, events will eventually be passed to the
driver's queue. The sequencer @code{dump_buf()} method flushes the
module's buffer to the driver's event queue.
 
The sequencer driver processes most events in its queue immediately.
The sequencer method @code{wait_time()} intersperses timing events
between other events. When the driver processes a timing event in the
queue, it waits until that absolute time before continuing. Note that in
order for the sequencer to see the timing event it must be flushed to
the event queue using @code{dump_buf()}.
    
@menu
* sequencer Instantiation::     
* sequencer Methods::           
@end menu

@node sequencer Instantiation, sequencer Methods, sequencer Objects, sequencer Objects
@subsection sequencer Instantiation

Create an sequencer object using the module function @code{open_sequencer()}.
Only one sequencer may be open at a time; even within the same 
application.

An open sequencer object will be closed before it is deleted.
    
@defun open_sequencer (filename, flags):
Create, open, and return a new sequencer object.

@table @var
@item filename
 defaults to @code{"/dev/sequencer"}.
@item flags 
defaults to @code{FCNTL.O_RDWR}.

Use @code{FCNTL.O_WRONLY} for an output-only program so unnecessary
functions like MIDI input aren't initialized.  Likewise, use
@code{FCNTL.O_RDONLY} for input-only programs.
@end table

@end defun

@node sequencer Methods,  , sequencer Instantiation, sequencer Objects
@subsection sequencer Methods

@defmethod sequencer fileno ()
Return the file number associated with this sequencer.
@end defmethod

@defmethod sequencer close ()
Free the resources associated with this sequencer.

Called on deletion if not called explicitly.  Do not call any
methods of a closed sequencer.
	
@code{close()} shuts off all synthesizer sounds immediately, so you might
want to add an extra delay before closing this device.
@end defmethod

@defmethod sequencer nrsynths ()
Return the number of internal synthesizer devices.
@end defmethod

@defmethod sequencer synth_info (obj)
Describe a specific synthesizer.

@var{obj} may be either an integer device number or a 
synth_info object with its @code{device} member initialized.

If @var{obj} is an integer then return a new synth_info object
describing the device.  If @var{obj} is an existing synth_info then it
is filled in with the description and returned.

You must provide a device number that is less than the value
returned by the method @code{nrsynths()}.

@xref{synth_info Objects}
@end defmethod
	
@defmethod sequencer nrmidis ()
Return the number of MIDI ports available.
@end defmethod

@defmethod sequencer midi_info (obj)
Describe a specific MIDI port.

@var{obj} may be either an integer port number or a midi_info object
with its @code{device} member initialized to the desired MIDI port.

If @var{obj} is an integer then return a new midi_info object describing
the port.  If @var{obj} is an existing midi_info then it is filled in
with the description and returned.

You must provide a port number that is less than the value
returned by the @code{nrmidis()} method.

@xref{midi_info Objects}.

@end defmethod

@defmethod sequencer start_timer ()
EVENT Reset the sequencer's timer.

Note that this method generates an @emph{event} that will 
be processed only when it makes it to the head of the queue.

The timer may not be restarted immediately.
@end defmethod

@defmethod sequencer wait_time (time)
EVENT Pause the sequencer until @var{time}.

@var{time} is the absolute time when the driver should continue reading
the event queue.  Absolute time is measured in units of the kernel timer
(typically 100 Hz, 10 ms/tick) from the time the device was opened.

Use the @code{ctrlrate()} method to determine the actual timer
resolution.
@end defmethod

@defmethod sequencer ctrlrate ()
Return the timer resolution in ticks per second.
@end defmethod

@defmethod sequencer midiout (midi_dev, byte)
EVENT Write a byte to a MIDI port.

@table @var
@item midi_dev
the MIDI port number.
@item byte
either an integer or a single character that is the byte to output.
@end table
@end defmethod

@defmethod sequencer set_patch (dev, voice, patch)
EVENT Assign synthesizer instrument number (patch) to a voice.
@end defmethod

@defmethod sequencer start_note (dev, voice, note, vel=64)
EVENT Start a voice on a synthesizer device.

@table @var
@item  note
@itemx vel
valid MIDI note number and velocity values, [0,127].
@end table

Some synthesizers support adjusting the volume of a note (rather than
starting a new note) with a @var{note} value of 255.  A @var{vel} of 255
may specify a volume stored in some synthesizers' internal tables. The
use of these values is not portable.

@end defmethod

@defmethod sequencer stop_note (dev, voice, note, vel=64)
EVENT Stop the synthesizer note being played.

@table @var
@item note
the MIDI note number
@item vel 
the speed of the key release.
@end table

For portability, use the same note number that started the voice.

The voice may have already stopped or decayed.  The release time is an
instrument-specific parameter so the sound may not stop immediately.
Consider adding a delay between the final note and the @code{close()}
method, so the last notes have time to decay before being cut off.
@end defmethod

@defmethod sequencer chn_pressure (dev, voice, pressure)
EVENT Change the channel pressure.
	
@code{chn_pressure()} mimics the pressure used on some MIDI keyboards.
The driver translates pressure into the amount of vibrato in 
OPL-3 voices.  @var{pressure} may be in the range [0,127].
@end defmethod

@defmethod sequencer panning (dev, voice, pos)
EVENT  Pan the voice between the left and right voice channels.

@var{pos} is an integer [-128, 127] where -128 is far left, 0 is
center, and 127 is far right.
	
The pan position is determined by adding @var{pos} to the pan
value stored in the instrument parameters and lasts until
until the note is stopped. The OPL-3 pan value is
simply its volume level.
@end defmethod

@defmethod sequencer control (voice, controller, value)
EVENT Mimic standard MIDI controllers with the synthesizer.

The change may be made before starting a note and lasts until the note
is stopped. Once a note is stopped the controller value reverts to its
default.
	
Midi controllers that may be supported are:
@vtable @code 

@item CTRL_EXPRESSION
expression controller of MIDI with values in the range [0,127].

@item CTRL_MAIN_VOLUME
main volume controller with values in the range [0,100].
@end vtable

Note that these values may have different ranges than their
standard MIDI counterparts.
@end defmethod

@defmethod sequencer bender_range (voice, value)
Define the magnitude of the lowest and highest pitch-bends.
	
@var{value} is in units of cents (1/100 of a semitone).  Although
@var{value} may be set larger, the maximum bend is two octaves (1200
cents or 12 semitones).

See @code{pitch_bend()}.
@end defmethod

@defmethod sequencer pitch_bend (voice, value)
EVENT Alter the pitch of a sequencer voice.

@var{value} is in the range [-8192, 8191] representing the pitches of
the most extreme low and high bends.

The magnitude of the pitch bend is determined by the method
@code{bender_range()}.  If you want *value* to be in units of cents
(1/100 semitone) then call @code{bender_range()} with a value of 8192.

The value can be assigned before or after starting the note
and the effect lasts until the note stops.

See @code{bender_range()}.

@end defmethod

@defmethod sequencer expression (voice, value)
EVENT Apply an "expression" MIDI controller to a synthesizer voice.
	
???
@end defmethod

@defmethod sequencer main_volume (voice, value)
EVENT Apply a "main volume" MIDI controller to a synthesizer voice.

???
@end defmethod

@menu
* synth_info Objects::          
* midi_info Objects::          
@end menu

@node synth_info Objects, midi_info Objects, sequencer Objects, Sequencer Programming
@section synth_info Objects

A synth_info object is a description of a synthesizer device.

@menu
* synth_info Instantiation::    
* synth_info Members::          
@end menu

@node synth_info Instantiation, synth_info Members, synth_info Objects, synth_info Objects
@subsection synth_info Instantiation

Typically a sequencer's @code{synth_info()} method creates and returns a
synth_info object.  You can also create a synth_info (for a sequencer to 
fill in) with the module-level function @code{synth_info()}.

@defun synth_info ()
Return a new, uninitialized synth_info object. 
@end defun

@node synth_info Members,  , synth_info Instantiation, synth_info Objects
@subsection synth_info Members

All of these members are read-only except for @code{device}.

When a synth_info object is printed, it decodes and displays all of its
members.  This behavior may change in a future release.

@table @code

@item name
a string containing the name of the device

@item device
the device number of the synthesizer 
This is used only when this synth_info object is 
passed to a sequencer's @code{synth_info()} method. 

@item synth_type
integer describing the type of synthesizer.

@vtable @code
@item SYNTH_TYPE_FM
@item SYNTH_TYPE_SAMPLE
@item SYNTH_TYPE_MIDI
@end vtable

@item synth_subtype 
integer which may be used to detect the hardware type.

@item nr_voices 
maximum number of voices the device supports in its current mode. If you
change the mode, the value will change also.

@end table


@node midi_info Objects,  , synth_info Objects, Sequencer Programming
@section midi_info Objects

A midi_info object describes a MIDI port.

@menu
* midi_info Instantiation::     
* midi_info Members::           
@end menu

@node midi_info Instantiation, midi_info Members, midi_info Objects, midi_info Objects
@subsection midi_info Instantiation

Typically a sequencer's @code{midi_info()} method creates and returns a
midi_info object.  You can also create a midi_info (for a sequencer to 
fill in) with the module-level function @code{midi_info()}.

@defun midi_info ()
Return a new, uninitialized midi_info object. 
@end defun

@node midi_info Members,  , midi_info Instantiation, midi_info Objects
@subsection midi_info Members

All of these members are read-only except for @code{device}.

When a midi_info object is printed, it decodes and displays all of its
members.  This behavior may change in a future release.

@table @code
@item name 
a string containing the name of the device

@item device
the midi port number, less than sequencer.nrmidis().
This is used only when this midi_info object is 
passed to a sequencer's @code{midi_info()} method. 

@item dev_type
integer describing the type of sound card where
the MIDI port resides.

@xref{Sound Card ID Numbers}.

@item capabilities
bit mask describing some MIDI capabilities?? One mask is defined:


@vtable @code
@item MIDI_CAP_MPU401
mask
@end vtable

@end table


@c **********************************************************************

@menu
* Audio Programming::                       
@end menu

@node Audio Programming, Miscellaneous , Sequencer Programming, Top
@chapter Audio Programming

@menu
* Audio Formats::               
* audio Objects::               
@end menu

@node Audio Formats, audio Objects, Audio Programming, Audio Programming
@section Audio Formats

Audio formats are represented by the following module-level bit-flag
values.

@vtable @code
@item AFMT_MU_LAW
logarithmic mu-Law (8-bit)
@item AFMT_A_LAW
logarithmic A-Law  (8-bit)
@item AFMT_IMA_ADPCM
ADPCM as defined by the Interactive Multimedia Association (IMA).  This
is @emph{not} the Creative ADPCM format. Requires an average of 4 bits
per sample.
@item AFMT_U8
unsigned 8-bit 
@item AFMT_S16_LE
signed 16-bit little-endian (Intel)
@item AFMT_S16_BE
signed 16-bit big-endian (Motorola)
@item AFMT_S8
unsigned 8-bit
@item AFMT_U16_LE
unsigned 16-bit little-endian
@item AFMT_U16_BE
unsigned 16-bit big-endian
@item AFMT_MPEG
MPEG audio format
@end vtable


@node audio Objects,  , Audio Formats, Audio Programming
@section audio Objects

An audio object allows you to play and record digitized audio.

You do so by writing and reading samples to the audio device.

Please be aware that because Python is not as fast as languages that
are compiled to machine code, you may have difficulty producing
some sounds without output buffer underruns and input overflows.
These may manifest themselves as pauses, clicking, humming, or other
distortions in the sound. 

You may have some luck, however, if you use some of the built-in modules
and modules compiled from C. Consider using operations in the
@code{array} and @code{audioop} modules.

Before an audio object can be read or written, you must perform 
at least three operations on it:
@enumerate
@item
Set its sample format with the @code{format()} method.
@item
Set the number of channels (mono or stereo) with the @code{stereo()} method.
@item
Set the sample rate with the @code{speed()} method.
@end enumerate

These operations must be performed in the order presented above.  Please
consult the OSS Programmer's Guide for more information.
 
@menu
* audio Instantiation::         
* audio Methods::               
@end menu

@node audio Instantiation, audio Methods, audio Objects, audio Objects
@subsection audio Instantiation

Create an audio object using the module function @code{open_audio()}.

An open audio object will be closed before it is deleted.
    
@defun open_audio (filename, flags):
Create, open, and return a new audio object.

@table @var
@item filename
 defaults to @code{"/dev/audio"}.
@item flags 
defaults to @code{FCNTL.O_RDWR}.

Use @code{FCNTL.O_WRONLY} if you intend to only play audio.
Likewise, use @code{FCNTL.O_RDONLY} to only record audio.
@end table

@end defun

@node audio Methods,  , audio Instantiation, audio Objects
@subsection audio Methods

@defmethod audio fileno ()
Return the file number associated with this audio object.
@end defmethod

@defmethod audio close ()
Free the resources associated with this audio object.

Called on deletion if not called explicitly.  Do not call any
methods of a closed audio object.
	
@code{close()} performs a @code{sync()} operation.
@end defmethod

@defmethod audio reset ()
Stop the audio device.

Once an audio device is reset you may set new format, stereo, and speed
parameters.
@end defmethod

@defmethod audio sync ()
Wait until the last byte has been played.

Once all of the bytes that were written have been played, @code{sync()}
performs a @code{reset()} on the audio device.
@end defmethod

@defmethod audio post ()
Warn the audio device of a pause in the output.
@end defmethod

@defmethod audio format (format_flag)
Select and return the audio format.

@xref{Audio Formats} for valid values of @var{format_flag}.

You should check the return value to ensure that the format you
requested is supported.  

To check the current audio format, pass @code{AFMT_QUERY} as
@var{format} or use the @code{query_format()} method.

@end defmethod

@defmethod audio get_formats ()
Return a mask of all the audio formats supported by this device.

@xref{Audio Formats}.
@end defmethod

@defmethod audio query_format ()
Return the current audio format.

This is a shortcut for @code{format(AFMT_QUERY)}.
@xref{Audio Formats}.
@end defmethod

@defmethod audio stereo (is_stereo)
Set the number of channels. 

@var{is_stereo}: 0=mono, 1=stereo
@end defmethod

@defmethod audio channels (num_channels)
Set the number of channels. 

@emph{This operation is documented in the OSS manuals, but not implemented
in my version. -twb}

@var{num_channels}: 1=mono, 2=stereo
@end defmethod

@defmethod audio speed (sampling_rate)
Set the sampling rate. 

Sets and returns the sampling rate that was as close as the device could
get to the requested @var{sampling_rate}.
@end defmethod

@defmethod audio read (bytes_requested)
Record bytes from the audio device. 

Returns a string holding the bytes that were read.  This may 
not be the same length as the number of bytes requested.

Note that the request is in units of @emph{bytes}, not samples.
For example, if the device is configured for 16-bit stereo, you
should request multiples of four bytes.

@end defmethod

@defmethod audio write (samples)
Play a string of samples.

@var{samples} is a string holding the bytes that should be written
to the audio device.

Returns the actual number of bytes that were written. This could
be less than the length of @var{samples}.

@var{samples} should be a length that is a multiple of the the sample
size (#channels * format size).

@end defmethod

@node Miscellaneous , Variable Index, Audio Programming, Top
@chapter Miscellaneous 

@menu
* Sound Card ID Numbers::       
@end menu

@node Sound Card ID Numbers,  , Miscellaneous , Miscellaneous
@section Sound Card ID Numbers

These module-level variables hold numbers that identify sound cards. 

@vtable @code
@item SNDCARD_ADLIB
@item SNDCARD_SB
@item SNDCARD_PAS
@item SNDCARD_GUS
@item SNDCARD_MPU401
@item SNDCARD_SB16
@item SNDCARD_SB16MIDI
@item SNDCARD_UART6850
@item SNDCARD_GUS16
@item SNDCARD_MSS
@item SNDCARD_PSS
@item SNDCARD_SSCAPE
@item SNDCARD_PSS_MPU
@item SNDCARD_PSS_MSS
@item SNDCARD_SSCAPE_MSS
@item SNDCARD_TRXPRO
@item SNDCARD_TRXPRO_SB
@item SNDCARD_TRXPRO_MPU
@item SNDCARD_AWE32
@end vtable



@node Variable Index, Function Index, Miscellaneous , Top
@unnumbered Variable Index
@printindex vr

@node Function Index,  , Variable Index, Top
@unnumbered Function Index


@printindex fn

@contents
@bye