Skip to content
Download

Sound and music (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. 32 functions, the newest from API 1.7.

Explanations and examples: Sound and music. Every function of the sound 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_sound_play cl.sound.play both TICK 1.0
cl_sound_play_except cl.sound.play_except server TICK 1.0
cl_sound_play_to_player cl.sound.play_to_player server TICK 1.0
cl_sound_play_at_entity cl.sound.play_at_entity both TICK 1.0
cl_sound_stop_for_player cl.sound.stop_for_player server TICK 1.0
cl_sound_play_local cl.sound.play_local client ANY 1.0
cl_sound_play_ui cl.sound.play_ui client ANY 1.0
cl_sound_stop cl.sound.stop client ANY 1.0
cl_sound_is_playing cl.sound.is_playing client ANY 1.0
cl_sound_stop_local cl.sound.stop_local client ANY 1.0
cl_sound_exists cl.sound.exists client ANY 1.0
cl_music_play cl.music.play client ANY 1.0
cl_music_stop cl.music.stop client ANY 1.0
cl_music_is_playing cl.music.is_playing client ANY 1.0
cl_sound_set_position cl.sound.set_position client ANY 1.7
cl_sound_position cl.sound.position client ANY 1.7
cl_sound_set_volume cl.sound.set_volume client ANY 1.7
cl_sound_volume cl.sound.volume client ANY 1.7
cl_sound_set_pitch cl.sound.set_pitch client ANY 1.7
cl_sound_pitch cl.sound.pitch client ANY 1.7
cl_sound_attach cl.sound.attach client ANY 1.7
cl_sound_detach cl.sound.detach client ANY 1.7
cl_sound_get_category cl.sound.get_category client ANY 1.7
cl_sound_event cl.sound.event client ANY 1.7
cl_sound_is_relative cl.sound.is_relative client ANY 1.7
cl_sound_is_voice cl.sound.is_voice client ANY 1.7
cl_sound_range cl.sound.range client ANY 1.7
cl_sound_set_range cl.sound.set_range client ANY 1.7
cl_sound_set_distance_model cl.sound.set_distance_model client ANY 1.7
cl_sound_set_filter cl.sound.set_filter client ANY 1.7
cl_sound_set_send cl.sound.set_send client ANY 1.7
cl_sound_playing cl.sound.playing client ANY 1.7

cl_sound_play

cl_result cl_sound_play(cl_level level, cl_vec3 pos, cl_str sound, cl_sound_category category, float volume, float pitch);

Level#playSound(null, …): every player near pos hears it. On a server level it is sent to the players within the attenuation range (16 x max(volume, 1) blocks); on the client level it plays locally only.

  • Side: both. Context: TICK (tick thread). Since: API 1.0.
  • Lua: cl.sound.play, level:play(...)
  • C++: Level::sound_play(cl_vec3 pos, std::string_view sound, cl_sound_category category, float volume, float pitch) → Expected<void>; clight::sound::play(Level level, cl_vec3 pos, std::string_view sound, cl_sound_category category, float volume, float pitch) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_sound_play_except

cl_result cl_sound_play_except(cl_level level, cl_entity except, cl_vec3 pos, cl_str sound, cl_sound_category category, float volume, float pitch);

Level#playSound(except, …): like sound_play but not sent to ‘except’ (the player who caused it, whose client predicts the sound itself).

  • Side: server. Context: TICK (tick thread). Since: API 1.0.
  • Lua: cl.sound.play_except, level:play_except(...)
  • C++: Level::sound_play_except(Entity except, cl_vec3 pos, std::string_view sound, cl_sound_category category, float volume, float pitch) → Expected<void>; clight::sound::play_except(Level level, Entity except, cl_vec3 pos, std::string_view sound, cl_sound_category category, float volume, float pitch) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_sound_play_to_player

cl_result cl_sound_play_to_player(cl_entity player, cl_vec3 pos, cl_str sound, cl_sound_category category, float volume, float pitch);

Only this player hears it (ServerPlayer#playNotifySound / a sound packet to one connection).

  • Side: server. Context: TICK (tick thread). Since: API 1.0.
  • Lua: cl.sound.play_to_player, entity:play_to_player(...)
  • C++: Entity::sound_play_to_player(cl_vec3 pos, std::string_view sound, cl_sound_category category, float volume, float pitch) → Expected<void>; clight::sound::play_to_player(Entity player, cl_vec3 pos, std::string_view sound, cl_sound_category category, float volume, float pitch) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_sound_play_at_entity

cl_result cl_sound_play_at_entity(cl_entity e, cl_str sound, cl_sound_category category, float volume, float pitch);

Entity#playSound: at the entity’s position, in the entity’s level, following vanilla’s rules (silent entities stay silent).

  • Side: both. Context: TICK (tick thread). Since: API 1.0.
  • Lua: cl.sound.play_at_entity, entity:play_at_entity(...)
  • C++: Entity::sound_play_at_entity(std::string_view sound, cl_sound_category category, float volume, float pitch) → Expected<void>; clight::sound::play_at_entity(Entity e, std::string_view sound, cl_sound_category category, float volume, float pitch) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_sound_stop_for_player

cl_result cl_sound_stop_for_player(cl_entity player, cl_str sound, cl_sound_category category);

ClientboundStopSoundPacket: stops a sound (empty = all) in a category (MASTER = all categories) for one player.

  • Side: server. Context: TICK (tick thread). Since: API 1.0.
  • Lua: cl.sound.stop_for_player, entity:stop_for_player(...)
  • C++: Entity::sound_stop_for_player(std::string_view sound, cl_sound_category category) → Expected<void>; clight::sound::stop_for_player(Entity player, std::string_view sound, cl_sound_category category) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_sound_play_local

cl_result cl_sound_play_local(cl_vec3 pos, cl_str sound, cl_sound_category category, float volume, float pitch, bool looping, cl_sound* out);

Plays a positional sound on this client only. ‘out’ can be used with cl_sound_stop.

  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.sound.play_local
  • C++: clight::sound::play_local(cl_vec3 pos, std::string_view sound, cl_sound_category category, float volume, float pitch, bool looping) → Expected<Sound>
  • 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_sound_play_ui

cl_result cl_sound_play_ui(cl_str sound, float volume, float pitch, cl_sound* out);

SimpleSoundInstance.forUI: non-positional, category UI (button clicks, notifications).

  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.sound.play_ui
  • C++: clight::sound::play_ui(std::string_view sound, float volume, float pitch) → Expected<Sound>
  • 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_sound_stop

cl_result cl_sound_stop(cl_sound s);
  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.sound.stop, sound:stop(...)
  • C++: Sound::stop() → Expected<void>; clight::sound::stop(Sound s) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_sound_is_playing

bool cl_sound_is_playing(cl_sound s);
  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.sound.is_playing, sound:is_playing(...)
  • C++: Sound::is_playing() → bool; clight::sound::is_playing(Sound s) → bool

cl_sound_stop_local

cl_result cl_sound_stop_local(cl_str sound, cl_sound_category category);

SoundEngine#stop(id, source) on this client: empty sound = all; MASTER = every category.

  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.sound.stop_local
  • C++: clight::sound::stop_local(std::string_view sound, cl_sound_category category) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_sound_exists

bool cl_sound_exists(cl_str sound);

Whether the sound event exists in the loaded sounds.json files (vanilla, packs and mods).

  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.sound.exists
  • C++: clight::sound::exists(std::string_view sound) → bool

cl_music_play

cl_result cl_music_play(cl_str sound, bool replace_vanilla);

MusicManager#startPlaying: replaces the current background music with this sound event (streamed). The vanilla music selection resumes after it ends unless ‘replace_vanilla’ is set (then call music_stop yourself).

  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.music.play, cl.sound.music_play (old name)
  • C++: clight::sound::music_play(std::string_view sound, bool replace_vanilla) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_music_stop

cl_result cl_music_stop(void);

Stops the music a mod started; vanilla music then resumes through its normal selection delay.

  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.music.stop, cl.sound.music_stop (old name)
  • C++: clight::sound::music_stop() → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_music_is_playing

bool cl_music_is_playing(void);
  • Side: client. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.music.is_playing, cl.sound.music_is_playing (old name)
  • C++: clight::sound::music_is_playing() → bool

cl_sound_set_position

cl_result cl_sound_set_position(cl_sound s, cl_vec3 pos);

Moves a playing sound (not for listener-relative sounds or voice chat; PCM streams may move).

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.sound.set_position, sound:set_position(...)
  • C++: Sound::set_position(cl_vec3 pos) → Expected<void>; clight::sound::set_position(Sound s, cl_vec3 pos) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_sound_position

cl_result cl_sound_position(cl_sound s, cl_vec3* out);
  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.sound.position, sound:position(...)
  • C++: Sound::position() → Expected<cl_vec3>; clight::sound::position(Sound s) → Expected<cl_vec3>
  • 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_sound_set_volume

cl_result cl_sound_set_volume(cl_sound s, float volume);

The sound’s own volume (0…1 before the volume sliders); on voice chat and PCM streams an extra gain (0…16).

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.sound.set_volume, sound:set_volume(...)
  • C++: Sound::set_volume(float volume) → Expected<void>; clight::sound::set_volume(Sound s, float volume) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_sound_volume

cl_result cl_sound_volume(cl_sound s, float* out);
  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.sound.volume, sound:volume(...)
  • C++: Sound::volume() → Expected<float>; clight::sound::volume(Sound s) → Expected<float>
  • 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_sound_set_pitch

cl_result cl_sound_set_pitch(cl_sound s, float pitch);

0.5…2 like vanilla (not for voice chat and PCM streams).

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.sound.set_pitch, sound:set_pitch(...)
  • C++: Sound::set_pitch(float pitch) → Expected<void>; clight::sound::set_pitch(Sound s, float pitch) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_sound_pitch

cl_result cl_sound_pitch(cl_sound s, float* out);
  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.sound.pitch, sound:pitch(...)
  • C++: Sound::pitch() → Expected<float>; clight::sound::pitch(Sound s) → Expected<float>
  • 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_sound_attach

cl_result cl_sound_attach(cl_sound s, cl_entity e, cl_vec3 offset);

The sound follows the entity (its position plus offset) every tick until it ends or sound_detach.

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.sound.attach, sound:attach(...)
  • C++: Sound::attach(Entity e, cl_vec3 offset) → Expected<void>; clight::sound::attach(Sound s, Entity e, cl_vec3 offset) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_sound_detach

cl_result cl_sound_detach(cl_sound s);
  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.sound.detach, sound:detach(...)
  • C++: Sound::detach() → Expected<void>; clight::sound::detach(Sound s) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_sound_get_category

cl_result cl_sound_get_category(cl_sound s, cl_sound_category* out);
  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.sound.get_category, sound:get_category(...)
  • C++: Sound::get_category() → Expected<cl_sound_category>; clight::sound::get_category(Sound s) → Expected<cl_sound_category>
  • 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_sound_event

cl_result cl_sound_event(cl_sound s, char* buf, size_t cap, size_t* out_len);

The sound event (“minecraft:entity.zombie.ambient”); “voice:<uuid>” for voice chat, “stream:<mod>” for PCM streams.

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.sound.event, sound:event(...)
  • C++: Sound::event() → Expected<std::string>; clight::sound::event(Sound s) → 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_sound_is_relative

bool cl_sound_is_relative(cl_sound s);
  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.sound.is_relative, sound:is_relative(...)
  • C++: Sound::is_relative() → bool; clight::sound::is_relative(Sound s) → bool

cl_sound_is_voice

bool cl_sound_is_voice(cl_sound s);

A voice chat stream (Simple Voice Chat) or a mod PCM stream.

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.sound.is_voice, sound:is_voice(...)
  • C++: Sound::is_voice() → bool; clight::sound::is_voice(Sound s) → bool

cl_sound_range

cl_result cl_sound_range(cl_sound s, float* out);

The audible range in blocks (Sound#getAttenuationDistance x max(volume, 1), or the value set by a mod).

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.sound.range, sound:range(...)
  • C++: Sound::range() → Expected<float>; clight::sound::range(Sound s) → Expected<float>
  • 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_sound_set_range

cl_result cl_sound_set_range(cl_sound s, float range);
  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.sound.set_range, sound:set_range(...)
  • C++: Sound::set_range(float range) → Expected<void>; clight::sound::set_range(Sound s, float range) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_sound_set_distance_model

cl_result cl_sound_set_distance_model(cl_sound s, cl_distance_model model, float rolloff);

rolloff: how fast the model falls off (1 = natural). LINEAR with rolloff 1 is vanilla.

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.sound.set_distance_model, sound:set_distance_model(...)
  • C++: Sound::set_distance_model(cl_distance_model model, float rolloff) → Expected<void>; clight::sound::set_distance_model(Sound s, cl_distance_model model, float rolloff) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_sound_set_filter

cl_result cl_sound_set_filter(cl_sound s, const cl_audio_filter* filter);

A filter on the sound’s direct path (null: none). Combined with the default filter and Sound Physics.

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

cl_sound_set_send

cl_result cl_sound_set_send(cl_sound s, cl_audio_bus bus, float gain, const cl_audio_filter* filter);

Sends the sound to an effect bus (gain 0: not to this bus, also not through a default route). The filter (optional) shapes only that send. CL_E_LIMIT past cl_audio_max_sends sends.

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

cl_sound_playing

cl_result cl_sound_playing(cl_sound* out, size_t cap, size_t* out_count);

Every sound playing on this client (vanilla, server, mod, voice chat, PCM streams).

  • Side: client. Context: ANY (any thread). Since: API 1.7.
  • Lua: cl.sound.playing
  • C++: clight::sound::playing() → Expected<std::vector<Sound>>
  • Fills an array: pointer / cap / out_count. Lua returns a list, C++ a std::vector.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.