Page History: Direct Sound Element

Compare Page Revisions

« Older Revision - Back to Page History - Newer Revision »

Page Revision: 2011/07/20 14:48

	New Element
Info
Category:		AddIn:	Base Elements
Creator:	OkazoLab Team	Scope:	Parent Event
Owns Snippets:	no	Usage:	Runtime Screen,Snippets

DirectSound element is capable to play WAV audio clips.

Table of Contents [Hide/Show]

Description
Snapshots
Practical Use
    Playback modes
       Once mode
      Loop mode
       Manual mode
    3D audio
    Performance notes
    Design-time testing
Notes
Properties
    Generic propertices

Description ¶

DirectSound element is capable to play audio clips in the Waveform Audio File Format (WAV) via a fast, low-level interface to sound cards provided by Microsoft DirectSound library. In result, a very good temporal precision of audio playback can be achieved in experiments, especially with an appropriate sound hardware. The WAV format is adequate for majority of auditory stimuli-the multichannel sounds of various resolutions are supported. The DirectSound element also offers an advance management of the playback process: multiple sounds mixing, changes in sound volume and playback position, the real-time listener positioning in 2D/3D space.

Snapshots ¶

Snapshot 1

Snapshot 2

Practical Use ¶

Name	Description	Attributes	Value Type
Settings
Sound Device	The particular sound device selected for the audio playback among a list of devices installed on a computer . If the option Primary Audio Driver is selected, the default sound device will be always used for a playback.	D	List
Playback mode	Defines the synchronization mode of the playback process. One of three modes can be selected: Once – the sound playback is initiated synchronously with activation of the parent event and an audio clip is played once. Loop - the start of sound playback is synchronized with activation of the parent event but, since that, an audio clip is played in a loop. Manual – the sound playback is initiated manually by a request from code snippets.	D	List
Monitor Playback	Defines if the element monitors the start and end playback times and is triggered at the end of the each playback	D	Boolean
Test Playback	Use this action at the design time to initiate an testing playback with the current settings.	Design-time action
Sound buffer
Buffer Type	Defines a type of the sound buffer created for a playback. The buffer type is determined by its location in device/computer memory.	D	List
Is Primary	f true, the element will try to allocate the primary buffer memory of the sound device for the fastest playback (exclusively for this element). The sound device has to support this option.	D	Boolean
Priority	efines the priority of the allocated sound buffer relatively to other buffers. The lowest priority corresponds to 0. The greater is the positive value, the higher priority is given.	D	Int 32
Volume control	f true, the volume of played audio can be adjusted at runtime. If false, it can improve temporal precision the playback.	D	Boolean
Balance Control	f true, the stereophonic balance of played audio can be adjusted at runtime. If false, it can improve temporal precision of the playback.	D	Boolean
Design-time info
Device Info	Information about capacities of the currently selected sound device. Click to expand all sub-fields.	D	Struct
Buffer Info	Information about the sound buffer created for the currently selected audio clip. Click to expand all sub-fields.	D	Struct
Playback
Volume	Defines the volume of the audio playback, in percentages, from 0 (ground) to 100 (full)	D,R	Int32
Balance	Defines the stereophonic balance of the audio playback, from 100 (most left) to 100 (most right)	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.	,R	Double
Position	The current playback position in percentages (0..100) to the total duration of the currently played audio. The property can be used only at runtime.	D,R	Double
Is Playing	Indicates if the element is currently playing an audio. Changing this property at runtime results in toggling between the play/pause states.	R	Boolean
3D Audio
Enable 3D	If true, it turns on the 3D audio effect for the playback (if supported by the selected sound device)	Boolean
Listener Position	The current 3D position of the virtual listener relatively to the fixed sound source in (0,0,0). Values are in the distance units.	D,R	cl3DVector (fields: X,Y,Z)
Front Heading	The current 3D orientation of the front of the virtual listener relatively to the sound source in (0,0,0). Values are in the distance units.	D,R	cl3DVector (fields: X,Y,Z)
Top Heading	The current 3D orientation of the top of the virtual listener relatively to the sound source in (0,0,0). Values are in the distance units.	D,R	cl3DVector (fields: X,Y,Z)
Distance Factor	Number of meters in the distance unit	D,R	float
Doppler Factor	The Doppler factor that has a range of 0.0 (no Doppler effects) to 10.0 (ten times the Doppler effects found in the real world)	D,R	float
Rolloff Factor	Determines the rate of the sound attenuation over distance. Has a range of 0.0 (no rolloff) to 10.0 (ten times the rolloff found in the real world).	D,R	float
Listener's velocity	Listener's velocity that is used for generation of the Doppler effect, in the distance units per second	D,R	float
Runtime info
Start Time	If [Monitor Playback] property is true, this property stores the actual event time when the last playback started. Indicates the actual playback startup latency in ms if the "Once" playback mode is chosen.	R, Read-Only	UInt64
End Time	If [Monitor Playback] property is true, this property stores the actual event time when the last playback ended. [End Time]-[Start Time] indicates the actual duration of the last playback in ms.	R, Read-Only	UInt64
Was triggered	If [Monitor Playback] property is true, this property indicates if the element has been triggered at least once since activation of the parent event. The triggering occurs each time when the playback ends.	R, Read-Only	Boolean

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.	Status..	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.	Design Time..	Boolean

Name	Description	Constraints	Value Type
Control
Is Enabled	If set to false the element is completely omitted when the experiment is run.	Design Time..	Boolean
Title	Title of the element.	Design Time..	String

*

You can use this element to deliver rich auditory stimuli in experimental scenarios where accurate timing is important and a playback process need to be controlled. For simplest sound tones you can get even better good temporal precision if you use the Beeper element. Alternatively, in scenarios where temporal precision is not necessary, for example: for a post-stimulus voice feedback, you can use the Audio Player element that supports the widest range of sound formats.

The DirectSound element has several properties for a fine tuning of the sound hardware. You can select a sound card among multiple sound cards installed on the same computer and set up its memory configuration for the most efficient audio playback. The element can collects and present to you information about hardware capacities of the sound card. However, it's always better to test the real playback performance empirically, since it may depend on many factors. The element can help you in measuring the basic playback statistics, like a real startup latency and actual playback duration at runtime.

Playback modes ¶
The DirectSound element can work in one of three playback modes which define temporal synchronization of the playback process:

Once mode ¶
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.

Loop mode ¶
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 element plays an audio by a manual request made in code snippets at will time. The playback is initiated by assigning true to the [IsPlaying] property of the element. Later, the same property can be used to monitor if the audio is still currently played. [IsPlaying] property automatically turns to false when the playback ends. At this moment and later you can initiate a new playback if the parent event is still active.

3D audio ¶
The DirectSound element supports the 3D audio effect widening the perceived sound image for a listener. For most realistic results using more than 2 speakers is necessary. The overall control over 3D audio effect is very simple- the element adjusts audible channels according to the position of a virtual listener relatively to a fixed sound source in 3D space. You can dynamically change the listener position at runtime, changing just 3 coordinates. In addition, you can customize the produced 3D audio with the Doppler effect and with the effect of sound attenuation over a distance. Notice, that you have to provide a monochannel WAV clip for playback if 3D audio is enabled ([3D enable] property)

Performance notes ¶
In general, the temporal accuracy of the DirectSound playback is always traded for requested controls over the playback process. For example, you may get more accurate timing if you decide not to change the sound volume during playback. The DirectSound element allows you to choose only controls that are currently necessary. Set the properties [Volume control], [Balance control], [3D enable], [Triggering] to False in order to get better temporal performance. In addition, you can manually set up the memory management for playing sound. If the sound card supports it, try to allocate the memory buffer for an audio in the hardware memory of the sound card by setting the [Buffer type] property. If you have a single auditory stimulus delivery in your experiment, you can try to use the Primary buffer of the sound card for a single DirectSound element (the [Primary Buffer] property) - it should give you even better playback performance. Using audio clips of uncompressed formats, like WAVE PCM, with the sample rate and other characteristics matching to the format of the sound card memory buffers can also greatly improve the playback performance.

Design-time testing ¶
While choosing appropriate values for the element's properties, check the content of the Device Info and Buffer Info properties. These properties are refreshed after any related property change and should not be empty or contain error messages. If you see an error, the playback is not possible, and you have to choose different values for the element's properties. You can also always test an audio playback with the current element settings by clicking the Test Audio property.

Notes ¶

The DirectSound interface in Windows XP in most cases accesses the sound hardware directly. It is NOT the case for Windows Vista and Windows 7, where DirectSound works in the software emulation mode. Although such emulation can be very efficient, the temporal precision of sound playback with DirectSound element can be lower under Windows Vista and Windows 7.
If you enable 3D audio, you should use mono audio clips as playback resources for the element.
For better synchronization of the audio playback (in the Once and Loop playback modes), move the DirectSound element at the top of the elements list in the parent event. Elements in the list get to work one by one, as soon as the parent event is activated, so the top position in the list will minimize possible delays.
)))

Properties ¶
Generic propertices ¶

Name Description Attributes Value Type
Settings
Sound Device The particular sound device selected for the audio playback among a list of devices installed on a computer . If the option Primary Audio Driver is selected, the default sound device will be always used for a playback. D List
Playback mode Defines the synchronization mode of the playback process. One of three modes can be selected: Once – the sound playback is initiated synchronously with activation of the parent event and an audio clip is played once. Loop - the start of sound playback is synchronized with activation of the parent event but, since that, an audio clip is played in a loop. Manual – the sound playback is initiated manually by a request from code snippets. D List
Monitor Playback Defines if the element monitors the start and end playback times and is triggered at the end of the each playback D Boolean
Test Playback Use this action at the design time to initiate an testing playback with the current settings. Design-time action
Sound buffer
Buffer Type Defines a type of the sound buffer created for a playback. The buffer type is determined by its location in device/computer memory. D List
Is Primary f true, the element will try to allocate the primary buffer memory of the sound device for the fastest playback (exclusively for this element). The sound device has to support this option. D Boolean
Priority efines the priority of the allocated sound buffer relatively to other buffers. The lowest priority corresponds to 0. The greater is the positive value, the higher priority is given. D Int 32
Volume control f true, the volume of played audio can be adjusted at runtime. If false, it can improve temporal precision the playback. D Boolean
Balance Control f true, the stereophonic balance of played audio can be adjusted at runtime. If false, it can improve temporal precision of the playback. D Boolean
Design-time info
Device Info Information about capacities of the currently selected sound device. Click to expand all sub-fields. D Struct
Buffer Info Information about the sound buffer created for the currently selected audio clip. Click to expand all sub-fields. D Struct
Playback
Volume Defines the volume of the audio playback, in percentages, from 0 (ground) to 100 (full) D,R Int32
Balance Defines the stereophonic balance of the audio playback, from 100 (most left) to 100 (most right) 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. ,R Double
Position The current playback position in percentages (0..100) to the total duration of the currently played audio. The property can be used only at runtime. D,R Double
Is Playing Indicates if the element is currently playing an audio. Changing this property at runtime results in toggling between the play/pause states. R Boolean
3D Audio
Enable 3D If true, it turns on the 3D audio effect for the playback (if supported by the selected sound device) Boolean
Listener Position The current 3D position of the virtual listener relatively to the fixed sound source in (0,0,0). Values are in the distance units. D,R cl3DVector (fields: X,Y,Z)
Front Heading The current 3D orientation of the front of the virtual listener relatively to the sound source in (0,0,0). Values are in the distance units. D,R cl3DVector (fields: X,Y,Z)
Top Heading The current 3D orientation of the top of the virtual listener relatively to the sound source in (0,0,0). Values are in the distance units. D,R cl3DVector (fields: X,Y,Z)
Distance Factor Number of meters in the distance unit D,R float
Doppler Factor The Doppler factor that has a range of 0.0 (no Doppler effects) to 10.0 (ten times the Doppler effects found in the real world) D,R float
Rolloff Factor Determines the rate of the sound attenuation over distance. Has a range of 0.0 (no rolloff) to 10.0 (ten times the rolloff found in the real world). D,R float
Listener's velocity Listener's velocity that is used for generation of the Doppler effect, in the distance units per second D,R float
Runtime info
Start Time If [Monitor Playback] property is true, this property stores the actual event time when the last playback started. Indicates the actual playback startup latency in ms if the "Once" playback mode is chosen. R, Read-Only UInt64
End Time If [Monitor Playback] property is true, this property stores the actual event time when the last playback ended. [End Time]-[Start Time] indicates the actual duration of the last playback in ms. R, Read-Only UInt64
Was triggered If [Monitor Playback] property is true, this property indicates if the element has been triggered at least once since activation of the parent event. The triggering occurs each time when the playback ends. 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.
Status..
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.
Design Time..
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.
Design Time..
Boolean
Title Title of the element.
Design Time..
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

EventIDE Wiki

Navigation¶

Page History: Direct Sound Element

Page Revision: 2011/07/20 14:48

Description ¶

Snapshots ¶

Practical Use ¶

Playback modes ¶

Once mode ¶

Loop mode ¶

Manual mode ¶

3D audio ¶

Performance notes ¶

Design-time testing ¶

Notes ¶

Properties ¶

Generic propertices ¶