vibra-mini

vibra-mini is a clean, daemon-focused fork of vibra for Autostream.

Its purpose is deliberately narrow: accept raw PCM audio over a local Unix socket, generate a Shazam-compatible fingerprint, submit it to Shazam, and return the resulting track JSON. Public C ABI, Python, JavaScript/WebAssembly, demo, and general-purpose CLI surfaces have been removed from this fork.

Runtime Shape

The production binary is vibra-mini.

It listens on a local Unix socket and accepts newline-delimited JSON requests. The main request is:

{"type":"recognize","frames":80000,"rate":16000,"channels":1,"bits":16}

The JSON line is followed by exactly frames x 2 bytes of raw 16-bit little-endian mono PCM audio at 16 kHz. Responses are JSON objects terminated by a newline.

Logs are written to stderr as:

19-Jun-26 14:03:05: [INFO] vibra-mini 1.0.1 starting

Supported log levels are error, warn, info, debug, and spam. Keep normal service operation at info; debug and spam are intended for diagnosis.

For testability, the protocol and recognition boundary can use a fake lookup that returns canned JSON without touching the network. The real production lookup uses libcurl where available.

Build

Linux/Pi Target

Install dependencies:

sudo apt-get update
sudo apt-get install -y build-essential cmake libcurl4-openssl-dev libjson-c-dev

Build and install manually:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF
cmake --build build --parallel 2
sudo cmake --install build --prefix /opt/autostream/vibra

Or use the repository installer:

sudo bash scripts/install-vibra-mini.sh --enable --restart

The installer builds the daemon, installs it under /opt/autostream/vibra, and installs system/systemd/vibra-mini.service.

Pi/Linux runtime verification is out of scope in the current Windows development environment and must be completed on target hardware or a Linux VM.

Windows Development Tests

CMake is installed locally at:

C:\Program Files\CMake\bin\cmake.exe

Configure, build, and run the network-free unit tests:

& 'C:\Program Files\CMake\bin\cmake.exe' -S . -B .tmp-build-test -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON
& 'C:\Program Files\CMake\bin\cmake.exe' --build .tmp-build-test --config Debug
& 'C:\Program Files\CMake\bin\ctest.exe' --test-dir .tmp-build-test -C Debug --output-on-failure

On Windows, the POSIX socket daemon executable is not built; the reusable core library and protocol tests are built and exercised.

WSL / Linux Verification

From WSL or a Linux shell, install dependencies once:

sudo apt-get update
sudo apt-get install -y build-essential cmake libcurl4-openssl-dev libjson-c-dev pkg-config python3

Then run:

scripts/test-linux.sh

The script configures and builds the project, runs CTest, syntax-checks the shell scripts, verifies the systemd unit when systemd-analyze is available, and starts vibra-mini for a no-network Unix socket ping smoke test.

Development Rules

Work is organized into small packages that map cleanly to local git commits. Before each commit:

1. Run the relevant kept or newly added tests.
2. Review the staged diff against the implementation plan.
3. Commit only the files for that work package.

New behavior should include tests as it is introduced. Network-dependent behavior should be covered through fake lookups or request-building tests unless the work explicitly targets integration testing on Linux/Pi.

License

This fork remains GPLv3-licensed. See LICENSE.

The daemon uses the same unofficial Shazam endpoint as upstream Vibra. That external dependency may change without notice and may carry terms-of-service risk for deployments.