< GeeXLab Reference Guide />

> Back to Reference Guide Index


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: 21

  1. gh_audio.sound_create ()
  2. gh_audio.sound_create_from_buffer ()
  3. gh_audio.sound_create_from_sqlite3_blob ()
  4. gh_audio.sound_create_from_zip ()
  5. gh_audio.sound_create_v2 ()
  6. gh_audio.sound_get_duration_ms ()
  7. gh_audio.sound_get_open_state ()
  8. gh_audio.sound_get_position_ms ()
  9. gh_audio.sound_get_volume ()
  10. gh_audio.sound_is_playing ()
  11. gh_audio.sound_kill ()
  12. gh_audio.sound_play ()
  13. gh_audio.sound_set_loop_state ()
  14. gh_audio.sound_set_paused ()
  15. gh_audio.sound_set_volume ()
  16. gh_audio.sound_spectrum_get_num_values ()
  17. gh_audio.sound_spectrum_get_value ()
  18. gh_audio.sound_spectrum_read ()
  19. gh_audio.sound_spectrum_read_v2 ()
  20. gh_audio.sound_update_audio_data_params ()
  21. gh_audio.update ()



sound_create

Description

Creates a sound.


Syntax

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

Languages


Parameters


Return Values


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_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


Return Values


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


Return Values


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


Return Values


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


Return Values


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


Return Values


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


Return Values


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


Return Values


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


Return Values


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


Return Values


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


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


Return Values


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


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


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


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


Return Values


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


Return Values


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


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


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


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 | Newsletter