commit 565655f2cce0358026afc9f7be5b8aeec7ca9d44
parent ee60b1aba00501f54c01387f974c02d11a404889
Author: Paco Esteban <paco@e1e0.net>
Date: Sun, 24 Oct 2021 20:10:18 +0200
add license and readme
Diffstat:
A | LICENSE | | | 13 | +++++++++++++ |
M | README.md | | | 79 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
2 files changed, 92 insertions(+), 0 deletions(-)
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,13 @@
+Copyright (c) 2021 Paco Esteban <paco@e1e0.net>
+
+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/README.md b/README.md
@@ -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.