Elevate your music experience. Aurras transforms your terminal into a sophisticated, feature-rich music hub, letting your audio fill your space, uninterrupted and unburdened. Seamlessly access both online streaming platforms and your local offline music library. Take command with robust playlist management and advanced queue controls for precise playback. Personalize your setup further with deep customizability and vibrant theme support, among many other powerful capabilities.
Real-Time Synced Lyrics - Enjoy advanced lyrics synchronization with gradient highlighting, theme integration, and millisecond-accurate timing that makes every word dance with your music
Dynamic Intelligence Search - Context-aware search bar with live recommendations, smart autocompletion, command palette integration, history integration, all this with adaptive highlighting
Live Theme Ecosystem - 10 built-in themes with instant switching mid-playback, complete visual consistency across all components, and deep customization for every interface element
Comprehensive Settings Engine - Hierarchical configuration system with highly customizable options, keyboard shortcut remapping, appearance controls, and settings that adapt to your workflow
Smart Backup - Intelligent automated protection with smart restoration, missing media detection, and one-command recovery for complete peace of mind
Dual Interface Mastery - Seamlessly switch between streamlined CLI for power users and feature-rich TUI(Upcoming...) for immersive experiences, both with full feature parity
Seamless Platform Integration - Complete Spotify library import, YouTube unlimited access, local music prioritization, and unified search across all sources with intelligent content discovery
Smart Download Management - High-quality offline music with format selection, instant local playback prioritization, playlist batch downloads, and gapless transitions
Aurras offers both command-line and terminal UI modes to suit different workflows:
"With great power comes great responsibility" - Aurras understands this very well and that's why it equips you with every weapon in its arsenal that you'll need.
Basic controls are visible at the bottom of the player, but those are not enough, right? Yes, that's what I thought too, which is why it has:
Jump Mode - Before pressing b or n, you can press any number to jump through that many songs
Collapsible Lyrics View - If you do not want to see the lyrics, you can hide them by pressing l
And just to help you with all this, Aurras also provides real-time feedback during playback so you are always in control.
Oh boy! Where do I even start with this one? A real-time, context-aware search bar featuring command palette, options menu, and even supports shortcuts for commands and shorthands!
But wait, there's more! Every keystroke is intelligently highlighted with adaptive theming that matches your current theme, making commands and search terms visually distinct. As you type, Aurras provides live song recommendations right in the search bar, and maintains a smart history accessible with simple up/down arrow keys.
Intelligent Search Features:
Smart Autocompletion - Not just basic autocomplete, the more you use it the better it gets
Contextual Highlighting - Commands, song names, and search operators are beautifully highlighted with theme-aware colors
Instant Recommendations - See song suggestions appear in real-time as you type, no need to hit enter
Navigation History - Use ↑ and ↓ arrows to browse through your search history like a true terminal pro
For a detailed look at how the intelligent search bar functions, a dedicated blog post is currently in the works.
An intelligent Search module is another great feat of aurras, it uses providers to achieve a multi-level search implementation, check the Search implementation for better understanding on how it works.
Download and manage offline music with support for selecting your preffered format, bitrate, and location.
You can also download songs as a playlist,
Master your music collection with Aurras' intelligent playlist ecosystem that seamlessly bridges online and offline worlds. Our advanced playlist engine delivers sophisticated management capabilities with smart organization, automated synchronization, and reliability that keeps your musical universe perfectly curated.
Core Capabilities: Smart creation • Batch operations • Spotify import • Fuzzy search • Download management • Song manipulation • Queue integration • Database optimization • Sync automation
Build your musical universe with precision and ease. Aurras' playlist management system combines intelligent automation with granular control, allowing you to create, organize, and maintain complex playlist hierarchies with database-backed reliability and intelligent search capabilities.
"My Favrites" finds "My Favorites" seamlesslyListen with ease: aurras playlist my_playlist — comes with offline playback priority
Seamlessly bridge your Spotify universe with Aurras. Our sophisticated import system provides OAuth-authenticated access to your entire Spotify library with intelligent synchronization, selective import options, and an upcoming feature ~ automated playlist updating that keeps your collections perfectly aligned.
Bridge platforms effortlessly: aurras playlist --import — instant access to your entire Spotify collection
Transform streaming playlists into high-quality offline collections. Our advanced download engine provides intelligent batch processing, format selection, and local prioritization that ensures your favorite playlists are always available, optimized, and ready for instant playback.
Download with precision: aurras download --playlist "Chill Mix" --format flac --bitrate 320k
Run aurras playlist --help to explore the complete playlist management suite.
Aurras believes in "Your music, your way" — and that philosophy extends deep into every configurable aspect of the application. To start, just run aurras settings --help
Aurras uses settings.yaml file to store all your settings located at ~/.aurras/config/settings.yaml
Hierarchical Settings - Settings are organized in logical groups with inheritance, so changing them is very easy aurras settings --set <key> <value>
quit-playback qtoggle-play-pause SPACEnext-track nprevious-track bvolume-up UPvolume-down DOWNseek-forward RIGHTseek-backward LEFTtoggle-lyrics lquit-playback qstop-jump-mode ESCswitch-themes tdownload-song downloadplay-offline offlineplay-playlist playlistdownload-playlist downloadpview-playlist viewdelete-playlist deleteimport-playlist importsearch-by-song-or-artist searchdisplay-history historyplay-previous-song previousclear-listening-history clearsetup-spotify setupdisplay-cache-info cachecleanup-cache cleanuptoggle-lyrics lyricsself-management self (update, uninstall, version info, check dependencies)download-song dplay-offline oplay-previous-song prevplay-playlist pdownload-playlist dpview-playlist vdelete-playlist dedisplay-history htheme cyberpunkdisplay-video nodisplay-lyrics nouser-feedback-visible yesdate-format yyyy-mm-ddtime-format 24hAurras ships with a carefully curated collection of themes and design to improve experience and accessibility. To get started quickly run aurras theme --help:
Galaxy Deep space-inspired theme with rich purples and bluesNeon Vibrant digital visualization styleVintage Warm retro vinyl player feelMinimal Clean distraction-free interfaceNightclub Clean distraction-free interfaceCyberpunk Bright futuristic cyberpunk aestheticForest Earthy green natural environmentOcean Calming blue oceanic color paletteSunset Warm orange and pink sunset tonesMonochrome Classic black and white stylingAurras provides unparalleled control over its appearance, allowing you to perfectly match your preferences:
t to cycle through a variety of themes instantly.l.
If you are interested in knowing how this app centralized theme system works, take a look at Theme Module
Your musical journey is precious, and losing it should never be an option. Aurras delivers backup protection with intelligent automation, smart restoration, and comprehensive data preservation that ensures your playlists, preferences, and entire music experience remain safe, accessible, and perfectly restored whenever you need them.
Core Capabilities: Automated backups • Smart restoration • Selective backup items • Timed scheduling • Intelligent cleanup • Missing media detection • One-click recovery • Storage optimization • Data integrity
Never lose a beat with proactive backup automation. Our intelligent backup system continuously monitors your data and automatically creates comprehensive backups based on configurable schedules, ensuring your musical universe is always protected without manual intervention.
~/.local/share/aurras/backup, macOS: ~/Library/Application Support/aurras/backup, Windows: %LOCALAPPDATA%\aurras\backup)Run aurras backup --help to get started with using backup system.
Transform your listening experience into an immersive journey where every word comes alive. Aurras delivers industry-leading synced lyrics with real-time highlighting, intelligent parsing, and theme-integrated visual effects that make you feel every beat and word as they flow through your speakers.
Core Capabilities: Real-time synchronization • Word-level highlighting • Theme integration • Multi-format support • Intelligent caching • Asynchronous fetching • Visual gradients • Context-aware display • Fallback mechanisms • Live positioning
Experience lyrics that dance with your music. Our advanced synchronization engine delivers almost pixel-perfect timing with gradient-highlighted text that flows seamlessly with the rhythm, creating an immersive karaoke-like experience right in your terminal.
[mm:ss.ss] LRC timestamp formats and enhanced word-level timingExperience the magic: Watch lyrics come alive with synchronized highlighting as your music plays
This guide provides comprehensive instructions for installing Aurras on various operating systems.
When you install Aurras using a system-specific package manager, all necessary dependencies are handled automatically. This is the simplest and recommended method.
choco install aurras
yay -S aurras
If you don't have
yayor another AUR helper, consult the Arch Wiki for installation instructions.
brew install aurras
When installing Aurras via pip, you'll need to manually ensure that certain external dependencies are present on your system. Aurras requires libmpv (MPV's shared library) for audio playback and ffmpeg for media processing.
Aurras comes bundled with all necessary MPV components for Windows, but you will need to install FFmpeg separately.
choco install ffmpeg
Once FFmpeg is installed, you can proceed with installing Aurras:
pip install aurras
Before installing Aurras, you must first install MPV and FFmpeg using your system's package manager.
Ubuntu/Debian:
sudo apt update && sudo apt install mpv ffmpeg
Arch Linux:
sudo pacman -S mpv ffmpeg
Fedora/RHEL:
sudo dnf install mpv ffmpeg
macOS:
brew install mpv ffmpeg
After ensuring MPV and FFmpeg are installed, you can install Aurras:
pip install aurras
Technical Note: Aurras requires
libmpv(MPV's shared library) for audio playback. Installing thempvpackage provides both the executable and the requiredlibmpvlibrary that Aurras uses through python-mpv bindings.
# 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 Contributions Guide
Connect your music universe - Aurras currently provides Spotify integration with a flexible architecture designed to support additional music services as the community grows.
Currently supported:
# View Spotify integration options
aurras setup --spotify --help
# Check current integration status
aurras setup --spotify --status
# Run the interactive setup wizard
aurras setup --spotify
# Import your playlists after setup
aurras playlist --import
# Check integration status
aurras setup --spotify --status
Create Spotify App: Visit Spotify Developer Console
http://127.0.0.1:8080 (must be exact)Configure Aurras: Run aurras setup --spotify and enter your credentials
Import Playlists: Run aurras playlist --import to access your Spotify library
aurras setup --spotify --status # Check connection status
aurras setup --spotify --reset # Reset credentials
aurras playlist --import # Import playlists
Need help? See the complete Spotify Integration Guide for detailed instructions and troubleshooting.
Aurras is designed with an extensible architecture to support additional music service integrations. Potential future additions based on community interest:
Community-driven development: Want to see a specific service integrated? Request it here or contribute to the development!
Ensure Aurras fits perfectly into your workflow. This section outlines how to effortlessly customize themes, manage core application settings, and safeguard your unique setup with robust backup and restore functionality.
aurras theme # List out all the themes
aurras theme ocean # Change the app theme to 'ocean'
Aurras empowers you to personalize your player's appearance by creating your own themes. This allows for complete control over the color scheme, ensuring your terminal music experience perfectly matches your aesthetic.
To define a custom theme, simply create a themes.yaml file within the ~/.aurras/config directory.
Here's an example of a custom theme configuration:
DRACULA:
name: "DRACULA"
display_name: "Dracula"
description: "The famous dark theme with purple, pink, and cyan colors"
category: "CUSTOM"
dark_mode: true
# Core colors
primary: "#BD93F9" # Purple
secondary: "#8BE9FD" # Cyan
accent: "#FF79C6" # Pink
# UI background colors
background: "#282A36" # Dark background
surface: "#44475A" # Lighter surface
panel: "#6272A4" # Panel color
# Status colors
warning: "#FFB86C" # Orange
error: "#FF5555" # Red
success: "#50FA7B" # Green
info: "#8BE9FD" # Cyan
# Text colors
text: "#F8F8F2" # Foreground
text_muted: "#6272A4" # Comment
# Border colors
border: "#6272A4"
# Gradients for enhanced visuals
title_gradient: ["#BD93F9", "#FF79C6", "#8BE9FD"]
artist_gradient: ["#8BE9FD", "#50FA7B", "#FFB86C"]
status_gradient: ["#F8F8F2", "#F8F8F2AA", "#F8F8F277"]
progress_gradient: ["#BD93F9", "#FF79C6", "#50FA7B"]
feedback_gradient: ["#50FA7B", "#50FA7BAA", "#50FA7B77"]
history_gradient: ["#8BE9FD", "#8BE9FDAA", "#8BE9FD77", "#8BE9FD44"]
# Dim
dim: "#333366"
aurras settings # List out the app settings
aurras settings --set appearance-settings.display-lyrics no # Updating settings to disable lyrics display
aurras settings --reset # Restore all app settings to their default values
| Key | Action |
|---|---|
Space | Play/Pause |
n | Next song |
b | Previous song |
l | Toggle lyrics |
↑ / ↓ | Volume up/down |
← / → | Seek backward/forward |
aurras backup # List out all the existing backups
aurras backup --create # Create a backup
aurras backup --restore ID # Restore to a specific backup with its unique id
Encountering an issue? Here are solutions to some common problems. For more in-depth guidance, refer to our comprehensive Troubleshooting Guide.
mpv or libmpv not found:
Windows: Aurras includes bundled MPV DLLs, so this error shouldn't occur. If you see MPV-related errors, try reinstalling with choco upgrade aurras.
Linux/macOS:
yay -S aurras or brew reinstall aurras# Fedora/RHEL
sudo dnf install mpv
# Debian/Ubuntu
sudo apt install mpv
# Arch Linux
sudo pacman -S mpv
# macOS
brew install mpv
Technical Detail: Aurras uses python-mpv bindings which load
libmpvdynamically. You need the shared library (libmpv.soon Linux,libmpv.dylibon macOS), which is provided by the main MPV package.
Display Information Not Updating During Playback:
If the player's display freezes or fails to update song progress and information, this often relates to your slow internet connection.
For more detailed troubleshooting, including specific error codes, advanced scenarios, and solutions to less common issues, please consult the comprehensive Troubleshooting Guide.
Need to remove Aurras from your system? We've made it easy with our built-in self-management command that safely removes all traces of the application.
# Using built-in uninstall command (recommended)
aurras self --uninstall
Package-only removal will:
Warning: Complete data removal will permanently delete all your songs, playlists, history, spotify credentials, settings, and themes. This action cannot be undone.
sudo on Linux/macOS or run as administrator on WindowsAurras is a new project with huge ambitions, and we're just getting started! Your contributions are incredibly valuable in shaping its future and making it even better. We warmly welcome all ideas and help. Here's how you can join in:
git clone https://github.com/vedant-asati03/Aurras.git
cd Aurras
# Set up development environment
python setup_dev_env.py
Code Contributions:
Non-Code Contributions:
We follow these standards:
For detailed guidelines, see our Contributing Guide.
This project is licensed under the MIT License - see the LICENSE file for details.
Aurras comes alive thanks to these amazing open-source projects. Huge shoutout to their creators and maintainers:
Made with ❤️ by the Aurras Community
FAQs
A high-end command line music player
We found that aurras demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
MCP spec updated with structured tool output, stronger OAuth 2.1 security, resource indicators, and protocol cleanups for safer, more reliable AI workflows.
Security News
More than half of CISOs now manage 10+ security areas, often with few legal safeguards and short tenures, yet continue to secure budgets and higher pay.
Security News
Libxml2’s solo maintainer drops embargoed security fixes, highlighting the burden on unpaid volunteers who keep critical open source software secure.