The sound sprite module helps you to save memory when you have a lot
of short sound files (like dialogues in a video game): compile them
into a single sound file and write an according configuration file
and the system will see how to split it and play those sounds as if
they were separated.
If you set a sound manager, pay attention: the sound sprite play and
stop functions must be called instead of the sound manager play and
stop functions (they are called anyway by sound sprite play and stop)
Description
The sound sprite is an extension of the
t_bunny_music structure.
Its purpose is to be treated not as a single big chunk of sound but as
a collection of sound effect (typically: voices) and played partially
thanks to a set of associated functions.
The reason behind this is to save audio memory, which can be really
short when you use a wide amount of small sound files: as the
t_bunny_sound_sprite is based on
t_bunny_music, the audio content
is streamed from the disk and do not consume a lot of memory.
INDEX
Description
The sound slice structure is used by the field
sound_areas of
t_bunny_sound_sprite and contains several information.
First: it contains the subpart of the music file that is used by
the sound sprite, with
index and
duration. It also contains
the
active_duration which is the length of the slice which is
loaded with meaning: for example, a character is talking in an heavily
echoed place and you want to animate its mouth: the
active_duration
is the part of moving the character's mouth is cool. The remaning
part between
active_duration and
duration would be filled with
echoes only.
It also contains the id for internal purpose: the name of the slice
from the configuration file, hashed with
bunny_sound_sprite_slice_name.
Finally, it contains a
sound field which contains tweaking information
to read the sound as you desire: with a pitch, a volume, a placement, etc.
INDEX
Description
Open a configuration file describing a way to exploit a sound file.
Delete the sound sprite file with
bunny_delete_sound when you do not
need it anymore.
Parameters
-
const char *file:
The sound sprite configuration file to open.
Supported files are any file support by bunny_configuration.
The configuration file format is described below.
Error values and logs
On error, $Vbunny_errno is set to:
Logs written by this function or subfunctions may be tagged with
"ressource",
"configuration",
"sound",
"syntax" or
"sound_sprite"
labels.
Configuration file format
DABSIC format and complete field description
Mandatory field
-
Any field mandatory for a t_bunny_music is mandatory for a
t_bunny_sound_sprite.
-
A t_bunny_sound_sprite also needs a 'Slices' node to describe
slices. Example:
[Slices
[Slice00
'Content
]
]
-
Inside the node describing a single slice in the 'Slices' node,
two fields are mandatory. The first one is the 'Index' double.
It is in seconds and is used to indicates where the slice start
in the sound file.
Example:
[Slices
[Slice00
Index=2.0
Duration=1.0
]
]
-
The other mandatory field is 'Duration' and indicates the duration
of the sound slice.
Example:
[Slices
[Slice00
Index=2.0
Duration=1.0
]
]
Optionnal fields
INI format
The INI format follow the same architecture as the DABSIC one.
Here is its architecture:
RessourceFile="Sound file that will be loaded"
Volume=42
Pitch=3
Loop=true
Position=X, Y, Y
Attenuation=10
[Slices.Slice00]
Index=1.0
Duration=2.0
ActiveDuration=1.0
Volume=84
Pitch=2
Loop=false
#Etc
[Slices.Slice01]
#Etc
CSV format
Not documented yet.
XML format
Not documented yet.
LUA format
Not documented yet.
JSON format
Not documented yet.
LISP format
Not documented yet.
YAML format
There is no support for YAML yet.
INDEX
Description
Play the subpart named
name from
sprite. If the sound sprite
is managed by a
t_bunny_sound_manager, then precise a track or if it is
not the case, use
BST_LAST_TRACK.
You cannot play a slice which is already being played.
Return value
-
On success, the function returns true, which means the slice will
be played.
-
On failure, it returns false and the slice will not be played.
Error values and logs
On error, $Vbunny_errno is set to:
Logs written by this function or subfunctions may be tagged with
"ressource",
"configuration",
"sound",
"syntax" or
"sound_sprite"
labels.
INDEX
Description
Play the subpart named
name from
sprite. If the sound sprite
is managed by a
t_bunny_sound_manager, then precise a track or if it is
not the case, use
BST_LAST_TRACK.
You cannot play a slice which is already being played.
Return value
-
On success, the function returns true, which means the slice will
be played.
-
On failure, it returns false and the slice will not be played.
Error values and logs
On error, $Vbunny_errno is set to:
Logs written by this function or subfunctions may be tagged with
"ressource",
"configuration",
"sound",
"syntax" or
"sound_sprite"
labels.
INDEX
Description
Play the subpart with id
id from
sprite. If the sound sprite
is managed by a
t_bunny_sound_manager, then precise a track or if it is
not the case, use
BST_LAST_TRACK.
You cannot play a slice which is already being played.
Return value
-
On success, the function returns true, which means the slice will
be played.
-
On failure, it returns false and the slice will not be played.
Error values and logs
On error, $Vbunny_errno is set to:
Logs written by this function or subfunctions may be tagged with
"ressource",
"configuration",
"sound",
"syntax" or
"sound_sprite"
labels.
INDEX
Description
Stop the slice being played in the sent sound sprite.
Return value
-
On success, if the sound was stopped the function returns true.
-
On failure, it returns false, probably the sound was already stopped.
INDEX
Description
Indicates if you want to use the trap system from
bunny_asynclock, which
is working in the main thread.. or a thread from the asynchronous computation
system in the
bunny_loop threadpool.
By default, the sound sprite module use the trap system.
To use the threaded system, you must before create the bunny loop thread
pool with
bunny_set_async_computation. If this thread pool does not exists,
even if you have requested to use it, it will use the trap system.
Parameters
-
bool trap:
Send true to use the asynclock system, false for the threaded
system.
INDEX
Description
Return true if the slice being played is inside its active duration.
Return value
Returns true or false depending of the current time being inside
the activate duration of the slice.
INDEX
Description
Hash the sent string.
INDEX
