Skip to content
Download

Audio and effects (function list)

Status: Implemented (API 1.24). Generated from client/clight/idl/clight_api.json by tools/docs/gen_api_reference.py; do not edit by hand. 21 functions, the newest from API 1.7.

Explanations and examples: Sound and music, Guide: Audio and effects. Every function of the audio module is listed here in table order. The details of each function follow the table, in the same order. Side: where the function works (server, client, both). Context: the thread it may be called on (Conventions). Since: the API version that added it.

C function Lua Side Context Since
cl_audio_bus_create cl.audio.bus_create client ANY 1.7
cl_audio_bus_set cl.audio.bus_set client ANY 1.7
cl_audio_bus_set_vec3 cl.audio.bus_set_vec3 client ANY 1.7
cl_audio_bus_set_gain cl.audio.bus_set_gain client ANY 1.7
cl_audio_bus_set_output cl.audio.bus_set_output client ANY 1.7
cl_audio_bus_remove cl.audio.bus_remove client ANY 1.7
cl_audio_bus_effect cl.audio.bus_effect client ANY 1.7
cl_audio_route_default cl.audio.route_default client ANY 1.7
cl_audio_route_remove cl.audio.route_remove client ANY 1.7
cl_audio_set_default_filter cl.audio.set_default_filter client ANY 1.7
cl_audio_max_sends cl.audio.max_sends client ANY 1.7
cl_audio_efx_available cl.audio.efx_available client ANY 1.7
cl_audio_hrtf_enabled cl.audio.hrtf_enabled client ANY 1.7
cl_audio_get_listener cl.audio.get_listener client ANY 1.7
cl_audio_stream_open cl.audio.stream_open client ANY 1.7
cl_audio_stream_push cl.audio.stream_push client ANY 1.7
cl_audio_stream_queued cl.audio.stream_queued client ANY 1.7
cl_audio_stream_sound cl.audio.stream_sound client ANY 1.7
cl_audio_stream_close cl.audio.stream_close client ANY 1.7
cl_audio_trace_paths cl.audio.trace_paths client ANY 1.7
cl_audio_trace_acoustics cl.audio.trace_acoustics client ANY 1.7

cl_audio_bus_create

cl_result cl_audio_bus_create(cl_str effect, cl_audio_bus* out);

effect: “reverb”, “echo”, “chorus”, “distortion”, “flanger”, “ring_modulator”, “pitch_shifter”, “equalizer”, “compressor”, “autowah”, “frequency_shifter”, “vocal_morpher”. Works without an EFX device too (silently).

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.bus_create
  • C++: clight::audio::bus_create(std::string_view effect) → Expected<AudioBus>
  • The last parameter receives the result. Lua returns it; C++ returns it in Expected<T>.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_audio_bus_set

cl_result cl_audio_bus_set(cl_audio_bus bus, cl_str param, float value);

One effect parameter by its EFX name in snake case (“decay_time”, “delay”…); smoothed, so changing it every tick never clicks. CL_E_NOT_FOUND for a name the effect does not have.

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.bus_set, audio_bus:set(...)
  • C++: AudioBus::set(std::string_view param, float value) → Expected<void>; clight::audio::bus_set(AudioBus bus, std::string_view param, float value) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_audio_bus_set_vec3

cl_result cl_audio_bus_set_vec3(cl_audio_bus bus, cl_str param, cl_vec3 value);

A vector parameter (reverb “reflections_pan”, “late_reverb_pan”).

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.bus_set_vec3, audio_bus:set_vec3(...)
  • C++: AudioBus::set_vec3(std::string_view param, cl_vec3 value) → Expected<void>; clight::audio::bus_set_vec3(AudioBus bus, std::string_view param, cl_vec3 value) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_audio_bus_set_gain

cl_result cl_audio_bus_set_gain(cl_audio_bus bus, float gain);

The bus output level (0…1).

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.bus_set_gain, audio_bus:set_gain(...)
  • C++: AudioBus::set_gain(float gain) → Expected<void>; clight::audio::bus_set_gain(AudioBus bus, float gain) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_audio_bus_set_output

cl_result cl_audio_bus_set_output(cl_audio_bus bus, cl_audio_bus target);

Chains the bus into another one (0: the main mix). CL_E_UNSUPPORTED without AL_SOFT_effect_target.

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.bus_set_output, audio_bus:set_output(...)
  • C++: AudioBus::set_output(AudioBus target) → Expected<void>; clight::audio::bus_set_output(AudioBus bus, AudioBus target) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_audio_bus_remove

cl_result cl_audio_bus_remove(cl_audio_bus bus);
  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.bus_remove, audio_bus:remove(...)
  • C++: AudioBus::remove() → Expected<void>; clight::audio::bus_remove(AudioBus bus) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_audio_bus_effect

cl_result cl_audio_bus_effect(cl_audio_bus bus, char* buf, size_t cap, size_t* out_len);
  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.bus_effect, audio_bus:effect(...)
  • C++: AudioBus::effect() → Expected<std::string>; clight::audio::bus_effect(AudioBus bus) → Expected<std::string>
  • Writes a string: buf / cap / out_len (a too small buffer returns CL_E_BUFFER_TOO_SMALL with the needed length in *out_len). Lua and C++ return the string.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_audio_route_default

cl_result cl_audio_route_default(cl_audio_bus bus, float gain, cl_audio_categories categories, bool positional_only, const cl_audio_filter* filter);

Every new and playing sound of the categories gets a send to the bus (positional_only: not music / UI / listener-relative sounds). One route per bus (calling again replaces it).

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.route_default, audio_bus:route_default(...)
  • C++: AudioBus::route_default(float gain, cl_audio_categories categories, bool positional_only, const cl_audio_filter* filter) → Expected<void>; clight::audio::route_default(AudioBus bus, float gain, cl_audio_categories categories, bool positional_only, const cl_audio_filter* filter) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_audio_route_remove

cl_result cl_audio_route_remove(cl_audio_bus bus);
  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.route_remove, audio_bus:route_remove(...)
  • C++: AudioBus::route_remove() → Expected<void>; clight::audio::route_remove(AudioBus bus) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_audio_set_default_filter

cl_result cl_audio_set_default_filter(const cl_audio_filter* filter);

A filter on every positional sound (underwater, deafness…); null clears it.

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.set_default_filter
  • C++: clight::audio::set_default_filter(const cl_audio_filter* filter) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_audio_max_sends

int32_t cl_audio_max_sends(void);

Sends a sound can have to mod buses: the device’s sends minus the 4 Sound Physics uses while it is on.

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.max_sends
  • C++: clight::audio::max_sends() → int32_t

cl_audio_efx_available

bool cl_audio_efx_available(void);

Whether the device has EFX (filters and effects are audible); without it the API works but nothing is heard.

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.efx_available
  • C++: clight::audio::efx_available() → bool

cl_audio_hrtf_enabled

bool cl_audio_hrtf_enabled(void);
  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.hrtf_enabled
  • C++: clight::audio::hrtf_enabled() → bool

cl_audio_get_listener

cl_result cl_audio_get_listener(cl_audio_listener* out);

The camera the sounds are heard from (Lua: cl.audio.listener(), in_fluid nil on land).

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.get_listener
  • C++: clight::audio::get_listener() → Expected<cl_audio_listener>
  • The last parameter receives the result. Lua returns it; C++ returns it in Expected<T>.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_audio_stream_open

cl_result cl_audio_stream_open(const cl_audio_stream_opts* opts, cl_audio_stream* out);
  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.stream_open
  • C++: clight::audio::stream_open(const cl_audio_stream_opts* opts) → Expected<AudioStream>
  • The last parameter receives the result. Lua returns it; C++ returns it in Expected<T>.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_audio_stream_push

cl_result cl_audio_stream_push(cl_audio_stream st, cl_str pcm);

pcm: signed 16-bit little-endian samples, channels interleaved (Lua: a string from string.pack or a table of numbers). At most 2 s are buffered; CL_E_LIMIT when full.

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.stream_push, audio_stream:push(...)
  • C++: AudioStream::push(std::string_view pcm) → Expected<void>; clight::audio::stream_push(AudioStream st, std::string_view pcm) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_audio_stream_queued

cl_result cl_audio_stream_queued(cl_audio_stream st, int32_t* out);

Frames buffered and not played yet.

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.stream_queued, audio_stream:queued(...)
  • C++: AudioStream::queued() → Expected<int32_t>; clight::audio::stream_queued(AudioStream st) → Expected<int32_t>
  • The last parameter receives the result. Lua returns it; C++ returns it in Expected<T>.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_audio_stream_sound

cl_sound cl_audio_stream_sound(cl_audio_stream st);

The stream as a sound (position, volume, filters and sends).

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.stream_sound, audio_stream:sound(...)
  • C++: AudioStream::sound() → Sound; clight::audio::stream_sound(AudioStream st) → Sound

cl_audio_stream_close

cl_result cl_audio_stream_close(cl_audio_stream st);
  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.stream_close, audio_stream:close(...)
  • C++: AudioStream::close() → Expected<void>; clight::audio::stream_close(AudioStream st) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_audio_trace_paths

cl_result cl_audio_trace_paths(cl_vec3 from, cl_vec3 to, const cl_audio_trace_opts* opts, cl_audio_trace* out);

Synchronous native line trace (client thread; a few microseconds for 48 blocks).

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.trace_paths
  • C++: clight::audio::trace_paths(cl_vec3 from, cl_vec3 to, const cl_audio_trace_opts* opts) → Expected<cl_audio_trace>
  • The last parameter receives the result. Lua returns it; C++ returns it in Expected<T>.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_audio_trace_acoustics

cl_result cl_audio_trace_acoustics(cl_vec3 from, cl_vec3 to, cl_audio_acoustics* out);
  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.audio.trace_acoustics
  • C++: clight::audio::trace_acoustics(cl_vec3 from, cl_vec3 to) → Expected<cl_audio_acoustics>
  • The last parameter receives the result. Lua returns it; C++ returns it in Expected<T>.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.