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| Name | Type | Description |
|---|---|---|
| url_or_path | string | http(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| Name | Type | Description |
|---|---|---|
| path | string | Local path or URL. |
| rateoptional | number | 0.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])| Name | Type | Description |
|---|---|---|
| handleoptional | integer | 0 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)| Name | Type | Description |
|---|---|---|
| handle | integer | |
| paused | boolean | true pauses; false or omitted resumes. |
Pauses or resumes a stream; unknown handles are ignored.
audio.set_volume
audio.set_volume([handle,] volume)| Name | Type | Description |
|---|---|---|
| handleoptional | integer | A stream from audio.stream or play_file. |
| volume | number | Master 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| Name | Type |
|---|---|
| handleoptional | integer |
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| Name | Type |
|---|---|
| handle | integer |
true while playing; false if ended, stopped, paused, failed or unknown.
False briefly right after audio.stream.
audio.position
audio.position(handle) -> number| Name | Type |
|---|---|
| handle | integer |
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| Name | Type |
|---|---|
| handle | integer |
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| Name | Type | Description |
|---|---|---|
| handle | integer | |
| seconds | number | Song 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| Name | Type | Description |
|---|---|---|
| path | string | Any 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| Name | Type | Description |
|---|---|---|
| path_or_id | string | integer | Sample id or path (cached). |
| gainoptional | number | Volume 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| Name | Type |
|---|---|
| handle | integer |
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| Name | Type | Description |
|---|---|---|
| handle | integer | |
| binsoptional | integer | Frequency 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.