Doc/library/al.rst

   1
   2 :mod:`al` --- Audio functions on the SGI
   3 ========================================
   4
   5 .. module:: al
   6    :platform: IRIX
   7    :synopsis: Audio functions on the SGI.
   8
   9
  10 This module provides access to the audio facilities of the SGI Indy and Indigo
  11 workstations.  See section 3A of the IRIX man pages for details.  You'll need to
  12 read those man pages to understand what these functions do!  Some of the
  13 functions are not available in IRIX releases before 4.0.5.  Again, see the
  14 manual to check whether a specific function is available on your platform.
  15
  16 All functions and methods defined in this module are equivalent to the C
  17 functions with ``AL`` prefixed to their name.
  18
  19 .. index:: module: AL
  20
  21 Symbolic constants from the C header file ``<audio.h>`` are defined in the
  22 standard module :mod:`AL`, see below.
  23
  24 .. warning::
  25
  26    The current version of the audio library may dump core when bad argument values
  27    are passed rather than returning an error status.  Unfortunately, since the
  28    precise circumstances under which this may happen are undocumented and hard to
  29    check, the Python interface can provide no protection against this kind of
  30    problems. (One example is specifying an excessive queue size --- there is no
  31    documented upper limit.)
  32
  33 The module defines the following functions:
  34
  35
  36 .. function:: openport(name, direction[, config])
  37
  38    The name and direction arguments are strings.  The optional *config* argument is
  39    a configuration object as returned by :func:`newconfig`.  The return value is an
  40    :dfn:`audio port object`; methods of audio port objects are described below.
  41
  42
  43 .. function:: newconfig()
  44
  45    The return value is a new :dfn:`audio configuration object`; methods of audio
  46    configuration objects are described below.
  47
  48
  49 .. function:: queryparams(device)
  50
  51    The device argument is an integer.  The return value is a list of integers
  52    containing the data returned by :cfunc:`ALqueryparams`.
  53
  54
  55 .. function:: getparams(device, list)
  56
  57    The *device* argument is an integer.  The list argument is a list such as
  58    returned by :func:`queryparams`; it is modified in place (!).
  59
  60
  61 .. function:: setparams(device, list)
  62
  63    The *device* argument is an integer.  The *list* argument is a list such as
  64    returned by :func:`queryparams`.
  65
  66
  67 .. _al-config-objects:
  68
  69 Configuration Objects
  70 ---------------------
  71
  72 Configuration objects returned by :func:`newconfig` have the following methods:
  73
  74
  75 .. method:: audio configuration.getqueuesize()
  76
  77    Return the queue size.
  78
  79
  80 .. method:: audio configuration.setqueuesize(size)
  81
  82    Set the queue size.
  83
  84
  85 .. method:: audio configuration.getwidth()
  86
  87    Get the sample width.
  88
  89
  90 .. method:: audio configuration.setwidth(width)
  91
  92    Set the sample width.
  93
  94
  95 .. method:: audio configuration.getchannels()
  96
  97    Get the channel count.
  98
  99
 100 .. method:: audio configuration.setchannels(nchannels)
 101
 102    Set the channel count.
 103
 104
 105 .. method:: audio configuration.getsampfmt()
 106
 107    Get the sample format.
 108
 109
 110 .. method:: audio configuration.setsampfmt(sampfmt)
 111
 112    Set the sample format.
 113
 114
 115 .. method:: audio configuration.getfloatmax()
 116
 117    Get the maximum value for floating sample formats.
 118
 119
 120 .. method:: audio configuration.setfloatmax(floatmax)
 121
 122    Set the maximum value for floating sample formats.
 123
 124
 125 .. _al-port-objects:
 126
 127 Port Objects
 128 ------------
 129
 130 Port objects, as returned by :func:`openport`, have the following methods:
 131
 132
 133 .. method:: audio port.closeport()
 134
 135    Close the port.
 136
 137
 138 .. method:: audio port.getfd()
 139
 140    Return the file descriptor as an int.
 141
 142
 143 .. method:: audio port.getfilled()
 144
 145    Return the number of filled samples.
 146
 147
 148 .. method:: audio port.getfillable()
 149
 150    Return the number of fillable samples.
 151
 152
 153 .. method:: audio port.readsamps(nsamples)
 154
 155    Read a number of samples from the queue, blocking if necessary. Return the data
 156    as a string containing the raw data, (e.g., 2 bytes per sample in big-endian
 157    byte order (high byte, low byte) if you have set the sample width to 2 bytes).
 158
 159
 160 .. method:: audio port.writesamps(samples)
 161
 162    Write samples into the queue, blocking if necessary.  The samples are encoded as
 163    described for the :meth:`readsamps` return value.
 164
 165
 166 .. method:: audio port.getfillpoint()
 167
 168    Return the 'fill point'.
 169
 170
 171 .. method:: audio port.setfillpoint(fillpoint)
 172
 173    Set the 'fill point'.
 174
 175
 176 .. method:: audio port.getconfig()
 177
 178    Return a configuration object containing the current configuration of the port.
 179
 180
 181 .. method:: audio port.setconfig(config)
 182
 183    Set the configuration from the argument, a configuration object.
 184
 185
 186 .. method:: audio port.getstatus(list)
 187
 188    Get status information on last error.
 189
 190
 191 :mod:`AL` --- Constants used with the :mod:`al` module
 192 ======================================================
 193
 194 .. module:: AL
 195    :platform: IRIX
 196    :synopsis: Constants used with the al module.
 197
 198
 199 This module defines symbolic constants needed to use the built-in module
 200 :mod:`al` (see above); they are equivalent to those defined in the C header file
 201 ``<audio.h>`` except that the name prefix ``AL_`` is omitted.  Read the module
 202 source for a complete list of the defined names.  Suggested use::
 203
 204    import al
 205    from AL import *
 206