🎧 Bitwave - Next-Gen Multi-Channel Audio Format

🔥 Features

🎵 Cross-Platform Player

Player Features

Player Controls

Running the Player

# Install dependencies
pip install -r requirements.txt

# Run the player
python player/run.py

🧩 Supported Extensions

📦 File Structure (v1)

🚀 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

🛠️ Developer Tools & Modules

Core Modules

CLI Commands

Features

🧪 Roadmap

Completed ✅

In Progress 🚧

Planned 📋

💬 Community & Feedback

⚡ License

📖 Documentation

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