xhookLua
Game

audio

Internet radio, music files and one-shot sounds; streams die with their script, handle 0 means failure.

Functions

audio.stream

audio.stream(url_or_path) -> integer
NameTypeDescription
url_or_pathstringhttp(s) URL or local path, UTF-8.

Plays anything Windows decodes from a URL or file.

Returns handle, or 0 on failure

  • Connecting to a URL blocks and can stall a frame.
  • Relative paths use the game's working directory; build absolute ones with engine.settings_path().

audio.play_file

audio.play_file(path [, rate]) -> integer
NameTypeDescription
pathstringLocal path or URL.
rateoptionalnumber0.25 to 4.0, speed and pitch. Default 1.0.

audio.stream with a playback rate, for music.

Returns handle, or 0 on failure

audio.position reports file seconds, not wall time.

audio.stop

audio.stop([handle])
NameTypeDescription
handleoptionalinteger0 or omitted stops all. Default 0.

Stops and frees a stream; the handle dies.

No handle stops every script's streams, not play_sound one-shots.

audio.pause

audio.pause(handle, paused)
NameTypeDescription
handleinteger
pausedbooleantrue pauses; false or omitted resumes.

Pauses or resumes a stream; unknown handles are ignored.

audio.set_volume

audio.set_volume([handle,] volume)
NameTypeDescription
handleoptionalintegerA stream from audio.stream or play_file.
volumenumberMaster 0.0 to 1.0; a stream 0.0 to 4.0. Clamped.

Master volume, or one stream's own volume with a handle.

Master default is 0.6. A stream's own is 1 and multiplies the master.

audio.volume

audio.volume([handle]) -> number
NameType
handleoptionalinteger

Master volume, or a stream's own with a handle.

Returns 0.0 to 1.0, or 0.0 to 4.0 for a stream

0 for an unknown handle.

audio.is_playing

audio.is_playing(handle) -> boolean
NameType
handleinteger

true while playing; false if ended, stopped, paused, failed or unknown.

False briefly right after audio.stream.

audio.position

audio.position(handle) -> number
NameType
handleinteger

Heard position from the device's play cursor, for music sync.

Returns seconds

0 for an unknown handle.

audio.duration

audio.duration(handle) -> number | nil
NameType
handleinteger

Total length of the stream.

Returns total seconds, or nil

nil for live radio or an unknown handle.

audio.seek

audio.seek(handle, seconds) -> boolean
NameTypeDescription
handleinteger
secondsnumberSong time, clamped to 0 and the duration.

Jumps a stream to a time in the song.

Returns true when the jump was accepted

false for live radio, an ended stream or an unknown handle.

audio.load_sound

audio.load_sound(path) -> integer
NameTypeDescription
pathstringAny format Windows decodes.

Decodes a short sound for play_sound; cached by path.

Returns sample id, or 0 on failure

  • Blocks while decoding; preload at script start.
  • Sounds longer than 30 seconds are cut at 30.

audio.play_sound

audio.play_sound(path_or_id [, gain]) -> integer
NameTypeDescription
path_or_idstring | integerSample id or path (cached).
gainoptionalnumberVolume multiplier; above 1 may clip. Default 1.0.

Fires an overlapping one-shot like a hitsound; cheap to spam.

Returns sample id, 0 if load failed

  • At most 64 play at once; extras are dropped.
  • One-shots cannot be stopped individually.

audio.tags

audio.tags(handle) -> table | nil
NameType
handleinteger

Stream metadata; bitrate is in kbps.

Returns {title, artist, bitrate}, or nil

title and artist come from file tags (ID3, WMA, MP4); live radio leaves them empty.

audio.spectrum

audio.spectrum(handle [, bins]) -> table
NameTypeDescription
handleinteger
binsoptionalintegerFrequency bands, up to 256. Default 32.

Left-channel magnitude spectrum of the last ~12 ms, for visualizers.

Returns 0.0 to 1.0, lowest frequency first

  • Empty table for an unknown handle or bins <= 0.
  • Runs about a second ahead of what you hear.
audio ยท Lua API ยท xhook