VoluMod

License & Philosophy

This project is licensed under the Mozilla Public License, v. 2.0. See the LICENSE file for details.

SPDX-License-Identifier: MPL-2.0

A User-Friendly, Cross-Platform Tool for Autonomous Audio Volume and Clarity Optimization

VoluMod automatically optimizes audio volume and clarity in real-time for non-technical users across browsers and system tray applications.

Features

Core Audio Processing

• Real-time Volume Normalization - EBU R128 / LUFS-based loudness normalization

• Dynamic Range Compression - Adaptive compression with configurable modes

• Perceptual Noise Reduction - AI-ready noise floor detection and reduction

• Graphic Equalization - 10-band EQ with adaptive presets

• Brick-wall Limiting - Protection against clipping

Contextual Adaptation

• Time-of-Day Profiles - Automatic adjustment based on time (quieter at night)

• Device Detection - Optimized settings for headphones, speakers, etc.

• Environment Awareness - Adapts to ambient noise levels (optional microphone input)

User Experience

• Zero-Learning-Curve Interface - Simple, intuitive design for all ages

• One-Click Bypass - Instantly disable all processing

• WCAG Compliant - Full accessibility support including screen readers

• Keyboard Navigation - Complete keyboard shortcut support

Installation

System Application

# Clone the repository
git clone https://github.com/hyperpolymath/volumod.git
cd volumod

# Build with V
v -prod src/main.v -o volumod

# Run
./volumod

Browser Extension

# Build ReScript components
cd browser/rescript
npm install
npm run build

# Load extension in browser
# Chrome: chrome://extensions → Load unpacked → select browser/
# Firefox: about:debugging → Load Temporary Add-on → select browser/manifest.json

Architecture

volumod/
├── src/
│   ├── core/              # Core audio types and DSP utilities
│   │   ├── audio_buffer.v
│   │   └── dsp_utils.v
│   ├── processors/        # Audio processing modules
│   │   ├── normalizer.v   # Loudness normalization
│   │   ├── compressor.v   # Dynamic range compression
│   │   ├── noise_reducer.v # Noise reduction
│   │   └── equalizer.v    # Graphic/parametric EQ
│   ├── engine/            # Processing engine
│   │   ├── processor.v    # Main audio processor chain
│   │   └── context.v      # Contextual adaptation
│   ├── platform/          # Platform-specific audio capture
│   │   └── audio_capture.v
│   ├── ffi/               # Cross-language interop (Bebop)
│   │   ├── bebop_types.v
│   │   └── bebop_bridge.v
│   ├── ui/                # User interface
│   │   ├── tray.v         # System tray
│   │   └── accessibility.v # WCAG compliance
│   └── main.v             # Application entry point
├── browser/               # Browser extension
│   ├── manifest.json
│   ├── background.js
│   ├── content.js
│   ├── popup/
│   └── rescript/          # ReScript audio processor
└── v.mod                  # V module definition

Technical Stack

Component	Technology
Core Audio Processing	V language (memory-safe, high-performance)
Cross-Platform IPC	Bebop (serialization/interop framework)
Browser Extension	ReScript → JavaScript (Web Audio API)
Audio Capture	PortAudio / WASAPI / CoreAudio / ALSA
UI Framework	V UI (cross-platform native)

Audio Processing Pipeline

Input Audio
    │
    ▼
┌─────────────────┐
│ Noise Reduction │ ← Clean up source audio
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Normalization  │ ← Achieve consistent loudness (-14 LUFS default)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Compression    │ ← Control dynamic range
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Equalization   │ ← Shape frequency response
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    Limiting     │ ← Protect output from clipping
└────────┬────────┘
         │
         ▼
    Output Audio

Presets

Preset	Description	Target LUFS	Compression
Auto	Balanced for general content	-14	Moderate
Speech	Optimized for podcasts/calls	-16	Light
Music	Preserves dynamics	-14	Light
Night Mode	Quieter, compressed for low volume	-20	Aggressive
Hearing Assistance	Boosted clarity, enhanced speech	-12	Moderate

Accessibility

VoluMod is designed to be accessible to all users:

• Screen Reader Support - Full ARIA labels and live regions

• Keyboard Navigation - All features accessible via keyboard

• High Contrast Mode - Respects system preferences

• Reduced Motion - Respects prefers-reduced-motion

• Hearing Loop Integration - Telecoil/T-coil support planned

Keyboard Shortcuts

Shortcut	Action
Ctrl+Shift+B	Toggle bypass
Ctrl+Shift+N	Start noise learning
Ctrl+Shift+Up	Increase target loudness
Ctrl+Shift+Down	Decrease target loudness
F1	Open help

Privacy

• 100% On-Device Processing - No audio data leaves your device

• No Analytics - No usage tracking or telemetry

• Optional Microphone - Ambient noise detection is opt-in

• Local Storage Only - Settings stored locally

Development

Building from Source

# Prerequisites
# - V compiler: https://vlang.io
# - Node.js (for browser extension)

# Clone
git clone https://github.com/hyperpolymath/volumod.git
cd volumod

# Build V application
v -prod src/main.v -o volumod

# Build browser extension
cd browser/rescript
npm install
npm run build

Running Tests

v test src/

Roadmap

Phase	Features	Status
v0.1.0 Foundation	Project structure, V source (11 modules), ReScript extension (3 modules), build verified	Complete
v0.2.0 Audio Pipeline	PipeWire/PulseAudio integration, loopback capture, lookahead buffer, unit tests	Not started
v0.3.0 MVP	End-to-end normalization, compression, bypass, system tray UI, basic presets	Not started
v0.4.0 Advanced	Noise reduction, adaptive EQ, time-of-day profiles, device detection, environment awareness	Not started
v0.5.0 Browser	Chrome/Firefox extension, Web Audio API, ReScript deprecation fixes	Not started
v0.6.0 Accessibility	WCAG 2.1 AA audit, screen reader testing, hearing loop, keyboard navigation	Not started
v1.0.0 Stable	Full feature set, comprehensive tests, cross-platform, production ready	Not started

See ROADMAP.adoc for detailed milestone breakdown and DESIGN-DECISIONS.adoc for architecture rationale.

License

This project is licensed under the Mozilla Public License, v. 2.0. See the LICENSE file for details.

SPDX-License-Identifier: MPL-2.0

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

Documentation

• ROADMAP.adoc - Phased development roadmap with milestones

• TOPOLOGY.md - System architecture diagram and completion dashboard

• RESEARCH-REPORT.adoc - Market research and technology survey

• DESIGN-DECISIONS.adoc - Architecture decisions with rationale

• TESTING-REPORT.adoc - Build verification report (2025-12-29)

• STATE.scm - Machine-readable project state

• META.scm - Architecture Decision Records

Acknowledgments

• V Language: https://vlang.io

• Bebop: https://github.com/betwixt-labs/bebop

• ReScript: https://rescript-lang.org

• Web Audio API: https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API

• PortAudio: https://www.portaudio.com/

• PipeWire: https://pipewire.org/

• EBU R128: https://tech.ebu.ch/publications/r128