KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #codex #claude-code #mcp #rust #deepseek-harness #typescript #ai-agent #cli

Bitwave

★ 24 Open GitHub ↗

Bitwave is a high-fidelity, developer-friendly, future-proof audio format designed for modern sound experiences — including spatial audio, dynamic tempo adjustment, and multi-track support.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🎧 Bitwave - Next-Gen Multi-Channel Audio Format

![Version](https://img.shields.io/badge/version-v1.0-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Build](https://img.shields.io/badge/build-passing-brightgreen)
![Platform](https://img.shields.io/badge/platform-cross--platform-lightgrey)
![Status](https://img.shields.io/badge/status-alpha-orange)
![Python](https://img.shields.io/badge/python-3.8%2B-blue)
![Rust](https://img.shields.io/badge/rust-1.70%2B-blue)

**Bitwave** is a high-fidelity, developer-friendly, future-proof audio format designed for modern sound experiences — including spatial audio, dynamic tempo adjustment, and multi-track support.

> Minimal. Powerful. Immersive.

---

## 🔥 Features

- 🎚️ **Multi-channel support** – From stereo to 7.1+, ambisonic, and 3D formats
- ⏱️ **Dynamic tempo control** – Ideal for DJs, generative music, and interactive environments
- 🌐 **Spatial-ready** – Built-in XYZ positioning for VR/AR and immersive experiences
- 🧠 **AI-enhanced compatibility** – Ready for real-time audio transformation and neural mixing
- 💾 **Compact & efficient** – Optimized binary format with optional lossless compression (ZLIB, LZMA, FLAC-style)
- 📁 **Modern file extension**: `.bwx`
- 🐍 **Python SDK** – Easy-to-use Python implementation for rapid development
- 🗜️ **Compression Support** – Lossless (ZLIB, LZMA) and lossy compression options
- 📊 **Audio Analysis** – BPM detection, spectral analysis, fingerprinting, key detection
- 🔄 **Format Conversion** – Convert to/from WAV, FLAC, OGG, and more
- 🎛️ **Audio Effects** – Reverb, delay, distortion, filters, compression, EQ, and more
- 📦 **Batch Processing** – Process multiple files in parallel
- 📝 **Metadata Management** – Extended metadata with search and export capabilities
- 🔍 **Quality Analysis** – SNR, THD, frequency response, clipping detection
- ✨ **Unique Tools** – Tempo matching, pitch shifting, spatial audio, granular synthesis

---

## 🎵 Cross-Platform Player

Bitwave comes with a modern, feature-rich player that works on both macOS and Windows:

### Player Features

- 🎨 **Modern UI** – Clean, intuitive interface with dark mode support
- 📊 **Waveform Visualization** – Real-time waveform display with playback position
- 🎚️ **Volume Control** – Smooth volume adjustment with keyboard shortcuts
- 📋 **Playlist Support** – Create, save, and load playlists (M3U format)
- 🌐 **Spatial Audio Visualization** – 3D visualization of spatial audio data
- 📝 **Metadata Display** – View track information, duration, and BPM
- ⌨️ **Keyboard Shortcuts** – Quick access to all playback controls
- 🎯 **System Tray Integration** – Control playback from the system tray

### Player Controls

| Action | Keyboard Shortcut | Description |
|--------|------------------|-------------|
| Play/Pause | Space | Toggle playback |
| Next Track | Right Arrow | Play next track |
| Previous Track | Left Arrow | Play previous track |
| Volume Up | Up Arrow | Increase volume |
| Volume Down | Down Arrow | Decrease volume |
| Open File | Ctrl+O | Open Bitwave file |
| Save Playlist | Ctrl+S | Save current playlist |
| Load Playlist | Ctrl+L | Load saved playlist |

### Running the Player

```bash
# Install dependencies
pip install -r requirements.txt

# Run the player
python player/run.py
```

---

## 🧩 Supported Extensions

| Extension | Description |
|-----------|-------------|
| `.bw2`    | Bitwave v2 – Latest version with enhanced features |
| `.bwx`    | Bitwave eXtended – Multichannel, 3D, spatial audio |
| `.bwa`    | Bitwave Audio – Standard audio content |
| `.bwm`    | Bitwave Master – Mastering / studio-level quality |
| `.bwd`    | Bitwave Dynamic – Tempo & rhythm adaptive version |
| `.bwl`    | Bitwave Light – Lightweight, streaming optimized |
| `.bwf`    | Bitwave Full – Includes full metadata and spatial data |
| `.bwr`    | Bitwave Raw – Uncompressed or minimally processed |
| `.bwi`    | Bitwave Immersive – VR/AR ready, full 3D audio |
| `.bwt`    | Bitwave Track – Optimized for music tracks |
| `.bwp`    | Bitwave Pro – Professional content & production ready |

---

## 📦 File Structure (v1)

| Section        | Description                            |
|----------------|----------------------------------------|
| `BWX_HEADER`   | Magic bytes, version, flags            |
| `META_BLOCK`   | Sample rate, channels, duration, bpm   |
| `SPATIAL_BLOCK`| Positional data (x, y, z) per channel  |
| `AUDIO_STREAM` | Encoded audio frames                   |
| `FOOTER`       | Checksum & optional tags               |

---

## 🚀 Getting Started

### Python Installation

```bash
# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Unix/macOS
# or
.\venv\Scripts\activate  # On Windows

# Install dependencies
pip install -r requirements.txt

# Install package in development mode
pip install -e .
```

### Rust Installation

```bash
# Navigate to the Rust implementation
cd rust

# Build the project
cargo build

# Run tests
cargo test

# Build documentation
cargo doc --open
```

### Command Line Tools

```bash
# Get information about a Bitwave file
bitwave info file.bwx
bitwave info file.bwx --json  # JSON output

# Convert audio files to/from Bitwave format
bitwave convert input.wav output.bwx --bpm 120 --compression zlib
bitwave convert input.bwx output.wav  # Convert from Bitwave

# Analyze audio files
bitwave analyze file.bwx --all  # Run all analyses
bitwave analyze file.bwx --bpm --spectral --fingerprint

# Apply audio effects
bitwave effects input.bwx output.bwx --reverb 0.7 --delay 250 --normalize

# Batch process files
bitwave batch input_dir output_dir --convert bwx --workers 4
bitwave batch input_dir output_dir --normalize
bitwave batch input_dir --analyze --workers 8

# Manage metadata
bitwave metadata file.bwx  # View metadata
bitwave metadata file.bwx --set "title=My Song" --set "artist=Artist Name"
bitwave metadata audio_dir --export-csv metadata.csv

# Quality analysis
bitwave quality file.bwx
bitwave quality file.bwx --reference original.bwx  # Compare with reference

# Unique audio tools
bitwave unique input.bwx output.bwx --tempo-match 140
bitwave unique input.bwx output.bwx --pitch-shift 2  # Shift up 2 semitones
bitwave unique input.bwx output.bwx --spatial "0.5,0.3,0.1"  # 3D positioning
```

### Python API

#### Basic File Operations

```python
from bitwave import BitwaveFile, CompressionType

# Read a Bitwave file
bw_file = BitwaveFile("track.bwx")
bw_file.read()
metadata = bw_file.get_metadata()
audio_data = bw_file.get_audio_data()

# Write a Bitwave file with compression
bw_file.write(
    audio_data=np.array(...),  # 2D array (samples x channels)
    sample_rate=44100,
    bpm=120,
    spatial_data=np.array(...),  # Optional spatial data
    compression=CompressionType.LZMA  # Compression option
)
```

#### Audio Analysis

```python
from bitwave import AudioAnalyzer

# Detect BPM
bpm = AudioAnalyzer.detect_bpm(audio_data, sample_rate=44100)

# Spectral analysis
spectral = AudioAnalyzer.spectral_analysis(audio_data, sample_rate=44100)
print(f"Dominant frequency: {spectral['dominant_frequency']} Hz")

# Generate audio fingerprint
fingerprint = AudioAnalyzer.audio_fingerprint(audio_data, sample_rate=44100)

# Detect musical key
key = AudioAnalyzer.detect_key(audio_data, sample_rate=44100)

# Loudness analysis (LUFS)
loudness = AudioAnalyzer.analyze_loudness(audio_data, sample_rate=44100)
```

#### Format Conversion

```python
from bitwave import AudioConverter

# Convert to Bitwave
AudioConverter.to_bitwave("input.wav", "output.bwx", bpm=120)

# Convert from Bitwave
AudioConverter.from_bitwave("input.bwx", "output.wav", format="wav")

# Batch conversion
results = AudioConverter.batch_convert(
    ["file1.wav", "file2.flac"],
    "output_dir",
    output_format="bwx"
)
```

#### Audio Effects

```python
from bitwave import AudioEffects

# Apply reverb
reverb_audio = AudioEffects.apply_reverb(audio_data, sample_rate=44100, room_size=0.7)

# Apply delay
delayed_audio = AudioEffects.apply_delay(audio_data, sample_rate=44100, delay_ms=250)

# Apply distortion
distorted_audio = AudioEffects.apply_distortion(audio_data, drive=0.8)

# Apply EQ
eq_audio = AudioEffects.apply_eq(
    audio_data, sample_rate=44100,
    frequencies=[100, 1000, 5000],
    gains_db=[3, -2, 1]
)

# Normalize
normalized = AudioEffects.normalize(audio_data, target_level=0.95)
```

#### Batch Processing

```python
from bitwave import BatchProcessor

# Batch convert directory
results = BatchProcessor.batch_convert(
    "input_dir", "output_dir",
    output_format="bwx",
    max_workers=4
)

# Batch analyze
analysis = BatchProcessor.batch_analyze(
    "audio_dir",
    output_file="analysis.json"
)

# Batch normalize
BatchProcessor.batch_normalize("input_dir", "output_dir")
```

#### Unique Tools

```python
from bitwave import UniqueTools

# Tempo matching (time-stretch without pitch change)
matched = UniqueTools.tempo_match(
    audio_data, source_bpm=120, target_bpm=140,
    sample_rate=44100
)

# Pitch shifting (change pitch without tempo change)
shifted = UniqueTools.pitch_shift(
    audio_data, sample_rate=44100, semitones=2
)

# Create spatial audio (3D positioning)
spatial = UniqueTools.create_spatial_position(
    audio_data, x=0.5, y=0.3, z=0.1, sample_rate=44100
)

# Ambisonic encoding
ambisonic = UniqueTools.create_ambisonic(audio_data, x=0.5, y=0.3, z=0.1)

# Granular synthesis
granular = UniqueTools.create_granular_synthesis(
    audio_data, grain_size_ms=50.0, overlap=0.5, pitch_shift=1.2
)
```

#### Quality Analysis

```python
from bitwave import QualityAnalyzer

# Comprehensive quality analysis
quality = QualityAnalyzer.analyze_quality(audio_data, sample_rate=44100)

# Calculate SNR (with reference)
snr = QualityAnalyzer.calculate_snr(reference_audio, processed_audio)

# Detect clipping
clipping = QualityAnalyzer.detect_clipping(audio_data)
print(f"Clipped samples: {clipping['percent_clipped']}%")
```

#### Metadata Management

```python
from bitwave import MetadataManager, ExtendedMetadata

# Read metadata
metadata = MetadataManager.read_metadata("file.bwx")
extended = MetadataManager.read_extended_metadata("file.bwx")

# Write metadata
meta = ExtendedMetadata(
    title="My Song",
    artist="Artist Name",
    album="Album Name",
    genre="Electronic",
    bpm=128.0,
    key="Am"
)
MetadataManager.write_metadata("file.bwx", meta)

# Search by metadata
matches = MetadataManager.search_by_metadata("audio_dir", {"genre": "Electronic"})
```

### Rust API

```rust
use bitwave::{BitwaveFile, Metadata, SpatialData};

// Read a Bitwave file
let file = BitwaveFile::read("track.bwx")?;
let metadata = file.metadata();

// Write a Bitwave file
let metadata = Metadata {
    sample_rate: 44100,
    channels: 2,
    duration: 0.0,
    bpm: Some(120.0),
};

let file = BitwaveFile::new(metadata, None, audio_data);
file.write("output.bwx")?;
```

---

## 📚 Use Cases

- 🎮 **Game Audio Engines** – Unity, Unreal, Godot with spatial audio support
- 🎧 **VR / AR Experiences** – Immersive 3D audio with HRTF simulation
- 🎛️ **Live DJ Sets** – Tempo-controlled transitions and beat matching
- 🎼 **Immersive Installations** – 3D soundscapes and ambisonic audio
- 📡 **Real-time Streaming** – Spatial audio streaming capabilities
- 🎨 **Audio Production** – Professional effects and quality analysis
- 🔬 **Audio Research** – Comprehensive analysis and fingerprinting tools
- 📦 **Batch Processing** – Efficient processing of large audio libraries
- 🎵 **Music Production** – Tempo matching, pitch shifting, and effects
- 🎬 **Post-Production** – Quality analysis and format conversion

---

## 🛠️ Developer Tools & Modules

### Core Modules

- **`bitwave.core`** – Core file format handler with compression support
- **`bitwave.compression`** – Lossless (ZLIB, LZMA) and lossy compression
- **`bitwave.analysis`** – BPM detection, spectral analysis, fingerprinting, key detection
- **`bitwave.converter`** – Multi-format conversion (WAV, FLAC, OGG, etc.)
- **`bitwave.effects`** – Professional audio effects (reverb, delay, distortion, filters, EQ)
- **`bitwave.batch`** – Parallel batch processing utilities
- **`bitwave.metadata`** – Extended metadata management and search
- **`bitwave.quality`** – Audio quality analysis (SNR, THD, clipping detection)
- **`bitwave.unique`** – Unique tools (tempo matching, pitch shifting, spatial audio, granular synthesis)
- **`bitwave.utils`** – Utility functions for common audio operations

### CLI Commands

- `bitwave info` – File information and metadata
- `bitwave convert` – Format conversion with compression options
- `bitwave analyze` – Comprehensive audio analysis
- `bitwave effects` – Apply audio effects via CLI
- `bitwave batch` – Batch process multiple files
- `bitwave metadata` – Manage file metadata
- `bitwave quality` – Analyze audio quality metrics
- `bitwave unique` – Unique audio processing tools

### Features

- ✅ CLI tools for encoding/decoding
- ✅ Python SDK with NumPy integration
- ✅ Comprehensive audio analysis tools
- ✅ Professional audio effects library
- ✅ Batch processing with parallel execution
- ✅ Format conversion capabilities
- ✅ Metadata management system
- ✅ Quality analysis tools
- ✅ Cross-platform player with advanced features
- ✅ Compression support (lossless and lossy)

---

## 🧪 Roadmap

### Completed ✅

- [x] Core `.bwx` format & parser
- [x] Python SDK implementation
- [x] Open source cross-platform player
- [x] Lossless & hybrid compression support (ZLIB, LZMA, FLAC-style)
- [x] Audio analysis tools (BPM, spectral, fingerprinting)
- [x] Format conversion (WAV, FLAC, OGG, etc.)
- [x] Professional audio effects library
- [x] Batch processing utilities
- [x] Metadata management system
- [x] Quality analysis tools
- [x] Unique audio processing tools (tempo matching, spatial audio, etc.)

### In Progress 🚧

- [ ] Enhanced spatial audio with HRTF data
- [ ] Real-time processing capabilities
- [ ] Streaming support

### Planned 📋

- [ ] Realtime tempo-sync with MIDI/OSC
- [ ] Plugin SDK for audio software (Ableton, FL Studio, Reaper)
- [ ] Web-based player interface
- [ ] Machine learning integration for audio enhancement
- [ ] Cloud storage integration
- [ ] Advanced granular synthesis engine

---

## 💬 Community & Feedback

We're building Bitwave in the open. Feedback, feature requests, and contributors are welcome!

👉 [Issues](https://github.com/makalin/Bitwave/issues) • [Discussions](https://github.com/makalin/Bitwave/discussions)

---

## ⚡ License

MIT License — use it freely, contribute openly, play it loud.

---

## 📖 Documentation

For detailed documentation on all features and tools, see:
- [NEW_FEATURES.md](NEW_FEATURES.md) – Comprehensive guide to all new features
- API documentation available via `help()` in Python interactive shell
- CLI help available via `bitwave --help` or `bitwave <command> --help`

## 🎯 Quick Examples

### Convert and Analyze

```bash
# Convert WAV to Bitwave with compression
bitwave convert song.wav song.bwx --compression lzma

# Analyze the file
bitwave analyze song.bwx --all

# Apply effects and save
bitwave effects song.bwx song_processed.bwx --reverb 0.6 --normalize
```

### Batch Processing

```bash
# Convert entire directory
bitwave batch ./wav_files ./bwx_files --convert bwx --workers 8

# Analyze all files and export results
bitwave batch ./audio_dir --analyze > analysis.json
```

### Python Workflow

```python
from bitwave import BitwaveFile, AudioAnalyzer, AudioEffects, CompressionType

# Load and analyze
bw = BitwaveFile("track.bwx")
bw.read()
audio = bw.get_audio_data()
bpm = AudioAnalyzer.detect_bpm(audio, 44100)

# Process with effects
processed = AudioEffects.apply_reverb(audio, 44100, room_size=0.7)
processed = AudioEffects.normalize(processed)

# Save with compression
output = BitwaveFile("output.bwx")
output.write(processed, 44100, bpm=bpm, compression=CompressionType.LZMA)
```

---

**Built for creators, coders, and cosmic listeners.**  
→ _Bitwave: Redefining the sound of the future._

Bitwave

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README