Subsonic ncurses client
git clone
Log | Files | Refs | README | LICENSE

commit 565655f2cce0358026afc9f7be5b8aeec7ca9d44
parent ee60b1aba00501f54c01387f974c02d11a404889
Author: Paco Esteban <>
Date:   Sun, 24 Oct 2021 20:10:18 +0200

add license and readme

ALICENSE | 13+++++++++++++ | 79+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 92 insertions(+), 0 deletions(-)

diff --git a/LICENSE b/LICENSE @@ -0,0 +1,13 @@ +Copyright (c) 2021 Paco Esteban <> + +Permission to use, copy, modify, and distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. diff --git a/ b/ @@ -0,0 +1,79 @@ +# subclient + +`subclient` is a minimal player for subsonic compatible servers. +It's just really glue code between the subsonic API and the `mpv` player, which +uses in the background, presented with an spartan ncurses interface. + +The whole program is a bit rough around the edges, and the functionality is +pretty minimal, but it's functional and I plan to expand it a bit to cover all +my needs. + +## Installation +I haven't yet published it to pypi, so to install: + +* clone this repo +* install from local: + `pip install --user .` + +This installs a executable called `subclient` you can call from your terminal. +This assumes you have the path pip puts the executables in in your `$PATH`. +For OpenBSD and Linux, this is usually `~/.local/bin`, for Mac +`~/Library/Python/<PythonVersion>/bin`. If you're a Windows user, I'm truly +sorry about that and you have my sincere condolences, but I guess nowadays it +should work somehow with the WSL thingy. + +## Configuration +`subclient` expects to find a config file on `$XDG_CONFIG_HOME/subclient.ini` +or if `$XDG_CONFIG_HOME` is not defined, on `~/.config/subclient.ini`. + +The config file looks like this: + +``` +[subclient] +url = https://my.subsonic.server.tld +username = myuser +password = mypassword +max_cache = 524288000 +``` + +All config items are mandatory. The first 3 are pretty self explanatory, the +last one `max_cache` is the max size in bytes of the cache folder. See the +next section for more info. + +## Cache +`subclient` downloads the music files from the subsonic server and stores them +on the`$XDG_CACHE_HOME/subclient` or, if `$XDG_CACHE_HOME` is not defined, on +`~/.cache/subclient`. This is a bit primitive for now. It downloads all the +files from the one you pick till the end of the album. I may refine this in +the future, but it works for me for now. + +On start, it launches a thread that runs a cache clean routine every 60 seconds +(this timing might change in the future). If the size of the cache folder is +bigger than `max_cache` defined on the config file, it deletes 3 random files +until the disk usage is below that threshold. + +## Usage +On start you'll be presented with a list of artists that `subclient` gets from +the subsonic server. + +You can then navigate the list with `j` for down and `k` for up. `l` +_"enters"_ the next category (albums) from the selected artist, and `h` +_"exits"_ back to the artists list. When you're on the albums list `l` enters +the songs list, so you have 3 levels artists/albums/songs you can navigate. + +With `f` and `b` you can go a page forwards/backwards on a given list. + +`enter` starts playing at the song position until the end of the current list. +This only works from the songs view for now. `space` pauses/resumes playback. +`n` plays the next song on the list, and `p` the previous one. + +There is no support to play, create or remove playlists for the moment. But +I plan to implement that functionality. + +`q` quits the program. + +You'll find a somewhat useful window at the bottom with information of the +current song being played. + +## License +Check the LICENSE file, but basically this is published under the ISC license.