Prerequisites

Python 3.12 or newer: Aurras is built on Python 3.12+ and requires this version for proper functionality. You can download the latest version of Python from the official Python website.

Installation Methods

Recommended: Python Package Index (pip)

This is the most universal method and is recommended for all users:

Windows

No additional dependencies required. Aurras comes bundled with all necessary MPV components.

pip install aurras

Linux & macOS

You’ll need to install MPV first, then you can install Aurras.

# Install MPV (choose your platform)
 
# Ubuntu/Debian
sudo apt update && sudo apt install mpv
 
# Arch Linux
sudo pacman -S mpv
 
# Fedora/RHEL
sudo dnf install mpv
 
# macOS (via Homebrew)
brew install mpv

Once MPV is installed, proceed with the Aurras installation:

# Install Aurras
pip install aurras

Alternative Installation Methods

For users on specific operating systems, there are alternative installation methods available.

Arch User Repository (AUR) - Arch Linux Only

If you’re on Arch Linux, you can use a helper like yay to install Aurras from the AUR:

yay -S aurras

Homebrew - macOS Only

macOS users can also install Aurras directly via Homebrew:

brew install aurras

Chocolatey - Windows Only

Windows users can use Chocolatey for a convenient installation:

choco install aurras

Development Installation

For contributors and developers:

# Clone the repository
git clone https://github.com/vedant-asati03/Aurras.git
cd Aurras
 
# Setup the development environment
python setup_dev_env.py
 
# Launch in development mode
aurras --help

For comprehensive guidelines on contributing to Aurras, please refer to our Contributing Guide.

Technical Note: Aurras requires libmpv (MPV’s shared library) for audio playback. Installing the mpv package provides both the executable and the required libmpv library that Aurras uses through python-mpv bindings.

Post-Installation Setup

1. First Run

After installation, run Aurras for the first time:

aurras

On first launch, Aurras will:

Create configuration directories
Scan for audio devices
Set up default settings
Create a sample configuration file

2. Configuration Directory

Aurras stores its configuration in:

Linux/macOS: ~/.config/aurras/
Windows: %APPDATA%\Aurras\

3. Audio System Setup

Linux (ALSA/PulseAudio)

# Check audio devices
aurras --list-devices
 
# If you have issues, install additional audio libraries
sudo apt install libasound2-plugins pulseaudio-utils  # Ubuntu/Debian
sudo dnf install alsa-plugins-pulseaudio              # Fedora

macOS (CoreAudio)

No additional setup required. Aurras automatically detects available audio devices.

Windows (WASAPI)

Ensure your audio drivers are up to date. Aurras works with any Windows-compatible audio device.

Verification

Test your installation:

# Check version
aurras --version
 
# List available audio devices
aurras --list-devices
 
# Run with a test file (if you have audio files)
aurras /path/to/music/file.mp3
 
# Check help for all commands
aurras --help

Troubleshooting Installation

Common Issues

”Command not found” error

Cause: Aurras not in system PATH
Solution: Add the installation directory to your PATH environment variable

Audio device errors on Linux

Cause: Missing audio libraries or permissions

Solution:

# Add user to audio group
sudo usermod -a -G audio $USER
 
# Install missing libraries
sudo apt install libasound2-dev pulseaudio

Permission denied on macOS

Cause: macOS security restrictions