* Bug 16365 fixed: median(m,'r'|'c') was wrong after 5dc990
[scilab.git] / scilab / modules / sound / help / en_US / playsnd.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) ????-2006 - INRIA - Scilab
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2019 - Samuel GOUGEON
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"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
18           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
19           xml:lang="en" xml:id="playsnd">
20     <refnamediv>
21         <refname>playsnd</refname>
22         <refpurpose>command-line sound player facility</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             playsnd(filename)
28             playsnd(filename, speed)
29             playsnd(filename, speed, nbiter)
30             playsnd(filename, speed, nbiter, playerCmd)
31             playsnd(filename, speed, playerCmd)
32
33             playsnd(y)
34             playsnd(y, rate)
35             playsnd(y, rate, nbiter)
36             playsnd(y, rate, nbiter, playerCmd)
37             playsnd(y, rate, playerCmd)
38
39             playsnd([])
40         </synopsis>
41     </refsynopsisdiv>
42     <refsection>
43         <title>Arguments</title>
44         <variablelist>
45             <varlistentry>
46                 <term>filename</term>
47                 <listitem>
48                     single string: the path and name of the sound file to play.
49                     <para/>
50                 </listitem>
51             </varlistentry>
52             <varlistentry>
53                 <term>speed</term>
54                 <listitem>
55                     real positive number: relative playing speed.
56                     <varname>speed</varname> &lt; 1 plays slower,
57                     while <varname>speed</varname> > 1 plays faster. (1.0 by default).
58                     <para/>
59                 </listitem>
60             </varlistentry>
61             <varlistentry>
62                 <term>y</term>
63                 <listitem>
64                     matrix of normalized linear sound data, in [-1,1]. Each row feeds a channel.
65                     <para/>
66                 </listitem>
67             </varlistentry>
68             <varlistentry>
69                 <term>rate</term>
70                 <listitem>
71                     real positive number: sampling frequency in Hz (default value is 22050).
72                     <para/>
73                 </listitem>
74             </varlistentry>
75             <varlistentry>
76                 <term>nb_iter</term>
77                 <listitem>
78                     positive decimal integer: number of consecutive times (iterations) that
79                     the sound must be played.
80                     <para/>
81                 </listitem>
82             </varlistentry>
83             <varlistentry>
84                 <term>playerCmd</term>
85                 <listitem>
86                     Only used on Unix and MacOS systems. Single string giving the OS command
87                     to use for playing sound (wav) files. The default value is
88                     <literal>"aplay"</literal> on Linux and <literal>"afplay"</literal> on MacOS.
89                     <para/>
90                     If <varname>playerCmd</varname> is set to <literal>/dev/audio</literal>,
91                     then a 8 bits mu-law raw sound file is created and send to
92                     <literal>/dev/audio</literal>.
93                     <para/>
94                 </listitem>
95             </varlistentry>
96         </variablelist>
97     </refsection>
98     <refsection>
99         <title>Description</title>
100         <para>
101             <emphasis role="bold">playsnd(filename,..)</emphasis> or
102             <emphasis role="bold">playsnd(y,..)</emphasis>
103             cancels any running sound and then starts playing a single or multi channel signal.
104         </para>
105         <para>
106             When <varname>nb_iter</varname> is not used, the sound is played only once, and
107             <literal>playsnd(…)</literal> behaves in a non-modal way: Scilab returns to the prompt
108             or to the next instruction just after starting playing, without waiting for the end of
109             the sound.
110         </para>
111         <para>
112             Otherwise, the sound is played <varname>nb_iter</varname> consecutive times,
113             and <literal>playsnd(…)</literal> becomes modal (even for
114             <varname>nb_iter</varname>=1): Scilab returns to the prompt
115             or to the next instruction only after the end of the last time the sound is played.
116             <note>
117                 The repetition is interruptible with CTRL-C or any <literal>pause</literal> or
118                 <literal>abort</literal> callback instruction.
119             </note>
120         </para>
121         <para>
122             <emphasis role="bold">playsnd([])</emphasis> cancels any sound running without
123             <varname>nb_iter</varname> and not through /dev/audio.
124         </para>
125     </refsection>
126     <refsection>
127         <title>Examples</title>
128         <para>
129             Playing a sound from its audio file:
130         </para>
131         <programlisting role="example"><![CDATA[
132 // A two channel signal
133 File = "SCI/modules/sound/demos/chimes.wav";
134 playsnd(File)           // Play it once at normal speed
135 sleep(5)
136 playsnd(File, 2)        // Play it once at speed x 2
137 sleep(5)
138 playsnd(File,, 3)       // Play it 3 times at normal speed
139 sleep(5)
140 playsnd(File, 1.5, 3)   // Play it 3 times at speed x 1.5
141 sleep(5)
142 playsnd(File, 0.2)      // Play it once and slowly.
143                         // Note that Scilab returns as soon as the player starts.
144 // Plays a longer sound. Interrupts it 1.0 s after it started:
145 playsnd(File, 0.2), sleep(1,'s'), playsnd([])
146  ]]></programlisting>
147         <para/>
148         <para>
149             Playing a sound from its data in a matrix:
150         </para>
151         <programlisting role="example"><![CDATA[
152 y = loadwave("SCI/modules/sound/demos/chimes.wav");
153 playsnd(y)              // Play it once at the default 22050 Hz sampling rate
154 sleep(5)
155 playsnd(y, 3e4)         // Play it once at 30 kHz sampling rate
156 sleep(5)
157 playsnd(y,, 3)          // Play it 3 times at the default sampling rate
158 sleep(5)
159 playsnd(y, 44100, 3)    // Play it 3 times at 44.1 kHZ sampling rate
160  ]]></programlisting>
161         <para/>
162         <para>
163             Interrupting  with CTRL + C a repeated sound:
164         </para>
165         <programlisting role="example"><![CDATA[
166 playsnd("SCI/modules/sound/demos/chimes.wav",, 20);
167 // Now enter CTRL-C to interrupt the repetition
168 // Then type "resume" or "abort"
169  ]]></programlisting>
170     </refsection>
171     <refsection role="see also">
172         <title>See also</title>
173         <simplelist type="inline">
174             <member>
175                 <link linkend="beep">beep</link>
176             </member>
177             <member>
178                 <link linkend="realtime">realtime</link>
179             </member>
180             <member>
181                 <link linkend="lin2mu">lin2mu</link>
182             </member>
183             <member>
184                 <link linkend="wavread">wavread</link>
185             </member>
186             <member>
187                 <link linkend="auread">auread</link>
188             </member>
189             <member>
190                 <link linkend="mcisendstring">mcisendstring</link>
191             </member>
192             <member>
193                 <link linkend="winopen">winopen</link>
194             </member>
195         </simplelist>
196     </refsection>
197     <refsection role="history">
198         <title>History</title>
199         <revhistory>
200             <revision>
201                 <revnumber>6.1.0</revnumber>
202                 <revdescription>
203                     <itemizedlist>
204                         <listitem>
205                             playsnd(filename,..) can now be used. The relative speed wrt the native
206                             one in the file can be specified.
207                         </listitem>
208                         <listitem>
209                             nb_iter option introduced.
210                         </listitem>
211                         <listitem>
212                             playsnd([]) is introduced to stop a sound run without repetition.
213                         </listitem>
214                         <listitem>
215                             playsnd(…) is now by default not-modal on Linux and MacOS, like on Windows.
216                         </listitem>
217                         <listitem>
218                             playsnd(…) can now be modal on any OS, through any explicit nb_iter value.
219                         </listitem>
220                         <listitem>
221                             Input argument bits removed.
222                         </listitem>
223                     </itemizedlist>
224                 </revdescription>
225             </revision>
226         </revhistory>
227     </refsection>
228 </refentry>