1:mod:`sndhdr` --- Determine type of sound file
2==============================================
3
4.. module:: sndhdr
5   :synopsis: Determine type of a sound file.
6   :deprecated:
7
8.. sectionauthor:: Fred L. Drake, Jr. <[email protected]>
9.. Based on comments in the module source file.
10
11**Source code:** :source:`Lib/sndhdr.py`
12
13.. index::
14   single: A-LAW
15   single: u-LAW
16
17.. deprecated-removed:: 3.11 3.13
18   The :mod:`sndhdr` module is deprecated
19   (see :pep:`PEP 594 <594#sndhdr>` for details and alternatives).
20
21--------------
22
23The :mod:`sndhdr` provides utility functions which attempt to determine the type
24of sound data which is in a file.  When these functions are able to determine
25what type of sound data is stored in a file, they return a
26:func:`~collections.namedtuple`, containing five attributes: (``filetype``,
27``framerate``, ``nchannels``, ``nframes``, ``sampwidth``). The value for *type*
28indicates the data type and will be one of the strings ``'aifc'``, ``'aiff'``,
29``'au'``, ``'hcom'``, ``'sndr'``, ``'sndt'``, ``'voc'``, ``'wav'``, ``'8svx'``,
30``'sb'``, ``'ub'``, or ``'ul'``.  The *sampling_rate* will be either the actual
31value or ``0`` if unknown or difficult to decode.  Similarly, *channels* will be
32either the number of channels or ``0`` if it cannot be determined or if the
33value is difficult to decode.  The value for *frames* will be either the number
34of frames or ``-1``.  The last item in the tuple, *bits_per_sample*, will either
35be the sample size in bits or ``'A'`` for A-LAW or ``'U'`` for u-LAW.
36
37
38.. function:: what(filename)
39
40   Determines the type of sound data stored in the file *filename* using
41   :func:`whathdr`.  If it succeeds, returns a namedtuple as described above, otherwise
42   ``None`` is returned.
43
44   .. versionchanged:: 3.5
45      Result changed from a tuple to a namedtuple.
46
47
48.. function:: whathdr(filename)
49
50   Determines the type of sound data stored in a file based on the file  header.
51   The name of the file is given by *filename*.  This function returns a namedtuple as
52   described above on success, or ``None``.
53
54   .. versionchanged:: 3.5
55      Result changed from a tuple to a namedtuple.
56
57The following sound header types are recognized, as listed below with the return value
58from :func:`whathdr`: and :func:`what`:
59
60+------------+------------------------------------+
61| Value      | Sound header format                |
62+============+====================================+
63| ``'aifc'`` | Compressed Audio Interchange Files |
64+------------+------------------------------------+
65| ``'aiff'`` | Audio Interchange Files            |
66+------------+------------------------------------+
67| ``'au'``   | Au Files                           |
68+------------+------------------------------------+
69| ``'hcom'`` | HCOM Files                         |
70+------------+------------------------------------+
71| ``'sndt'`` | Sndtool Sound Files                |
72+------------+------------------------------------+
73| ``'voc'``  | Creative Labs Audio Files          |
74+------------+------------------------------------+
75| ``'wav'``  | Waveform Audio File Format Files   |
76+------------+------------------------------------+
77| ``'8svx'`` | 8-Bit Sampled Voice Files          |
78+------------+------------------------------------+
79| ``'sb'``   | Signed Byte Audio Data Files       |
80+------------+------------------------------------+
81| ``'ub'``   | UB Files                           |
82+------------+------------------------------------+
83| ``'ul'``   | uLAW Audio Files                   |
84+------------+------------------------------------+
85
86.. data:: tests
87
88   A list of functions performing the individual tests.  Each function takes two
89   arguments: the byte-stream and an open file-like object. When :func:`what` is
90   called with a byte-stream, the file-like object will be ``None``.
91
92   The test function should return a string describing the image type if the test
93   succeeded, or ``None`` if it failed.
94
95Example:
96
97.. code-block:: pycon
98
99   >>> import sndhdr
100   >>> imghdr.what('bass.wav')
101   'wav'
102   >>> imghdr.whathdr('bass.wav')
103   'wav'
104
105