🎧 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 ✅

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.

📖 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.

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
bitwave		bitwave
player		player
rust		rust
.gitignore		.gitignore
LICENSE		LICENSE
NEW_FEATURES.md		NEW_FEATURES.md
README.md		README.md
bitwave_logo.pdf		bitwave_logo.pdf
bitwave_logo.svg		bitwave_logo.svg
icon.pdf		icon.pdf
requirements.txt		requirements.txt
setup.py		setup.py

Uh oh!

License

makalin/Bitwave

Folders and files

Latest commit

History

Repository files navigation

🎧 Bitwave - Next-Gen Multi-Channel Audio Format

🔥 Features

🎵 Cross-Platform Player

Player Features

Player Controls

Running the Player

🧩 Supported Extensions

📦 File Structure (v1)

🚀 Getting Started

Python Installation

Rust Installation

Command Line Tools

Python API

Basic File Operations

Audio Analysis

Format Conversion

Audio Effects

Batch Processing

Unique Tools

Quality Analysis

Metadata Management

Rust API

📚 Use Cases

🛠️ Developer Tools & Modules

Core Modules

CLI Commands

Features

🧪 Roadmap

Completed ✅

In Progress 🚧

Planned 📋

💬 Community & Feedback

⚡ License

📖 Documentation

🎯 Quick Examples

Convert and Analyze

Batch Processing

Python Workflow

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Packages 0

Languages

Packages