* Bug 15977 fixed: wavread() page fixed & improved
[scilab.git] / scilab / modules / sound / help / en_US / wavread.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) ????-2008 - INRIA - Scilab
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2019 - Samuel GOUGEON
7  * Copyright (C) 2019 - Federico MIYARA
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16 -->
17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
18           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml"
19           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
20           xmlns:scilab="http://www.scilab.org" xml:id="wavread" xml:lang="en">
21     <refnamediv>
22         <refname>wavread</refname>
23         <refpurpose>reads sound data or querries data info from a .wav audio file</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Syntax</title>
27         <synopsis>
28             Info = wavread(wavfile, 'info')
29             s = wavread(wavfile, 'size')
30             y = wavread(wavfile)
31             y = wavread(wavfile, n)
32             y = wavread(wavfile, [i1 i2])
33             [y, Fs, bits] = wavread(..)
34         </synopsis>
35     </refsynopsisdiv>
36     <refsection>
37         <title>Arguments</title>
38         <variablelist>
39             <varlistentry>
40                 <term>wavfile</term>
41                 <listitem>
42                     <para>
43                         string: path and file name pointing to the audio file. Included heading
44                         constant strings <literal>SCI</literal>, <literal>TMPDIR</literal>,
45                         <literal>SCIHOME</literal>, or <literal>home</literal> are
46                         automatically expanded.
47                         The .wav extension is appended if no extension is given.
48                     </para>
49                 </listitem>
50             </varlistentry>
51             <varlistentry>
52                 <term>n</term>
53                 <listitem>
54                     <para>
55                         positive integer: number of first samples to get, per channel.
56                     </para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>[i1 i2]</term>
61                 <listitem>
62                     <para>
63                         positive integers, to select and return from each channel the samples #i1 to #i2.
64                     </para>
65                 </listitem>
66             </varlistentry>
67             <varlistentry>
68                 <term>y</term>
69                 <listitem>
70                     <para>
71                         Matrix: values of sound amplitudes in [-1,+1], with one row per channel.
72                     </para>
73                 </listitem>
74             </varlistentry>
75             <varlistentry>
76                 <term>Fs</term>
77                 <listitem>
78                     <para>integer: sampling frequency in Hz = number of samples per second per channel.
79                     </para>
80                 </listitem>
81             </varlistentry>
82             <varlistentry>
83                 <term>bits</term>
84                 <listitem>
85                     <para>Positive integer: number of bits for <literal>y</literal> values.
86                     </para>
87                 </listitem>
88             </varlistentry>
89             <varlistentry>
90                 <term>Info</term>
91                 <listitem>
92                     <para>
93                         Row vector of 8 decimal integers describing the recorded signal.
94                         See the description section for details.
95                     </para>
96                 </listitem>
97             </varlistentry>
98         </variablelist>
99     </refsection>
100     <refsection>
101         <title>Description</title>
102         <para>
103             Utility function to read <literal>.wav</literal> sound file.
104             <literal>wavread(wavfile)</literal> loads a sound file specified by the
105             string wavfile, returning the sampled data in y. Amplitude values are in
106             the range [-1,+1]. Supports multi-channel data in the following formats:
107             8-, 16-, and 32-bit linear, and floating point.
108         </para>
109         <para>
110             <literal>[y,Fs,bits]=wavread(wavfile)</literal> returns the sample
111             rate (Fs) in Hertz and the number of bits per sample used to encode the
112             data in the file.
113         </para>
114         <para>
115             <literal>wavread(wavfile,n)</literal> returns the first n samples
116             from each channel.
117         </para>
118         <para>
119             <literal>wavread(wavfile,[n1,n2])</literal> returns samples n1 to
120             n2.
121         </para>
122         <para>
123             <literal>wavread(wavfile,'size')</literal> returns the size of the
124             audio data contained in the file in place of the actual audio data,
125             returning the vector as [channels samples].
126         </para>
127         <para>
128             <literal>wavread(wavfile,'info')</literal> returns information
129             about the audio data contained in the file, instead of the actual audio
130             data, returning a row vector with the following components:
131         </para>
132         <table border="0">
133             <tr>
134                 <th>(1)</th>
135                 <td>encoding code</td><td>:</td>
136                 <td>
137                  AKA <emphasis>format category</emphasis>: positive integer = standard id of the
138                  type of data encoding. Supported formats: 1 (PCM), 3 (normalized floating point).
139                 </td>
140             </tr>
141             <tr>
142                 <th>(2)</th>
143                 <td style="white-space: nowrap">number of channels</td><td>:</td>
144                 <td>
145                     Number of simultaneous single-valued collected signals = <literal>size(y,1)</literal>.
146                 </td>
147             </tr>
148             <tr>
149                 <th>(3)</th>
150                 <td>sampling frequency</td><td>:</td>
151                 <td>
152                     number of samples recorded for each channel, per second.
153                 </td>
154             </tr>
155             <tr>
156                 <th>(4)</th>
157                 <td>average bytes per second</td><td>:</td>
158                 <td>
159                     For plain PCM it is the sampling rate multiplied by the number of channels and
160                     the number of bytes per sample. For compressed formats it is approximately
161                     the total data length in bytes divided by the duration of the sound.
162                 </td>
163             </tr>
164             <tr>
165                 <th>(5)</th>
166                 <td>block alignment</td><td>:</td>
167                 <td>
168                     The number of bytes associated with each sampling instant. For the plain
169                     PCM uncompressed format, it is equal to the number of channels multiplied by
170                     the number of bytes per channel.
171                 </td>
172             </tr>
173             <tr>
174                 <th>(6)</th>
175                 <td>bits per sample (per channel)</td><td>:</td>
176                 <td>
177                     Number of bits used to quantize each value of the sound amplitude.
178                 </td>
179             </tr>
180             <tr>
181                 <th>(7)</th>
182                 <td>bytes per sample (per channel)</td><td>:</td>
183                 <td>
184                     Number of bytes assigned to each individual value of the sound amplitude.
185                 </td>
186             </tr>
187             <tr>
188                 <th>(8)</th>
189                 <td>length of sound data (per channel)</td><td>:</td>
190                 <td>
191                    The total number of samples on each channel = <literal>size(y,2)</literal>.
192                    Hence, the record's duration is <literal>Info(8)/Info(3)</literal>.
193                 </td>
194             </tr>
195         </table>
196     </refsection>
197     <refsection>
198         <title>Examples</title>
199         <programlisting role="example"><![CDATA[
200 File = "SCI/modules/sound/demos/chimes.wav";
201 wavread(File, "size")
202 wavread(File, "info")
203 y = wavread(File, 5)     // the first five samples
204 y = wavread(File, [4 7]) // only samples #4 to #7
205 [y, Fs, bits] = wavread(File); Fs, bits
206 clf
207 subplot(2,1,1)
208 plot2d(y(1,:)) // first channel
209 subplot(2,1,2)
210 plot2d(y(2,:)) // second channel
211  ]]></programlisting>
212     <screen><![CDATA[
213 --> wavread(File, "size")
214  ans  =
215    2.   13921.
216
217 --> wavread(File, "info")
218  ans  =
219    1.   2.   22050.   88200.   4.   16.   2.   13921.
220
221 --> y = wavread(File, 5)     // the first five samples
222  y  =
223    0.000061    0.0002747   0.0002136   0.0001526   0.0000916
224    0.0000916   0.0001831   0.000061    0.          0.0000916
225
226 --> y = wavread(File, [4 7]) // only samples #4 to #7
227  y  =
228    0.0001526   0.0000916   0.0000305  -0.0000305
229    0.          0.0000916   0.000061    0.0000916
230
231 --> [y, Fs, bits] = wavread(File); Fs, bits
232  Fs  =
233    22050.
234
235  bits  =
236    16.
237 ]]></screen>
238         <scilab:image>
239             wavread("SCI/modules/sound/demos/chimes.wav","size")
240             [y,Fs,bits]=wavread("SCI/modules/sound/demos/chimes.wav");
241             subplot(2,1,1)
242             plot2d(y(1,:))
243             subplot(2,1,2)
244             plot2d(y(2,:))
245             y=wavread("SCI/modules/sound/demos/chimes.wav",[1 5])
246         </scilab:image>
247     </refsection>
248     <refsection role="see also">
249         <title>See also</title>
250         <simplelist type="inline">
251             <member>
252                 <link linkend="auread">auread</link>
253             </member>
254             <member>
255                 <link linkend="wavwrite">wavwrite</link>
256             </member>
257             <member>
258                 <link linkend="analyze">analyze</link>
259             </member>
260             <member>
261                 <link linkend="mapsound">mapsound</link>
262             </member>
263             <member>
264                 <ulink url="http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Docs/riffmci.pdf">RIFF-wav encoding (p.56)</ulink>
265             </member>
266         </simplelist>
267     </refsection>
268 </refentry>