User Guide

An audiovisual performance tool

bzzzbz lets you experiment and play with audio-reactive visuals, giving you the ability of controlling them live, creating your own mappings and patterns for immersive audiovisual performances. The user guide will give you a quick insight on how to run the in-repository shaders (the scripts generating the videos). If you want to know more about audiovisuals and the reasons behind bzzzbz check out the design specifications page.

Run the in-repository shaders

There are a number of shader programs (graphics) provided with v1.0, useful to demonstrate the various features of bzzzbz. Since the Raspberry Pi is (and should be) flashed with the CLI only Raspbian disribution, a windowing surface is needed for rendering which would be automatically provided in a GUI. To create this surface an X Server session needs to be started to initialise the display. To run any of the following demo programs you will need to edit the xinit.rc file found in the /home/{user} folder with:

#for the main
exec /home/{user}/bzzzbz/src/bz
#or for the examples
exec /home/{user}/bzzzbz/src/examples/ex_{name}

then use startx to run the program from the directory where the program is located. Note this does NOT have to be done on desktop environments and the executables can be run straightaway from the CLI.

Main program

The executable bz is created in the src folder by running cmake . then make in the main folder. Running this demonstrates the real-time responsiveness of bzzzbz to audio and hands-on control using the shader cells.glsl to generate graphics. This step can be skipped on a desktop environment.

Example shaders

..to outline bzzzbz. There are a number of examples included that clearly demonstrate the available features and help in understanding our product. To run these, first run cmake . then make in the /src/examples/ directory which will create the executables. The name of the executable corresponds to that of the implementation file.

Demonstrating: Graphics

Desktop compatible

This program is designed to show the OpenGL renderer in action and produce an output based on the shader creation.glsl. This can also be used to test new shaders as it relies only on OpenGL. To import your own shaders the implementation file ex_opengl.cpp must be modified .

Demonstrating: Audio Response

Desktop compatible

With this program you can try out how the graphics respond to audio by running ex_audio. The example displays a simple spectrum to visualize the incoming audio using the shader spectrum.glsl There is another shader available spectrum_slow.glsl which led to performance issues (especially on the Pi). Compare the two shaders to gain better insight into efficient GPU programming with GLSL.

Demonstrating: Control Surface

Our prototype can be controlled with three potentiometers adding an extra layer to the audiovisual performance. To try this out run ex_SPI which uses the example shader wavepatterns.glsl. Static values can be assigned to the uniforms corresponding to the knobs to simply limit controls or debug the code. This can done in the implementation file.

Create your own shader

You can create and import your own shaders (or port existing ones) and perform with them. An introduction to OpenGL and GLSL is given here with some useful tips about writing your own.