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.

• 🎚️ 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

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

• 🎨 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

# Install dependencies
pip install -r requirements.txt

# Run the player
python player/run.py

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

# Navigate to the Rust implementation
cd rust

# Build the project
cargo build

# Run tests
cargo test

# Build documentation
cargo doc --open

# 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

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
)

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)

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"
)

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)

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")

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
)

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']}%")

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"})

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")?;

• 🎮 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

• 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

• 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

• ✅ 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)

• 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.)

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

• 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

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

👉 Issues • Discussions

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

Copyright © 2025 Mehmet T. AKALIN / Digital Vision

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

# 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

# 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

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.