1# Soundpacks
2
3A soundpack can be installed in the `data/sound` directory. It has to be a subdirectory that contains at least a file named `soundpack.txt`. It can include any number of json files which add any number of `sound_effect` or playlists.
4
5## soundpack.txt format
6
7The `soundpack.txt` file format needs 2 values, a NAME and a VIEW. The NAME value should be unique. The VIEW value will be shown in the options menu. Every line starting with a `#` is a comment line.
8
9```
10#Basic provided soundpack
11#Name of the soundpack
12NAME: basic
13#Viewing name of the soundpack
14VIEW: Basic
15```
16
17## JSON format
18
19### Sound effects
20
21Sound effects can be included with a format like this:
22
23```javascript
24[
25  {
26    "type": "sound_effect",
27    "id": "menu_move",
28    "volume": 100,
29    "files": [ "nenadsimic_menu_selection_click.wav" ]
30  },
31  {
32    "type": "sound_effect",
33    "id": "fire_gun",
34    "volume": 90,
35    "variant": "bio_laser_gun",
36    "files": [ "guns/energy_generic/weapon_fire_laser.ogg" ]
37  }
38]
39```
40
41Adding variety: If for a certain `id`'s `variant` multiple `files` are defined, they will be chosen at random when `variant` is played.
42
43The volume key may range from 0-100.
44
45Cataclysm has its own set of user-controllable volumes that will additionally affect the sound. These range from 0-128, and the default is 100. This means that at default volume, any sound that Cataclysm plays will default to playing at about 78% of the maximum; if you are working on sounds in an external audio editor, expect Cataclysm at default volume settings to play that sound file back quieter than your editor does.
46
47### Preloading SFX
48
49Sound effects can be included for preloading with a format like this:
50
51```javascript
52[
53  {
54    "type": "sound_effect_preload",
55    "preload": [ { "id": "environment", "variant": "daytime" }, { "id": "environment" } ]
56  }
57]
58```
59
60### Playlist
61
62A playlist can be included with a format like this:
63
64```javascript
65[
66  {
67    "type": "playlist",
68    "playlists": [
69      {
70        "id": "title",
71        "shuffle": false,
72        "files": [ { "file": "Dark_Days_Ahead_demo_2.wav", "volume": 100 }, { "file": "cataclysmthemeREV6.wav", "volume": 90 } ]
73      }
74    ]
75  }
76]
77```
78
79Each sound effect is identified by an id and a variant. If a sound effect is played with a variant that does not exist in the json files, but a variant "default" exists, then the "default" variant is played instead. The file name of the sound effect is relative to the soundpack directory, so if the file name is set to "sfx.wav" and your soundpack is in `data/sound/mypack`, the file must be placed at `data/sound/mypack/sfx.wav`.
80
81## JSON Format Sound Effects List
82
83A full list of sound effect IDs and variants is given in the following. Each line in the list has the following format:
84
85`id variant1|variant2`
86
87Where `id` describes the ID of the sound effect, and a list of variants separated by | follows. When the variants are omitted, the variant "default" is assumed. Where the variants do not represent literal strings, but variables, they will be enclosed in `<` `>`. For instance, `<furniture>` is a placeholder for any valid furniture ID (as in the furniture definition JSON).
88
89### Open/close doors
90
91* `open_door default|<furniture>|<terrain>`
92* `close_door default|<furniture>|<terrain>`
93
94### Smashing attempts and results
95
96Includes special ones that are furniture/terrain specific.
97
98* `bash default`
99* `smash wall|door|door_boarded|glass|swing|web|paper_torn|metal`
100* `smash_success hit_vehicle|smash_glass_contents|smash_cloth|<furniture>|<terrain>`
101* `smash_fail default|<furniture>|<terrain>`
102
103### Melee
104
105* `melee_swing default|small_bash|small_cutting|small_stabbing|big_bash|big_cutting|big_stabbing`
106* `melee_hit_flesh default|small_bash|small_cutting|small_stabbing|big_bash|big_cutting|big_stabbing|<weapon>`
107* `melee_hit_metal default|small_bash|small_cutting|small_stabbing|big_bash|big_cutting|big_stabbing!<weapon>`
108* `melee_hit <weapon>` # note: use weapon id "null" for unarmed attacks
109
110### Firearm/ranged weapon
111
112* `fire_gun <weapon>|brass_eject|empty`
113* `fire_gun_distant <weapon>`
114* `reload <weapon>`
115* `bullet_hit hit_flesh|hit_wall|hit_metal|hit_glass|hit_water`
116
117### Environmental SFX
118
119Divided by sections for clarity.
120
121* `environment thunder_near|thunder_far`
122* `environment daytime|nighttime`
123* `environment indoors|indoors_rain|underground`
124* `environment <weather_type>` # examples: `WEATHER_DRIZZLE|WEATHER_RAINY|WEATHER_THUNDER|WEATHER_FLURRIES|WEATHER_SNOW|WEATHER_SNOWSTORM`
125* `environment alarm|church_bells|police_siren`
126* `environment deafness_shock|deafness_tone_start|deafness_tone_light|deafness_tone_medium|deafness_tone_heavy`
127
128### Misc environmental sounds
129
130* `footstep default|light|clumsy|bionic`
131* `explosion default|small|huge`
132
133### Ambient danger theme
134
135Triggered by seeing large numbers of zombies.
136
137* `danger_low`
138* `danger_medium`
139* `danger_high`
140* `danger_extreme`
141
142### Chainsaw pack
143
144* `chainsaw_cord     chainsaw_on`
145* `chainsaw_start    chainsaw_on`
146* `chainsaw_start    chainsaw_on`
147* `chainsaw_stop     chainsaw_on`
148* `chainsaw_idle     chainsaw_on`
149* `melee_swing_start chainsaw_on`
150* `melee_swing_end   chainsaw_on`
151* `melee_swing       chainsaw_on`
152* `melee_hit_flesh   chainsaw_on`
153* `melee_hit_metal   chainsaw_on`
154* `weapon_theme      chainsaw`
155
156### Monster death and bite attacks
157
158* `mon_death zombie_death|zombie_gibbed`
159* `mon_bite bite_miss|bite_hit`
160* `melee_attack monster_melee_hit`
161* `player_laugh laugh_f|laugh_m`
162
163### Player movement sfx
164
165Important: `plmove <terrain>` has priority over default `plmove|walk_<what>` (excluding `|barefoot`).
166
167Example: if `plmove|t_grass_long` is defined it will be played before default `plmove|walk_grass` default for all grassy terrains.
168
169* `plmove <terrain>|<vehicle_part>`
170* `plmove walk_grass|walk_dirt|walk_metal|walk_water|walk_tarmac|walk_barefoot|clear_obstacle`
171
172### Fatigue
173
174* `plmove fatigue_m_low|fatigue_m_med|fatigue_m_high|fatigue_f_low|fatigue_f_med|fatigue_f_high`
175
176### Player hurt
177
178* `deal_damage hurt_f|hurt_m`
179
180### Player death and end-game
181
182* `clean_up_at_end game_over|death_m|death_f`
183
184### Various bionics
185
186* `bionic elec_discharge|elec_crackle_low|elec_crackle_med|elec_crackle_high|elec_blast|elec_blast_muffled|acid_discharge|pixelated`
187* `bionic bio_resonator|bio_hydraulics|`
188
189### Various tools/traps being used
190
191Includes some associated terrain/furniture.
192
193* `tool alarm_clock|jackhammer|pickaxe|oxytorch|hacksaw|axe|shovel|crowbar|boltcutters|compactor|gaspump|noise_emitter|repair_kit|camera_shutter|handcuffs`
194* `tool geiger_low|geiger_medium|geiger_high`
195* `trap bubble_wrap|bear_trap|snare|teleport|dissector|glass_caltrop|glass`
196
197### Various activities
198
199* `activity burrow`
200
201### Musical instruments
202
203* `musical_instrument <instrument>`
204* `musical_instrument_bad <instrument>`: used when you fail to play well
205
206### Various shouts and screams
207
208* `shout default|scream|scream_tortured|roar|squeak|shriek|wail|howl`
209
210### Speech
211
212This is currently linked with either item or monster id, with the exception of NPCs and robots.
213
214TODO: full vocalization of speech.json
215
216* `speech <item_id>` # examples: `talking_doll`, `creepy_doll`, `granade` (sic),
217* `speech <monster_id>` # examples: eyebot, minitank, mi-go, many robots
218* `speech NPC_m|NPC_f|NPC_m_loud|NPC_f_loud` # special for NPCs
219* `speech robot` # special for robotic voice from a machine etc.
220
221### Radio chatter
222
223* `radio static|inaudible_chatter`
224
225### Humming sounds of various origins
226
227* `humming electric|machinery`
228
229### Fire
230
231* `fire ignition`
232
233### Vehicle
234
235Engines and other parts in action. The defaults are executed when a specific option is not defined.
236
237* `engine_start <vehicle_part>`: specific engine start (ID of any `engine`/`motor`/`steam_engine`/`paddle`/`oar`/`sail`/etc.)
238* `engine_start combustion|electric|muscle|wind`: default engine starts groups
239* `engine_stop <vehicle_part>`: specific engine stop (ID of any `engine`/`motor`/`steam_engine`/`paddle`/`oar`/`sail`/etc.)
240* `engine_stop combustion|electric|muscle|wind`: default engine stop groups
241
242  Internal engine sound is dynamically pitch shifted depending on vehicle speed. It is an ambient looped sound with a dedicated channel.
243* `engine_working_internal <vehicle_part>`: sound of engine working heard inside vehicle
244* `engine_working_internal combustion|electric|muscle|wind`: default engine working (inside) groups
245
246  External engine sound volume and pan is dynamically shifted depending on distance and angle to vehicle. Volume heard at given distance is linked to engine's `noise_factor` and stress to the engine (see `vehicle::noise_and_smoke()`). It is an ambient looped sound with its own dedicated channel. This is a single-channel solution that picks loudest heard vehicle (TODO: multi-channel for every heard vehicle). There is no pitch shift here (may be introduced when need for it emerges).
247* `engine_working_external <vehicle_part>`: sound of engine working heard outside vehicle
248* `engine_working_external combustion|electric|muscle|wind`: default engine working (outside) groups
249
250  `gear_up`/`gear_down` is done automatically by pitch manipulation. Gear shift is dependent on max safe speed, and works on the assumption that there are 6 forward gears, gear 0 is neutral, and gear -1 is reverse.
251* `vehicle gear_shift`
252* `vehicle engine_backfire|engine_bangs_start|fault_immobiliser_beep|engine_single_click_fail|engine_multi_click_fail|engine_stutter_fail|engine_clanking_fail`
253* `vehicle horn_loud|horn_medium|horn_low|rear_beeper|chimes|car_alarm`
254* `vehicle reaper|scoop|scoop_thump`
255* `vehicle_open <vehicle_part>` # id of: doors, trunks, hatches, etc.
256* `vehicle_close <vehicle part>`
257
258### Miscellaneous
259
260* `misc flashbang|flash|shockwave|earthquake|stairs_movement|stones_grinding|bomb_ticking|lit_fuse|cow_bell|bell|timber`
261* `misc rc_car_hits_obstacle|rc_car_drives`
262* `misc default|whistle|airhorn|horn_bicycle|servomotor`
263* `misc beep|ding|`
264* `misc rattling|spitting|coughing|heartbeat|puff|inhale|exhale|insect_wings|snake_hiss` # mostly organic noises
265