hum

A local-first, customizable terminal music player.

Your music. Your terminal. Your layout.

About

hum is an open-source music player for people who keep their own local music libraries. It is a terminal application: a keyboard-driven TUI meant to run in a real terminal, not a desktop or web application styled to look like one.

You point hum at one or more directories, such as ~/Music, and it builds a local library from the files it finds. It reads metadata, groups tracks into albums and artists, and keeps a searchable index and a local listening history.

hum does not take ownership of your files. It does not move, rename, or reorganize anything on disk. The original files stay exactly where you put them, and the local database holds only the index and metadata, never copies of the audio.

There are no accounts, no cloud sync, and no streaming back end. Music files in, music out.

Why hum?

Most music players fall into one of two groups: streaming clients tied to a commercial service, or graphical library managers that want to manage your files for you. hum is neither.

It is built around a few priorities:

• Local ownership. Your library is your files and a local index. Nothing leaves your machine.
• Keyboard-first interaction. The interface is designed to be driven from the keyboard, in the terminal you already live in.
• Customization. The layout is meant to be configured and rearranged by the user, not fixed by the application.
• Terminal-native behavior. Dense, predictable, and fast, following the conventions of good Unix tools.
• High-quality local playback. A native audio pipeline rather than a wrapper around an external media player.

What hum is not

hum is not a streaming service, a social network, or a cloud platform. It is not an account-based or subscription product. It is not an Electron or web application, and it does not depend on any commercial streaming platform.

The initial project is focused entirely on local music libraries.

Planned features

None of the following is implemented yet. This section describes the intended product, not its current state.

• A TUI organized around familiar concepts: Now Playing, Library, Albums, Artists, Tracks, Playlists, Queue, Search, and listening history.
• Library scanning of user-configured directories, with metadata parsing and automatic grouping into artists, albums, and tracks.
• A native audio engine for local playback of common formats.
• Album artwork rendering in terminals that support image protocols, with a text-based fallback where they do not.
• A configurable layout system with splits, panes, and widgets.
• User-defined themes and keybindings.
• Configuration hot reload, so saving a config file updates the running interface without a restart.

Illustrative keybindings

These are draft defaults for discussion. They are not a stable interface and may change.

j / k     navigate
h / l     seek
space     play / pause
n         next
p         previous
/         search
6         queue
?         help
q         quit
Esc       back

Customization

Customization is a defining goal of the project. The intent is that a user can open a configuration file and make hum their own, in the spirit of tools like tmux, Neovim, or a tiling window manager.

Internally, the interface is planned as a tree of layout nodes rather than a hardcoded screen. That tree is what a configuration file describes: how the window is split, which widgets live in which panes, their relative sizes, the active theme, and the keybindings.

The configuration format has not been finalized and is intentionally left undefined here. See docs/configuration.md and docs/layout-system.md.

Terminal artwork

hum is a terminal application, but album artwork still matters. Where the terminal supports it, hum aims to render real cover images; where it does not, it falls back to a Unicode-based representation.

Artwork is expected to come from embedded metadata or from files in the album directory, such as cover.jpg, folder.jpg, or front.jpg.

Support for terminal image protocols (for example the Kitty graphics protocol, Sixel, and iTerm2-style images) is planned, not implemented. Details are in docs/artwork.md.

Technical direction

The intended implementation language is Rust. The planned stack:

Area	Direction
TUI	Ratatui
Terminal I/O	Crossterm
Audio output	CPAL
Audio decoding	Symphonia
Resampling	Rubato
Metadata	Lofty
Local index	SQLite (via rusqlite)
Artwork	image + ratatui-image
File watching	notify

This is a plan, not a status report. Decisions and rationale live in docs/architecture.md and docs/audio-engine.md.

Architecture

hum is planned as a modular monolith shipped as a single native executable. It may use a Cargo workspace internally to keep clear boundaries between the core, audio, library, configuration, UI, and platform layers, but these are internal modules, not services.

There is no backend, no web server, and no container requirement.

Two rules shape the design:

• The UI does not know how to play music.
• The audio engine does not know that a TUI exists.

Audio decoding and resampling happen away from the real-time audio callback, which is kept minimal. See docs/architecture.md and docs/audio-engine.md.

Project status

hum is in the planning and specification phase. There is no application code yet.

The current work is designing and documenting the project before implementation begins. The files under docs/ are the specification from which implementation work will later be derived. There are no releases, versions, or installation instructions at this stage.

Documentation

Start with docs/README.md. Individual topics:

• docs/vision.md — goals and scope
• docs/architecture.md — system design
• docs/audio-engine.md — playback pipeline
• docs/library.md — scanning and indexing
• docs/artwork.md — album art and terminal images
• docs/tui.md — interface concepts
• docs/layout-system.md — the layout tree
• docs/configuration.md — configuration model
• docs/keybindings.md — key handling
• docs/filesystem.md — paths and file layout
• docs/platform-support.md — target platforms
• docs/testing.md — testing approach
• docs/distribution.md — packaging and releases
• docs/development.md — working on hum
• docs/roadmap.md — planned direction

Platform priority is Linux first, macOS second, Windows later. None of these is supported yet; see docs/platform-support.md.

Contributing

The project is still being specified, so the most useful contributions right now are discussion and review of the documents under docs/. Development setup and conventions will be described in docs/development.md.

License

See LICENSE.