Page History: Wave Player Element
Compare Page Revisions
Page Revision: 2012/05/21 12:32
|
Wave Player Element
|
| Info |
| Category: |
Auditory stimuli |
|
AddIn: |
Base Elements |
| Creator: |
OkazoLab Team |
|
Scope: |
Parent Event |
| Owns Snippets: |
On Triggered |
|
Usage: |
Design-time,Runtime,Snippets |
Wave Player element is capable of playing audio clips in the Waveform Audio File Format (WAV) with high temporal accuracy.
Description
Wave Player is a default element in EventIDE for delivering audio stimuli recorded in the Wave format. The element is recommended for modern sound cards on Vista and Windows 7 OS system, when high temporal accuracy of audio playback is required. For Windows XP and old sound cards the Direct Sound element may produce better results.
The Wave Player element allows to choose one of four audio playback API: DirectSound, WaveOut, ASIO and WSAPI.
In the most cases, WSAPI in the exclusive mode delivers the best temporal accuracy and fidelity of audio playback. (for example, the mid-range Creative SB X-Fi Titanium Professional card, used in Windows 7, can start a playback just in 2ms after onset of the parent event)
The Wave Player element allows selection of the output sound device when multiple sound cards installed on a computer.
For some professional sound cards another low-level sound API,
Audio Stream Input/Output ASIO, can be recommended. Using ASIO API and compatible sound hardware and drivers (the last two are essential) may also help to achieve perfect temporal precision and fidelity.
Wave Player element supports the majority of resolutions and encodings used in the Wave format. The element automatically converts input wave clips into uncompressed PCM data streams before a playback. Since the conversion takes some time, using the uncompressed PCM wave clips is recommended for faster processing of audio stimuli.
When to use the Wave Player element
EventIDE provides several
elements for delivering auditory stimuli. The audio elements have similar functionality and a choice depends on design demands and the used sound hardware. A guidance on selecting an audio element is available in
Auditory Stimuli article.
In short, the Wave Player element is the simplest and most recommended audio element, especially if Windows Vista/7 system and modern sound card is used.
Stimulus Set
The element can be easily adapted to make up an audio stimulus set that contains multiple audio clips. Then one of these clips can be selected to be played in the given trial.
To make a stimulus set, load selected audio clips from
Material Library directly into the element (e.g. by drag and drop). Then use the Item Index property to select an audio clip for playback. It's recommended to change the Item Index property before the onset of the parent event because preparing the clip for playback takes some time.
Practical Use
- Add a new Wave Player element into the selected event (where an audio has to be played).
- Select the element in the Element panel, then its properties will appear in the Property panel at the right.
- Load selected audio clips from the Material Library to the item list of the element and select the current clip via Item Index property.
- Browse to the Hardware Settings group in the element properties and select Playback API and Sound Device in the corresponding properties.
- Select a playback mode for the element in the Playback Setting group. The most common mode for presentation of auditory stimulus is "Single playback on onset of the parent event"
- Test, if an audio is played by clicking over the Test Playback property.
- Make sure that duration of the parent event is greater or equal to duration of the selected audio clip- an audio playback is always aborted on offset of the parent event.
Playback modes
At runtime the element can work in 3 different playback modes, which define how playback process starts and stops. The mode has to be selected at design-time and cannot be changed. However, it's possible to use multiple elements working in different modes in parallel. The available modes are:
Single playback on event onset
In this mode the element starts to play an audio synchronously with activation of the parent event. The audio is played once. When the playback stops you can initiate a new one manually if the parent event is still active.
Looped playback on event onset
In this mode the element starts to play an audio synchronously with activation of the parent event and automatically restarts the playback as soon as the end of the audio clip is reached. This playback loop lasts until deactivation of the parent event.
Manual mode
In this mode the playback is controlled solely by element's IsPlaying property, which can be changed in snippets. If IsPlaying is set to true before onset of the parent event, the playback behaviour will be similar to 'Single playback on event onset' mode. If the parent event is active, the playback starts/stops on a change of the IsPlaying property. The Is Playing property automatically turns to false when the playback ends.
Triggering at the end of the playback
Sometimes it's necessary to abort the parent event immediately after the playback has reached its end. Since the Wave Player element can contain multiple audio clips of different durations, the duration of the parent event can not set to fix value. The wave player elements offers an easy solution - it monitors the playback process and gets triggered at the end of each audio clip. Triggering causes a call of the OnTriggered snippet that can be used for user actions. In addition, the element has a boolean property, called Is Triggered, which can be used directly (as
Proxy) in controlling the event flow.
Notes
The Wave Player elements is otimized t deliver the best timing accuracy of the audio playback. However, it's always recommended to measure empirically the timing of the actual playback when high accuracy is required. The measurements can be done with oscilloscope connected to the output of the sound card. Probing different settings of the element can help to achieve the optimal results.
Properties
Generic properties
| Name | Description | Attributes | Value Type |
|---|
| Settings |
| Test Playback | Use this action at the design time to initiate an testing playback with the current settings. | | Design-time action |
| Is Mixing | If true, the ASIO engine will be able to play multiple audios simultaneously. However, it may increase the playback latencies. | | Boolean |
| Playback mode | Determines the playback mode for the element. If the property is set to None, the playback has to be initiated manually, otherwise it is synchronized with activation of the parent event. | | Object |
| Monitor Playback | Indicates if the element triggers at the end of the each playback and records its start and end times. | D | Boolean |
| Clip Info | Information about the sound buffer created for the currently selected audio clip. Click to expand all fields. | D | stASIOBufferInfo |
| Playback |
| Volume | Volume, from ground (0) to full (100), of the playback of a wave audio | | Double |
| Balance | Stereophonic balance, left (-100) to right (100), of the audio clip. | D,R | Int32 |
| Start position | Defines the start position of the audio playback in percentages (0..100) to the total duration of the currently selected audio clip. | D,R | Double |
| Position | The current playing position (percentages, 0..100, to the total duration) of the audio. Changes are accepted only if the audio is playing at runtime. | D,R | Double |
| Runtime info |
| Start Time | If the playback triggering is on, indicates the actual event time when the last playback has started. | R, Read-Only | UInt64 |
| End Time | If the playback triggering is on, indicates the actual event time when the last playback has reached its end. | R, Read-Only | UInt64 |
| Is triggered | If the playback triggering is on, indicates that the element has been triggered at least once since the parent event is active. | R, Read-Only | Boolean |
+=== Properties inherited from clLibraryElement ===
| Name | Description | Constraints | Value Type | Upon Runtime Change |
|---|
| Material List |
| Selected Index | Defines the index of the active item in the material list of the element. | | Int32 | A change causes the current item to be reloaded and an update of the element. |
| Selected Item | Defines the name of the active item in the material list of the element. The name matches to a name of item in the Material Library | | String | A change causes the current item to be reloaded and an update of the element. |
| Item Count | Returns the total number of items in the material list of the element. | | Int32 |
| Equalize RGB | The property is only available in the visual element. If the value is true, the average RGB pixel intensity will be equalized across all items in the material list. You can turn on this property, when you need to obtain a luminance-balanced set of visual stimulus. | | Boolean | |
+=== Properties inherited from clElement ===
Inherited properties of clElement
| Name | Description | Constraints | Value Type | Upon Change |
|---|
| Control |
| Is Enabled | If set to false the element is completely omitted when the experiment is run. | | Boolean |
|
| Title | Title of the element. | | String |
|
The list of Text element properties:
Resource Holder inherited properties
| CATEGORY ,Property name | Description | type | Value type |
| RESOURCE LIST |
| Resource index | The index of item in the resource list that is currently used by the element. Notice, that index starts from 1. | D,R,* | Int32 |
| Resource count | The number of items loaded in the resource list of the element | D,R,Read-only | Int32 |
|