🎧 Bitwave - Next-Gen Multi-Channel Audio Format

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

# 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

# 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

# Navigate to the Rust implementation
cd rust

# Build the project
cargo build

# Run tests
cargo test

# Build documentation
cargo doc --open

Command Line Tools

# 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

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

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

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

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

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

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

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

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

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 ✅

• Core .bwx format & parser
• Python SDK implementation
• Open source cross-platform player
• Lossless & hybrid compression support (ZLIB, LZMA, FLAC-style)
• Audio analysis tools (BPM, spectral, fingerprinting)
• Format conversion (WAV, FLAC, OGG, etc.)
• Professional audio effects library
• Batch processing utilities
• Metadata management system
• Quality analysis tools
• 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 • Discussions

---

⚡ License

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

Copyright © 2025 Mehmet T. AKALIN / Digital Vision

---

📖 Documentation

For detailed documentation on all features and tools, see:

• 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

# 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

# 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

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.