mirror of
https://github.com/python/cpython.git
synced 2024-12-01 03:01:36 +01:00
89ab163479
the default value is determined.
203 lines
7.4 KiB
TeX
203 lines
7.4 KiB
TeX
\section{\module{aifc} ---
|
|
Read and write AIFF and AIFC files}
|
|
|
|
\declaremodule{standard}{aifc}
|
|
\modulesynopsis{Read and write audio files in AIFF or AIFC format.}
|
|
|
|
|
|
This module provides support for reading and writing AIFF and AIFF-C
|
|
files. AIFF is Audio Interchange File Format, a format for storing
|
|
digital audio samples in a file. AIFF-C is a newer version of the
|
|
format that includes the ability to compress the audio data.
|
|
\index{Audio Interchange File Format}
|
|
\index{AIFF}
|
|
\index{AIFF-C}
|
|
|
|
\strong{Caveat:} Some operations may only work under IRIX; these will
|
|
raise \exception{ImportError} when attempting to import the
|
|
\module{cl} module, which is only available on IRIX.
|
|
|
|
Audio files have a number of parameters that describe the audio data.
|
|
The sampling rate or frame rate is the number of times per second the
|
|
sound is sampled. The number of channels indicate if the audio is
|
|
mono, stereo, or quadro. Each frame consists of one sample per
|
|
channel. The sample size is the size in bytes of each sample. Thus a
|
|
frame consists of \var{nchannels}*\var{samplesize} bytes, and a
|
|
second's worth of audio consists of
|
|
\var{nchannels}*\var{samplesize}*\var{framerate} bytes.
|
|
|
|
For example, CD quality audio has a sample size of two bytes (16
|
|
bits), uses two channels (stereo) and has a frame rate of 44,100
|
|
frames/second. This gives a frame size of 4 bytes (2*2), and a
|
|
second's worth occupies 2*2*44100 bytes, i.e.\ 176,400 bytes.
|
|
|
|
Module \module{aifc} defines the following function:
|
|
|
|
\begin{funcdesc}{open}{file\optional{, mode}}
|
|
Open an AIFF or AIFF-C file and return an object instance with
|
|
methods that are described below. The argument \var{file} is either a
|
|
string naming a file or a file object. \var{mode} must be \code{'r'}
|
|
or \code{'rb'} when the file must be opened for reading, or \code{'w'}
|
|
or \code{'wb'} when the file must be opened for writing. If omitted,
|
|
\code{\var{file}.mode} is used if it exists, otherwise \code{'rb'} is
|
|
used. When used for writing, the file object should be seekable,
|
|
unless you know ahead of time how many samples you are going to write
|
|
in total and use \method{writeframesraw()} and \method{setnframes()}.
|
|
\end{funcdesc}
|
|
|
|
Objects returned by \function{open()} when a file is opened for
|
|
reading have the following methods:
|
|
|
|
\begin{methoddesc}[aifc]{getnchannels}{}
|
|
Return the number of audio channels (1 for mono, 2 for stereo).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{getsampwidth}{}
|
|
Return the size in bytes of individual samples.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{getframerate}{}
|
|
Return the sampling rate (number of audio frames per second).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{getnframes}{}
|
|
Return the number of audio frames in the file.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{getcomptype}{}
|
|
Return a four-character string describing the type of compression used
|
|
in the audio file. For AIFF files, the returned value is
|
|
\code{'NONE'}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{getcompname}{}
|
|
Return a human-readable description of the type of compression used in
|
|
the audio file. For AIFF files, the returned value is \code{'not
|
|
compressed'}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{getparams}{}
|
|
Return a tuple consisting of all of the above values in the above
|
|
order.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{getmarkers}{}
|
|
Return a list of markers in the audio file. A marker consists of a
|
|
tuple of three elements. The first is the mark ID (an integer), the
|
|
second is the mark position in frames from the beginning of the data
|
|
(an integer), the third is the name of the mark (a string).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{getmark}{id}
|
|
Return the tuple as described in \method{getmarkers()} for the mark
|
|
with the given \var{id}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{readframes}{nframes}
|
|
Read and return the next \var{nframes} frames from the audio file. The
|
|
returned data is a string containing for each frame the uncompressed
|
|
samples of all channels.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{rewind}{}
|
|
Rewind the read pointer. The next \method{readframes()} will start from
|
|
the beginning.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{setpos}{pos}
|
|
Seek to the specified frame number.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{tell}{}
|
|
Return the current frame number.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{close}{}
|
|
Close the AIFF file. After calling this method, the object can no
|
|
longer be used.
|
|
\end{methoddesc}
|
|
|
|
Objects returned by \function{open()} when a file is opened for
|
|
writing have all the above methods, except for \method{readframes()} and
|
|
\method{setpos()}. In addition the following methods exist. The
|
|
\method{get*()} methods can only be called after the corresponding
|
|
\method{set*()} methods have been called. Before the first
|
|
\method{writeframes()} or \method{writeframesraw()}, all parameters
|
|
except for the number of frames must be filled in.
|
|
|
|
\begin{methoddesc}[aifc]{aiff}{}
|
|
Create an AIFF file. The default is that an AIFF-C file is created,
|
|
unless the name of the file ends in \code{'.aiff'} in which case the
|
|
default is an AIFF file.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{aifc}{}
|
|
Create an AIFF-C file. The default is that an AIFF-C file is created,
|
|
unless the name of the file ends in \code{'.aiff'} in which case the
|
|
default is an AIFF file.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{setnchannels}{nchannels}
|
|
Specify the number of channels in the audio file.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{setsampwidth}{width}
|
|
Specify the size in bytes of audio samples.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{setframerate}{rate}
|
|
Specify the sampling frequency in frames per second.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{setnframes}{nframes}
|
|
Specify the number of frames that are to be written to the audio file.
|
|
If this parameter is not set, or not set correctly, the file needs to
|
|
support seeking.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{setcomptype}{type, name}
|
|
Specify the compression type. If not specified, the audio data will
|
|
not be compressed. In AIFF files, compression is not possible. The
|
|
name parameter should be a human-readable description of the
|
|
compression type, the type parameter should be a four-character
|
|
string. Currently the following compression types are supported:
|
|
NONE, ULAW, ALAW, G722.
|
|
\index{u-LAW}
|
|
\index{A-LAW}
|
|
\index{G.722}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{setparams}{nchannels, sampwidth, framerate, comptype, compname}
|
|
Set all the above parameters at once. The argument is a tuple
|
|
consisting of the various parameters. This means that it is possible
|
|
to use the result of a \method{getparams()} call as argument to
|
|
\method{setparams()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{setmark}{id, pos, name}
|
|
Add a mark with the given id (larger than 0), and the given name at
|
|
the given position. This method can be called at any time before
|
|
\method{close()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{tell}{}
|
|
Return the current write position in the output file. Useful in
|
|
combination with \method{setmark()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{writeframes}{data}
|
|
Write data to the output file. This method can only be called after
|
|
the audio file parameters have been set.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{writeframesraw}{data}
|
|
Like \method{writeframes()}, except that the header of the audio file
|
|
is not updated.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[aifc]{close}{}
|
|
Close the AIFF file. The header of the file is updated to reflect the
|
|
actual size of the audio data. After calling this method, the object
|
|
can no longer be used.
|
|
\end{methoddesc}
|