92d54457fdce8c6195a3e8e615598f36ecaa88cb
[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     *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14     *
15     -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="wavread" xml:lang="en">
17     <refnamediv>
18         <refname>wavread</refname>
19         <refpurpose>load .wav sound file</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Syntax</title>
23         <synopsis>y=wavread(wavfile)
24             y=wavread(wavfile,ext)
25             [y,Fs,bits]=wavread(wavfile)
26             [y,Fs,bits]=wavread(wavfile,ext)
27         </synopsis>
28     </refsynopsisdiv>
29     <refsection>
30         <title>Arguments</title>
31         <variablelist>
32             <varlistentry>
33                 <term>wavfile</term>
34                 <listitem>
35                     <para>string (The .wav extension is appended if no extension is
36                         given)
37                     </para>
38                 </listitem>
39             </varlistentry>
40             <varlistentry>
41                 <term>Fs</term>
42                 <listitem>
43                     <para>integer, frequency sampling in Hz (number of samples per
44                         second).
45                     </para>
46                 </listitem>
47             </varlistentry>
48             <varlistentry>
49                 <term>ext</term>
50                 <listitem>
51                     <para>
52                         string (<literal>'size'</literal>) or string('info') or
53                         integer (to read n samples) or 1 x 2 integer vector [n1,n2] (to read
54                         from n1 to n2).
55                     </para>
56                 </listitem>
57             </varlistentry>
58         </variablelist>
59     </refsection>
60     <refsection>
61         <title>Description</title>
62         <para>
63             Utility function to read <literal>.wav</literal> sound file.
64             <literal>wavread(wavfile)</literal> loads a sound file specified by the
65             string wavfile, returning the sampled data in y. Amplitude values are in
66             the range [-1,+1]. Supports multi-channel data in the following formats:
67             8-bit mu-law, 8-, 16-, and 32-bit linear, and floating point.
68         </para>
69         <para>
70             <literal>[y,Fs,bits]=wavread(wavfile)</literal> returns the sample
71             rate (Fs) in Hertz and the number of bits per sample used to encode the
72             data in the file.
73         </para>
74         <para>
75             <literal>wavread(wavfile,n)</literal> returns the first n samples
76             from each channel.
77         </para>
78         <para>
79             <literal>wavread(wavfile,[n1,n2])</literal> returns samples n1 to
80             n2.
81         </para>
82         <para>
83             <literal>wavread(wavfile,'size')</literal> returns the size of the
84             audio data contained in the file in place of the actual audio data,
85             returning the vector as [channels samples].
86         </para>
87         <para>
88             <literal>wavread(wavfile,'info')</literal> returns information
89             about the audio data contained in the file in place of the actual audio
90             data, returning the vector as [data format, number of channels, samples
91             per second per channel, estimate of bytes per second needed, byte
92             alignment of a basic sample block, bits per sample, length of sound data
93             in bytes, bytes per sample (per channel)].
94         </para>
95     </refsection>
96     <refsection>
97         <title>Examples</title>
98         <programlisting role="example"><![CDATA[
99 wavread("SCI/modules/sound/demos/chimes.wav","size")
100 [y,Fs,bits]=wavread("SCI/modules/sound/demos/chimes.wav");Fs,bits
101 subplot(2,1,1)
102 plot2d(y(1,:)) // first channel
103 subplot(2,1,2)
104 plot2d(y(2,:)) // second channel
105 y=wavread("SCI/modules/sound/demos/chimes.wav",[1 5]) //the first five samples
106  ]]></programlisting>
107         <scilab:image>
108             wavread("SCI/modules/sound/demos/chimes.wav","size")
109             [y,Fs,bits]=wavread("SCI/modules/sound/demos/chimes.wav");
110             subplot(2,1,1)
111             plot2d(y(1,:))
112             subplot(2,1,2)
113             plot2d(y(2,:))
114             y=wavread("SCI/modules/sound/demos/chimes.wav",[1 5])
115         </scilab:image>
116
117     </refsection>
118     <refsection role="see also">
119         <title>See also</title>
120         <simplelist type="inline">
121             <member>
122                 <link linkend="auread">auread</link>
123             </member>
124             <member>
125                 <link linkend="savewave">savewave</link>
126             </member>
127             <member>
128                 <link linkend="analyze">analyze</link>
129             </member>
130             <member>
131                 <link linkend="mapsound">mapsound</link>
132             </member>
133         </simplelist>
134     </refsection>
135 </refentry>