Document sound-related cutscene steps

documentation/levels/cutscenes/README.md

@@ -43,10 +43,10 @@ after their final step is executed.
 
 See the pages below for details on specific cutscene steps.
 
-* play_sound (TODO)
+* [play_sound](./play_sound.md)
-* start_sound (TODO)
+* [start_sound](./start_sound.md)
-* q_sound (TODO)
+* [q_sound](./q_sound.md)
-* wait_for_channel (TODO)
+* [wait_for_channel](./wait_for_channel.md)
 * delay (TODO)
 * open_portal (TODO)
 * close_portal (TODO)

documentation/levels/cutscenes/play_sound.md

@@ -0,0 +1,25 @@
+# play_sound
+
+Plays a sound immediately and blocks until it has finished (unless looped).
+
+## Syntax
+
+```
+play_sound SOUND_ID [VOLUME] [SPEED]
+```
+
+## Arguments
+
+| Name                | Description                                                                                           |
+| ------------------- | ----------------------------------------------------------------------------------------------------- |
+| `SOUND_ID`          | The ID of the sound to play. `SOUNDS_` prefix can be omitted.                                         |
+| `VOLUME` (optional) | The volume to play the sound at. 0 is muted and 1 is normal volume.                                   |
+| `SPEED` (optional)  | The speed to play the sound at. Effectively a multiplier of the game's output sample rate (44100 Hz). |
+
+## Notes
+
+Only 12 sounds can be playing simultaneously. Any sounds played while at the
+limit are treated as if they have a length of zero.
+
+The game outputs audio at 44100 Hz but most sounds are sampled at 22050 Hz, and
+so a speed of 0.5 is needed for normal playback in the majority of cases.

documentation/levels/cutscenes/q_sound.md

@@ -0,0 +1,36 @@
+# q_sound
+
+Queues a sound to play without blocking.
+
+## Syntax
+
+```
+q_sound SOUND_ID CHANNEL_NAME SUBTITLE_ID [VOLUME]
+```
+
+## Arguments
+
+| Name                | Description                                                                                                                                |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `SOUND_ID`          | The ID of the sound to queue. `SOUNDS_` prefix can be omitted.                                                                             |
+| `CHANNEL_NAME`      | The name of the channel to queue the sound on                                                                                              |
+| `SUBTITLE_ID`       | The ID of the subtitle to display when playing the sound with subtitles enabled, or `SubtitleKeyNone`. Only shown for `CH_GLADOS` channel. |
+| `VOLUME` (optional) | The volume to play the sound at. 0 is muted and 1 is normal volume.                                                                        |
+
+## Notes
+
+There are three cutscene sound channels:
+
+* `CH_GLADOS`: Intended for GLaDOS dialog. The intercom chime sound is inserted
+               automatically, subtitles are shown (if enabled), and other sounds
+               are dampened while this channel is playing.
+* `CH_MUSIC`: Intended for music. Affected by the music volume setting in the
+              audio options menu.
+* `CH_AMBIENT`: Intended for test chamber ambience.
+
+Only one sound per channel is played at a time. A channel's current sound is
+played in its entirety before moving on to the next one queued on a first in,
+first out basis.
+
+A maximum of 25 sounds can be queued for each channel. Any queued while at the
+limit will be ignored.

documentation/levels/cutscenes/start_sound.md

@@ -0,0 +1,25 @@
+# starts_sound
+
+Starts a sound immediately without blocking.
+
+## Syntax
+
+```
+start_sound SOUND_ID [VOLUME] [SPEED]
+```
+
+## Arguments
+
+| Name                | Description                                                                                           |
+| ------------------- | ----------------------------------------------------------------------------------------------------- |
+| `SOUND_ID`          | The ID of the sound to start. `SOUNDS_` prefix can be omitted.                                        |
+| `VOLUME` (optional) | The volume to play the sound at. 0 is muted and 1 is normal volume.                                   |
+| `SPEED` (optional)  | The speed to play the sound at. Effectively a multiplier of the game's output sample rate (44100 Hz). |
+
+## Notes
+
+Only 12 sounds can be playing simultaneously. Any sounds started while at the
+limit are treated as if they have a length of zero.
+
+The game outputs audio at 44100 Hz but most sounds are sampled at 22050 Hz, and
+so a speed of 0.5 is needed for normal playback in the majority of cases.

documentation/levels/cutscenes/wait_for_channel.md

@@ -0,0 +1,15 @@
+# wait_for_channel
+
+Blocks until a specified sound channel has no queued or playing sounds.
+
+## Syntax
+
+```
+wait_for_channel CHANNEL_NAME
+```
+
+## Arguments
+
+| Name                | Description                                                                                                          |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `CHANNEL_NAME`      | The name of the channel to wait for. See [q_sound](./q_sound.md#notes) for details on channels and queue processing. |