phiola

June 6, 2026 · View on GitHub

phiola is a fast audio player, recorder, converter, and streaming server for Windows, Linux, and Android. It can play audio files from your device or a remote server, record audio from your microphone or an internet radio stream, and convert audio into various formats. Its low CPU consumption helps extend the battery life of laptops and phones. You can control phiola via CLI, TUI, GUI, system pipe, or its API. Its fast startup time makes it ideal for custom scripts used on a "play-and-exit" or "record-and-exit" basis.

It is completely portable (all codecs are bundled), meaning you can run it directly from a read-only flash drive. phiola is free and open-source; use it as a standalone application or integrate it as a library into your own software.

Screenshots of phiola GUI on Android, KDE/Linux and Windows 10:

Contents:

Features
Install
How to Use CLI
How to Use GUI
How to Use on Android
How to Use API
Configuration
External Libraries
Build
Bug report
Why use phiola

Features

Play audio: .mp3, .ogg(Vorbis/Opus), .mp4/.mov(AAC/ALAC/MP3), .mkv/.webm(AAC/ALAC/MP3/Vorbis/Opus/PCM), .caf(AAC/ALAC/PCM), .avi(AAC/MP3/PCM), .ts(AAC/MP3), .aac, .mpc; .flac, .ape, .wv, .wav.
Record audio: .m4a(AAC), .aac(AAC-LC), .mp3, .ogg(Vorbis), .opus; .flac, .wav
Convert audio
Broadcast audio over HTTP
List/search file metadata; edit file tags, write ReplayGain tags (.mp3, .ogg/.opus, .flac)
List available audio devices
Input: file, directory, ICY/HLS/HTTP/HTTPS URL, console (stdin), playlists: .m3u, .pls, .cue
Audio filters:
- DynamicAudioNormalizer, auto loudness and ReplayGain normalizer
- multi-band equalizer
- noise gate
Command Line Interface for Desktop OS
Terminal/Console UI for interaction at runtime
GUI for Windows, Linux, Android: manage your playlists and audio files
Instant startup time: very short initial delay until the audio starts playing (e.g. Linux/PulseAudio: TUI: ~25ms, GUI: ~50ms)
Fast (small footprint, low overhead): keeps your CPU, memory & disk I/O at absolute minimum; spends 99% of its time inside codec algorithms

Bonus: Convenient API with plugin support which allows using all the above features from any C/C++/Java app!

Features and notes by platform:

Feature	Linux	Windows	Android
Dark themed GUI	✅ (GTK default)	incomplete	✅
File formats	✅ all supported	✅ all supported	all supported except `.mpc`, `.ape`, `.wv`
Record what you hear	✅ (PulseAudio)	✅	❌
Audio Streaming Server	✅ (AAC,Opus)	✅ (AAC,Opus)	❌
Requirements	glibc-2.36	Windows 7	Android 8 (ARM64), Android 6 (ARM)
HW Requirements	AMD64, ARM64	AMD64	ARM64, ARM(incomplete)

Although not officially supported, phiola should build fine for macOS, FreeBSD and Windows XP after tweaking the build script.

Important: ALAC decoder is disabled by default in phiola/Android because of potential security issues (see https://github.com/macosforge/alac).

Install

Download the latest package for your OS and CPU from phiola Releases

Linux (Portable)

In case you've chosen the portable package (i.e. phiola-....tar.zst), here's how you can install it into the ~/bin directory:

wget https://github.com/stsaz/phiola/releases/download/v2.3.12/phiola-2.3.12-linux-amd64.tar.zst
mkdir -p ~/bin
tar xf phiola-2.3.12-linux-amd64.tar.zst -C ~/bin
ln -s ~/bin/phiola-2/phiola ~/bin/phiola
cp ~/bin/phiola-2/mod/gui/phiola.desktop ~/.local/share/applications

If you choose another directory rather than ~/bin, then you should also edit Icon= value in ~/.local/share/applications/phiola.desktop.

Windows

The easiest way to install phiola on Windows is to execute phiola-...-windows-x64-setup.exe and specify the installation directory.

Another option is to manually unpack phiola-...-windows-x64.zip and add the phiola directory to your PATH environment.

Android

Install from IzzyOnDroid:

Or install .apk manually:

To be able to install .apk you need to enable "Allow installation from unknown sources" option in your phone's settings (you can disable it again after installation)
Tap on .apk file to install it on your phone

Or you can install an .apk file from the PC connected to your phone with adb install.

How to Use CLI

Important: enclose file names containing spaces or special characters in quotes, e.g.: phiola play "My Music"; phiola play "My Recordings" -include "*.wav".

Play:

# Play files, directories and URLs
phiola play file.mp3 *.flac "My Music" http://server/music.m3u
# or just
phiola file.mp3 *.flac "My Music" http://server/music.m3u

# Play all files within a directory in random order and auto-skip the first 20 seconds from each track
phiola "My Music" -random -seek 0:20

# Play on Linux directly via ALSA (and not PulseAudio)
phiola file.mp3 -audio alsa

# Play an internet radio and save the tracks as local files.
# These files will be named automatically using the metadata sent by the server.
phiola http://server/stream -tee "@artist - @title.mp3"

# Play an internet radio with on-demand recording
phiola http://server/stream -recordable
# Then at any time press Shift+R to start/stop recording

# Play MP3 audio via HTTP and convert to a local 64-kbit/sec AAC file
phiola http://server/music.mp3 -dup @stdout.wav | phiola convert @stdin -aac_q 64 -o output.m4a

# Play audio with 3-band Equalizer:
#  (low-shelf +3 dB; 600Hz band, 1.5 Q-factor width, -6 dB gain; high-shelf +3 dB)
phiola file.mp3 -equalizer "t bass g 3, f 600 w 1.5q g -6, t treble g 3"

While audio is playing, you can control phiola via the keyboard. The most commonly used commands are:

Key	Action
`Space`	Play/Pause
`Right Arrow`	Seek forward
`n`	Play next track
`p`	Play previous track
`q`	Quit
`h`	Show all supported commands

Record:

# Record from the default audio device until stopped
phiola record -o audio.flac

# Record for 1 minute, then stop automatically
phiola record -o audio.flac -until 1:0

# Record and set meta data
phiola record -meta "artist=Great Artist" -o audio.flac

# Record to the automatically named output file
phiola record -o @nowdate-@nowtime.flac

# Record with a specific audio format
phiola record -aformat int16 -rate 48000 -channels 2 -o audio.flac

# Record what is currently playing on your system ("what you hear")
# * WASAPI:
phiola record -loopback -o audio.flac
# * PulseAudio:
phiola record -dev $(phiola dev list -f Monitor -n) -o audio.flac

# Start recording in background, then stop recording from another process:
#   Step 1: record while listening for system-wide commands
phiola -Background record -o audio.flac -remote
#   Step 2: send 'stop' signal to the phiola instance that is recording audio
phiola remote stop

# Record and split the output files by 1 hour
phiola record -split 1:00:00 -o @nowdate-@nowtime.flac

# Record and pass the audio through Dynamic Audio Normalizer filter
phiola record -danorm 'frame 500 size 15' -o audio.flac

# Record and pass the audio to another program
phiola record -o @stdout.wav | your_program

Note: the output audio format is chosen automatically by the file extension you specify.

Note: it's not required to always type the whole name of a command or an option - you may type just its prefix (enough for phiola to recognize it), e.g. instead of phiola record -aformat int16 you may type phiola rec -af int16.

Convert:

# Convert
phiola convert audio.flac -o audio.m4a

# Convert with parameters
phiola convert file.mp3 -aformat int16 -o file.wav
phiola convert file.wav -vorbis_q 7 -o file.ogg
phiola convert file.wav -rate 48000 -aac_q 5 -o file.m4a

# Convert multiple files from .wav to .flac
phiola convert *.wav -o .flac

# Convert all .wav files inside a directory,
#  preserving the original file names and file modification time
phiola convert "My Recordings" -include "*.wav" -o @filepath/@filename.flac -preserve_date

# Copy (without re-encoding) MP3 audio region from 1:00 to 2:00 to another file
phiola convert -copy -seek 1:0 -until 2:0 input.mp3 -o output.mp3

# Extract (100% accurately) several tracks from a .cue file
phiola convert input.cue -tracks 3,5-7,13 -o "@tracknumber. @artist - @title.flac"

# Increase .wav file's volume by 6 dB
phiola convert file.wav -gain 6 -o file-louder.wav

Note: the output audio format is chosen automatically by the file extension you specify.

Show file info:

# Show meta info on all .wav files inside a directory
phiola info "My Recordings" -include "*.wav"

# Show meta info including all tags
phiola info -tags file.mp3

# Search for the .mp3 files containing a specific tag
phiola info -tags -inc "*.mp3" . | grep -B10 "Purple Haze"

# Analyze and show PCM info
phiola info -peaks file.mp3

# Analyze audio loudness
phiola info -loudness file.mp3

Edit file tags:

# Replace/add MP3 tags in-place
# WARNING: please test this first before using it on real files (or at least make backups)!
phiola tag -m "artist=Great Artist" -m "title=Cool Song" file.mp3

# Remove all existing tags; add new tags
phiola tag -clear -m "artist=Great Artist" -m "title=Cool Song" file.mp3

# Write ReplayGain tag for all .mp3 & .flac files in the directory
phiola tag -rg track_gain "My Music" -include "*.mp3" -include "*.flac"

Create/edit playlist files:

# Create a playlist from all .mp3 files in the directory
phiola list create "My Music" -include "*.mp3" -o my-music.m3u

# Sort entries (by file name) in all playlists in the current directory
phiola list sort *.m3u

# Automatically correct the file paths inside playlist (e.g. after some files were moved)
phiola list heal Music/playlist.m3u

Other use-cases:

# List all available audio playback and recording devices
phiola device list

# Auto-rename all .opus files according to a pattern
phiola rename *.opus -o "@tracknumber. @artist - @title"

# Start HTTP audio streaming server (Opus, 128kbps)
phiola server "My Music" -inc "*.flac" -shuffle -opus_q 128

Currently supported commands:

Command	Description
convert	Convert audio
device	List audio devices
gui	Start graphical interface
info	Analyze audio files
list	Process playlist files
play	Play audio
record	Record audio
remote	Send remote command
rename	Auto-rename files
server	Start audio streaming server
tag	Edit file tags

For the details on each command you can click on the links above or execute phiola COMMAND -h on your PC.

How to Use GUI

Start phiola GUI:

On Windows: via phiola-gui.exe
On Linux:
```
phiola gui
```

Then add some files to your playlist via drag-n-drop from your File Manager, or via List->Add menu command.

Bonus: you can modify the appearance by editing the GUI source file: phiola-2/mod/gui/ui.conf. You can also modify the text by editing language files, e.g. phiola-2/mod/gui/lang_en.conf. On Windows you can modify the dark theme colors by editing phiola-2/mod/gui/theme-dark-white.conf. Restart phiola GUI after you make changes to those files.

100% Portable Mode

By default, phiola GUI saves and restores its state (including your playlists) on each restart at these locations:

Windows: %APPDATA%\phiola
Linux: $HOME/.config/phiola

If you prefer not to save state, simply create an empty [phiola directory]/mod/gui/user.conf file. As long as this file is present, phiola GUI will store its state there, and it won't touch anything inside your user directory.

How to Use on Android

Starting for the first time:

Run phiola app
Tap on Explorer tab
Android will ask you to grant/deny permissions to phiola. Allow phiola to read your storage files.
Tap on the music file you want to listen to
Or long-press on the directory with your music, it will be added to the playlist; tap Play
Tap on Playlist tab to switch the view to your playlist

Recording From Radio on Android

By default the Record button starts recording from microphone. Here's how you can reconfigure phiola for recording audio from the internet radio:

Go to Settings, then under the First Control Button setting, choose Record From Radio; return to main screen.
Go to List -> List: Add... and paste the URL; tap Add.
Tap on the URL in the playlist to start playback.
Tap on Record button (bottom-left button) to start recording; tap again to stop recording. Your recorded files are stored inside Recording directory.

Note: phiola supports recording from AAC or MP3 radio streams.

How to Use API

The best example of how to use the phiola software interface is to see the source code of phiola executor in src/exe, e.g. src/exe/play.h contains the code that adds input files into a playlist and starts the playback.

src/phiola.h describes all interfaces implemented either by phiola Core or dynamic modules
android/.../Phiola.java is a Java interface
src/track.h contains internal declarations for a phiola track, and you'll need it only if you want to write your own filter

Here's how phiola works:

When the user launches the phiola app, the top-level module, the Executor, begins running.
The Executor loads the Core module, which provides access to all of phiola's functions.
In graphical mode, the Executor waits for and analyzes user commands to decide the next action.
For audio playback, the Executor prepares a queue of tracks and initiates playback.
A Track represents a single job (e.g., a single file being played) and consists of several Filters linked together to form a processing pipeline. While a track is running, the Core calls these Filters in sequence until the entire pipeline is complete. Multiple tracks can run in parallel.
A Filter is a piece of code located within a Module that performs a single, specific task on a Track.
A Module is a shared library that may contain one or more Filters. It provides access for those Filters to the Executor, Core, or other Modules. All necessary Modules are loaded on-demand while Tracks are running.
Before a Track begins, it is assigned to a Worker — a system thread that executes the Filter code.
When a Track starts, stops, or is updated, the Executor's internal Filters are called to relay status updates to the user interface.

Configuration

Global settings can be specified in phiola-2/phiola.conf file. See the contents of phiola-2/phiola-example.conf for more info.

External Libraries

phiola uses modified versions of these third party libraries: libALAC, libfdk-aac, libFLAC, libebur128, libMAC, libmpg123, libmp3lame, libmpc, libopus, libvorbis, libwavpack, libsox, libsoxr, libzstd, libDynamicAudioNormalizer. And these unmodified libraries: openssl. Many thanks to their creators for the great work!!! Please consider their licenses before commercial use. See contents of alib3/ for more info.

Additionally:

ffbase library and ffsys interface make it easy to write high level cross-platform code in C language
avpack library provides multimedia file read/write capabilities
ffaudio interface provides cross-platform audio I/O capabilities
ffgui - cross-platform GUI
netmill provides network capabilities

Build

Build Instructions

Bug report

If you encounter a bug, please report it via phiola GitHub Issues. When filing a bug report, please provide as much information as possible to help developers understand and fix the problem.

When using CLI, additional debug messages may help sometimes - just add -D after phiola when executing a command, e.g.:

phiola -D play file.mp3

With phiola on Android, there's a button in "About" screen that will save system logs to a file. It will contain the necessary information about the last time phiola crashed, for example.

Why use phiola

phiola is not a competitor to large-scale commercial projects; instead, its focus is security and speed. Its main advantages are:

Open-Source. phiola and all its dependencies are completely open-source. You aren't running private, potentially insecure code on your device — this is critical for software that runs for hours every day.
High Flexibility. phiola is highly adaptable and can easily accommodate a wide range of functions. It is also designed to be embedded as a module in other projects. For example, if you were building a smart coffee machine that needed to play music, phiola would be the perfect choice!
Minimal Resource Footprint. While powerful and user-friendly, phiola uses the absolute minimum amount of CPU and memory — often significantly less than many mainstream alternatives. This efficiency extends device battery life and contributes to lower overall power consumption.

License

phiola is licensed under BSD-2. Please review the licenses of all third-party libraries before any commercial use. Playback control icons by Icons8.