Wavy

A local networking solution for audio streaming and sharing, supporting lossless and lossy audio formats through a unified platform.

Table of Contents

• Introduction
• Dependencies
• Building
• Architecture
• API References
• Server
• Usage
• Documentation
• License

Introduction

Wavy is a lightweight and efficient solution for audio streaming within a local network. It is designed to encode, decode, and dispatch audio streams seamlessly while ensuring secure data transfer via SSL/TLS encryption.

Important

The Wavy Project currently is only supported for *NIX Operating Systems (on x86-64 architecture).

Currently supported and tested distributions:

1. Arch Linux
2. Ubuntu (Debian)

In the future, perhaps Windows / MacOS will be supported.

It supports:

• Lossless formats (FLAC, ALAC, WAV)
• Lossy formats (MP3, AAC, Opus, Vorbis)
• Adaptive bitrate streaming (Soon) using HLS (HTTP Live Streaming).
• Metadata extraction and TOML-based configuration.
• Transport stream decoding via FFmpeg for real-time audio playback.

Dependencies

To build and run Wavy, install the following dependencies:

Dependency	Purpose
FFmpeg	Audio encoding, decoding, and streaming
Base-devel	Includes g++ / clang++ for C++ compilation
OpenSSL	Secure communication using SSL/TLS
Boost	Asynchronous networking & utility functions
libzstd	Lossless compression (Zstandard)
CMake & Make	Build system tools
Pkg-Config	Build system tools helper
Libarchive	Handling .tar, .gz, .zst compressed files

Note

Ensure that FFmpeg is installed with libavformat, libavcodec, libavutil, and libswresample

This is particular critical for Ubuntu / Debian: (FFmpeg and its dev libs are different packages)

sudo apt install ffmpeg libavcodec-dev libavformat-dev libavutil-dev libavfilter-dev libswscale-dev libswresample-dev

On Arch Linux:

sudo pacman -S ffmpeg # should be enough

Building

The Wavy Project uses a simple Makefile to run simple and straightforward functions that acts as a wrapper around the CMake Build System that currently creates and links different binaries that are NOT integrated yet!

To initialize the project:

make init

To compile the different components, run:

make encoder     # Builds encode.cpp
make decoder     # Builds decode.cpp
make dispatcher  # Builds dispatcher for stream management
make server      # Builds the Wavy streaming server
make remove      # Cleans up all generated transport streams and playlists

make all         # Builds all components at once

Note

If you want to use any extra flags:

make all EXTRA_FLAGS="-DUSE_MOLD=ON"

This will try to use mold as the linker for the project. You can try different flags but it is recommended that you do not. It is not necessary.

Architecture

The Wavy system consists of the following components:

• Encoder: Converts audio files into HLS (HTTP Live Streaming) format.
• Decoder: Parses transport streams for playback.
• Dispatcher: Manages transport stream distribution.
• Server: Handles secure file uploads, downloads, and client session management.

System Overview:

For a more detailed explanation, read:
ARCHITECTURE.md

API References

Wavy relies on FFmpeg's core libraries for processing audio:

• libavformat - Format handling & demuxing.
• libavcodec - Audio decoding & encoding.
• libavutil - Utility functions for media processing.
• libswresample - Audio resampling & format conversion.

For detailed API documentation, see:
APIREF.md

Server

The Wavy-Server allows secure transport stream handling over HTTPS.

The Server Storage Organization is indexed below:

hls_storage/
├── 192.168.1.10/                                    # IP Address 192.168.1.10 (example)
│   ├── 1435f431-a69a-4027-8661-44c31cd11ef6/        # Randomly generated audio id
│   │   ├── index.m3u8
│   │   ├── hls_mp3_64.m3u8                          # HLS MP3 encoded playlist (64-bit)
│   │   ├── hls_mp3_64_0.ts                          # First transport stream of hls_mp3_64 playlist                
│   │   ├── ...                                      # Similarly for 128 and 256 bitrates
│   │   ├── metadata.toml                            # Metadata and other song information
│   ├── e5fdeca5-57c8-47b4-b9c6-60492ddf11ae/
│   │   ├── index.m3u8
│   │   ├── hls_flac_64.m3u8                         # HLS FLAC encoded playlist (64-bit)
│   │   ├── hls_flac_64_0.ts                         # First transport stream of hls_mp3_64 playlist 
│   │   ├── ...                                      # Similarly for 128 and 256 bitrates
│   │   ├── metadata.toml                            # Metadata and other song information
│    

The server does not delete these indices after the server dies. The server allows for PERSISTENT STORAGE.

This makes it so that every owner can index multiple audio files under a clean directory structure that is logical to query and playback.

So the capability of the server totally depends on YOUR filesystem. This gives you full power to manage your server library to the fullest.

Flexibility

The architecture is designed in a way to make it more flexible in the future.

The server's importance in the overall flow of operations is always kept at a minimum, to ensure that if we were to implement a P2P solution for this someday, the transition and implementation would lead to no heads being bashed into a wall.

Generating SSL Certificates

To generate a self-signed certificate, run:

openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt -days 365 -nodes

Or use the Makefile shortcut:

make server-cert

Note

Place server.crt and server.key in the current working directory before starting the server.

Warning

This is a self-signed certificate.

• Use -k flag in cURL to bypass SSL validation.
• Accept the self-signed certificate when using VLC/MPV.

---

Usage

Starting the Server

Once compiled, start the server:

make run-server

It will:

1. Accept secure .m3u8 & .ts uploads.
2. Assign UUIDs to clients for session tracking.
3. Serve stored playlists via GET /hls/<ip-id>/<client_id>/<filename>.

Uploading a Playlist

To upload a compressed HLS playlist:

curl -X POST -F "file=@playlist.tar.gz" https://localhost:8080/upload -k

Fetching a Client List

curl https://localhost:8443/hls/clients -k

Documentation

Generating Docs

Install Doxygen, then run:

doxygen .Doxyfile
xdg-open docs/html/index.html  # Opens the documentation in a browser

Credits

1. TOML++: Header-only TOML config file parser and serializer for C++17. TOML++ (tomlplusplus)
2. Miniaudio: Audio playback and capture library written in C, in a single source file. Miniaudio

License

The Wavy Project is licensed under the BSD-3-Clause License.
LICENSE