• Introduction
• Examples
• Installation
• Features
  • Connect
  • Media Control
  • Image
  • Notify
  • Mouse support
  • Daemon
  • Fuzzy search
  • CLI commands
• Commands
• Configurations
• Caches
  • Logging
• Acknowledgement

_player is a fast, easy to use, and configurable terminal music player.

Features

• Minimalist UI with an intuitive paging and popup system.
• Highly configurable
• Feature parity with the official application.
• Support remote control with Connect.
• Support songs directly from the terminal.
• Support synced lyrics.
• Support cross-platform media control.
• Support image rendering.
• Support desktop notification.
• Support running the application as a daemon
• Offer a wide range of CLI commands

A demo of _player v0.5.0- on youtube or on asciicast:

Checkout examples/README.md for more examples.

By default, the application's installed binary is _player.

A Premium account is required.

• Rust and cargo as the build dependencies

• Rust and cargo as the build dependencies

• install openssl, alsa-lib ( feature), libdbus (media-control feature).

  • For example, on Debian based systems, run the below command to install application's dependencies:

    sudo apt install libssl-dev libasound2-dev libdbus-1-dev

Application's prebuilt binaries can be found in the Releases Page.

Note: to run the application, Linux systems need to install additional dependencies as specified in the Dependencies section.

Run brew install _player to install the application.

Run scoop install -player to install the application.

Run cargo install _player --locked to install the application from crates.io.

Run yay -S -player to install the application as an AUR package.

Alternatively, run yay -S -player-full to install an AUR package compiled with full feature support and Pulseaudio/Pipewire instead of rodio.

Run xbps-install -S -player to install the application.

Run pkg install -player to install the _player binary from FreeBSD ports.

Using the package manager, run pkgin install -player to install from the official repositories.

Building from source,

cd /usr/pkgsrc/audio/-player
make install

-player is available as a Nix package and can be installed via nix-shell -p -player or as part of your system configuration.

If you want to build the source locally you can run nix-shell in the root of a checkout of the source code. The provided shell.nix file will install the build prerequisites.

Note: feature is disabled when using the docker image.

You can download the binary image of the latest build from the master branch by running

docker pull aome510/_player:latest

then run

docker run --rm -it aome510/_player:latest

to run the application.

You can also use your local config folder to configure the application or your local cache folder to store the application's cache data when running the docker image:

docker run --rm \
-v $APP_CONFIG_FOLDER:/app/config/ \
-v $APP_CACHE_FOLDER:/app/cache/ \
-it aome510/_player:latest

To enable a full connect support, user will need to register a application and specify the application's client_id in the general configuration file as described in the configuration documentation.

More details about registering a application can be found in the official documentation.

When _player runs with your own client_id, press D (default shortcut for SwitchDevice command) to get the list of available devices, then press enter (default shortcut for ChooseSelected command) to connect to the selected device.

_player supports , which needs to be built/installed with feature (enabled by default) and with an audio backend (rodio-backend by default). The feature allows to _player to play music directly from terminal.

The application uses librespot library to create an integrated client while running. The integrated client will register a speaker device under the -player name, which is accessible on the connect device list.

_player uses rodio as the default audio backend. List of available audio backends:

• alsa-backend
• pulseaudio-backend
• rodio-backend
• portaudio-backend
• jackaudio-backend
• rodiojack-backend
• sdl-backend
• gstreamer-backend

User can change the audio backend when building/installing the application by specifying the --features option. For example, to install _player with pulseaudio-backend, run

cargo install _player --no-default-features --features pulseaudio-backend

Note:

• needs to specify --no-default-features here because rodio-backend is one of the default features.
• user will need to install additional dependencies depending on the selected audio backend. More details can be found in the Librespot documentation.

The feature can be also disabled upon installing by running

cargo install _player --no-default-features

To enable media control support, _player needs to be built/installed with media-control feature (enabled by default) and set the enable_media_control config option to true in the general configuration file.

Media control support is implemented using MPRIS DBus on Linux and OS window event listener on Windows and MacOS.

To enable image rendering support, _player needs to be built/installed with image feature (disabled by default). To install the application with image feature included, run:

cargo install _player --features image

_player supports rendering image in a full resolution if the application is run on either Kitty or iTerm2. Otherwise, the image will be displayed as block characters.

_player also supports rendering images with sixel behind sixel feature flag, which also enables image feature:

cargo install _player --features sixel

Notes:

• Not all terminals supported by libsixel are supported by _player as it relies on a third-party library for image rendering. A possible list of supported terminals can be found in here.
• Images rendered by sixel can have a weird scale. It's recommended to tweak the cover_img_scale config option to get the best result as the scaling works differently with different terminals and fonts.

Examples of image rendering:

• iTerm2:

• Kitty:

• Sixel (foot terminal, cover_img_scale=1.8):

• Others:

To enable desktop notification support, _player needs to be built/installed with notify feature (disabled by default). To install the application with notify feature included, run:

cargo install _player --features notify

Note: the notification support in MacOS and Windows are quite restricted compared to Linux.

Currently, the only supported use case for mouse is to seek to a position of the current playback by left-clicking to such position in the playback's progress bar.

To enable a daemon support, _player needs to be built/installed with daemon feature (disabled by default). To install the application with daemon feature included, run:

cargo install _player --features daemon

You can run the application as a daemon by specifying the -d or --daemon option: _player -d.

Notes:

• daemon feature is not supported on Windows

• daemon feature requires the feature to be enabled and the application to be built with an audio backend

• because of the OS's restrictions, daemon feature doesn't work with the media-control feature on MacOS, which is enabled by default. In other words, if you want to use the daemon feature on MacOS, you must install the application with media-control feature disabled:

  cargo install _player --no-default-features --features daemon,rodio-backend

To enable fuzzy search support, _player needs to be built/installed with fzf feature (disabled by default).

_player offers several CLI commands to interact with :

• get: Get data (playlist/album/artist data, user's data, etc)
• playback: Interact with the playback (start a playback, play-pause, next, etc)
• search: Search
• connect: Connect to a device
• like: Like currently playing track
• authenticate: Authenticate the application
• playlist: Playlist editing (new, delete, import, fork, etc)

For more details, run _player -h or _player {command} -h, in which {command} is a CLI command.

Notes

• When using the CLI for the first time, you'll need to run _player authenticate to authenticate the application beforehand.
• Under the hood, CLI command is handled by sending requests to a _player client socket running on port client_port, a general application configuration with a default value of 8080. If there is no running application's instance, a new client will be created upon handling the CLI commands, which increases the latency of the command.

The _player command-line interface makes scripting easy. With the search subcommand, you can search and retrieve data in JSON format, enabling queries with tools like jq.

Here’s an example of starting playback for the first track from a search query:

read -p "Search : " query
_player playback start track --id $(_player search "$query" | jq '.tracks.[0].id' | xargs)

To go to the shortcut help page, press ? or C-h (default shortcuts for OpenCommandHelp command).

Tips:

• you can search in the shortcut help page (and some other pages) using Search command
• RefreshPlayback can be used to manually update the playback status.
• RestartIntegratedClient is useful when user wants to switch to another audio device (headphone, earphone, etc) without restarting the application, as the integrated client will be re-initialized with the new device.

List of supported commands:

To add new shortcuts or modify the default shortcuts, please refer to the keymaps section in the configuration documentation.

A general list of actions is available; however, not all items (track, album, artist, or playlist) implement each action. To get the list of available actions on an item, call the ShowActionsOnCurrentTrack command or the ShowActionsOnSelectedItem command, then press enter (default binding for the ChooseSelected command) to initiate the selected action. Some actions may not appear in the popup but can be bound to a shortcut.

List of available actions:

• GoToArtist
• GoToAlbum
• GoToRadio
• AddToLibrary
• AddToPlaylist
• AddToQueue
• AddToLiked
• DeleteFromLiked
• DeleteFromLibrary
• DeleteFromPlaylist
• ShowActionsOnAlbum
• ShowActionsOnArtist
• ShowActionsOnShow
• ToggleLiked
• CopyLink
• Follow
• Unfollow

These actions can also be bound to a shortcut. To add new shortcuts, please refer to the actions section in the configuration documentation.

When first entering the search page, the application focuses on the search input. User can then input text, delete one character backward using backspace, or search the text using enter.

To move the focus from the search input to the other windows such as track results, album results, etc, use FocusNextWindow or FocusPreviousWindow.

By default, _player will look into $HOME/.config/-player for application's configuration files. This can be changed by either specifying -c <FOLDER_PATH> or --config-folder <FOLDER_PATH> option.

If an application configuration file is not found, one will be created with default values.

Please refer to the configuration documentation for more details on the configuration options.

By default, _player will look into $HOME/.cache/-player for application's cache files, which include log files, 's authorization credentials, audio cache files, etc. This can be changed by either specifying -C <FOLDER_PATH> or --cache-folder <FOLDER_PATH> option.

The application stores logs inside the $APP_CACHE_FOLDER/-player-*.log file. For debugging or submitting an issue, user can also refer to the backtrace file in $APP_CACHE_FOLDER/-player-*.backtrace, which includes the application's backtrace in case of panics/unexpected errors.

_player uses RUST_LOG environment variable to define the application's logging level. RUST_LOG is default to be _player=INFO, which only shows the application's logs.

_player is written in Rust and is built on top of awesome libraries such as ratatui, r, librespot, and many more. It's highly inspired by -tui and ncspot.