audiofilus
Music player for Linux handhelds

Your music keeps playing while you game.

audiofilus is a pixel-art music player with album covers, visualizers, six arcade games and a chiptune tracker. Close it, open an emulator, and the music goes on. Turn the screen off and control it from your pocket.

Download for PortMaster Source on GitHub

Knulli · muOS · ROCKNIX · ArkOS · dArkOS — also on Linux and Windows desktops.

The Now Playing screen: album cover, track info and a spectrum visualizer pulsing with the song
  • MP3
  • AAC / M4A
  • ALAC
  • FLAC
  • Ogg Vorbis
  • Opus
  • WAV
  • AIFF
  • MOD · XM · IT · S3M
  • M3U playlists
Background play

A player that stays out of the way

The audio lives in its own service

The interface is just a remote. Close it and the music keeps going; launch a game and it still plays, with gapless track changes and a quick fade when you pause.

Controls from inside any game

Hold FN and tap a button to pause, skip, go back or seek. Your headphones' play button works too, over Bluetooth or cable: one press pauses, two skip, three go back.

Sleep mode for your pocket

Press START twice or the power button: the screen turns off, the CPU slows down and the triggers become gestures. Close the lid and it stays asleep. On an RG34XX-SP it draws about 260 mA in this mode: around 11 to 12 hours of music on its 3300 mAh battery.

Help is one button away

Hold FN on any screen to see what every button does there.

The controls guide over the player, listing the buttons for on-screen, everywhere, sleep and background use

The controls guide, shown while FN is held.

The More menu with Album, Artist, Add to a playlist, Queue, Shuffle, Repeat, Screen off, Background and Quit

START opens the More menu, including “Background” to leave the app and keep listening.

Visualizers and games

Something to look at

Seven visualizers that follow the beat, all drawn at low resolution and kept light on the CPU. Colors come from the album cover.

Lake visualizer: a night lake whose lily pads ripple with the music
Lake ripples on the beat
Drift visualizer: a car driving down a lit road at night
Drift three cameras
Trench visualizer: flying down a city canyon
Trench city canyon
Plasma visualizer: dithered glowing plasma
Plasma dithered
Tunnel visualizer: a pulsing ring tunnel
Tunnel pulses with bass
Waves visualizer: an oscilloscope trace
Waves oscilloscope
Bars visualizer: spectrum bars with falling peaks
Bars spectrum
Crypt: a hooded hero steps through a dungeon whose floor tiles flash on every beat, with slimes, coins and a rhythm bar
Crypt. A rhythm roguelike: step, fight and dive deeper, but only on the beat of your song. Enemies move to the music too.
Blocks: a falling-blocks game played next to the mini player
Blocks. Falling blocks with hold, next piece and a record, while the album keeps playing.
Snake: the snake steps on the song's beat subdivisions over a grid of dots that pulse with it
Snake. It moves on the song's own beat, so every song plays at its own speed.
Ships: a ship firing upward at pixel aliens over a starfield
Ships. Fire on every eighth note, spread shots on the bass, enemies arriving with the beats.
Name that song: four songs from the library to choose from while one plays
Name that song. A few seconds of a song from your library, four choices, ten rounds.
Rhythm: notes fall down lanes built from the song's beats, with a PERFECT hit message
Rhythm. Notes are generated from whatever song is playing. Hit them on time for combos.
Tracker

Make your own chiptune

A Game Boy style tracker for the D-pad: two pulse channels, a triangle and noise, 16-step patterns with arpeggios, duty and pitch bends, and a song order. Export a song as WAV and it lands in your library, ready to play in the background like anything else.

The tracker playing Pocket Pop: four channels with live oscilloscopes, cells lighting up as their notes play, the view following the song from pattern to pattern

The games and the tracker live behind one Games entry in the screens dock, each game with its own record. And there are a few secrets hidden around the app.

Colors

Every album paints it

The interface takes its colors from the cover that's playing. Change the album and the whole player, the visualizers and the games follow.

Shown with four albums from a real library: each cover gives two accents and a tint for the background.

The player switching between four albums, its accent going orange, blue, green and pink with each cover
Sources

Your files, your server, the radio

Everything shows up in the same library and the same player. Remote songs are cached on the SD card so the next listen is free.

Local

Your library

Folders, tags, embedded and folder covers, M3U playlists and your own playlists. Scanned once, then only new files are read.

Server

Subsonic

Navidrome and other Subsonic or OpenSubsonic servers. Songs stream, stay cached for the next listen, and can be downloaded.

Server

Jellyfin

Sign in with your Jellyfin user and browse its music library and playlists like your own files.

Live

Internet radio

Thousands of stations from radio-browser.info, by country or genre, with the current song title from the stream.

Episodes

Podcasts

Top shows for your country, search, or any RSS feed by address. Episodes download for offline listening and remember where you stopped.

Bring your own

YouTube Music

Copy your own yt-dlp next to the app and search appears: listen without downloading, or save songs into your library with cover and tags.

Search with All, Library and YouTube filters; songs you already have are checked
One search for the library and YouTube. A check marks songs you already have.
The player with a STREAMING badge while a song loads
Streaming songs get a badge, and you can keep them.
The player showing a live radio station with its current song
Radio plays live, with the song title from the station.
Screens

Made for a D-pad

SELECT opens a dock with every screen; press it twice to jump back to the last one. A QWERTY on-screen keyboard handles search and playlist names. Interface sounds are optional, in two separate switches for menus and for music actions.

Album grid with covers
Albums, with artists, songs, playlists and folders beside them.
The screens dock along the bottom of the display
The screens dock.
The play queue
The queue, with shuffle, repeat and “play next”.
Add to a playlist dialog
Your own playlists, saved as M3U8 files next to the app.
Any screen

From square to ultrawide

The layout adapts to the screen's real width instead of picking from a few fixed shapes, so it fills a 1:1 RGB30, a 3:2 clamshell and a 21:9 monitor.

Player on a 1:1 screen
1:1
Player on a 4:3 screen
4:3
Player on a 3:2 screen
3:2
Player on a 16:9 screen
16:9
Player on a 21:9 screen
21:9
Install

Through PortMaster

KnullimuOSROCKNIXArkOSdArkOS
  1. Download audiofilus-portmaster.zip from the latest release.
  2. Install it with PortMaster, or unzip it into your ports folder.
  3. Open audiofilus from Ports and pick your music folder.
  4. Optional: put a yt-dlp binary in the app's yt-dlp/ folder to enable YouTube Music.

On a Linux or Windows PC, see Desktop.

Each system is detected at startup. Lid, power button, battery saver and volume use that system's own tools; on a desktop all of that is skipped.

Build from source

One command

Written in Go without cgo for the handhelds. Codec libraries are loaded at runtime when the system has them.

# with Docker, nothing else to install
git clone https://github.com/juanvillacortac/audiofilus
cd audiofilus
docker build --target dist --output dist .

# or with Go installed
./build.sh

Both leave the desktop and arm64 binaries plus the PortMaster zip in dist/.

Desktop

At home on your PC

The same player runs on Linux and Windows. On Linux it fits in like a native app on GNOME, KDE, Hyprland and Omarchy.

In your app launcher

Audiofilus shows up with its icon, and right-clicking it offers play/pause, next and previous. Window rules and docks recognize its window.

Media keys and your bar

It speaks MPRIS, so your keyboard's media keys, headphones and the desktop's media widget control it, with the cover and the song title. On Omarchy that works with nothing to set up.

Still plays in the background

Close the window and the music keeps going; open it again and it picks up where it is.

Linux

One line to install

curl -fsSL https://juanvillacortac.github.io/audiofilus/install.sh | sh
  1. Downloads the latest release for x86_64 or aarch64 into ~/.local/share/audiofilus.
  2. Links audiofilus and audiofilus-ui into ~/.local/bin.
  3. Adds Audiofilus to your app launcher. Run it again any time to update; your settings stay.

Or set it up by hand

  1. Download audiofilus-linux-amd64.tar.gz (or -arm64) from the latest release and unpack it anywhere.
  2. In that folder, run ./audiofilus desktop install. It adds the launcher entry and the icon to ~/.local/share.
  3. Open Audiofilus from your app launcher. If you move the folder, run step 2 again.

Uninstall: audiofilus quit; audiofilus desktop uninstall; rm -rf ~/.local/share/audiofilus ~/.local/bin/audiofilus*

Windows 10 or later: download audiofilus-windows-amd64.zip, unzip it anywhere and run audiofilus-ui.exe.

Roadmap

Beyond handhelds

The same player, tuned for bigger screens and phones.

Runs today

Desktop

Already runs on Linux and Windows, with launcher, media keys and crisp pixel scaling. Next: mouse controls and layouts made for big windows.

Planned

Android

Touch controls, a lock-screen player and background playback through the system's media session.

Planned

iOS

The same pixel interface on iPhone and iPad, with Control Center and AirPods controls.

Support

Keep it playing

audiofilus is free and made in my spare time. If it plays on your handheld every day, a coffee helps me keep working on it and bring it to desktop and phones.

Buy me a coffee on Ko-fi