Audio element

description

Creates an audio player.

syntax

newAudio(ELEMENT_NAME: string, URL: string)
  • ELEMENT_NAME: The name of the newly-created element.
  • URL : The URL of the audio file.

note(s)

since

beta 0.3

example(s)

+ As of June 2019, **some browsers prevent multimedia content from automatically playing** before the user has interacted with the page. If automatic audio playback is important in your experiment, you should precede it with some sort of participant-page interaction, in order to make sure that automatic playback actually occurs. Clicking a `Button` or pressing a `Key` are examples of participant-page interaction. + By default, PennController preloads all resources, meaning that an experiment does not start until the audio stream is stored in the browser’s cache. + Currently, the MP3 format is the only audio format supported across Internet Explorer, Chrome, Firefox, Safari, and Opera. You may use WAV and OGG files in your experiment, but be aware that some browsers do not support these formats. For more information on web browser support, see [Audio Format and Browser Support](https://www.w3schools.com/tags/tag_audio.asp){:target="_blank"}. ```javascript newAudio(row.audio).play().wait() ```

Action commands

audio.disable

syntax

.disable()

description

Will disable the controls interface. Note that some browsers might be render disabled interfaces as a plain gray rectangle with no controls visible whatsoever.

example

click to expand 

@newAudio("test.mp3")
@  .print()
$  .disable()
@  .play()
@  .wait()
  • Prints a disabled interface for the audio test.mp3 and starts playing it.
↑ back to top

audio.log

syntax

.log()

description

Will log the time/results of the action to your results file.

example

click to expand 

@newText("instructions", "Please listen to the audio below")
@    .print()
@,
@newAudio("sentence", "test_sentence.ogg")
@    .once()
$    .log()
@    .print()
@    .wait()
@,
@newButton("validation", "Validate")
@    .print()
@    .wait()

  • Adds some instruction text to the screen and control buttons below the text. After the audio gets played, the control buttons are grayed out, and a Validate button appears below them.

  • The results file will contain as many lines for when the audio was played, paused, when it ended playing and when its position was changed by clicking the progress bar.

↑ back to top

audio.once

syntax

.once()

description

Disables the buttons to play/pause the audio right after its first playing (the audio can still be played using the action play).

example

click to expand 

@newText("instructions", "Please listen to the audio below")
@    .print()
@,
@newAudio("sentence", "test.mp3")
$    .once()
@    .print()
@    .wait()
@,
@newButton("validation", "Validate")
@    .print()
@    .wait()
  • Adds some instruction text to the screen and control buttons below the text. After the audio gets played, the control buttons are grayed out, and a Validate button appears below them.
↑ back to top

audio.pause

syntax

.pause()

description

Pauses the audio file.

example

click to expand 

@newAudio("sentence", "test.mp3")
@    .play()
@,
@newTimer("preview", 750)
@    .start()
@    .wait()
@,
@getAudio("sentence")
$    .pause()
@    .print()
@    .wait()
  • Starts playing the file test.mp3, pauses it after 750ms, and shows controls on the screen making it possible to resume playback.
↑ back to top

audio.play

syntax

.play()

description

Starts playing the audio file.

example

click to expand 

@newAudio("test", "test.mp3")
$    .play()
@    .wait()
  • Starts playing the file test.mp3 (nothing is added onto the screen).
↑ back to top

audio.print

syntax

.print()

description

Adds the <audio> element to the screen, containing buttons to control playback and volume.

example

click to expand 

@newAudio("test", "test.mp3")
$    .print()
@    .wait()
  • Adds an interface with buttons to start/stop playing the audio file test.mp3 onto the screen.
↑ back to top

audio.remove

syntax

.remove()

description

Removes the <audio> element from the screen, which contained buttons to control playback and volume.

example

click to expand 

@newAudio("beep", "test.mp3")
@    .print()
@    .wait()
@,
@getAudio("beep")
@    .remove()
  • Adds an interface to start/stop playing the audio file test.mp3 onto the screen, and removes it from the screen after the audio has been fully played.
↑ back to top

audio.stop

syntax

.stop()

description

Stops the playback of the audio and goes back to the start of it, making it impossible to resume from the current position later.

example

click to expand 

@newAudio("sentence", "test.mp3")
@    .play()
@,
@newTimer("preview", 750)
@    .start()
@    .wait()
@,
@getAudio("sentence")
@    .stop()
  • Starts playing the file test.mp3 and stops it after 750ms. Calling play later on would not resume playback from there, but start all over from the beginning.
↑ back to top

audio.wait

syntax

.wait()

description

It waits until the previous command or command specified is executed or the specified time runs out before moving onto the next command.

example

click to expand 

@newAudio("sentence", "test.mp3")
@    .play()
@,
@newButton("validation", "Validate")
@    .print()
$    .wait()
@,
@getAudio("sentence")
$    .wait("first")
@,
@newText("thanks", "Thank you for listening")
@    .print()
  • Starts playing the file test.mp3 and adds a button onto the screen. If the button is clicked before the audio is done playing for the first time, it waits until the end before printing the text Thank you for listening.
↑ back to top

Test commands

audio.test.hasPlayed

syntax

.test.hasPlayed()

description

Tests whether the audio stream has played at least once before in the trial.

example

click to expand 

@newAudio("test.mp3")
@  .print()
@  .play()
@  .test.hasPlayed()
@  .log()
  • Checks whether the audio was played at least once. In this case it would return the result as correct.
  • Note that you can use this command as a conditional to the other functions.
↑ back to top

audio.test.playing

syntax

.test.playing()

description

Tests whether the audio stream is playing at the moment when the test command gets evaluated.

example

click to expand 

@newAudio("test.mp3")
@  .print()
@  .play()
@  .test.playing()
@  .log()
  • Checks whether the audio is playing at the moment of the execution of the command. In this case it would return the result as correct.
  • Note that you can use this command as a conditional to the other functions.
↑ back to top

Table of contents