1 

     2 :mod:`aifc` --- Read and write AIFF and AIFC files

     3 ==================================================

     4 

     5 .. module:: aifc

     6    :synopsis: Read and write audio files in AIFF or AIFC format.

     7 

     8 

     9 .. index::

    10    single: Audio Interchange File Format

    11    single: AIFF

    12    single: AIFF-C

    13 

    14 This module provides support for reading and writing AIFF and AIFF-C files.

    15 AIFF is Audio Interchange File Format, a format for storing digital audio

    16 samples in a file.  AIFF-C is a newer version of the format that includes the

    17 ability to compress the audio data.

    18 

    19 .. warning::

    20    

    21    Some operations may only work under IRIX; these will raise :exc:`ImportError`

    22    when attempting to import the :mod:`cl` module, which is only available on IRIX.

    23 

    24 Audio files have a number of parameters that describe the audio data. The

    25 sampling rate or frame rate is the number of times per second the sound is

    26 sampled.  The number of channels indicate if the audio is mono, stereo, or

    27 quadro.  Each frame consists of one sample per channel.  The sample size is the

    28 size in bytes of each sample.  Thus a frame consists of

    29 *nchannels*\**samplesize* bytes, and a second's worth of audio consists of

    30 *nchannels*\**samplesize*\**framerate* bytes.

    31 

    32 For example, CD quality audio has a sample size of two bytes (16 bits), uses two

    33 channels (stereo) and has a frame rate of 44,100 frames/second.  This gives a

    34 frame size of 4 bytes (2\*2), and a second's worth occupies 2\*2\*44100 bytes

    35 (176,400 bytes).

    36 

    37 Module :mod:`aifc` defines the following function:

    38 

    39 

    40 .. function:: open(file[, mode])

    41 

    42    Open an AIFF or AIFF-C file and return an object instance with methods that are

    43    described below.  The argument *file* is either a string naming a file or a file

    44    object.  *mode* must be ``'r'`` or ``'rb'`` when the file must be opened for

    45    reading, or ``'w'``  or ``'wb'`` when the file must be opened for writing.  If

    46    omitted, ``file.mode`` is used if it exists, otherwise ``'rb'`` is used.  When

    47    used for writing, the file object should be seekable, unless you know ahead of

    48    time how many samples you are going to write in total and use

    49    :meth:`writeframesraw` and :meth:`setnframes`.

    50 

    51 Objects returned by :func:`open` when a file is opened for reading have the

    52 following methods:

    53 

    54 

    55 .. method:: aifc.getnchannels()

    56 

    57    Return the number of audio channels (1 for mono, 2 for stereo).

    58 

    59 

    60 .. method:: aifc.getsampwidth()

    61 

    62    Return the size in bytes of individual samples.

    63 

    64 

    65 .. method:: aifc.getframerate()

    66 

    67    Return the sampling rate (number of audio frames per second).

    68 

    69 

    70 .. method:: aifc.getnframes()

    71 

    72    Return the number of audio frames in the file.

    73 

    74 

    75 .. method:: aifc.getcomptype()

    76 

    77    Return a four-character string describing the type of compression used in the

    78    audio file.  For AIFF files, the returned value is ``'NONE'``.

    79 

    80 

    81 .. method:: aifc.getcompname()

    82 

    83    Return a human-readable description of the type of compression used in the audio

    84    file.  For AIFF files, the returned value is ``'not compressed'``.

    85 

    86 

    87 .. method:: aifc.getparams()

    88 

    89    Return a tuple consisting of all of the above values in the above order.

    90 

    91 

    92 .. method:: aifc.getmarkers()

    93 

    94    Return a list of markers in the audio file.  A marker consists of a tuple of

    95    three elements.  The first is the mark ID (an integer), the second is the mark

    96    position in frames from the beginning of the data (an integer), the third is the

    97    name of the mark (a string).

    98 

    99 

   100 .. method:: aifc.getmark(id)

   101 

   102    Return the tuple as described in :meth:`getmarkers` for the mark with the given

   103    *id*.

   104 

   105 

   106 .. method:: aifc.readframes(nframes)

   107 

   108    Read and return the next *nframes* frames from the audio file.  The returned

   109    data is a string containing for each frame the uncompressed samples of all

   110    channels.

   111 

   112 

   113 .. method:: aifc.rewind()

   114 

   115    Rewind the read pointer.  The next :meth:`readframes` will start from the

   116    beginning.

   117 

   118 

   119 .. method:: aifc.setpos(pos)

   120 

   121    Seek to the specified frame number.

   122 

   123 

   124 .. method:: aifc.tell()

   125 

   126    Return the current frame number.

   127 

   128 

   129 .. method:: aifc.close()

   130 

   131    Close the AIFF file.  After calling this method, the object can no longer be

   132    used.

   133 

   134 Objects returned by :func:`open` when a file is opened for writing have all the

   135 above methods, except for :meth:`readframes` and :meth:`setpos`.  In addition

   136 the following methods exist.  The :meth:`get\*` methods can only be called after

   137 the corresponding :meth:`set\*` methods have been called.  Before the first

   138 :meth:`writeframes` or :meth:`writeframesraw`, all parameters except for the

   139 number of frames must be filled in.

   140 

   141 

   142 .. method:: aifc.aiff()

   143 

   144    Create an AIFF file.  The default is that an AIFF-C file is created, unless the

   145    name of the file ends in ``'.aiff'`` in which case the default is an AIFF file.

   146 

   147 

   148 .. method:: aifc.aifc()

   149 

   150    Create an AIFF-C file.  The default is that an AIFF-C file is created, unless

   151    the name of the file ends in ``'.aiff'`` in which case the default is an AIFF

   152    file.

   153 

   154 

   155 .. method:: aifc.setnchannels(nchannels)

   156 

   157    Specify the number of channels in the audio file.

   158 

   159 

   160 .. method:: aifc.setsampwidth(width)

   161 

   162    Specify the size in bytes of audio samples.

   163 

   164 

   165 .. method:: aifc.setframerate(rate)

   166 

   167    Specify the sampling frequency in frames per second.

   168 

   169 

   170 .. method:: aifc.setnframes(nframes)

   171 

   172    Specify the number of frames that are to be written to the audio file. If this

   173    parameter is not set, or not set correctly, the file needs to support seeking.

   174 

   175 

   176 .. method:: aifc.setcomptype(type, name)

   177 

   178    .. index::

   179       single: u-LAW

   180       single: A-LAW

   181       single: G.722

   182 

   183    Specify the compression type.  If not specified, the audio data will not be

   184    compressed.  In AIFF files, compression is not possible.  The name parameter

   185    should be a human-readable description of the compression type, the type

   186    parameter should be a four-character string.  Currently the following

   187    compression types are supported: NONE, ULAW, ALAW, G722.

   188 

   189 

   190 .. method:: aifc.setparams(nchannels, sampwidth, framerate, comptype, compname)

   191 

   192    Set all the above parameters at once.  The argument is a tuple consisting of the

   193    various parameters.  This means that it is possible to use the result of a

   194    :meth:`getparams` call as argument to :meth:`setparams`.

   195 

   196 

   197 .. method:: aifc.setmark(id, pos, name)

   198 

   199    Add a mark with the given id (larger than 0), and the given name at the given

   200    position.  This method can be called at any time before :meth:`close`.

   201 

   202 

   203 .. method:: aifc.tell()

   204 

   205    Return the current write position in the output file.  Useful in combination

   206    with :meth:`setmark`.

   207 

   208 

   209 .. method:: aifc.writeframes(data)

   210 

   211    Write data to the output file.  This method can only be called after the audio

   212    file parameters have been set.

   213 

   214 

   215 .. method:: aifc.writeframesraw(data)

   216 

   217    Like :meth:`writeframes`, except that the header of the audio file is not

   218    updated.

   219 

   220 

   221 .. method:: aifc.close()

   222 

   223    Close the AIFF file.  The header of the file is updated to reflect the actual

   224    size of the audio data. After calling this method, the object can no longer be

   225    used.

   226