====== Play Music Across Several Pages ======

SoSci Survey offers the possibility to present music or a video across an entire questionnaire by using a frameset. One challenge is that modern browsers do not simply play music automatically -- so a little JavaScript is required, and the music can start at the earliest when the first page is submitted.

**Note:** Assume that respondents have turned off their speakers, need to put on headphones first, or have their smartphone on mute. Point out the audio output at an early stage and offer an opportunity to test the audio output in the questionnaire.


===== Define a Frameset =====

The first step is to create a frameset. What exactly a frameset is can be read here: [[http://wiki.selfhtml.org/wiki/HTML/Frames|SelfHTML: Frames]]. Roughly speaking, a frameset is a kind of table that divides the displayed website into separate areas whose contents can be handled individually.

To create a frameset in SoSci Survey, first create a text file on your desktop. Name this text file, e.g., "start.html".

**Important:** It is essential that the file is saved as plain ASCII text. Therefore, use a text editor to create/edit the file (e.g. [[https://notepad-plus-plus.org/|Notepad++]], [[http://www.scintilla.org/SciTE.html|SciTE]] or the Windows Notepad) and __no__ word processor such as Word or OpenOffice.

**Important:** Make sure that the file extension is changed accordingly, so that the former text file becomes an HTML file. You can download the contents of this file directly.

<file html start.html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">
<html>
  <head>
	<meta http-equiv="content-type" content="text/html; charset=utf-8">
	<title>Questionnaire</title>
  </head>
  <frameset rows="99%, 1%" border="0">
	<frame src="./index.php" name="survey">
	<frame src="./music.html" name="music">
  </frameset>
</html>
</file>


===== Content for the Frameset =====

The frameset refers once to the questionnaire (''index.php'') and once to a file ''music.html''. You will need this file as well.

<file html music.html>
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Audio</title>
    <script>
    window.addEventListener("message",
        function(evt) {
            var audio = document.getElementById("bgAudio");
            var data = evt.data;
            if ("source" in data) {
                audio.src = data.source;
            }
            if (data.action === "play") {
                audio.play();
            }
            if (data.action === "stop") {
                audio.stop();
            }
        },
        false
    );
    </script>
</head>
<body>
    <audio id="bgAudio" preload loop style="position: absolute; left: -9999px; top: -9999px">
        <source src="stimulus.mp3">
    </audio>
</body>
</html>
</file>

This file contains an ''<audio>'' element and remains open the entire time. At the end of the file, you will find the following line. Replace ''stimulus.mp3'' with the file name of your music file.

<code html>
<source src="stimulus.mp3">
</code>


===== Preparing the Questionnaire =====

If you use a redirect in the questionnaire, place the following PHP code on the first page of the questionnaire.

<code php>
option('frameset', true);
</code>

This tells SoSci Survey that the questionnaire is displayed within a frameset.


===== Using Content in the Questionnaire =====

In SoSci Survey, open **Images and Media Files** and there the tab "Media Files".

Upload (1) the two HTML files from above and (2) the mp3 music file(s) you want to use in your questionnaire.

For the playback to work, you must __not__ use the "protected file storage" when uploading.

In addition, you must (3) insert a little JavaScript code under **Compose Questionnaire**. Drag an "HTML code" element onto the questionnaire page before the music shall start and insert the following content there.

<code html>
<script>
function messageToMusic(msg) {
    var id = "music";
    if (parent.frames && parent.frames[id]) {
        var musicFrame = parent.frames[id];
    } else {
        return;
    }
    musicFrame.postMessage(msg);
}

SoSciTools.questionnaire.attachCheck(function() {
    messageToMusic({
        source: "Musik02.mp3",
        action: "play"
    });
    return true;
});
</script>
</code>

This JavaScript code does the following: When the respondent clicks the "Next" button (''SoSciTools.questionnaire.attachCheck()''), a message is sent to the window with the music file. This message is processed by the JavaScript in ''music.html'' and starts playing the music.

Note the following lines at the end of the code.

<code javascript>
messageToMusic({
    source: "Musik02.mp3",
    action: "play"
});
</code>

The ''source'' entry can (optionally) be used to load a different audio file. This entry can be omitted if you do not need to vary the audio file.

<code javascript>
messageToMusic({
    action: "play"
});
</code>

If you vary the audio file experimentally, you can also use a [[:en:create:placeholders|placeholder]] here. For more information, see [[:en:create:randomization-media#randomization_images_via_placeholders|Randomization of images using placeholders]].

<code javascript>
messageToMusic({
    source: "%filename%",
    action: "play"
});
</code>

Use the ''action'' entry to specify whether playback shall start (''play'') or stop (''stop'').


===== Start the Survey Period =====

For the link to work, make sure in the **Project Settings** that the questionnaire is accessible online.

Alternatively, you can enter a pretest link in the file ''start.html'' by adapting the following line:

<code html>
<frame src="./index.php" name="survey">
</code>

Replace ''./index.php'' with the pretest link if you cannot or do not want to put the questionnaire online regularly yet. Do not forget to upload the modified file and to change the file again when the data collection starts.


===== Accessing the Questionnaire =====

To load the frameset with its two components (questionnaire and file with the ''<audio>'' element), do not use the "normal" link to the questionnaire

    https://www.soscisurvey.de/PROJECT/

but add ''start.html'' at the end, i.e.

    https://www.soscisurvey.de/PROJECT/start.html

Instead of ''PROJECT'', you must of course use the project directory of your survey project ([[:en:survey:url]]). You can now enter this link in the address bar of the browser to test the background music. Later, you will also send this extended link to the addressees of your study.

**Important:** Do __not__ add ''start.html'' in SoSci Survey, but simply enter it in the address bar of your browser.

If the file does not play, open the [[:en:general:browser-tools]] after calling ''start.html'' and check whether error messages are displayed there.


===== Limitations =====

  * When calling the frameset, you cannot transmit any variables (e.g. reference or participation code) to the questionnaire, as described under [[:en:survey:url]].
  * With this solution, fading out the music at the end is only possible with additional effort. Otherwise, playback ends abruptly when the ''stop'' message is sent.