minau

A lightweight, efficient command-line music player built with Rust using symphonia for decoding and cpal for audio output.

Features

• 🎵 Simple and Fast - Minimal overhead, quick startup time
• 📊 Volume Control - Adjustable playback volume from command line
• 🎼 Multiple Format Support - Supports common audio formats (MP3, WAV, FLAC, OGG, etc.)
• 🖼️ Album Art Display - View album artwork during playback with GUI mode
• 💻 Cross-platform - Works on Windows, macOS, and Linux
• ⚡ Low Resource Usage - Efficient even in resource-constrained environments
• 🎛️ Easy to Use - Intuitive command-line interface
• ⌨️ Keyboard Controls - Pause/play, skip tracks, adjust volume, and seek through tracks
• 📃 M3U Playlist Support - Play music from M3U playlist files
• 🔄 Async Support - Built with async/await for better performance
• ⏩ Seek Control - Jump forward or backward within tracks using keyboard shortcuts
• 🌐 URL Streaming - Stream audio directly from HTTP/HTTPS URLs

Installation

Quick Install (macOS/Linux)

The easiest way to install minau on macOS or Linux:

curl -sSfL https://raw.githubusercontent.com/sirasaki-konoha/minst/refs/heads/master/script/install.sh | sh

Quick Install (Windows)

Download the latest executable installer from the releases page and run it directly.

From crates.io

You can also install minau via cargo:

cargo install minau

This will install the latest stable version from crates.io.

From Source

git clone https://github.com/sirasaki-konoha/minau.git
cd minau
cargo install --path .

Usage

Basic Usage

Play a single audio file:

minau path/to/music.mp3

Play multiple audio files:

minau song1.mp3 song2.mp3 song3.flac

Play all audio files in a directory:

minau path/to/music/folder/*

URL Streaming

Stream audio directly from URLs:

minau https://example.com/audio.mp3

Stream with volume control:

minau https://example.com/stream.mp3 --volume 50

Multiple URL support:

minau https://example.com/1.mp3 https://example.com/2.mp3

Volume Control

Set playback volume (1-100):

minau music.mp3 --volume 50

Maximum volume:

minau music.mp3 --volume 100

Minimum volume:

minau music.mp3 --volume 1

GUI Mode

Display album artwork during playback:

minau music.mp3 --gui

Combine with volume control:

minau music.mp3 --gui --volume 75

Keyboard Controls

During playback, you can use the following keyboard shortcuts:

Examples

# Play a single file at 75% volume
minau ~/Music/favorite.mp3 --volume 75

# Play with GUI mode to display album art
minau ~/Music/favorite.mp3 --gui

# Play multiple files with GUI
minau song1.mp3 song2.wav song3.flac --gui

# Play all MP3 files in current directory
minau *.mp3

# Play with minimum volume
minau quiet-music.mp3 --volume 1

# GUI mode with custom volume
minau album.flac --gui --volume 60

Command-line Arguments

• <FILES>... - One or more audio files or URLs to play (required)

  • Type: Vec<String>
  • Accepts file paths and HTTP/HTTPS URLs
  • Supports various audio formats including M3U playlists
  • Can handle both absolute and relative paths
  • Can stream audio from remote URLs

• --volume <VOLUME>, -v - Playback volume level (optional)

  • Type: u16
  • Range: 1-100
  • Default: 100 (maximum volume)
  • Values outside range will cause an error

• --gui, -g - Enable GUI mode to display album artwork (optional)

  • Shows embedded album art from audio file metadata
  • Works with files that have embedded cover images
  • Uses a native window for display

Supported Audio Formats

minau supports a wide range of audio formats through the symphonia library:

• MP3
• WAV
• FLAC
• OGG Vorbis
• AAC
• And many more formats supported by symphonia

Requirements

• Rust 1.82.0 or later (for building from source)
  • Note: This project uses Rust 2024 edition and requires a recent Rust version
• A system audio output device
• Cross-platform support: Windows, macOS, and Linux

Architecture

minau uses a modular architecture with direct audio processing:

• symphonia - High-performance audio decoding library supporting various formats
• cpal - Cross-platform audio library for low-latency audio output
• Direct audio pipeline for minimal overhead and maximum performance

Performance

minau is designed to be lightweight and efficient:

• Fast startup time
• Minimal memory footprint
• Low CPU usage during playback
• Direct audio pipeline without unnecessary abstractions
• Suitable for resource-constrained environments (e.g., embedded systems, older hardware)

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.

Author

@sirasaki-konoha

Note: Use keyboard controls during playback for pause/play, volume adjustment, and track navigation.