====== Audio Files in the Questionnaire ======

**Important:** Read the advice in [[:en:create:media]] before this manual.

There are several file formats that are well suited for use on the internet. Usually, mp3 will be the format of choice, because most browsers can play this format without problems ([[https://developer.mozilla.org/en-US/docs/Web/Guide/Audio_and_video_delivery/Cross-browser_audio_basics#audio_codec_support|Mozilla: Browser Support]]).

**Note:** The solutions presented here play an audio file only within one questionnaire page. How this restriction can be bypassed is described in the chapter [[:en:create:frameset]].


===== Simple Embedding of an mp3 =====

If the audio file has been encoded in mp3 format and uploaded to the survey server, it can simply be dragged into the questionnaire like a text element (**Compose Questionnaire**). With the display settings {{:button.settings.png?nolink|Settings}}, you can make the playback start automatically.


===== Embedding of an mp3 using HTML5 =====

For embedding, create a new text element with the following content and the //display// "HTML code" under **Text Elements and Labels**:

<code html>
<audio id="audio_with_controls" preload="auto" autoplay controls controlsList="nodownload">
  <source src="audio.mp3" type="audio/mpeg" />
  Unfortunately, your browser cannot play this audio file
</audio>
</code>

The file name(s) are entered in the ''<source>'' tags; the options ''controls'' and ''autoplay'' in the ''<audio>'' tag ensure that controls are displayed to the respondent and that the playback starts automatically -- for further options, see [[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio|MDN: The Embed Audio element]].

The size of the player can be adjusted with CSS formatting.

<code html>
<audio id="audio02" controls  controlsList="nodownload" style="width: 200px; height: 80px">
  <source src="audio.mp3" type="audio/mpeg" />
</audio>
</code>

===== Simple Play Button =====

Positioning the player outside the visible area makes it disappear completely. You can then start the playback with your own button and a little JavaScript.

<code html>
<audio id="stimulus" src="audiofile.mp3" style="position: absolute; top: -9999px;">
  <source src="audio.mp3" type="audio/mpeg" />
</audio>

<div style="text-align: center;">
    <button id="playButton" type="button">▶</button>
</div>

<script>
let button = document.getElementById("playButton");
let audio = document.getElementById("stimulus");

button.addEventListener("click", function() {
    // Rewind automatically (optional)
    audio.currentTime = 0;
    // Start playback
    audio.play();
});
</script>
</code>


===== Audio without Visible Player =====

With the attribute ''autoplay'', you can ask the browser to start the playback automatically.

**Note:** Most mobile devices (smartphones, some tablets) and partly also the desktop version of Safari block the autoplay function for starting a media file (audio or video) automatically.

<code html>
<audio id="audio03" autoplay controlsList="nodownload" style="position: absolute; top: -9999px">
  <source src="audio.mp3" type="audio/mpeg" />
</audio>
</code>

For this case, you should provide a JavaScript that displays the controls after a short time if the media file does not start. For example:

<code html>
<audio id="audio04" preload controlsList="nodownload" autoplay>
  <source src="someAudio.mp3">
</audio>

<script type="text/javascript">
<!--
window.addEventListener("load", function() {
  window.setTimeout(function() {
    var audio = document.getElementById("audio04");
    if (audio.paused) {
      audio.setAttribute("controls", "yes");
    }
  }, 500);
});
// -->
</script>
</code>


===== Automatically Continue =====

JavaScript can also be used to further refine the control of the audio file. For example, you can use the JavaScript event ''ended'' to automatically forward to the next page after the audio file has been played.

<code html>
<audio id="audio05" preload controlsList="nodownload" autoplay>
  <source src="someAudio.mp3">
</audio>

<script type="text/javascript">
<!--
window.addEventListener("load", function() {
  window.setTimeout(function() {
    // Identify the audio element by its ID
    var audio = document.getElementById("audio05");
    // Show controls if the audio does not start automatically
    if (audio.paused) {
      audio.setAttribute("controls", "yes");
    }
    // Automatically continue to the next page after playback
    audio.addEventListener("ended", SoSciTools.submitPage);
  }, 500);
});
// -->
</script>
</code>

**Tip:** If the embedded audio does not play correctly, take a look at your [[:en:general:browser-tools|browser's error console]].



===== Notes on Listening Studies =====

Almost all current browsers support the mp3 format. Optionally, you can additionally upload the audio file in the format ogg and offer both variants to the browser. There are a number of free programs for converting audio files into the compressed formats, e.g., the open source audio editor [[https://tenacityaudio.org/|Tenacity]].

<code html>
<audio id="audio_with_controls" preload="auto" autoplay controls controlsList="nodownload">
  <source src="audio.mp3" type="audio/mpeg" />
  <source src="audio.ogg" type="audio/ogg" />
  Unfortunately, your browser cannot play this audio file
</audio>
</code>

If the audio stimulus is not only intended to convey music or speech, but also the finest nuances, then lossy mp3 compression can become a problem. It is not optimized for compressing the knocking of a woodpecker, for example.

However, lossless audio compression is not so trivial in the context of an online survey:

  * The uncompressed PCM format (WAV files) is not supported by the outdated Internet Explorer (which is nevertheless frequently used) ([[https://caniuse.com/?search=wav|Can I Use: WAV]]), but above all the format requires a lot of storage space. SoSci Survey therefore does not allow uploads of WAV files.
  * A lossless compressed alternative to the WAV format is FLAC ([[https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Audio_codecs|Mozilla: Audio Codecs]]). Here, too, Internet Explorer is left out and may need an additional alternative -- but at least the format does not waste unnecessary storage space and bandwidth for the respondents.
  * A third option is mp3 files that are compressed at a very high quality (e.g., 320kbps). These are played by all browsers, and with a high bit rate, far fewer aspects of the audio signal are removed than with the standard compression at 128kbps.

Please note that there are further limits to authentic reproduction in online surveys. As a rule, the work computer is not a recording studio.

  * Some respondents cannot hear any audio signal at all, e.g., because they are in an open-plan office or because no speakers or headphones are connected to the computer.
  * Other respondents can only hear the audio with relevant background noise, for example on public transport. And even at home, undisturbed listening is often not guaranteed: Family members are present, the neighbor is mowing the lawn, or the parcel carrier is ringing...
  * Most respondents will only have poor audio hardware at home that cannot reproduce low tones and does not deliver a flat frequency response.
  * If Bluetooth headphones are used, the signal between the computer and the headphones is potentially compressed again with a loss.