# alsamixer

> A terminal-based audio mixer for Windows — inspired by the classic Linux `alsamixer`.

[![CI / Release](https://github.com/cumulus13/alsa-mixer/actions/workflows/ci.yml/badge.svg)](https://github.com/cumulus13/alsa-mixer/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Crates.io](https://img.shields.io/crates/v/alsa-mixer)](https://crates.io/crates/alsa-mixer)

```
┌─────────────────────────── alsamixer — Windows Audio Mixer ───────────────────────────┐
│  100%    85%    60%    45%                                                            │
│  ║███║  ║███║  ║███║  ║   ║                                                           │
│  ║███║  ║███║  ║███║  ║   ║                                                           │
│  ║███║  ║███║  ║   ║  ║   ║                                                           │
│  ║███║  ║███║  ║   ║  ║   ║                                                           │
│  ║███║  ║   ║  ║   ║  ║   ║                                                           │
│  Master  Spotify  Chrome  Discord                                                     │
│   🔊       🔊       🔊      MUTE                                                     │
└───────────────────────────────────────────────────────────────────────────────────────┘
       [←/→] Select   [↑/↓] Volume ±5   [M] Mute   [Q/Esc] Quit
```

## Features

- **Master volume** control via Windows WASAPI endpoint volume API
- **Per-application** volume & mute via Windows Audio Session API (WASAPI)
- Gradient-coloured vertical bars (blue → cyan → green → yellow → red)
- Full mute toggle with visual indicator
- Keyboard-driven — no mouse required
- Zero runtime dependencies beyond the Windows OS itself
- Single static executable, ~2 MB stripped

## Requirements

| Requirement | Version |
|---|---|
| OS | Windows 10 / 11 (any edition) |
| Rust toolchain | 1.75+ (MSVC ABI) |
| Terminal | Windows Terminal, ConEmu, or any VT100 terminal |

> **Note:** The classic Windows `cmd.exe` works but Windows Terminal gives the best visual experience.

## Installation

### Pre-built binary (recommended)

Download the latest `alsamixer-vX.Y.Z-x86_64-pc-windows-msvc.exe` from the
[Releases](https://github.com/cumulus13/alsa-mixer/releases) page, rename it to
`alsamixer.exe`, and place it anywhere on your `%PATH%`.

### From source

```powershell
# Requires Rust + MSVC build tools: https://rustup.rs
git clone https://github.com/cumulus13/alsa-mixer
cd alsa-mixer
cargo build --release
# Binary is at: target\release\alsamixer.exe
```

### Via cargo install (once published)

```powershell
cargo install alsa-mixer
```

## Usage

```
alsamixer
```

### Keyboard Controls

| Key | Action |
|-----|--------|
| `←` / `→` | Select previous / next channel |
| `Tab` / `F6` | Select next channel |
| `↑` | Volume +5% |
| `↓` | Volume −5% |
| `M` | Toggle mute |
| `Q` / `Esc` | Quit |
| `Ctrl+C` | Force quit |

## Architecture

```
src/
├── main.rs      — Entry point: COM init, terminal setup, teardown
├── app.rs       — Application state & main event loop
├── audio.rs     — WASAPI backend (WasapiMixer)
├── ui.rs        — Ratatui rendering (title, bars, controls)
├── input.rs     — Crossterm key-event → Action mapping
└── error.rs     — MixerError type
```

### Audio Backend

`alsamixer` uses the **Windows Audio Session API (WASAPI)** via the [`windows`](https://crates.io/crates/windows) crate:

- `IMMDeviceEnumerator` — discovers the default render endpoint
- `IAudioEndpointVolume` — master volume & mute
- `IAudioSessionManager2` → `IAudioSessionEnumerator` → `ISimpleAudioVolume` — per-app volume/mute

No third-party audio middleware is required.

## Building for Release

```powershell
cargo build --release
# Outputs: target\release\alsamixer.exe (~2 MB, fully stripped)
```

The `Cargo.toml` is configured with:
```toml
[profile.release]
opt-level = 3
lto       = true
codegen-units = 1
strip     = true
```

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| No channels shown | Ensure at least one audio output device is enabled in Sound settings |
| Garbled display | Use Windows Terminal for proper Unicode / VT100 support |
| Access denied errors | Run as the same user who owns the audio sessions (not as Administrator) |
| Per-app sessions missing | App must be actively playing audio to appear as a session |

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feat/my-feature`)
3. Commit with conventional commits (`feat:`, `fix:`, `docs:` …)
4. Open a Pull Request — CI will run `cargo fmt` check and `cargo clippy`

## License

MIT © 2026 [Hadi Cahyadi](mailto:cumulus13@gmail.com)

---

*Inspired by the Linux `alsamixer` TUI from the `alsa-utils` project.*

## 👤 Author
        
[Hadi Cahyadi](mailto:cumulus13@gmail.com)
    

[![Buy Me a Coffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/cumulus13)

[![Donate via Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/cumulus13)
 
[Support me on Patreon](https://www.patreon.com/cumulus13)