Skip to content

Home

Jump to bottom
Moros Smith edited this page Aug 26, 2022 · 12 revisions

Introduction

You wanted noise? Well is this loud enough? - javidx9

What is this?

olc::SoundWaveEngine is a single file, cross platform audio interface for lightweight applications that just need a bit of easy audio manipulation.

It's origins started in the olcNoiseMaker file that accompanied javidx9's "Code-It-Yourself: Synthesizer" series. It was refactored and absorbed into the "olcConsoleGameEngine.h" file, and then refactored again into olcPGEX_Sound.h, that was an extension to the awesome "olcPixelGameEngine.h" file.

Alas, it went underused and began to rot, with many myths circulating that "it doesn't work" and "it shouldn't be used". These untruths made javidx9 feel sorry for the poor file, and he decided to breathe some new life into it, in anticipation of new videos!

Getting Started

Setting Up Your Environment

Currently olcSoundWaveEngine has support on Linux, MacOS, and Windows using various compiler/toolchains, including Emscripten. We've done our best to provide details specific to each platform that we support. (Currently the instructions are evolving as the project matures).

Linux

Linux: Arch and related distributions

[user@is_awesome ~]$ sudo pacman -Sy base-devel libpulse

Linux: Debian, Ubuntu, and related distributions

[user@is_awesome ~]$ sudo apt update
[user@is_awesome ~]$ sudo apt install build-essential libpulse-dev

At this point, regardless of distribution, we assume you have the required software installed.

[user@is_awesome MySoundProject]$ g++ olcSoundWaveEngineExample.cpp -o olcSoundWaveEngineExample -lpulse -lpulse-simple -std=c++17

MacOS

TODO: XCode Specifics, seeking MacOS user to fill in this gap.

Windows

TODO: Visual Studio Specifics

TODO: MinGW Specifics

Emscripten: Set up

Unfortunately nobody can be told about Emscripten. You have to use it for yourself - Moros1138

Linux: Arch and related distributions

[user@is_awesome ~]$ sudo pacman -Sy python3 git

Linux: Debian, Ubuntu, and related distributions

[user@is_awesome ~]$ sudo apt update
[user@is_awesome ~]$ sudo apt install python3 git

At this point, regardless of distribution, we assume you have the required software installed.

Navigate to a directory where you want to keep the Emscripten SDK, for this example we will use ~/opt

[user@is_awesome ~]$ mkdir opt
[user@is_awesome ~]$ cd opt
[user@is_awesome opt]$ git clone https://github.com/emscripten/emsdk
[user@is_awesome opt]$ cd emsdk
[user@is_awesome emsdk]$ emsdk install latest
[user@is_awesome emsdk]$ emsdk activate latest

Every time you want to use Emscripten, you will be required to source the emsdk_env.sh like so:

[user@is_awesome ~]$ . ~/emsdk/emsdk_env.sh
Adding directories to PATH:
PATH += /home/user/opt/emsdk
PATH += /home/user/opt/emsdk/upstream/emscripten
PATH += /home/user/opt/emsdk/node/14.18.2_64bit/bin

Setting environment variables:
PATH = /home/user/opt/emsdk:/home/user/opt/emsdk/upstream/emscripten:/home/user/opt/emsdk/node/14.18.2_64bit/bin:/usr/local/bin:/usr/bin:/bin:/usr/local/sbin:/opt/cuda/bin:/opt/cuda/nsight_compute:/opt/cuda/nsight_systems/bin:/usr/lib/jvm/default/bin:/usr/bin/site_perl:/usr/bin/vendor_perl:/usr/bin/core_perl:/var/lib/snapd/snap/bin
EMSDK = /home/user/opt/emsdk
EM_CONFIG = /home/user/opt/emsdk/.emscripten
EMSDK_NODE = /home/user/opt/emsdk/node/14.18.2_64bit/bin/node

To ensure that you are set up and ready to use Emscription, run this as a test

[user@is_awesome ~]$ emcc -v
emcc (Emscripten gcc/clang-like replacement + linker emulating GNU ld) 3.1.14 (4343cbec72b7db283ea3bda1adc6cb1811ae9a73)
clang version 15.0.0 (https://github.com/llvm/llvm-project 7effcbda49ba32991b8955821b8fdbd4f8f303e2)
Target: wasm32-unknown-emscripten
Thread model: posix
InstalledDir: /home/user/opt/emsdk/upstream/bin

MacOS TODO: seeking MacOS user to provide documentation here.

Windows

Javidx9 made a video demonstrating how to install Emscripten on Windows. It was made for the olcPixelGameEngine, but Emscripten is Emscripten and those portions of the video are still relevant.

Emscripten: Usage

At this point, regardless of platform, we assume that you have an installed, activated, and working Emscripten environment

An in-depth explanation of the commands can be found here.

Run the following command:

embuilder build sdl2_mixer libpng zlib

Build with the following command:

em++ olcSoundWaveEngineExample.cpp -o olcSoundWaveEngineExample.html -sALLOW_MEMORY_GROWTH=1 -sMAX_WEBGL_VERSION=2 -sMIN_WEBGL_VERSION=2 -sUSE_LIBPNG=1 -sUSE_SDL_MIXER=2 -sLLD_REPORT_UNDEFINED  -std=c++17 --preload-file path/to/assets@assets

Test, with the following command:

emrun olcSoundWaveExample.html

Using olcSoundWaveEngine

Single-File Projects

TODO: example project code

Multiple-File Projects

If you intend to use olcSoundWaveEngine across multiple files, it's important to only have one instance of the implementation. This is done using the compiler preprocessor definition: OLC_SOUNDWAVE

This is defined typically before the header is included in the translation unit you wish the implementation to be associated with. To avoid things getting messy I recommend you create a file olcSoundWaveEngine.cpp and that file includes ONLY the following code:

#define OLC_SOUNDWAVE
#include "olcSoundWaveEngine.h"
Clone this wiki locally