================================================================================
tui123 - Terminal Music Player v0.1.5
================================================================================
DESCRIPTION
-----------
tui123 is a lightweight, terminal-based MP3 music player for Linux systems.
It provides a full-featured ncurses interface for managing and playing your
music library entirely from the command line.
FEATURES
--------
Audio Playback:
* MP3 file playback using libmpg123 decoder
* Audio output via libao (ALSA, OSS, PulseAudio) or native OSS
* Play/pause/stop controls
* Track seeking (forward/backward)
* Volume control (0-100%)
* Previous/next track navigation
* Shuffle queue support
Library Management:
* SQLite3 database for music library
* Automatic metadata scanning (ID3 tags)
* Browse by artist, album, and track
* Search and filter functionality
* Track duration and metadata display
Playlist Support:
* Create and manage multiple playlists
* Add/remove tracks from playlists
* Load playlists to queue
* Reorder tracks within playlists
* Persistent playlist storage
Queue Management:
* Add tracks to playback queue
* Remove tracks from queue
* Reorder queue entries (+/- keys)
* Shuffle queue (Ctrl+R)
* View current queue position
Album Artwork Display:
* Extract embedded album art from MP3 files (JPEG)
* Multiple rendering backends:
- fbdev: Direct framebuffer rendering (best quality)
- libcaca: Colored ASCII art in terminal
- libaa: Monochrome ASCII art
* Configurable color depth (Mono, CGA, EGA, VGA, Full)
* Smart caching and pre-caching of artwork
* Dithered rendering for lower color depths
User Interface:
* Full ncurses TUI with multiple views
* Pure ASCII interface, works on real physical terminals!
* Tab-based navigation (Queue, Library, Playlists, Settings)
* Keyboard-driven controls
* Real-time playback status display
* Progress bar with time elapsed/remaining
* Info bar showing track metadata
* Context-sensitive help for each view
Configuration:
* Customizable music directory
* Adjustable sample rate and channel configuration
* Mono downmix option
* Configurable metadata decoder backend
* Selectable album art renderer
* Settings persist across sessions
SYSTEM REQUIREMENTS
-------------------
* Linux-based operating system
* Terminal with ncurses support
* For audio: ALSA, OSS, or PulseAudio
* For framebuffer artwork: /dev/fb0 access (console mode)
DEPENDENCIES
------------
Required:
* C99 compatible compiler and linker
* make
* libncurses5-dev / ncurses-devel (TUI)
* libmpg123-dev / libmpg123-devel (MP3 decoding)
* libsqlite3-dev / sqlite-devel (database)
* libid3tag0-dev / libid3tag-devel (ID3 metadata)
* pkg-config
Optional (for album artwork):
* libao-dev / libao-devel (for audio output via ALSA or Pulseaudio)
* libcaca-dev / libcaca-devel (colored ASCII art)
* libaa1-dev / aalib-devel (monochrome ASCII art)
* libimlib2-dev / imlib2-devel (image processing)
* libjpeg-dev / libjpeg-turbo-devel (JPEG support)
Build Dependencies:
* pthread (thread support, usually built-in)
* libm (math library, usually built-in)
INSTALLATION INSTRUCTIONS
--------------------------
Debian/Ubuntu:
--------------
1. Install dependencies:
$ sudo apt-get update
$ sudo apt-get install build-essential gcc make pkg-config \
libncurses5-dev libmpg123-dev libsqlite3-dev \
libid3tag0-dev libao-dev
Optional (for album artwork):
sudo apt-get install libcaca-dev libaa1-dev libimlib2-dev libjpeg-dev
2. Build the project:
$ cd /path/to/tui123
$ make release
3. (Optional) Install system-wide:
$ sudo make install
This installs to /usr/local/bin/tui123
4. Run the player:
$ ./tui123
Or if installed:
$ tui123
Void Linux:
-----------
1. Install dependencies:
$ sudo xbps-install -S base-devel gcc make pkg-config \
ncurses-devel mpg123-devel sqlite-devel \
libid3tag-devel libao-devel
Optional (for album artwork):
$ sudo xbps-install -S libcaca-devel aalib-devel imlib2-devel libjpeg-turbo-devel
2. Build the project:
$ cd /path/to/tui123
$ make release
3. (Optional) Install system-wide:
$ sudo make install
4. Run the player:
$ ./tui123
Or if installed:
$ tui123
Building with OSS Audio Support:
---------------------------------
If you prefer native OSS audio instead of libao:
$ make release OSS=1
Note: This removes the libao dependency but requires OSS kernel support (snd-pcm-oss.ko).
BUILD TARGETS
-------------
make - Build debug version (with debug symbols)
make debug - Same as above
make release - Build optimized release version
make clean - Remove all build artifacts
make install - Build and install to /usr/local/bin
make uninstall - Remove installed binary
make check-deps - Check for required libraries
make help - Show Makefile help
USAGE
-----
Keyboard Controls:
Global:
Tab - Switch between control areas (tabs/content)
Space - Play/pause
P - Restart song
S - Stop playback
N - Next track
R - Previous track
I - Volume up
K - Volume down
Q - Quit
Queue View:
Up/Down - Navigate tracks
X - Remove selected track
Ctrl+R - Shuffle queue
+/- - Move track up/down in queue
Library View:
Up/Down - Navigate items
Enter/Right - Drill down into artist/album
Left - Go back up
A - Add selected item to queue
Playlists View:
Up/Down - Navigate playlists/tracks
Enter - Select playlist
A - Add track/list to queue
X - Remove track from playlist
Ctrl+A - Insert queue items into playlist
Ctrl+N - Create new playlist
Ctrl+X - Delete playlist
+/- - Move track up/down in playlist
Settings View:
Up/Down - Navigate settings
Left/Right - Change setting value
Enter - Edit setting
CONFIGURATION
-------------
On first run, tui123 creates a configuration directory at:
~/.config/tui123/
Configuration file:
~/.config/tui123/config.conf
Database file:
~/.config/tui123/music.db
Playlists directory:
~/.config/tui123/playlists/
Default music directory:
~/Music
To scan your music library, place MP3 files in the configured music directory
and open Settings in the player, then select "Rescan music folder".
TROUBLESHOOTING
---------------
No audio output:
- Check that libao is installed and ALSA/PulseAudio is working
- Try building with native OSS: make release OSS=1
- Verify your user has access to audio devices
Framebuffer artwork not working:
- Framebuffer rendering only works in console mode (not in terminal emulators)
- Ensure /dev/fb0 exists and you have permissions (chmod a+w /dev/fb0)
- Use libcaca or aalib renderers for terminal emulator support
Library not showing files:
- Verify music files are in the configured music directory
- Check that files have valid ID3 tags
- Delete ~/.config/tui123/music.db to force re-scan
LICENSE
-------
MIT License
Copyright (c) 2026 Minki the Avali
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
SUPPORT
-------
For bug reports and feature requests, please check the project repository or
contact the maintainer directly.
================================================================================
End of README
================================================================================