https://github.com/xuepoo/sonic-bridge
An ultra-fast, lightweight, zero-pretrain-model physical music aesthetic & listening translation middleware for AI Agents & LLMs
https://github.com/xuepoo/sonic-bridge
ai-agent audio-processing dsp dtw llm lrmd music-analysis musicology onset-detection rust
Last synced: 19 days ago
JSON representation
An ultra-fast, lightweight, zero-pretrain-model physical music aesthetic & listening translation middleware for AI Agents & LLMs
- Host: GitHub
- URL: https://github.com/xuepoo/sonic-bridge
- Owner: Xuepoo
- License: mit
- Created: 2026-05-29T09:29:39.000Z (21 days ago)
- Default Branch: main
- Last Pushed: 2026-05-29T11:38:19.000Z (21 days ago)
- Last Synced: 2026-05-29T12:24:03.950Z (21 days ago)
- Topics: ai-agent, audio-processing, dsp, dtw, llm, lrmd, music-analysis, musicology, onset-detection, rust
- Language: Rust
- Homepage: https://github.com/Xuepoo/sonic-bridge
- Size: 106 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.en.md
- License: LICENSE
Awesome Lists containing this project
README
# SonicBridge Core Audio Engine
[English](README.en.md) | [įŽäŊä¸æ](README.md)
An ultra-fast, lightweight, zero-pretrain-model physical music aesthetic & listening translation middleware designed for pure-text Large Language Models (LLMs).
**SonicBridge** bridges the physical listening gap (Modal Gap) for AI Agents. It is a digital signal processing (DSP) tool written entirely in Rust, with no heavy machine learning dependencies.
Leveraging high-performance audio decoding, short-time Fourier transform (STFT), Chroma pitch class projection, and Dynamic Time Warping (DTW) alignment, SonicBridge decouples raw 1D waveforms into **LRMD (LLM-Readable Music Descriptor) reports** in a fraction of a second. This empowers AI companion agents to truly "hear" music, sense vocal timbral emotional shifts, parse arrangement spaces, and compare Cover version performance differences.
---
## đ Key Features
* **Zero-Model Translation**: Built entirely on classic DSP algorithms (FFT, HPSS, Chroma), yielding a statically compiled binary of only **~5MB** with zero heavy GPU or neural network runtime dependencies.
* **Three Aesthetic Slicing Strategies**:
* **Approach A: Parameterized Adaptive Steps**: Customize temporal analysis windows via CLI or `config.toml` to track melodic changes.
* **Approach B: Spectral Flux Onset-Triggered Partitioning**: Compute consecutive spectral frames positive energy flux to dynamically slice acoustic boundaries right at transient attacks (drum entries, glissandos).
* **Approach C: Beat-Synchronous Resampling**: Estimate beat intervals using Autocorrelation functions, merging acoustic descriptors by musical beats.
* **XDG Specification Compliance**: Fully complies with **XDG Base Directory Specifications** supporting self-healing TOML configuration directories.
* **Cross-Version DTW Alignment**: Employs Dynamic Time Warping dual-backtracking pathfinding, enabling robust temporal alignment of Covers and Originals under non-linear tempo changes.
* **AI Agent Co-Listening Co-Intelligence**: Designed to seamlessly interface with CLI music players and clients. By generating standard `.lrmd.md` reports, text-only LLMs get full synesthetic ability to act as real-time musicological companions.
---
## đĨ Installation
SonicBridge provides multiple out-of-the-box installation strategies. Select the method that best matches your system layout:
### 1. Build via Cargo (Rust Ecosystem)
If you have a Rust toolchain configured locally, compile and install it globally via `cargo`:
```bash
cargo install sonic-bridge
```
### 2. Install from AUR (Arch Linux & Manjaro Users)
Statically compiled packages are natively distributed inside the Arch User Repository:
```bash
# Using paru
paru -S sonic-bridge-bin
# Using yay
yay -S sonic-bridge-bin
```
### 3. Deploy via Docker
A minimal runtime image built using multi-stage Alpine static linking compilation is published:
```bash
docker pull xuepoo/sonic-bridge:latest
```
### 4. Fetch Pre-compiled Binaries from GitHub Releases
Navigate to the [Official GitHub Releases Page](https://github.com/Xuepoo/sonic-bridge/releases/latest) to directly fetch statically linked standalone binaries compiled for your host architecture.
---
## đ ī¸ Quick Start
### 1. Build from Source
Statically linked, generating a single, self-contained binary without any external runtime dependencies:
```bash
# 1. Clone Repository
git clone https://github.com/Xuepoo/sonic-bridge.git
cd sonic-bridge
# 2. Compile Release Binary
cargo build --release
# 3. Run Tests
cargo test
```
*(The compiled executable `./target/release/sonic-bridge` is roughly 5MB)*
---
### 2. CLI Usage Guide
```bash
# 1. Default 5.0-second interval analysis
sonic-bridge "/path/to/song.mp3"
# 2. Enable Approach B: Event-Driven Onset Adaptive Segmentation
sonic-bridge "/path/to/song.mp3" --onset
# 3. Load custom TOML config
sonic-bridge "/path/to/song.mp3" --config "/path/to/my_config.toml"
# 4. Cross-Version Comparative Analysis (DTW Warp)
sonic-bridge "/path/to/original.mp3" "/path/to/cover_version.mp3"
```
---
## âī¸ XDG & Parameter Tuning (Configuration)
Prioritizes loading `$XDG_CONFIG_HOME/sonic-bridge/config.toml`.
For detailed field explanations, XDG environment interceptions, and musical style tuning metrics, please refer to:
đ **[SonicConfig User & Configuration Guide (docs/configuration.md)](docs/configuration.md)**.
---
## đĻ Containerization & Deployment
* **Docker Registry**: Uses a multi-stage [Dockerfile](Dockerfile) to compile a minimal runtime container based on Alpine Linux:
```bash
docker pull xuepoo/sonic-bridge:latest
```
* **Crates.io**:
```toml
[dependencies]
sonic-bridge = "0.1"
```
* **GitHub Actions CI/CD**: Automatically builds multi-platform binaries, publishing to Dockerhub, crates.io, and AUR upon version tags (e.g. `v0.1.0`).
---
## âī¸ License
Stably licensed under the [MIT License](LICENSE). Contributions, issues, and Pull Requests are welcome!