Updated the 2.3 and 2.2 audio recording tutorial.

Also added a section about selection of the input device. French translation by mantognini.

tutorials/2.2/audio-recording-fr.php

@@ -18,14 +18,14 @@
     Ce type de capture peut être effectué via l'interface très simple de la classe <?php class_link("SoundBufferRecorder") ?> :
 </p>
 <pre><code class="cpp">// tout d'abord on vérifie si la capture est supportée par le système
-if (!SoundBufferRecorder::isAvailable())
+if (!sf::SoundBufferRecorder::isAvailable())
 {
     // erreur : la capture audio n'est pas supportée
     ...
 }
 
 // création de l'enregistreur
-SoundBufferRecorder recorder;
+sf::SoundBufferRecorder recorder;
 
 // démarrage de l'enregistrement
 recorder.start();
@@ -64,7 +64,7 @@
         Accéder aux données brutes et les analyser, transformer, etc.
 <pre><code class="cpp">const sf::Int16* samples = buffer.getSamples();
 std::size_t count = buffer.getSampleCount();
-doSomething(samples, count);    
+doSomething(samples, count);
 </code></pre>
     </li>
 </ul>
@@ -73,6 +73,41 @@
     du buffer.
 </p>
 
+<?php h2('Sélectionner le périphérique d\'entrée') ?>
+<p>
+    Si vous avez plusieurs périphériques d'entrées audio connectés à votre ordinateur (par exemple un microphone, une carte son externe ou
+    encore une webcam dotée d'un micro), vous pouvez spécifier le périphérique utilisé pour l'enregistrement. Un périphérique d'entrée audio
+    est identifié par son nom. <code>std::vector&lt;std::string&gt;</code> contenant le nom de tous les périphériques connectés est disponible
+    via à la fonction statique <code>SoundBufferRecorder::getAvailableDevices()</code>. Vous pouvez sélectionner un périphérique de la liste
+    pour l'enregistrement en passant le nom du périphérique désiré à la fonction membre <code>setDevice()</code>. Il est même possible de
+    changer de périphérique à la volée (i.e. pendant l'enregistrement).
+</p>
+<p>
+    Le nom du périphérique actuellement utilisé peut être obtenu en appelant <code>getDevice()</code>. Si vous ne choisissez pas de périphérique
+    explicitement vous-même, celui par défaut sera utilisé. Son nom peut être obtenu grace à la fonction statique <code>SoundBufferRecorder::getDefaultDevice()</code>.
+</p>
+<p>
+    Voici un petit exemple illustrant comment sélectionner un périphérique d'entrée audio :
+</p>
+<pre><code class="cpp">// récupération des noms des périphériques d'enregistrement
+std::vector&lt;std::string&gt; availableDevices = sf::SoundRecorder::getAvailableDevices();
+
+// choix d'un périphérique
+std::string inputDevice = availableDevices[0];
+
+// création d'un enregistreur
+sf::SoundBufferRecorder recorder;
+
+// sélection du périphérique
+if (!recorder.setDevice(inputDevice))
+{
+    // erreur: sélection du périphérique ratée
+    ...
+}
+
+// utilisation habituelle de l'enregistreur
+</code></pre>
+
 <?php h2('Enregistrement personnalisé') ?>
 <p>
     Si stocker les données enregistrées dans un buffer audio n'est pas ce que vous voulez, vous pouvez tout aussi bien écrire votre propre enregistreur.
@@ -88,9 +123,11 @@
     Vous n'avez qu'une fonction virtuelle à redéfinir dans votre classe dérivée : <code>onProcessSamples</code>. Elle est appelée à chaque fois qu'un
     nouveau lot d'échantillons audio ont été capturés, c'est donc là que vous devez implémenter votre traitement perso.
 </p>
-<p class="important">
-    Des échantillons audio sont passés à la fonction <code>onProcessSamples</code> toutes les 100 ms. Cette valeur est fixée dans le code de SFML et
-    vous ne pouvez pas la changer (à moins de modifier SFML directement). Ceci sera probablement amélioré dans une prochaine version.
+<p>
+    Par défaut, les échantillons audio sont fournis à la fonction membre <code>onProcessSamples</code> toutes les 100 ms. Vous pouvez changer
+    l'intervalle en utilisant la fonction membre <code>setProcessingInterval</code>. Vous souhaiterez probablement utiliser un intervalle plus
+    petit si vous voulez manipuler les données enregistrées en temps réel, par exemple. Notez que ceci n'est qu'un indice et qu'il se peut que
+    l'intervalle utilisé en pratique varie, donc ne vous y fiez pas pour implémenter un timing précis.
 </p>
 <p>
     Il existe deux autres fonctions virtuelles que vous pouvez redéfinir si vous le souhaitez : <code>onStart</code> et <code>onStop</code>. Elles sont
@@ -110,7 +147,7 @@
         return true;
     }
 
-    virtual bool onProcessSamples(const Int16* samples, std::size_t sampleCount)
+    virtual bool onProcessSamples(const sf::Int16* samples, std::size_t sampleCount)
     {
         // faites ce que vous voulez des échantillons audio
         ...

tutorials/2.2/audio-recording.php

@@ -18,14 +18,14 @@
     This can be achieved with the very simple interface of the <?php class_link("SoundBufferRecorder") ?> class:
 </p>
 <pre><code class="cpp">// first check if an input audio device is available on the system
-if (!SoundBufferRecorder::isAvailable())
+if (!sf::SoundBufferRecorder::isAvailable())
 {
     // error: audio capture is not available on this system
     ...
 }
 
 // create the recorder
-SoundBufferRecorder recorder;
+sf::SoundBufferRecorder recorder;
 
 // start the capture
 recorder.start();
@@ -64,14 +64,48 @@
         Access the raw audio data and analyze it, transform it, etc.
 <pre><code class="cpp">const sf::Int16* samples = buffer.getSamples();
 std::size_t count = buffer.getSampleCount();
-doSomething(samples, count);    
+doSomething(samples, count);
 </code></pre>
     </li>
 </ul>
 <p class="important">
     If you want to use the captured audio data after the recorder is destroyed or restarted, don't forget to make a <em>copy</em> of the buffer.
 </p>
 
+<?php h2('Selecting the input device') ?>
+<p>
+    If you have multiple sound input devices connected to your computer (for example a microphone, a sound interface (external soundcard) or a
+    webcam microphone) you can specify the device that is used for recording. A sound input device is identified by its name.
+    A <code>std::vector&lt;std::string&gt;</code> containing the names of all connected devices is available through the static
+    <code>SoundBufferRecorder::getAvailableDevices()</code> function. You can then select a device from the list for recording, by passing the
+    chosen device name to the <code>setDevice()</code> method. It is even possible to change the device on the fly (i.e. while recording).
+</p>
+<p>
+    The name of the currently used device can be obtained by calling <code>getDevice()</code>. If you don't choose a device yourself, the default
+    device will be used. Its name can be obtained through the static <code>SoundBufferRecorder::getDefaultDevice()</code> function.
+</p>
+<p>
+    Here is a small example of how to set the input device:
+</p>
+<pre><code class="cpp">// get the available sound input device names
+std::vector&lt;std::string&gt; availableDevices = sf::SoundRecorder::getAvailableDevices();
+
+// choose a device
+std::string inputDevice = availableDevices[0];
+
+// create the recorder
+sf::SoundBufferRecorder recorder;
+
+// set the device
+if (!recorder.setDevice(inputDevice))
+{
+    // error: device selection failed
+    ...
+}
+
+// use recorder as usual
+</code></pre>
+
 <?php h2('Custom recording') ?>
 <p>
     If storing the captured data in a sound buffer is not what you want, you can write your own recorder. Doing so will allow you to process the
@@ -86,9 +120,10 @@
     You only have a single virtual function to override in your derived class: <code>onProcessSamples</code>. It is called every time a new chunk
     of audio samples is captured, so this is where you implement your specific stuff.
 </p>
-<p class="important">
-    Audio samples are provided to the <code>onProcessSamples</code> function every 100 ms. This is currently hard-coded into SFML and you can't change
-    that (unless you modify SFML itself). This may change in the future.
+<p>
+    By default Audio samples are provided to the <code>onProcessSamples</code> method every 100 ms. You can change the interval by using the
+    <code>setProcessingInterval</code> method. You may want to use a smaller interval if you want to process the recorded data in real time, for example.
+    Note that this is only a hint and that the actual period may vary, so don't rely on it to implement precise timing.
 </p>
 <p>
     There are also two additional virtual functions that you can optionally override: <code>onStart</code> and <code>onStop</code>. They are
@@ -108,7 +143,7 @@
         return true;
     }
 
-    virtual bool onProcessSamples(const Int16* samples, std::size_t sampleCount)
+    virtual bool onProcessSamples(const sf::Int16* samples, std::size_t sampleCount)
     {
         // do something useful with the new chunk of samples
         ...

tutorials/2.3/audio-recording-fr.php

@@ -18,14 +18,14 @@
     Ce type de capture peut être effectué via l'interface très simple de la classe <?php class_link("SoundBufferRecorder") ?> :
 </p>
 <pre><code class="cpp">// tout d'abord on vérifie si la capture est supportée par le système
-if (!SoundBufferRecorder::isAvailable())
+if (!sf::SoundBufferRecorder::isAvailable())
 {
     // erreur : la capture audio n'est pas supportée
     ...
 }
 
 // création de l'enregistreur
-SoundBufferRecorder recorder;
+sf::SoundBufferRecorder recorder;
 
 // démarrage de l'enregistrement
 recorder.start();
@@ -64,7 +64,7 @@
         Accéder aux données brutes et les analyser, transformer, etc.
 <pre><code class="cpp">const sf::Int16* samples = buffer.getSamples();
 std::size_t count = buffer.getSampleCount();
-doSomething(samples, count);    
+doSomething(samples, count);
 </code></pre>
     </li>
 </ul>
@@ -73,6 +73,41 @@
     du buffer.
 </p>
 
+<?php h2('Sélectionner le périphérique d\'entrée') ?>
+<p>
+    Si vous avez plusieurs périphériques d'entrées audio connectés à votre ordinateur (par exemple un microphone, une carte son externe ou
+    encore une webcam dotée d'un micro), vous pouvez spécifier le périphérique utilisé pour l'enregistrement. Un périphérique d'entrée audio
+    est identifié par son nom. <code>std::vector&lt;std::string&gt;</code> contenant le nom de tous les périphériques connectés est disponible
+    via à la fonction statique <code>SoundBufferRecorder::getAvailableDevices()</code>. Vous pouvez sélectionner un périphérique de la liste
+    pour l'enregistrement en passant le nom du périphérique désiré à la fonction membre <code>setDevice()</code>. Il est même possible de
+    changer de périphérique à la volée (i.e. pendant l'enregistrement).
+</p>
+<p>
+    Le nom du périphérique actuellement utilisé peut être obtenu en appelant <code>getDevice()</code>. Si vous ne choisissez pas de périphérique
+    explicitement vous-même, celui par défaut sera utilisé. Son nom peut être obtenu grace à la fonction statique <code>SoundBufferRecorder::getDefaultDevice()</code>.
+</p>
+<p>
+    Voici un petit exemple illustrant comment sélectionner un périphérique d'entrée audio :
+</p>
+<pre><code class="cpp">// récupération des noms des périphériques d'enregistrement
+std::vector&lt;std::string&gt; availableDevices = sf::SoundRecorder::getAvailableDevices();
+
+// choix d'un périphérique
+std::string inputDevice = availableDevices[0];
+
+// création d'un enregistreur
+sf::SoundBufferRecorder recorder;
+
+// sélection du périphérique
+if (!recorder.setDevice(inputDevice))
+{
+    // erreur: sélection du périphérique ratée
+    ...
+}
+
+// utilisation habituelle de l'enregistreur
+</code></pre>
+
 <?php h2('Enregistrement personnalisé') ?>
 <p>
     Si stocker les données enregistrées dans un buffer audio n'est pas ce que vous voulez, vous pouvez tout aussi bien écrire votre propre enregistreur.
@@ -88,9 +123,11 @@
     Vous n'avez qu'une fonction virtuelle à redéfinir dans votre classe dérivée : <code>onProcessSamples</code>. Elle est appelée à chaque fois qu'un
     nouveau lot d'échantillons audio ont été capturés, c'est donc là que vous devez implémenter votre traitement perso.
 </p>
-<p class="important">
-    Des échantillons audio sont passés à la fonction <code>onProcessSamples</code> toutes les 100 ms. Cette valeur est fixée dans le code de SFML et
-    vous ne pouvez pas la changer (à moins de modifier SFML directement). Ceci sera probablement amélioré dans une prochaine version.
+<p>
+    Par défaut, les échantillons audio sont fournis à la fonction membre <code>onProcessSamples</code> toutes les 100 ms. Vous pouvez changer
+    l'intervalle en utilisant la fonction membre <code>setProcessingInterval</code>. Vous souhaiterez probablement utiliser un intervalle plus
+    petit si vous voulez manipuler les données enregistrées en temps réel, par exemple. Notez que ceci n'est qu'un indice et qu'il se peut que
+    l'intervalle utilisé en pratique varie, donc ne vous y fiez pas pour implémenter un timing précis.
 </p>
 <p>
     Il existe deux autres fonctions virtuelles que vous pouvez redéfinir si vous le souhaitez : <code>onStart</code> et <code>onStop</code>. Elles sont
@@ -110,7 +147,7 @@
         return true;
     }
 
-    virtual bool onProcessSamples(const Int16* samples, std::size_t sampleCount)
+    virtual bool onProcessSamples(const sf::Int16* samples, std::size_t sampleCount)
     {
         // faites ce que vous voulez des échantillons audio
         ...

tutorials/2.3/audio-recording.php

@@ -18,14 +18,14 @@
     This can be achieved with the very simple interface of the <?php class_link("SoundBufferRecorder") ?> class:
 </p>
 <pre><code class="cpp">// first check if an input audio device is available on the system
-if (!SoundBufferRecorder::isAvailable())
+if (!sf::SoundBufferRecorder::isAvailable())
 {
     // error: audio capture is not available on this system
     ...
 }
 
 // create the recorder
-SoundBufferRecorder recorder;
+sf::SoundBufferRecorder recorder;
 
 // start the capture
 recorder.start();
@@ -64,14 +64,48 @@
         Access the raw audio data and analyze it, transform it, etc.
 <pre><code class="cpp">const sf::Int16* samples = buffer.getSamples();
 std::size_t count = buffer.getSampleCount();
-doSomething(samples, count);    
+doSomething(samples, count);
 </code></pre>
     </li>
 </ul>
 <p class="important">
     If you want to use the captured audio data after the recorder is destroyed or restarted, don't forget to make a <em>copy</em> of the buffer.
 </p>
 
+<?php h2('Selecting the input device') ?>
+<p>
+    If you have multiple sound input devices connected to your computer (for example a microphone, a sound interface (external soundcard) or a
+    webcam microphone) you can specify the device that is used for recording. A sound input device is identified by its name.
+    A <code>std::vector&lt;std::string&gt;</code> containing the names of all connected devices is available through the static
+    <code>SoundBufferRecorder::getAvailableDevices()</code> function. You can then select a device from the list for recording, by passing the
+    chosen device name to the <code>setDevice()</code> method. It is even possible to change the device on the fly (i.e. while recording).
+</p>
+<p>
+    The name of the currently used device can be obtained by calling <code>getDevice()</code>. If you don't choose a device yourself, the default
+    device will be used. Its name can be obtained through the static <code>SoundBufferRecorder::getDefaultDevice()</code> function.
+</p>
+<p>
+    Here is a small example of how to set the input device:
+</p>
+<pre><code class="cpp">// get the available sound input device names
+std::vector&lt;std::string&gt; availableDevices = sf::SoundRecorder::getAvailableDevices();
+
+// choose a device
+std::string inputDevice = availableDevices[0];
+
+// create the recorder
+sf::SoundBufferRecorder recorder;
+
+// set the device
+if (!recorder.setDevice(inputDevice))
+{
+    // error: device selection failed
+    ...
+}
+
+// use recorder as usual
+</code></pre>
+
 <?php h2('Custom recording') ?>
 <p>
     If storing the captured data in a sound buffer is not what you want, you can write your own recorder. Doing so will allow you to process the
@@ -86,9 +120,10 @@
     You only have a single virtual function to override in your derived class: <code>onProcessSamples</code>. It is called every time a new chunk
     of audio samples is captured, so this is where you implement your specific stuff.
 </p>
-<p class="important">
-    Audio samples are provided to the <code>onProcessSamples</code> function every 100 ms. This is currently hard-coded into SFML and you can't change
-    that (unless you modify SFML itself). This may change in the future.
+<p>
+    By default Audio samples are provided to the <code>onProcessSamples</code> method every 100 ms. You can change the interval by using the
+    <code>setProcessingInterval</code> method. You may want to use a smaller interval if you want to process the recorded data in real time, for example.
+    Note that this is only a hint and that the actual period may vary, so don't rely on it to implement precise timing.
 </p>
 <p>
     There are also two additional virtual functions that you can optionally override: <code>onStart</code> and <code>onStop</code>. They are
@@ -108,7 +143,7 @@
         return true;
     }
 
-    virtual bool onProcessSamples(const Int16* samples, std::size_t sampleCount)
+    virtual bool onProcessSamples(const sf::Int16* samples, std::size_t sampleCount)
     {
         // do something useful with the new chunk of samples
         ...