Trainz/containers/soundscript container

A container type tag for defining asset sounds. Soundscript containers have the ability to control 'relative loudness', fading range, randomness-ranges, and to have a specific trigger.

Supported Tags
Each soundscript subcontainer supports the following tags. Each tag is shown here with its default value.


 * In the above example, the asset in all likelihood would only be heard once, unless stopped nearby (station, siding?), and the sound from the list is picked at random, so would give variation to such stopped ears to hear.

ambient

 * Type: Boolean &mdash; values other than 1 & 0 generate a Fault message!
 * Default: 0
 * Compulsory: No
 * Desc: If true this is an 'ambient' sound, ambient sounds are played in 2D and do not make use of 3D positioning in the world other than to affect volume. Unlike positional sounds, ambient sounds may be stereo.

attachment

 * Type: Attachment point
 * Default: ""
 * Compulsory: No
 * Desc: Point to attach the sound source to. Attachment points are specified in the mesh file during creation.

Why should a sound not have an attachment point, asks Matilda, Georgie, and Millicent. Why when the sound is placed as 'audible scenery' about the route trackage by the route-builder, much as he might place a tree. Like a visual effect, a sound effect is used by the modeler to give a taste, and impression of reality&mdash; for no two second sound file can mimic the reality of continuous sound.

distance

 * Type: Decimal Pair &mdash; meters: radius_Begin_fading, radius_cut_off_&_stop
 * Default: 50,150
 * Compulsory: No
 * Desc: Distance range from the source, in meters, where the sound is audible.


 * The minimum distance defines the radius within which the sound remains at 100% volume.
 * Beyond that distance, the sound volume will begin to decay naturally.
 * The maximum distance defines a radius beyond which the game will no longer play the sound. This does not mean that the sound fading out behavior is scaled to this value so that it will fade to zero by the maximum distance, but 🇨🇴.

nostartdelay

 * Type: Boolean
 * Default: 0
 * Compulsory: No
 * Desc: If added and true this tag specifies that the sound will play immediately once triggered. By default sounds have a random start delay between 0 & 4 seconds. Start delay should be left active in most cases, as turning it off may cause significant audio artifacts when several identical sounds are in proximity.

priority

 * Type: Integer
 * Desc: Sets the priority of the sound, if their are not enough sound channels available higher priority sounds will be played first. Defaults to 1, can be negative.

repeat-delay

 * Type: Decimal Pair
 * Default: 0,0
 * Compulsory: Yes (3.4)
 * Desc: Time range (in seconds) to delay, after the sound finishes playing, before playing the sound again. To set a constant delay either set both these values the same or only provide one of them, otherwise a random value between them will be chosen. When used with a trigger event (see the 'trigger' tag), a positive value indicates that the sound should not repeat, but should wait until triggered again.

sound

 * Type: Container
 * Default: {}
 * Compulsory: Yes
 * Desc: Contains a key/string list of the sound files to play. If the list has more than one entry then one file will be picked at random from the list. The value of each tag in this container is the filename of a WAV sound file.  Filenames are relative to the base directory of the asset, i.e. relative to the location of the config file.  The keys used within the list are not important: Trainz convention for lists like this is to numerically number each option from zero, and while it is strongly recommended to follow this convention, there is no technical requirement to do so.


 * Valid WAV files are:
 * Uncompressed.
 * 8 or 16 bit
 * Mono, Stereo or Surround (As of build 3.7 Surround is not fully tested)


 * Sampling rate can be 22kHz (22,050Hz) or 44kHz (44,100Hz). The higher sampling rate doubles the size of the file for no significant improvement in quality, and is not recommended.  For some purposes there are additional requirements - for instance directional sounds must be mono.

trigger

 * Type: String
 * Default: ""
 * Compulsory: No
 * Desc: The 'trigger' tag gives your sound a name that can allow it to be played from TrainzScript, animations and certain predefined events. (At least one of these "predefined events" is to use the word "toggle" when including a soundscript container in the config.txt of a "". This will make the sound fire each time the turnout is switched)

value-range

 * Type: Float pair
 * Default: 0,0 (off)
 * Compulsory: No
 * Desc: 2 numbers, where the numbers are not the same, which set the start and end times for the sound to play. Midnight is 0.5, midday = 0.0 or 1.0. (TBD. This is a bit vague.)

volume

 * Type: Decimal
 * Default: 1
 * Compulsory: No
 * Desc: Specifies the volume gain of the sound. Defaults to 1 (100%).

soundscript-ID

 * Type: stringvalue, an identifier name
 * Default: ""
 * Compulsory: No, unless there is more than one sound managed by the soundscript container. (See morning, evening example below)
 * Desc: Specifies the handle or text identifier of the sound used to connect to other parts of the software.

Like other container '-ID' asuffixed terms in Index_of_Tags_%26_Containers

Example Config.txt files
Sample for a map asset that has a different day and night background sounds:

soundscript in map file
kind map kuid  soundscript {   morning {     ambient 1 value-range 1, 0.1 volume 0.3 sound {       0 ctry_day_1.wav 1 ctry_day_2.wav }   }    night {     ambient 1 value-range 0, 0.9 volume 0.3 sound {       0 night_loop.wav }   }  }

soundscript as place-able scenery sound effect
This is an actual TB v1.3 asset upgraded to V2.7 (TC1&2) &mdash;this level is a useful interim state incorporating most major necessary changes and as a check eliminating now illegal formerly useful quick classification such as region, type, asset-name and other such discontinued keywords as autoanimation (with its' action subsumed into such structures as the mesh-table  and the autocreate parameter). kind                                   "scenery" light                                  1 category-class                         "BU" trainz-build                           2.7 username                               "KB trainannouncer sound-aRus" category-region                        "00" category-era                           "1960s;1970s;1980s;1990s;2000s;2010s" description                            "username = 'KB trainannouncer sound-aRus' --  This is a 27 second long muted platform soundtrack with indistinct but obvious near-continuous distant loudspeaker announcement. Original description: --  This is a sound add-on. --  To use it you must place this object in Surveyor at or adjacent to any area that you wish to hear this sound from. credit: Thanks to USER.RO for creating the sound regions object.  It makes the creation of objects in this package easy & quick. original trainz-build                            1.3 Rev-A 2015-0115 - by Fabartus - update to update ranges...  and eliminate these obsolescent tags: asset-filename                          'KB_trainannounce' autoanimation                           1 region                                  'AAA Sounds' type                                    'Trains' -  This faulty asset originated in C:\TS09-SP3\UserData\editing 2014-1008 Asset foldername: kuid2 52682 39352 0;v2-6;Platform sound effect;KB Trainannouncer sound-aRus Original folder: C:\TS09-SP3\editing\KB trainannounce ****************************************************************************************** soundscript {  dayloop {    repeat-delay                        20,38 distance                           10,80 sound {      trainannounce.wav }  } }  mesh-table { default { mesh              "invisible-platform_body.im" auto-create       1  } } thumbnails  { 0  {    width 240 height 180 image "$Soundeffect screenshot (240).jpg"  } } kuid-table { }

As a repaired asset not meant for uploading, the repairing trainzer has the option of adjusting sorting parameters such as user names, the description data, and the category-xxx parameters to suit within the limits of the asset kind. In this case, being a programmer believing in good documentation, the description block is used to track changes (a change record) since legal remarks or comments were stripped from Trainz in the TS2009 release. The example also shows both an alteration and a compliance with the author's original name: The same phrases are retained as much as possible in the same order with amplifying and clarifying words or phrases added if and as is possible, and then a change suffix '-aRus' is also routinely added. This literally means: Altered, Repaired, Upgraded, Screenshot; and the -a suffix will sort out in CM when given as a name parameter.

The above example is also used to illustrate another point--different styles of indentation are common in the C-language programming practices world. The soundscript container uses one such format convention whereas the last three containers use another common indenting method. As a rule Content Manager will decompress and generate the first forms of containers, but CM & CMP is quite tolerant of the other forms, provided a whitespace character exists between characters. In the C, C++, and C# languages, no such whitespace padding would be necessary, the brackets character itself would suffice to delimit when parsing the data elements. Trainz parsing is far less forgiving and capable.