Configuration Overview
Aurras stores its configuration in platform-specific directories:
- Linux/macOS:
~/.config/aurras/config.toml
- Windows:
%APPDATA%\Aurras\config.toml
Initial Setup
On first run, Aurras creates a default configuration file. You can also generate a new one:
# Generate default config
aurras --generate-config
# Edit configuration file
aurras --edit-config
Basic Configuration
Audio Settings
[audio]
# Audio output device (auto-detected by default)
output_device = "auto"
# Default volume (0-100)
default_volume = 75
# Audio buffer size (lower = less latency, higher = more stable)
buffer_size = 4096
# Sample rate (44100, 48000, 96000)
sample_rate = 44100
# Audio quality (low, medium, high, lossless)
quality = "high"
# Enable audio normalization
normalize_audio = true
# Crossfade duration in seconds
crossfade_duration = 2.0
Display Settings
[display]
# Show album artwork (requires terminal with image support)
show_artwork = true
# Artwork size in terminal cells
artwork_size = [20, 10]
# Show spectrum visualizer
show_visualizer = true
# Visualizer style (bars, wave, circle)
visualizer_style = "bars"
# Color scheme (dark, light, auto)
theme = "dark"
# Show track progress bar
show_progress = true
# Display format for track info
track_format = "{artist} - {title} ({album})"
# Update interval for display (milliseconds)
update_interval = 100
Keybindings
Customize all keyboard shortcuts:
[keybindings]
# Playback controls
play_pause = "Space"
next_track = ["Right", "l"]
previous_track = ["Left", "h"]
stop = "s"
# Volume controls
volume_up = ["Up", "k", "+"]
volume_down = ["Down", "j", "-"]
mute = "m"
# Navigation
seek_forward = "Shift+Right"
seek_backward = "Shift+Left"
jump_to_start = "Home"
jump_to_end = "End"
# Playlist controls
shuffle_toggle = "z"
repeat_toggle = "r"
add_to_queue = "a"
remove_from_queue = "d"
# Library navigation
search = "/"
filter = "f"
sort = "o"
# Application
quit = ["q", "Ctrl+c"]
help = ["?", "F1"]
settings = ","
Library Management
[library]
# Music directories to scan
music_directories = [
"~/Music",
"/mnt/external/music"
]
# File formats to include
supported_formats = [
"mp3", "flac", "ogg", "m4a", "wav",
"opus", "aac", "wma", "aiff"
]
# Exclude directories
exclude_directories = [
".git", "temp", "cache"
]
# Scan subdirectories
recursive_scan = true
# Watch for file changes
watch_directories = true
# Metadata cache size (MB)
cache_size = 100
# Auto-organize library
auto_organize = false
organize_pattern = "{artist}/{album}/{track} - {title}"
Playlist Settings
[playlists]
# Default playlist directory
playlist_directory = "~/.config/aurras/playlists"
# Auto-save current queue as playlist
auto_save_queue = true
# Default shuffle mode for new playlists
default_shuffle = false
# Smart playlist generation
enable_smart_playlists = true
# Recently played history size
history_size = 100
Advanced Audio Configuration
Equalizer Presets
[equalizer]
# Enable equalizer
enabled = false
# Default preset
default_preset = "flat"
# Custom presets
[equalizer.presets.rock]
"60Hz" = 4
"230Hz" = 2
"910Hz" = -1
"4kHz" = 3
"14kHz" = 2
[equalizer.presets.classical]
"60Hz" = 0
"230Hz" = 0
"910Hz" = 0
"4kHz" = 0
"14kHz" = 2
Audio Effects
[effects]
# Reverb settings
[effects.reverb]
enabled = false
room_size = 0.3
damping = 0.5
wet_level = 0.1
# Bass boost
[effects.bass_boost]
enabled = false
frequency = 100 # Hz
gain = 3 # dB
# Dynamic range compression
[effects.compressor]
enabled = false
threshold = -20 # dB
ratio = 4.0
attack = 3 # ms
release = 100 # ms
Theme Customization
Built-in Themes
# List available themes
aurras --list-themes
# Switch theme
aurras --theme neon
Custom Theme
[theme]
name = "custom"
# Color palette
[theme.colors]
background = "#1a1a1a"
foreground = "#ffffff"
accent = "#00ff88"
secondary = "#ff6b6b"
muted = "#666666"
warning = "#ffaa00"
error = "#ff4444"
# UI elements
[theme.ui]
progress_bar = "█"
progress_empty = "░"
volume_bar = "▮"
volume_empty = "▯"
Performance Tuning
[performance]
# Number of worker threads
worker_threads = 4
# Memory usage limits
max_memory_mb = 512
# Prefetch next tracks
prefetch_count = 2
# Cache album artwork
cache_artwork = true
# Background processing priority
background_priority = "low"
# Disk cache settings
[performance.cache]
enabled = true
size_mb = 100
cleanup_interval = 3600 # seconds
Platform-Specific Settings
Linux/ALSA
[platform.linux]
# ALSA device
alsa_device = "default"
# PulseAudio server
pulseaudio_server = "unix:/run/user/1000/pulse/native"
# Audio latency
target_latency = 40 # milliseconds
macOS/CoreAudio
[platform.macos]
# CoreAudio device
coreaudio_device = "default"
# Exclusive mode
exclusive_mode = false
# Bit-perfect playback
bit_perfect = false
Windows/WASAPI
[platform.windows]
# WASAPI device
wasapi_device = "default"
# Exclusive mode
exclusive_mode = false
# Event mode
event_mode = true
Configuration Validation
# Check configuration syntax
aurras --check-config
# Validate and show effective config
aurras --show-config
# Reset to defaults
aurras --reset-config
# Backup current config
aurras --backup-config
Configuration Examples
Minimal Setup (Lightweight)
[audio]
default_volume = 75
quality = "medium"
[display]
show_artwork = false
show_visualizer = false
theme = "dark"
[performance]
worker_threads = 2
max_memory_mb = 128
Audiophile Setup (High Quality)
[audio]
output_device = "high_end_dac"
default_volume = 60
buffer_size = 8192
sample_rate = 96000
quality = "lossless"
normalize_audio = false
[effects.compressor]
enabled = false
[platform.linux]
target_latency = 20
Party Mode (Visual Focus)
[display]
show_artwork = true
show_visualizer = true
visualizer_style = "circle"
update_interval = 50
[audio]
crossfade_duration = 5.0
[playlists]
default_shuffle = true
Troubleshooting Configuration
Common Issues
Config file not found:
# Recreate default config
aurras --generate-config
Audio device errors:
# List available devices
aurras --list-audio-devices
# Test audio output
aurras --test-audio
Permission errors:
# Fix config directory permissions
chmod 755 ~/.config/aurras/
chmod 644 ~/.config/aurras/config.toml
Advanced Configuration Tips
- Multiple Configs: Use
--config-file
to specify different config files - Environment Variables: Override settings with
AURRAS_VOLUME=50
- Profile Switching: Create config profiles for different use cases
- Live Reload: Changes to config file are applied immediately (in most cases)
Next Steps
- Advanced Features - Explore power user capabilities
- Playlist Management - Master playlist features
- Troubleshooting - Fix configuration issues
⚙️ Configuration complete! Your Aurras setup is now perfectly tailored to your needs.