Getting Started

Getting Started

Astra is a desktop music player for local libraries. It runs on Windows, macOS, and Linux, and does not require an account.

This guide takes you from installation to your first playback. Most network features—including scrobbling, online lyrics, Discord presence, remote libraries, the phone remote, and Parallax—remain off until you enable or configure them.

Install Astra

Download the current beta from astramusic.dev or the GitHub Releases page.

Windows users can also install Astra with WinGet:

winget install Boof2015.Astra

Arch Linux users can install the official binary package from the AUR as astra-music-bin. Other community packages may package Astra differently; consult the package maintainer if a native audio or visualizer component is missing.

Add Your Music

1. Open Settings from the bottom of the sidebar.
2. Open Library.
3. Choose Manage Folders.
4. Choose Add Folder and select the top-level folder that contains your music.
5. Expand the folder tree if you want to exclude any subfolders.
6. Choose Save & Scan.

Astra scans all included subfolders, reads their metadata, and adds supported audio files to its library. The first scan can take time for a large collection. You can continue once the scan finishes or cancel it with the close button or Esc.

If some files cannot be indexed, the folder window shows a Scan Errors panel. Files listed there were skipped; the rest of the scan can still complete normally.

See Managing Your Music Library for supported formats, folder visibility, rescanning, metadata, artwork, and organization.

Browse the Library

Open Library from the sidebar. The tabs at the top provide six views:

• Tracks — Every visible track in one sortable list
• Albums — Releases grouped by album identity
• Artists — Artists in a list or artwork grid
• Genres — Tracks and albums grouped by genre
• Years — Releases and tracks grouped by release year
• Folders — Your library organized by its location on disk

Use the search field to narrow the current view. Press Ctrl+K on Windows or Linux, or Cmd+K on macOS, to open Quick Launch and search across tracks, albums, artists, playlists, views, and settings.

Play Music

Select a track to begin playback. Starting a track from an album, playlist, artist, or filtered library view builds the queue from that context.

The transport bar at the bottom of the window contains:

• Current track information and artwork
• Previous, play/pause, and next controls
• Shuffle and repeat controls
• The waveform seek bar and time readouts
• Volume and mute controls
• Buttons for the lyrics, track information, queue, mini player, and other active features

Right-click tracks, albums, artists, and playlists for actions such as Play Next or Add to Queue. See Queue and Playback Controls for the complete playback behavior.

Understand the Main Window

Sidebar — Opens Home, Library, optional Stats and Graph views, Equalizer, Playlists, and Settings. Frequently used playlists can appear directly in the sidebar.

Analyzer rack — The strip of audio scopes at the top of the window. Choose EDIT to arrange, resize, hide, configure, or pop out scopes. See Visualizers.

Main view — The active library, playlist, settings, or feature page.

Transport bar — Playback controls and the current track.

Queue and information panels — Open from the right side of the transport bar.

Audio Pipeline Shelf — Open from the left side of the transport bar to see the active signal path. See Audio Pipeline Shelf.

A Few Useful First Settings

• Settings > Appearance — Choose a theme, accent source, and interface scale.
• Settings > Audio Output — Confirm the output device and choose Standard or bit-perfect playback.
• Settings > Library — Configure normalization, ReplayGain preference, artist grouping, ratings, and optional tracklist columns.
• Settings > Playback — Choose where Jump to Playing opens and set a sleep timer.
• Settings > Keybinds — Review or change keyboard and mouse bindings.

You do not need to configure the advanced audio or experimental features to use Astra normally.

Keep Astra Updated

Open Settings > Info to view the installed version, enable automatic update checks, or choose Check Now. Astra opens the release page when an update is available; installation remains under your control.

Before moving to another computer or reinstalling, use the Settings Transfer wizard under Settings > Info. See Settings Transfer for what is included.