BeatViewer is a Python program that analyzes an audio stream, extracts onsets, tempo and beats, and creates visuals from them in real time. Feature extraction relies on state-of-the-art beat tracking algorithms. Visuals are rendered via Pygame or external programs such as OBS Studio or any WebSocket client.

For a detailed narration of the birth of the project, watch the associated video (in French, English subtitles are coming).

This program requires a working installation of Python 3. Tools such as FFmpeg and OBS Studio are recommended.

1. Download the latest release
2. Install it with pip:

   pip install ~/Downloads/beatviewer-1.0.0.tar.gz

Some resources (OBS script, tools, JS visuals) are available through direct download and are attached to the latest release.

Here is a summary of what you'll need to get started. For more options (file output, tracking parameters, etc.) please refer to the wiki.

By default, BeatViewer uses the default audio input. You can specify an audio device using the -a <device-id> parameter. You can get a list of audio devices by using the -l flag. You can also execute the module offline, by passing the path to an audio file with the -f argument (for now, only WAVE file are supported).

By default, no visualizer is attached to the tracker, it simply prints dots to stdout when a beat occurs. You can specify a visualizer by typing its name after the beat tracking arguments:

python -m beatviewer <visualizer-name> <visualizer-arguments+>

For a quick test, you can try the galaxy visualizer. You'll find a list with more options and instructions on the wiki.

Contributions are welcomed. For now, performance enhancements and addition of new visualizers are mostly needed. Do not hesitate to submit a pull request with your changes!

This project is licensed under the GPL-3.0 license.

Submit bug reports and feature suggestions in the issue tracker.