Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 1 | \section{\module{ossaudiodev} --- |
Greg Ward | 3e34f59 | 2003-03-10 02:09:51 +0000 | [diff] [blame] | 2 | Access to OSS-compatible audio devices} |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 3 | |
| 4 | \declaremodule{builtin}{ossaudiodev} |
Fred Drake | 1dc3bb4 | 2003-09-30 20:00:43 +0000 | [diff] [blame^] | 5 | \platform{Linux, FreeBSD, maybe other Unix-like systems} |
Greg Ward | 3e34f59 | 2003-03-10 02:09:51 +0000 | [diff] [blame] | 6 | \modulesynopsis{Access to OSS-compatible audio devices.} |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 7 | |
Greg Ward | 3e34f59 | 2003-03-10 02:09:51 +0000 | [diff] [blame] | 8 | This module allows you to access the OSS (Open Sound System) audio |
| 9 | interface. OSS is available for a wide range of open-source and |
Greg Ward | c50b088 | 2003-05-03 19:45:47 +0000 | [diff] [blame] | 10 | commercial Unices, and is the standard audio interface for Linux and |
| 11 | recent versions of FreeBSD. |
| 12 | |
| 13 | % Things will get more complicated for future Linux versions, since |
| 14 | % ALSA is in the standard kernel as of 2.5.x. Presumably if you |
| 15 | % use ALSA, you'll have to make sure its OSS compatibility layer |
| 16 | % is active to use ossaudiodev, but you're gonna need it for the vast |
| 17 | % majority of Linux audio apps anyways. |
| 18 | % |
| 19 | % Sounds like things are also complicated for other BSDs. In response |
| 20 | % to my python-dev query, Thomas Wouters said: |
| 21 | % |
| 22 | % > Likewise, googling shows OpenBSD also uses OSS/Free -- the commercial |
| 23 | % > OSS installation manual tells you to remove references to OSS/Free from the |
| 24 | % > kernel :) |
| 25 | % |
| 26 | % but Aleksander Piotrowsk actually has an OpenBSD box, and he quotes |
| 27 | % from its <soundcard.h>: |
| 28 | % > * WARNING! WARNING! |
| 29 | % > * This is an OSS (Linux) audio emulator. |
| 30 | % > * Use the Native NetBSD API for developing new code, and this |
| 31 | % > * only for compiling Linux programs. |
| 32 | % |
| 33 | % There's also an ossaudio manpage on OpenBSD that explains things |
| 34 | % further. Presumably NetBSD and OpenBSD have a different standard |
| 35 | % audio interface. That's the great thing about standards, there are so |
| 36 | % many to choose from ... ;-) |
| 37 | % |
| 38 | % This probably all warrants a footnote or two, but I don't understand |
| 39 | % things well enough right now to write it! --GPW |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 40 | |
Greg Ward | 3e34f59 | 2003-03-10 02:09:51 +0000 | [diff] [blame] | 41 | \begin{seealso} |
| 42 | \seetitle[http://www.opensound.com/pguide/oss.pdf] |
Greg Ward | c50b088 | 2003-05-03 19:45:47 +0000 | [diff] [blame] | 43 | {Open Sound System Programmer's Guide} {the official |
| 44 | documentation for the OSS C API} |
Greg Ward | 3e34f59 | 2003-03-10 02:09:51 +0000 | [diff] [blame] | 45 | \seetext{The module defines a large number of constants supplied by |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 46 | the OSS device driver; see \code{<sys/soundcard.h>} on either |
Greg Ward | 3e34f59 | 2003-03-10 02:09:51 +0000 | [diff] [blame] | 47 | Linux or FreeBSD for a listing .} |
| 48 | \end{seealso} |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 49 | |
Greg Ward | 3e34f59 | 2003-03-10 02:09:51 +0000 | [diff] [blame] | 50 | \module{ossaudiodev} defines the following variables and functions: |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 51 | |
Greg Ward | fb1b5a1 | 2003-05-29 01:39:32 +0000 | [diff] [blame] | 52 | \begin{excdesc}{OSSAudioError} |
Greg Ward | f882c77 | 2003-03-10 03:05:21 +0000 | [diff] [blame] | 53 | This exception is raised on certain errors. The argument is a string |
| 54 | describing what went wrong. |
| 55 | |
| 56 | (If \module{ossaudiodev} receives an error from a system call such as |
| 57 | \cfunction{open()}, \cfunction{write()}, or \cfunction{ioctl()}, it |
| 58 | raises \exception{IOError}. Errors detected directly by |
Greg Ward | fb1b5a1 | 2003-05-29 01:39:32 +0000 | [diff] [blame] | 59 | \module{ossaudiodev} result in \exception{OSSAudioError}.) |
| 60 | |
| 61 | (For backwards compatibility, the exception class is also available as |
| 62 | \code{ossaudiodev.error}.) |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 63 | \end{excdesc} |
| 64 | |
| 65 | \begin{funcdesc}{open}{\optional{device, }mode} |
Greg Ward | f882c77 | 2003-03-10 03:05:21 +0000 | [diff] [blame] | 66 | Open an audio device and return an OSS audio device object. This |
| 67 | object supports many file-like methods, such as \method{read()}, |
| 68 | \method{write()}, and \method{fileno()} (although there are subtle |
| 69 | differences between conventional Unix read/write semantics and those of |
| 70 | OSS audio devices). It also supports a number of audio-specific |
| 71 | methods; see below for the complete list of methods. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 72 | |
Greg Ward | f882c77 | 2003-03-10 03:05:21 +0000 | [diff] [blame] | 73 | \var{device} is the audio device filename to use. If it is not |
| 74 | specified, this module first looks in the environment variable |
| 75 | \envvar{AUDIODEV} for a device to use. If not found, it falls back to |
| 76 | \file{/dev/dsp}. |
| 77 | |
| 78 | \var{mode} is one of \code{'r'} for read-only (record) access, |
| 79 | \code{'w'} for write-only (playback) access and \code{'rw'} for both. |
Greg Ward | 451a766 | 2003-05-26 01:51:33 +0000 | [diff] [blame] | 80 | Since many sound cards only allow one process to have the recorder or |
| 81 | player open at a time, it is a good idea to open the device only for the |
| 82 | activity needed. Further, some sound cards are half-duplex: they can be |
Greg Ward | f882c77 | 2003-03-10 03:05:21 +0000 | [diff] [blame] | 83 | opened for reading or writing, but not both at once. |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 84 | |
| 85 | Note the unusual calling syntax: the \emph{first} argument is optional, |
| 86 | and the second is required. This is a historical artifact for |
| 87 | compatibility with the older \module{linuxaudiodev} module which |
| 88 | \module{ossaudiodev} supersedes. % XXX it might also be motivated |
| 89 | % by my unfounded-but-still-possibly-true belief that the default |
| 90 | % audio device varies unpredictably across operating systems. -GW |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 91 | \end{funcdesc} |
| 92 | |
Greg Ward | cd930f5 | 2003-03-10 03:18:19 +0000 | [diff] [blame] | 93 | \begin{funcdesc}{openmixer}{\optional{device}} |
Greg Ward | f882c77 | 2003-03-10 03:05:21 +0000 | [diff] [blame] | 94 | Open a mixer device and return an OSS mixer device object. |
| 95 | \var{device} is the mixer device filename to use. If it is |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 96 | not specified, this module first looks in the environment variable |
Greg Ward | 3e34f59 | 2003-03-10 02:09:51 +0000 | [diff] [blame] | 97 | \envvar{MIXERDEV} for a device to use. If not found, it falls back to |
Greg Ward | cd930f5 | 2003-03-10 03:18:19 +0000 | [diff] [blame] | 98 | \file{/dev/mixer}. |
Greg Ward | f882c77 | 2003-03-10 03:05:21 +0000 | [diff] [blame] | 99 | |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 100 | \end{funcdesc} |
| 101 | |
| 102 | \subsection{Audio Device Objects \label{ossaudio-device-objects}} |
| 103 | |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 104 | Before you can write to or read from an audio device, you must call |
| 105 | three methods in the correct order: |
Greg Ward | 074472b | 2003-03-10 00:24:42 +0000 | [diff] [blame] | 106 | \begin{enumerate} |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 107 | \item \method{setfmt()} to set the output format |
| 108 | \item \method{channels()} to set the number of channels |
| 109 | \item \method{speed()} to set the sample rate |
Greg Ward | 074472b | 2003-03-10 00:24:42 +0000 | [diff] [blame] | 110 | \end{enumerate} |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 111 | Alternately, you can use the \method{setparameters()} method to set all |
| 112 | three audio parameters at once. This is more convenient, but may not be |
| 113 | as flexible in all cases. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 114 | |
Greg Ward | 451a766 | 2003-05-26 01:51:33 +0000 | [diff] [blame] | 115 | The audio device objects returned by \function{open()} define the |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 116 | following methods: |
| 117 | |
| 118 | \begin{methoddesc}[audio device]{close}{} |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 119 | Explicitly close the audio device. When you are done writing to or |
| 120 | reading from an audio device, you should explicitly close it. A closed |
| 121 | device cannot be used again. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 122 | \end{methoddesc} |
| 123 | |
| 124 | \begin{methoddesc}[audio device]{fileno}{} |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 125 | Return the file descriptor associated with the device. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 126 | \end{methoddesc} |
| 127 | |
| 128 | \begin{methoddesc}[audio device]{read}{size} |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 129 | Read \var{size} bytes from the audio input and return them as a Python |
| 130 | string. Unlike most \UNIX{} device drivers, OSS audio devices in |
| 131 | blocking mode (the default) will block \function{read()} until the |
| 132 | entire requested amount of data is available. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 133 | \end{methoddesc} |
| 134 | |
| 135 | \begin{methoddesc}[audio device]{write}{data} |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 136 | Write the Python string \var{data} to the audio device and return the |
| 137 | number of bytes written. If the audio device is in blocking mode (the |
| 138 | default), the entire string is always written (again, this is different |
| 139 | from usual \UNIX{} device semantics). If the device is in non-blocking |
| 140 | mode, some data may not be written---see \method{writeall()}. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 141 | \end{methoddesc} |
| 142 | |
| 143 | \begin{methoddesc}[audio device]{writeall}{data} |
Greg Ward | 451a766 | 2003-05-26 01:51:33 +0000 | [diff] [blame] | 144 | Write the entire Python string \var{data} to the audio device: waits |
| 145 | until the audio device is able to accept data, writes as much data as it |
| 146 | will accept, and repeats until \var{data} has been completely written. |
| 147 | If the device is in blocking mode (the default), this has the same |
| 148 | effect as \method{write()}; \method{writeall()} is only useful in |
| 149 | non-blocking mode. Has no return value, since the amount of data |
| 150 | written is always equal to the amount of data supplied. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 151 | \end{methoddesc} |
| 152 | |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 153 | The following methods each map to exactly one |
Greg Ward | 451a766 | 2003-05-26 01:51:33 +0000 | [diff] [blame] | 154 | \function{ioctl()} system call. The correspondence is obvious: for |
| 155 | example, \method{setfmt()} corresponds to the \code{SNDCTL_DSP_SETFMT} |
| 156 | ioctl, and \method{sync()} to \code{SNDCTL_DSP_SYNC} (this can be useful |
| 157 | when consulting the OSS documentation). If the underlying |
| 158 | \function{ioctl()} fails, they all raise \exception{IOError}. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 159 | |
| 160 | \begin{methoddesc}[audio device]{nonblock}{} |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 161 | Put the device into non-blocking mode. Once in non-blocking mode, there |
| 162 | is no way to return it to blocking mode. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 163 | \end{methoddesc} |
| 164 | |
| 165 | \begin{methoddesc}[audio device]{getfmts}{} |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 166 | Return a bitmask of the audio output formats supported by the |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 167 | soundcard. On a typical Linux system, these formats are: |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 168 | |
Greg Ward | 074472b | 2003-03-10 00:24:42 +0000 | [diff] [blame] | 169 | \begin{tableii}{l|l}{constant}{Format}{Description} |
| 170 | \lineii{AFMT_MU_LAW} |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 171 | {a logarithmic encoding (used by Sun \code{.au} files and |
| 172 | \filenq{/dev/audio})} |
Greg Ward | 074472b | 2003-03-10 00:24:42 +0000 | [diff] [blame] | 173 | \lineii{AFMT_A_LAW} |
| 174 | {a logarithmic encoding} |
| 175 | \lineii{AFMT_IMA_ADPCM} |
| 176 | {a 4:1 compressed format defined by the Interactive Multimedia |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 177 | Association} |
Greg Ward | 074472b | 2003-03-10 00:24:42 +0000 | [diff] [blame] | 178 | \lineii{AFMT_U8} |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 179 | {Unsigned, 8-bit audio} |
Greg Ward | 074472b | 2003-03-10 00:24:42 +0000 | [diff] [blame] | 180 | \lineii{AFMT_S16_LE} |
| 181 | {Unsigned, 16-bit audio, little-endian byte order (as used by |
| 182 | Intel processors)} |
| 183 | \lineii{AFMT_S16_BE} |
| 184 | {Unsigned, 16-bit audio, big-endian byte order (as used by 68k, |
| 185 | PowerPC, Sparc)} |
| 186 | \lineii{AFMT_S8} |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 187 | {Signed, 8 bit audio} |
Greg Ward | 074472b | 2003-03-10 00:24:42 +0000 | [diff] [blame] | 188 | \lineii{AFMT_U16_LE} |
| 189 | {Signed, 16-bit little-endian audio} |
| 190 | \lineii{AFMT_U16_BE} |
| 191 | {Signed, 16-bit big-endian audio} |
| 192 | \end{tableii} |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 193 | Most systems support only a subset of these formats. Many devices only |
Greg Ward | 3e34f59 | 2003-03-10 02:09:51 +0000 | [diff] [blame] | 194 | support \constant{AFMT_U8}; the most common format used today is |
| 195 | \constant{AFMT_S16_LE}. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 196 | \end{methoddesc} |
| 197 | |
| 198 | \begin{methoddesc}[audio device]{setfmt}{format} |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 199 | Try to set the current audio format to \var{format}---see |
Greg Ward | 451a766 | 2003-05-26 01:51:33 +0000 | [diff] [blame] | 200 | \method{getfmts()} for a list. Returns the audio format that the device |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 201 | was set to, which may not be the requested format. May also be used to |
| 202 | return the current audio format---do this by passing an ``audio format'' |
| 203 | of |
| 204 | \constant{AFMT_QUERY}. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 205 | \end{methoddesc} |
| 206 | |
Greg Ward | fb1b5a1 | 2003-05-29 01:39:32 +0000 | [diff] [blame] | 207 | \begin{methoddesc}[audio device]{channels}{nchannels} |
| 208 | Set the number of output channels to \var{nchannels}. A value of 1 |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 209 | indicates monophonic sound, 2 stereophonic. Some devices may have more |
| 210 | than 2 channels, and some high-end devices may not support mono. |
| 211 | Returns the number of channels the device was set to. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 212 | \end{methoddesc} |
| 213 | |
| 214 | \begin{methoddesc}[audio device]{speed}{samplerate} |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 215 | Try to set the audio sampling rate to \var{samplerate} samples per |
| 216 | second. Returns the rate actually set. Most sound devices don't |
| 217 | support arbitrary sampling rates. Common rates are: |
| 218 | \begin{tableii}{l|l}{textrm}{Rate}{Description} |
| 219 | \lineii{8000}{default rate for \filenq{/dev/audio}} |
| 220 | \lineii{11025}{speech recording} |
| 221 | \lineii{22050}{} |
| 222 | \lineii{44100}{CD quality audio (at 16 bits/sample and 2 channels)} |
| 223 | \lineii{96000}{DVD quality audio (at 24 bits/sample)} |
| 224 | \end{tableii} |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 225 | \end{methoddesc} |
| 226 | |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 227 | \begin{methoddesc}[audio device]{sync}{} |
Greg Ward | 451a766 | 2003-05-26 01:51:33 +0000 | [diff] [blame] | 228 | Wait until the sound device has played every byte in its buffer. (This |
| 229 | happens implicitly when the device is closed.) The OSS documentation |
| 230 | recommends closing and re-opening the device rather than using |
| 231 | \method{sync()}. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 232 | \end{methoddesc} |
| 233 | |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 234 | \begin{methoddesc}[audio device]{reset}{} |
Greg Ward | 451a766 | 2003-05-26 01:51:33 +0000 | [diff] [blame] | 235 | Immediately stop playing or recording and return the device to a |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 236 | state where it can accept commands. The OSS documentation recommends |
Greg Ward | 3e34f59 | 2003-03-10 02:09:51 +0000 | [diff] [blame] | 237 | closing and re-opening the device after calling \method{reset()}. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 238 | \end{methoddesc} |
| 239 | |
Greg Ward | c316d0d | 2003-05-23 02:44:46 +0000 | [diff] [blame] | 240 | \begin{methoddesc}[audio device]{post}{} |
Greg Ward | 451a766 | 2003-05-26 01:51:33 +0000 | [diff] [blame] | 241 | Tell the driver that there is likely to be a pause in the output, making |
| 242 | it possible for the device to handle the pause more intelligently. You |
| 243 | might use this after playing a spot sound effect, before waiting for |
| 244 | user input, or before doing disk I/O. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 245 | \end{methoddesc} |
| 246 | |
Greg Ward | fb1b5a1 | 2003-05-29 01:39:32 +0000 | [diff] [blame] | 247 | The following convenience methods combine several ioctls, or one ioctl |
| 248 | and some simple calculations. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 249 | |
Greg Ward | fb1b5a1 | 2003-05-29 01:39:32 +0000 | [diff] [blame] | 250 | \begin{methoddesc}[audio device]{setparameters} |
| 251 | {format, nchannels, samplerate \optional{, strict=False}} |
| 252 | |
| 253 | Set the key audio sampling parameters---sample format, number of |
| 254 | channels, and sampling rate---in one method call. \var{format}, |
| 255 | \var{nchannels}, and \var{samplerate} should be as specified in the |
| 256 | \method{setfmt()}, \method{channels()}, and \method{speed()} |
| 257 | methods. If \var{strict} is true, \method{setparameters()} checks to |
| 258 | see if each parameter was actually set to the requested value, and |
| 259 | raises \exception{OSSAudioError} if not. Returns a tuple (\var{format}, |
| 260 | \var{nchannels}, \var{samplerate}) indicating the parameter values that |
| 261 | were actually set by the device driver (i.e., the same as the return |
| 262 | valus of \method{setfmt()}, \method{channels()}, and \method{speed()}). |
| 263 | |
| 264 | For example, |
| 265 | \begin{verbatim} |
| 266 | (fmt, channels, rate) = dsp.setparameters(fmt, channels, rate) |
| 267 | \end{verbatim} |
| 268 | is equivalent to |
| 269 | \begin{verbatim} |
| 270 | fmt = dsp.setfmt(fmt) |
| 271 | channels = dsp.channels(channels) |
| 272 | rate = dsp.rate(channels) |
| 273 | \end{verbatim} |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 274 | \end{methoddesc} |
| 275 | |
| 276 | \begin{methoddesc}[audio device]{bufsize}{} |
| 277 | Returns the size of the hardware buffer, in samples. |
| 278 | \end{methoddesc} |
| 279 | |
| 280 | \begin{methoddesc}[audio device]{obufcount}{} |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 281 | Returns the number of samples that are in the hardware buffer yet to be |
| 282 | played. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 283 | \end{methoddesc} |
| 284 | |
| 285 | \begin{methoddesc}[audio device]{obuffree}{} |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 286 | Returns the number of samples that could be queued into the hardware |
| 287 | buffer to be played without blocking. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 288 | \end{methoddesc} |
| 289 | |
| 290 | \subsection{Mixer Device Objects \label{mixer-device-objects}} |
| 291 | |
| 292 | File-like interface |
| 293 | |
| 294 | \begin{methoddesc}[mixer device]{close}{} |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 295 | This method closes the open mixer device file. Any further attempts to |
| 296 | use the mixer after this file is closed will raise an IOError. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 297 | \end{methoddesc} |
| 298 | |
| 299 | \begin{methoddesc}[mixer device]{fileno}{} |
| 300 | Returns the file handle number of the open mixer device file. |
| 301 | \end{methoddesc} |
| 302 | |
| 303 | Mixer interface |
| 304 | |
| 305 | \begin{methoddesc}[mixer device]{controls}{} |
| 306 | This method returns a bitmask specifying the available mixer controls |
| 307 | (``Control'' being a specific mixable ``channel'', such as |
Greg Ward | 3e34f59 | 2003-03-10 02:09:51 +0000 | [diff] [blame] | 308 | \constant{SOUND_MIXER_PCM} or \constant{SOUND_MIXER_SYNTH}). This |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 309 | bitmask indicates a subset of all available mixer channels---the |
Greg Ward | 3e34f59 | 2003-03-10 02:09:51 +0000 | [diff] [blame] | 310 | \constant{SOUND_MIXER_*} constants defined at module level. To determine if, |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 311 | for example, the current mixer object supports a PCM mixer, use the |
| 312 | following Python code: |
| 313 | |
| 314 | \begin{verbatim} |
| 315 | mixer=ossaudiodev.openmixer() |
| 316 | if mixer.channels() & (1 << ossaudiodev.SOUND_MIXER_PCM): |
| 317 | # PCM is supported |
| 318 | <code> |
| 319 | \end{verbatim} |
| 320 | |
Greg Ward | 3e34f59 | 2003-03-10 02:09:51 +0000 | [diff] [blame] | 321 | For most purposes, the \constant{SOUND_MIXER_VOLUME} (Master volume) and |
| 322 | \constant{SOUND_MIXER_PCM} channels should suffice---but code that uses the |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 323 | mixer should be flexible when it comes to choosing sound channels. On |
Greg Ward | 3e34f59 | 2003-03-10 02:09:51 +0000 | [diff] [blame] | 324 | the Gravis Ultrasound, for example, \constant{SOUND_MIXER_VOLUME} does not |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 325 | exist. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 326 | \end{methoddesc} |
| 327 | |
| 328 | \begin{methoddesc}[mixer device]{stereocontrols}{} |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 329 | Returns a bitmask indicating stereo mixer channels. If a bit is set, |
| 330 | the corresponding channel is stereo; if it is unset, the channel is |
| 331 | either monophonic or not supported by the mixer (use in combination with |
Greg Ward | 3e34f59 | 2003-03-10 02:09:51 +0000 | [diff] [blame] | 332 | \method{channels()} to determine which). |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 333 | |
Greg Ward | 3e34f59 | 2003-03-10 02:09:51 +0000 | [diff] [blame] | 334 | See the code example for the \method{channels()} function for an example |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 335 | of getting data from a bitmask. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 336 | \end{methoddesc} |
| 337 | |
| 338 | \begin{methoddesc}[mixer device]{reccontrols}{} |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 339 | Returns a bitmask specifying the mixer controls that may be used to |
Greg Ward | 3e34f59 | 2003-03-10 02:09:51 +0000 | [diff] [blame] | 340 | record. See the code example for \method{controls()} for an example of |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 341 | reading from a bitmask. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 342 | \end{methoddesc} |
| 343 | |
| 344 | \begin{methoddesc}[mixer device]{get}{channel} |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 345 | Returns the volume of a given mixer channel. The returned volume is a |
Greg Ward | 3e34f59 | 2003-03-10 02:09:51 +0000 | [diff] [blame] | 346 | 2-tuple \code{(left_volume,right_volume)}. Volumes are specified as |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 347 | numbers from 0 (silent) to 100 (full volume). If the channel is |
| 348 | monophonic, a 2-tuple is still returned, but both channel volumes are |
| 349 | the same. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 350 | |
| 351 | If an unknown channel is specified, \exception{error} is raised. |
| 352 | \end{methoddesc} |
| 353 | |
| 354 | \begin{methoddesc}[mixer device]{set}{channel, (left, right)} |
Greg Ward | 3e34f59 | 2003-03-10 02:09:51 +0000 | [diff] [blame] | 355 | Sets the volume for a given mixer channel to \code{(left,right)}. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 356 | \code{left} and \code{right} must be ints and between 0 (silent) and 100 |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 357 | (full volume). On success, the new volume is returned as a 2-tuple. |
| 358 | Note that this may not be exactly the same as the volume specified, |
| 359 | because of the limited resolution of some soundcard's mixers. |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 360 | |
| 361 | Raises \exception{IOError} if an invalid mixer channel was specified; |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 362 | \exception{TypeError} if the argument format was incorrect, and |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 363 | \exception{error} if the specified volumes were out-of-range. |
| 364 | \end{methoddesc} |
| 365 | |
| 366 | \begin{methoddesc}[mixer device]{get_recsrc}{} |
| 367 | This method returns a bitmask indicating which channel or channels are |
| 368 | currently being used as a recording source. |
| 369 | \end{methoddesc} |
| 370 | |
| 371 | \begin{methoddesc}[mixer device]{set_recsrc}{bitmask} |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 372 | Call this function to specify a recording source. Returns a bitmask |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 373 | indicating the new recording source (or sources) if successful; raises |
Greg Ward | 33bcd98 | 2003-03-09 23:57:34 +0000 | [diff] [blame] | 374 | \exception{IOError} if an invalid source was specified. To set the current |
Greg Ward | 620e343 | 2003-03-09 23:34:52 +0000 | [diff] [blame] | 375 | recording source to the microphone input: |
| 376 | |
| 377 | \begin{verbatim} |
| 378 | mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC) |
| 379 | \end{verbatim} |
| 380 | \end{methoddesc} |
| 381 | |
| 382 | |
| 383 | |