Overview
The sound atlas is a set of audio files merged into a single audio file. Mainly used to decrease the number of network requests and speed up loading times.
Sound atlas consists of two files: an audio file (usually mp3) and data file (JSON).
To see supported list of input audio files please refer to FFmpeg documentantion. When making a choice for the output format refer to platform specific documentation. https://caniuse.com/ for Browsers. For OS specific support just google it. Bear in mind not all formats are royalty free or may be not properly supported by destination platform. If in doubt just use mp3.
Installation
Download ffmpeg
and include it in your path export PATH=$PATH:path/to/ffmpeg/bin
(for Windows users)
Install Sound Atlas generator tool.
npm install -g bsa-gen
How to generate
bsa-gen --in *.mp3 --out atlas
Parameters
--in
- File mask in the current folder.
--out
- Output files name. Supports path, eg. outputFolder/atlas
.
--vbr
- (optional) Audio quality. Default preset for FFmpeg used is 7. Which is VBR 80-120 kbit, stereo.
How to use
Usual way to load the sound atlas:
Black.assets.enqueueSoundAtlas('my-sound-atlas', 'atlas.mp3', 'atlas.json');
To get the sound and create its intance:
let s = Black.assets.getSound('sound-name-from-atlas');
let soundInstance = s.play();
where sound-name-from-atlas
is the name of the input audio file without extension.
Simplier way to play sound:
MasterAudio.play('sound-name-from-atlas');