205 lines
6.3 KiB
Markdown
205 lines
6.3 KiB
Markdown
# Audio
|
|
|
|
## Definitions
|
|
|
|
### Backend
|
|
|
|
Internal audio system implementation controlling audio output.
|
|
- NoAudio - dummy audio used on OpenAL initialize fail or if audio is disabled by the *settings.toml*: *\[audio\] enabled=false*
|
|
- ALAudio - OpenAL audio used
|
|
|
|
### Channel
|
|
|
|
Defines a sound sources category for group volume control, effects and pause.
|
|
|
|
Now the engine has following channels:
|
|
- *master* - controls other channels volume. Should not be used as a target channel when playing an audio.
|
|
- *ui* - ui elements sounds (button clicks and other)
|
|
- *regular* - world sounds, that will be paused with the game.
|
|
- *ambient* - same as *regular* but added for background and ambient sounds/streams like weather.
|
|
- *music* - music channel.
|
|
|
|
Channels are controlled by the engine and currently are not available in scripts.
|
|
|
|
### Speaker
|
|
|
|
One-time use playing audio controller for sound or stream. Speaker is destroying after stop (**stop** method call or audio track end if not looped)
|
|
|
|
> [!NOTE]
|
|
> Speaker access is performed using 64 bit integer identifiers that **will not be reused** after speaker destruction. You should avoid storing direct references and pointers instead of ID.
|
|
|
|
Speaker ID starts with 1, so 0 means audio play failure.
|
|
|
|
### Sound
|
|
|
|
Audio data loaded in memory to play multiple simultaneous instances from multiple sources. Can give access to loaded PCM data.
|
|
|
|
### PCMStream (PCM data source)
|
|
|
|
Stream used by an audio stream as an audio data source. Implementation depends on audio file format, not a backend. This interface may be used to implement network audio stream.
|
|
|
|
### Stream
|
|
|
|
Streaming audio. Not fully loading to the memory. Cannot be played via multiple speakers simultaneously.
|
|
|
|
## Formats support
|
|
|
|
- WAV: 8 and 16 bit supported (24 bit is not supported by OpenAL)
|
|
- OGG: implemented with libvorbis
|
|
|
|
## Additional information
|
|
|
|
> [!WARNING]
|
|
> **Stereo** audio played with OpenAL will ignore 3D position relative to the listener. Sounds that supposed to be played at specific world position must be **mono**
|
|
|
|
## Scripting Audio API
|
|
|
|
### Playing audio
|
|
|
|
Library **audio** contains available Audio API in Lua scripts.
|
|
|
|
```lua
|
|
audio.play_stream(
|
|
-- audio file location
|
|
name: string,
|
|
-- audio source world position
|
|
x: number, y: number, z: number,
|
|
-- audio gain (0.0 - 1.0)
|
|
volume: number
|
|
-- audio playback speed (positive number)
|
|
pitch: number,
|
|
-- [optional] channel name: regular/ambient/music/ui (default - regular)
|
|
channel: string,
|
|
-- [optional] loop stream (default - false)
|
|
loop: bool
|
|
) -> int
|
|
```
|
|
|
|
Plays streaming audio from the specified file at the specified world position. Returns speaker ID.
|
|
|
|
```lua
|
|
audio.play_stream_2d(
|
|
-- audio file location
|
|
name: string,
|
|
-- audio gain (0.0 - 1.0)
|
|
volume: number
|
|
-- audio playback speed (positive number)
|
|
pitch: number,
|
|
-- [optional] channel name: regular/ambient/music/ui (default - regular)
|
|
channel: string,
|
|
-- [optional] loop stream (default - false)
|
|
loop: bool
|
|
) -> int
|
|
|
|
```
|
|
|
|
Plays streaming audio from the specified file. Returns speaker ID.
|
|
|
|
```lua
|
|
audio.play_sound(
|
|
-- name of a loaded sound without pack prefix, "sounds/", variant number and extension
|
|
-- example: "steps/stone" to play sound loaded from "sounds/steps/stone.ogg" or any of its variant
|
|
-- variant will be randomly chosen
|
|
name: string,
|
|
-- audio source world position
|
|
x: number, y: number, z: number,
|
|
-- audio gain (0.0 - 1.0)
|
|
volume: number
|
|
-- audio playback speed (positive number)
|
|
pitch: number,
|
|
-- [optional] channel name: regular/ambient/music/ui (default - regular)
|
|
channel: string,
|
|
-- [optional] loop sound (default - false)
|
|
loop: bool
|
|
) -> int
|
|
```
|
|
|
|
Plays the specified sound on the specified position in world. Returns speaker ID.
|
|
|
|
```lua
|
|
audio.play_sound_2d(
|
|
-- name of a loaded sound without pack prefix, "sounds/", variant number and extension
|
|
-- example: "steps/stone" to play sound loaded from "sounds/steps/stone.ogg" or any of its variant
|
|
-- variant will be randomly chosen
|
|
name: string,
|
|
-- audio gain (0.0 - 1.0)
|
|
volume: number
|
|
-- audio playback speed (positive number)
|
|
pitch: number,
|
|
-- [optional] channel name: regular/ambient/music/ui (default - regular)
|
|
channel: string,
|
|
-- [optional] loop sound (default - false)
|
|
loop: bool
|
|
) -> int
|
|
```
|
|
|
|
Plays the specified sound. Returns speaker ID.
|
|
|
|
### Speaker interaction
|
|
|
|
Interaction with a non-existing or destroyed speaker will be ignored.
|
|
|
|
|
|
```lua
|
|
-- stop audio playback and destroy the speaker
|
|
audio.stop(speakerid: integer)
|
|
|
|
-- pause speaker
|
|
audio.pause(speakerid: integer)
|
|
|
|
-- unpause speaker
|
|
audio.resume(speakerid: integer)
|
|
|
|
-- set audio loop
|
|
audio.set_loop(speakerid: integer, state: bool)
|
|
|
|
-- check if audio is in loop (false if does not exists)
|
|
audio.is_loop(speakerid: integer) -> bool
|
|
|
|
-- get audio gain value (0.0 if does not exists)
|
|
audio.get_volume(speakerid: integer) -> number
|
|
|
|
-- set audio gain value
|
|
audio.set_volume(speakerid: integer, volume: number)
|
|
|
|
-- get audio playback speed (1.0 if does not exists)
|
|
audio.get_pitch(speakerid: integer) -> number
|
|
|
|
-- set audio playback speed
|
|
audio.set_pitch(speakerid: integer, pitch: number)
|
|
|
|
-- get current audio playback time in seconds (0.0 if does not exists)
|
|
audio.get_time(speakerid: integer) -> number
|
|
|
|
-- set audio playback time position in seconds
|
|
audio.set_time(speakerid: integer, time: number)
|
|
|
|
-- get audio source world position (nil if does not exists)
|
|
audio.get_position(speakerid: integer) -> number, number, number
|
|
|
|
-- set audio source world position
|
|
audio.set_position(speakerid: integer, x: number, y: number, z: number)
|
|
|
|
-- get audio source movement speed in world (nil if does not exists)
|
|
-- (OpenAL uses it for Doppler effect simulation)
|
|
audio.get_velocity(speakerid: integer) -> number, number, number
|
|
|
|
-- set audio source movement speed in world
|
|
-- (OpenAL uses it for Doppler effect simulation)
|
|
audio.set_velocity(speakerid: integer, x: number, y: number, z: number)
|
|
|
|
-- get audio duration
|
|
-- returns 0, if does not exists
|
|
-- also returns 0, if duration is unknown (example: radio)
|
|
audio.get_duration(speakerid: integer) -> number
|
|
```
|
|
|
|
### Other functions
|
|
|
|
```lua
|
|
-- get current number of alive speakers
|
|
audio.count_speakers() -> integer
|
|
|
|
-- get current number of playing streams
|
|
audio.count_streams() -> integer
|
|
``` |