SteamVR/Environments/Adding Sound/Soundevents: Difference between revisions
(Added headings and parameter documentation) |
(Added usage examples and troubleshooting tips) |
||
| Line 1: | Line 1: | ||
== A guide to adding Soundevents to your Environment == | |||
First, sound files go in the content/youraddon/sounds/ folder. | First, sound files go in the content/youraddon/sounds/ folder. | ||
| Line 40: | Line 39: | ||
===== Types ===== | ===== Types ===== | ||
There are 2 'type' settings you can use for sound behavior control in environments. | There are 2 main 'type' settings you can use for sound behavior control in environments. | ||
'''"destinations.simple_vr"''' <br /> | '''"destinations.simple_vr"''' <br /> | ||
| Line 48: | Line 47: | ||
For sounds without positional information, whose stereo information will be preserved no matter the orientation of the player. Example usages - non-diagetic music, ambience beds, atmospheric rumbles. | For sounds without positional information, whose stereo information will be preserved no matter the orientation of the player. Example usages - non-diagetic music, ambience beds, atmospheric rumbles. | ||
== Using | == Using Soundevents == | ||
===== point_soundevent ===== | ===== point_soundevent ===== | ||
The simplest way of using soundevents is by the [[point_soundevent]] entity in Hammer. Placing one and clicking the magnifying glass next to '''Sound Event Name''' in the Object properties presents a list of available soundevents. | |||
See [[SteamVR/Environments/Turret_Tutorial| the turret tutorial]] for an example on how to wire up the point_soundevent to a trigger. | |||
===== Animation Events ===== | ===== Animation Events ===== | ||
Soundevents can be attached to animation frames of custom models. To do so, select an animation in the Model Editor and click the plus sign next to Animation Events in the Property Editor, and a new event entry will appear. Expand it and select '''AE_CL_PLAYSOUND''' (or one of the other PLAYSOUND events) from the Event dropdown. Then type in the Frame to play on and finally the name of the sound event into the Data String. | |||
{{Note | The sound may not play in the editor unless the game window is focused and the VR headset is tracking.}} | |||
===== Emitting from VScript ===== | ===== Emitting from VScript ===== | ||
Soundevents can be directly played from [[VScript]] Lua scripts, for example for special effects on [[Environments/Scripting/Flashlight_Tool_Tutorial|tools]]. There are functions available for both emitting sounds from certain locations and entities, as well as emitting non-directional sounds either to one player or all. | |||
See the scripting API for the available functions: [[SteamVR/Environments/Scripting/API#Sound]] | |||
===== Emitting from Panorama ===== | |||
Soundevents can be played on [[Dota_2_Workshop_Tools/Panorama|Panorama]] UI elements using the CSS <code>sound</code> and <code>sound-out</code> properties: [[Dota_2_Workshop_Tools/Panorama/CSS_Properties#sound]] | |||
== Troubleshooting == | == Troubleshooting == | ||
It is advisable to make sure that any sound files have been imported properly before troubleshooting the soundevent. The sound files should appear in the asset browser as ''.vsnd'' files, and play when clicked on. Note that the sound may not play if no map is running or the VR headset isn't tracking. | |||
Soundevent files require a strict syntax and spotting errors in them can be difficult. The [[SteamVR/Environments/Introduction#Console|Developer Console]] will output any errors it finds when parsing the file. Re-save the file and look for new messages from the ResourceCompilerSystem. If the parsing failed, several error messages should appear. The first one should at least provide a hint on what the error is. | |||
If the soundevent file passed compile, the <code>snd_sos_start_soundevent</code> console command can be used to play it back. Typing in the command and pressing space should provide an autocomplete list of valid sound events. Note that the soundevent may not play if no map is running or the VR headset isn't tracking. If the sound still doesn't play, the issue is likely with the soundscript entry in the file. | |||
== Extended Documentation == | == Extended Documentation == | ||
| Line 73: | Line 96: | ||
| string | | string | ||
| | | | ||
| | | Using one of the sound types listed below will determine the playback behavior of the sound. | ||
|- | |- | ||
| vsnd_files | | vsnd_files | ||
| string/array | | string/array | ||
| | | | ||
| The | | The sound file(s) you wish to play. Using an array of strings enclosed in square braces allow for multiple sound files to be added for one soundevent. When the soundevent is called to play, it will respond with one of the files chosen at random. Once a sound file is used it will not be chosen again until the list is exhausted. | ||
|} | |} | ||
| Line 91: | Line 114: | ||
| float | | float | ||
| 1.0 | | 1.0 | ||
| | | A float value set between 0.0 and 1.0 that acts as a multiplier on the sounds volume. | ||
|- | |- | ||
| pitch | | pitch | ||
| float | | float | ||
| 1.0 | | 1.0 | ||
| | | A float value that determines the pitch at which the sound plays back. Ideally set it between 0.9 and 1.1 to avoid digital distortion from extreme pitch shifting, but feel free to experiment if you want some crazy sounds. | ||
|- | |- | ||
| delay | | delay | ||
| float | | float | ||
| 0.0 | | 0.0 | ||
| | | A float value representing a millisecond delay between the soundevent being called to start and the sound file playing. | ||
|- | |- | ||
| use_hrtf | | use_hrtf | ||
| float | | float | ||
| 1.0 | | 1.0 | ||
| | | A parameter available only to the 3D spacialized sound types. By default this is a 1.0 for all soundevents, directing them to use the SteamAudio HRTF panning feature. To use regular/legacy panning, add this parameter and set it to 0.0. | ||
|- | |- | ||
| volume_falloff_min | | volume_falloff_min | ||
| float | | float | ||
| 200.0 | | 200.0 | ||
| | | A float value that determines at what distance the volume should start fading. Below this distance the sound will be played at the full volume. | ||
|- | |- | ||
| volume_falloff_max | | volume_falloff_max | ||
| float | | float | ||
| 2000.0 | | 2000.0 | ||
| | | A float value that determines the maximum distance the sound can be heard. | ||
|- | |- | ||
| volume_falloff_limit | | volume_falloff_limit | ||
| Line 325: | Line 348: | ||
|- | |- | ||
| destinations.drone_acc | | destinations.drone_acc | ||
| | | The types below provide the dynamic pitch effects for the Drone and Cache Finder tools. | ||
|- | |- | ||
| destinations.drone_dec | | destinations.drone_dec | ||
Revision as of 06:05, 22 July 2019
A guide to adding Soundevents to your Environment
First, sound files go in the content/youraddon/sounds/ folder.
With a text editor, open the provided file, "soundevents_addon.vsndevts" from the content soundevents folder. Do not rename this file to match your addon, just edit the contents.
You add soundevent definitions inside the existing curly braces already present in the file-
name
Replace 'soundname_01/02' with the name for your soundevent, this is what you will reference elsewhere in the tools to call your sound.
type
Replacing 'soundtype' inside the quotations with one of the two types explained below will determine the playback behavior of the sound.
volume
An optional parameter requiring a float value, ideally set between 0.0 and 1.0, that acts as a multiplier on the sounds volume. If undeclared, it will default to 1.0.
pitch
An optional parameter requiring a float value, that determines the pitch at which the sound plays back. Ideally set it between 0.9 and 1.1 to avoid digital distortion from extreme pitch shifting, but feel free to experiment if you want some crazy sounds. If undeclared, it will default to 1.0.
delay
An optional parameter requiring a float value, representing a millisecond delay between the soundevent being called to start and the sound file playing. If undeclared, it will default to 0.0.
use_hrtf
An optional parameter, available only to the "destinations.simple_vr" soundtype explained below. By default this is a 1.0 for all soundevents, directing them to use the SteamAudio HRTF panning feature. To use regular/legacy panning, add this parameter and set it to 0.0.
vsnd_files
The value here is the sound file you wish to play. Note for soundname_02, the square braces allow for multiple sound files to be added for one soundevent. When the soundevent is called to play, it will respond with one of the files chosen at random. Once a sound file is used it will not be chosen again until the list is exhausted.
Note: The .vsnd extension is for the compiled version of audio files in Source 2. When the sound first plays, it will get compiled into a .vsnd automatically. You don't need to change the audio file extension by hand, just use .vsnd in the script.
Types
There are 2 main 'type' settings you can use for sound behavior control in environments.
"destinations.simple_vr"
For sounds with positional information and that require a falloff of volume against distance. Example usages - a bird call, dog bark, door closing.
"destinations.simple_2d"
For sounds without positional information, whose stereo information will be preserved no matter the orientation of the player. Example usages - non-diagetic music, ambience beds, atmospheric rumbles.
Using Soundevents
point_soundevent
The simplest way of using soundevents is by the point_soundevent entity in Hammer. Placing one and clicking the magnifying glass next to Sound Event Name in the Object properties presents a list of available soundevents.
See the turret tutorial for an example on how to wire up the point_soundevent to a trigger.
Animation Events
Soundevents can be attached to animation frames of custom models. To do so, select an animation in the Model Editor and click the plus sign next to Animation Events in the Property Editor, and a new event entry will appear. Expand it and select AE_CL_PLAYSOUND (or one of the other PLAYSOUND events) from the Event dropdown. Then type in the Frame to play on and finally the name of the sound event into the Data String.
Note: The sound may not play in the editor unless the game window is focused and the VR headset is tracking.
Emitting from VScript
Soundevents can be directly played from VScript Lua scripts, for example for special effects on tools. There are functions available for both emitting sounds from certain locations and entities, as well as emitting non-directional sounds either to one player or all.
See the scripting API for the available functions: SteamVR/Environments/Scripting/API#Sound
Emitting from Panorama
Soundevents can be played on Panorama UI elements using the CSS sound and sound-out properties: Dota_2_Workshop_Tools/Panorama/CSS_Properties#sound
Troubleshooting
It is advisable to make sure that any sound files have been imported properly before troubleshooting the soundevent. The sound files should appear in the asset browser as .vsnd files, and play when clicked on. Note that the sound may not play if no map is running or the VR headset isn't tracking.
Soundevent files require a strict syntax and spotting errors in them can be difficult. The Developer Console will output any errors it finds when parsing the file. Re-save the file and look for new messages from the ResourceCompilerSystem. If the parsing failed, several error messages should appear. The first one should at least provide a hint on what the error is.
If the soundevent file passed compile, the snd_sos_start_soundevent console command can be used to play it back. Typing in the command and pressing space should provide an autocomplete list of valid sound events. Note that the soundevent may not play if no map is running or the VR headset isn't tracking. If the sound still doesn't play, the issue is likely with the soundscript entry in the file.
Extended Documentation
Properties
Required properties
| Parameter | Type | Default | Description |
|---|---|---|---|
| type | string | Using one of the sound types listed below will determine the playback behavior of the sound. | |
| vsnd_files | string/array | The sound file(s) you wish to play. Using an array of strings enclosed in square braces allow for multiple sound files to be added for one soundevent. When the soundevent is called to play, it will respond with one of the files chosen at random. Once a sound file is used it will not be chosen again until the list is exhausted. |
Optional properties
| Parameter | Type | Default | Description |
|---|---|---|---|
| volume | float | 1.0 | A float value set between 0.0 and 1.0 that acts as a multiplier on the sounds volume. |
| pitch | float | 1.0 | A float value that determines the pitch at which the sound plays back. Ideally set it between 0.9 and 1.1 to avoid digital distortion from extreme pitch shifting, but feel free to experiment if you want some crazy sounds. |
| delay | float | 0.0 | A float value representing a millisecond delay between the soundevent being called to start and the sound file playing. |
| use_hrtf | float | 1.0 | A parameter available only to the 3D spacialized sound types. By default this is a 1.0 for all soundevents, directing them to use the SteamAudio HRTF panning feature. To use regular/legacy panning, add this parameter and set it to 0.0. |
| volume_falloff_min | float | 200.0 | A float value that determines at what distance the volume should start fading. Below this distance the sound will be played at the full volume. |
| volume_falloff_max | float | 2000.0 | A float value that determines the maximum distance the sound can be heard. |
| volume_falloff_limit | float | 0.0 | [Todo] |
Advanced properties
| Parameter | Type | Default | Description |
|---|---|---|---|
| fade_in | float | 0.0 | Adds a fade in effect for the specified number of seconds. |
| fade_out | float | 0.0 | Adds a fade out effect for the specified number of seconds. |
| occlusion_amount | float | 0.0 | |
| occlusion_loss | float | -12.0 | |
| occlusion_source_radius | float | 20.0 | |
| size | float | 0.0 | |
| spread_min | float | 0 | |
| spread_max | float | 0 | |
| spread_min_value | float | 0.0 | |
| spread_max_value | float | 1.0 | |
| use_passed_position | bool | false | |
| attachment | string_token | "<unknown>" | |
| memory_type | float | 0 | |
| mixgroup | string | "ambient" | |
| event_type | float | 0.0 | |
| draw_debug_on | float | 0.0 | |
| minimum_volume | float | 0.5 | |
| volume_filter_amount | float | 999.0 | |
| block_stop | float | 0.0 | |
| volume_input_01 | float | 1.0 | |
| volume_input_02 | float | 1.0 | |
| volume_input_03 | float | 1.0 | |
| start | float | 1.0 | (2D only) |
| volume_rand_min | float | 0.0 | (2D only) |
| volume_rand_max | float | 0.0 | (2D only) |
| pitch_rand_min | float | 0.0 | (2D only) |
| pitch_rand_max | float | 0.0 | (2D only) |
Sound Types
| Type | Description |
|---|---|
| destinations.simple_vr | For sounds with positional information and that require a falloff of volume against distance. Example usages - a bird call, dog bark, door closing. |
| destinations.simple_2d | For sounds without positional information, whose stereo information will be preserved no matter the orientation of the player. Example usages - non-diagetic music, ambience beds, atmospheric rumbles. |
| destinations.advanced_vr | This type has more SteamAudio settings available. |
| destinations.randompos | |
| destinations.simple_vr_scalable | |
| destinations.voip | |
| destinations.voip_simple | |
| destinations.rand_pos_line | |
| destinations.3line_rand_pos_3d | |
| destinations.simple_vr_soundscapes | |
| destinations.ambient_fixed_rotation | |
| destinations.ambient_closest_pos_on_box | |
| destinations.2d_w_falloff | |
| destinations.envelope_2d | |
| destinations.focuschange_2d | |
| destinations.src1_2d | |
| destinations.drone_acc | The types below provide the dynamic pitch effects for the Drone and Cache Finder tools. |
| destinations.drone_dec | |
| destinations.cache_finder_rate | |
| destinations.cache_finder_progress | |
| destinations.cache_finder_ping | |
| destinations.cache_finder_progress |