< GeeXLab Reference Guide />

gh_audio library

Description

gh_audio is the module that manages sounds: creation, destruction, playing. The audio module is based on FMOD and is available for the Windows, Linux and macOS platforms. For the Raspberry Pi platform, look at the gh_av library.

Number of functions: 22

gh_audio.sound_create ()
gh_audio.sound_create_v3 ()
gh_audio.sound_create_from_buffer ()
gh_audio.sound_create_from_sqlite3_blob ()
gh_audio.sound_create_from_zip ()
gh_audio.sound_create_v2 ()
gh_audio.sound_get_duration_ms ()
gh_audio.sound_get_open_state ()
gh_audio.sound_get_position_ms ()
gh_audio.sound_get_volume ()
gh_audio.sound_is_playing ()
gh_audio.sound_kill ()
gh_audio.sound_play ()
gh_audio.sound_set_loop_state ()
gh_audio.sound_set_paused ()
gh_audio.sound_set_volume ()
gh_audio.sound_spectrum_get_num_values ()
gh_audio.sound_spectrum_get_value ()
gh_audio.sound_spectrum_read ()
gh_audio.sound_spectrum_read_v2 ()
gh_audio.sound_update_audio_data_params ()
gh_audio.update ()

sound_create

Description

Creates a sound.

Syntax

sound_id = gh_audio.sound_create( filename, absolute_path, streaming )

Languages

Parameters

filename [STRING]: audio filename
absolute_path [BOOLEAN]: file path: 1 (absolute) or 0 (relative)
streaming [BOOLEAN]: streaming: 1 (enabled) or 0 (disabled)

Return Values

sound_id [ID]: sound identifier

Code sample


filename = demo_dir .. "audio/sound01.mp3"
local is_absolute_path = 0
sound_id = gh_audio.sound_create(filename, is_absolute_path, 1)

sound_create_v3

Description

Creates a sound from a absolute path filename.

Syntax

sound_id = gh_audio.sound_create_v3( filename, streaming )

Languages

Parameters

filename [STRING]: audio filename
streaming [BOOLEAN]: streaming: 1 (enabled) or 0 (disabled)

Return Values

sound_id [ID]: sound identifier

Code sample


filename = demo_dir .. "audio/sound01.mp3"
streaming = 1
sound_id = gh_audio.sound_create_v3(filename, streaming)

sound_create_from_buffer

Description

Creates a sound from a memory buffer.

Syntax

sound_id = gh_audio.sound_create_from_buffer( buff_ptr, buff_size, streaming )

Languages

Parameters

buff_ptr [POINTER]: pointer to the buffer
buff_size [INTEGER]: size of the buffer in bytes
streaming [BOOLEAN]: streaming: 1 (enabled) or 0 (disabled)

Return Values

sound_id [ID]: sound identifier

Code sample


buffer, buffer_size = gh_utils.file_buffer_create(audio_filename)
sound_id = gh_audio.sound_create_from_buffer(buffer, buffer_size, 0)
gh_utils.file_buffer_kill(buffer)

sound_create_from_sqlite3_blob

Description

Creates a sound from raw data stored a in a SQLite3 blob.

Syntax

sound_id = gh_audio.sound_create_from_sqlite3_blob( db_id, column, streaming )

Languages

Parameters

db_id [ID]: database identifier
column [INTEGER]: index of the column
streaming [BOOLEAN]: streaming: 1 (enabled) or 0 (disabled)

Return Values

sound_id [ID]: sound identifier

Code sample


sound_id = gh_audio.sound_create_from_sqlite3_blob_v1(db_id, column, 0)

sound_create_from_zip

Description

Creates a sound from a filename stored a in zip archive.

Syntax

sound_id = gh_audio.sound_create_from_zip( zip_filename, filename, streaming )

Languages

Parameters

zip_filename [STRING]: absolute path of the zip file
filename [STRING]: sound file in the zip archive
streaming [BOOLEAN]: streaming: 1 (enabled) or 0 (disabled)

Return Values

sound_id [ID]: sound identifier

Code sample


zip_filename = demo_dir .. "data.zip"
sound_id = gh_audio.sound_create_from_zip(zip_filename, "audio/sound01.wav", 0)

sound_create_v2

Description

Creates a sound - Not well tested / experimental

Syntax

sound_id = gh_audio.sound_create_v2( sampling_rate, num_channels, duration_sec, bits_per_sample, frequency, generator_type, volume, time )

Languages

Parameters

sampling_rate [INTEGER]: sampling rate
num_channels [INTEGER]: number of channels
duration_sec [INTEGER]: duration in seconds
bits_per_sample [INTEGER]: bits per sample
frequency [INTEGER]: frequency in Hz
generator_type [ENUM]: type of sound generator (1 to 4)
volume [REAL]: sound volume
time [REAL]: time

Return Values

sound_id [ID]: sound identifier

Code sample


FMOD_GENERATOR_SINE_WAVE = 1
FMOD_GENERATOR_SAWTOOTH = 2
FMOD_GENERATOR_SQUARE = 3
FMOD_GENERATOR_WHITE_NOISE = 4

generator_type = FMOD_GENERATOR_SINE_WAVE

sound_id = gh_audio.sound_create_v2(sampling_rate, num_channels, duration_sec, bits_per_sample, frequency, generator_type, volume, time)

sound_get_duration_ms

Description

Gets the duration of a sound in milliseconds.

Syntax

duration = gh_audio.sound_get_duration_ms( sound_id )

Languages

Parameters

sound_id [ID]: sound identifier

Return Values

duration [INTEGER]: duration in milliseconds

Code sample


duration = gh_audio.sound_get_duration_ms(sound_id)

sound_get_open_state

Description

Gets the open status of a sound.

Syntax

open_state, percent_buffered = gh_audio.sound_get_open_state( sound_id )

Languages

Parameters

sound_id [ID]: sound identifier

Return Values

open_state [ENUM]: state (0 to 7)
percent_buffered [INTEGER]: percent buffered

Code sample


-- Possible states
FMOD_OPENSTATE_READY = 0 -- Opened and ready to play.
FMOD_OPENSTATE_LOADING = 1 -- Initial load in progress.
FMOD_OPENSTATE_ERROR = 2 -- Failed to open - file not found, out of memory etc.
FMOD_OPENSTATE_CONNECTING = 3 -- Connecting to remote host (internet sounds only).
FMOD_OPENSTATE_BUFFERING = 4 -- Buffering data.
FMOD_OPENSTATE_SEEKING = 5 -- Seeking to subsound and re-flushing stream buffer.
FMOD_OPENSTATE_PLAYING = 6 -- Ready and playing, but not possible to release at this time without stalling the main thread.
FMOD_OPENSTATE_SETPOSITION = 7 -- Seeking within a stream to a different position.

open_state, percentbuffered = gh_audio.sound_get_open_state(sound_id)

sound_get_position_ms

Description

Gets the current position in a sound instance in milliseconds.

Syntax

position = gh_audio.sound_get_position_ms( sound_id, channel )

Languages

Parameters

sound_id [ID]: sound identifier
channel [INTEGER]: sound instance

Return Values

position [INTEGER]: current position in milliseconds

Code sample


position = gh_audio.sound_get_position_ms(sound_id, channel)

sound_get_volume

Description

Gets the volume level of a particular sound instance.

Syntax

volume = gh_audio.sound_get_volume( sound_id, channel )

Languages

Parameters

sound_id [ID]: sound identifier
channel [INTEGER]: sound instance

Return Values

volume [REAL]: volume from 0.0 to 1.0

Code sample


volume = gh_audio.sound_get_volume(sound_id, channel)

sound_is_playing

Description

Checks if a sound is currently playing.

Syntax

is_playing = gh_audio.sound_is_playing( sound_id, channel )

Languages

Parameters

sound_id [ID]: sound identifier
channel [INTEGER]: sound instance

Return Values

is_playing [BOOLEAN]: playing state: 1 (true) or 0 (false)

Code sample


is_playing = gh_audio.sound_is_playing(sound_id, channel)

sound_kill

Description

Destroys a sound.

Syntax

gh_audio.sound_kill( sound_id )

Languages

Parameters

sound_id [ID]: sound identifier

Return Values

This function has no return value(s).

Code sample


gh_audio.sound_kill(sound_id)

sound_play

Description

Plays a sound.

Syntax

channel = gh_audio.sound_play( sound_id )

Languages

Parameters

sound_id [ID]: sound identifier

Return Values

channel [INTEGER]: sound instance

Code sample


channel = gh_audio.sound_play(sound_id)

sound_set_loop_state

Description

Sets the loop state.

Syntax

gh_audio.sound_set_loop_state( sound_id, state )

Languages

Parameters

sound_id [ID]: sound identifier
state [BOOLEAN]: 1 (enabled) or 0 (disabled)

Return Values

This function has no return value(s).

Code sample


gh_audio.sound_set_loop_state(sound_id, 1)

sound_set_paused

Description

Sets the paused state of a particular sound instance.

Syntax

gh_audio.sound_set_paused( sound_id, channel, state )

Languages

Parameters

sound_id [ID]: sound identifier
channel [INTEGER]: sound instance
state [BOOLEAN]: paused: 1 (true) or 0 (false)

Return Values

This function has no return value(s).

Code sample


gh_audio.sound_set_paused(sound_id, channel, 1)

sound_set_volume

Description

Sets the volume level of a particular sound instance.

Syntax

gh_audio.sound_set_volume( sound_id, channel, volume )

Languages

Parameters

sound_id [ID]: sound identifier
channel [INTEGER]: sound instance
volume [REAL]: volume from 0.0 to 1.0

Return Values

This function has no return value(s).

Code sample


gh_audio.sound_set_volume(sound_id, channel, 0.5)

sound_spectrum_get_num_values

Description

Gets the number of entries in the audio buffer.

Syntax

num_entries = gh_audio.sound_spectrum_get_num_values( sound_id, channel )

Languages

Parameters

sound_id [ID]: sound identifier
channel [INTEGER]: sound instance

Return Values

num_entries [INTEGER]: number of entries

Code sample


num_values = gh_audio.sound_spectrum_get_num_values(sound_id, channel)

sound_spectrum_get_value

Description

Gets a particular value from the audio buffer.

Syntax

value = gh_audio.sound_spectrum_get_value( sound_id, channel, value_index )

Languages

Parameters

sound_id [ID]: sound identifier
channel [INTEGER]: sound instance
value_index [INTEGER]: entry index (from 0 to num_values-1)

Return Values

value [REAL]: value

Code sample


local value = gh_audio.sound_spectrum_get_value(sound_id, channel, value_index)

sound_spectrum_read

Description

Reads the audio buffer.

Syntax

gh_audio.sound_spectrum_read( sound_id, channel )

Languages

Parameters

sound_id [ID]: sound identifier
channel [INTEGER]: sound instance

Return Values

This function has no return value(s).

Code sample


gh_audio.sound_spectrum_read(sound_id, channel)

sound_spectrum_read_v2

Description

Reads the audio buffer.

Syntax

gh_audio.sound_spectrum_read_v2( sound_id, channel, fft_window_type )

Languages

Parameters

sound_id [ID]: sound identifier
channel [INTEGER]: sound instance
fft_window_type [ENUM]: FFT window type - Default value: window_hamming

Return Values

This function has no return value(s).

Code sample


-- Possible window types:
"window_rect"
"window_triangle"
"window_hamming" -- Default value
"window_hanning"
"window_blackman"
"window_blackmanharris"

fft_window_type =  "window_hamming"
gh_audio.sound_spectrum_read_v2(sound_id, channel, fft_window_type)

sound_update_audio_data_params

Description

Updates parameters of a sound that has been created with sound_create_v2().

Syntax

gh_audio.sound_update_audio_data_params( sound_id, sampling_rate, num_channels, duration_sec, bits_per_sample, frequency, generator_type, volume, time )

Languages

Parameters

sound_id [ID]: sound identifier
sampling_rate [INTEGER]: sampling rate
num_channels [INTEGER]: number of channels
duration_sec [INTEGER]: duration in seconds
bits_per_sample [INTEGER]: bits per sample
frequency [INTEGER]: frequency in Hz
generator_type [ENUM]: type of sound generator (1 to 4)
volume [REAL]: sound volume
time [REAL]: time

Return Values

This function has no return value(s).

Code sample


FMOD_GENERATOR_SINE_WAVE = 1
FMOD_GENERATOR_SAWTOOTH = 2
FMOD_GENERATOR_SQUARE = 3
FMOD_GENERATOR_WHITE_NOISE = 4

generator_type = FMOD_GENERATOR_SINE_WAVE

gh_audio.sound_update_audio_data_params(sound_id, sampling_rate, num_channels, duration_sec, bits_per_sample, frequency, generator_type, volume, time)

update

Description

Updates the sound system. Must be called once per frame.

Syntax

gh_audio.update()

Languages

Parameters

This function has no input parameter(s).

Return Values

This function has no return value(s).

Code sample


gh_audio.update()

GeeXLab Rootard Guide | Downloads | Contact