~sumner/sublime-music

ref: 1c099532d460e429cd71800ad1dccbed9827de12 sublime-music/README.rst -rw-r--r-- 6.5 KiB
1c099532Sumner Evans doc: moved type documentation to description to unclutter signatures 4 months ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
.. image:: https://gitlab.com/sublime-music/sublime-music/-/raw/master/logo/logo.png
   :alt: Sublime Music Logo

Sublime Music is a native, GTK3
`Subsonic`_/`Airsonic`_/`Revel`_/`Gonic`_/`Navidrome`_/`Ampache`_/\*sonic client for the
Linux Desktop.

CI
  .. image:: https://gitlab.com/sublime-music/sublime-music/badges/master/pipeline.svg
     :target: https://gitlab.com/sublime-music/sublime-music/pipelines
     :alt: GitLab build status
  .. image:: https://builds.sr.ht/~sumner/sublime-music/commits/build.yml.svg
     :target: https://builds.sr.ht/~sumner/sublime-music/commits/build.yml
     :alt: sourcehut build status
  .. image:: https://gitlab.com/sublime-music/sublime-music/badges/master/coverage.svg
     :target: https://sublime-music.gitlab.io/sublime-music/htmlcov
     :alt: code coverage report

Community
  .. image:: https://img.shields.io/matrix/sublime-music:matrix.org?logo=matrix
     :target: https://matrix.to/#/!veTDkgvBExJGKIBYlU:matrix.org?via=matrix.org
     :alt: Matrix chat
  .. image:: https://img.shields.io/pypi/l/sublime-music?color=0c0
     :target: https://gitlab.com/sublime-music/sublime-music/-/blob/master/LICENSE
     :alt: GPLv3 or later
  .. image:: http://img.shields.io/liberapay/receives/sumner.svg?logo=liberapay
     :target: https://liberapay.com/sumner/donate
     :alt: liberapay donate

Packages
  .. image:: https://repology.org/badge/vertical-allrepos/sublime-music.svg?columns=3
     :target: https://repology.org/project/sublime-music/versions
     :alt: Packaging status

.. _Subsonic: http://www.subsonic.org/pages/index.jsp
.. _Airsonic: https://airsonic.github.io/
.. _Revel: https://gitlab.com/robozman/revel
.. _Gonic: https://github.com/sentriz/gonic
.. _Navidrome: https://www.navidrome.org/
.. _Ampache: http://ampache.org/

-------------------------------------------------------------------------------

.. figure:: https://gitlab.com/sublime-music/sublime-music/-/raw/master/docs/_static/screenshots/play-queue.png
   :align: center
   :target: https://gitlab.com/sublime-music/sublime-music/-/raw/master/docs/_static/screenshots/play-queue.png

   The Albums tab of Sublime Music with the Play Queue opened. `More
   Screenshots <https://sublime-music.gitlab.io/sublime-music/screenshots.html_>`_

Features
--------

* Switch between multiple Subsonic-API-compliant [1]_ servers.
* Play music through Chromecast devices on the same LAN.
* Offline Mode where Sublime Music will not make any network requests.
* DBus MPRIS interface integration for controlling Sublime Music via clients
  such as ``playerctl``, ``i3status-rust``, KDE Connect, and many commonly used
  desktop environments.
* Browse songs by the sever-reported filesystem structure, or view them
  organized by ID3 tags in the Albums, Artists, and Playlists views.
* Intuitive play queue.
* Create/delete/edit playlists.
* Download songs for offline listening.

.. [1] Requires a server which implements the Subsonic API version 1.8.0+.

Installation
------------

**Via the AUR**:

Install the |AUR Package|_. Example using ``yay``::

    yay -S sublime-music

If you want support for storing passwords in the system keychain, also install
``python-keyring``.

If you want support for playing on Chromecast devices, install
``python-pychromecast``. If you want to serve cached files from your computer
over the LAN to Chromecast devices also install ``python-bottle``.

.. |AUR Package| replace:: ``sublime-music`` package
.. _AUR Package: https://aur.archlinux.org/packages/sublime-music/

**Via NixOS**:

Sublime Music is part of the ``nixos-20.09`` channel and newer (including
``nixos-unstable``).

To install Sublime Music on NixOS, either use the declarative or the imperative
way:

- In ``configuration.nix`` (declarative)::

    environment.systemPackages = [ pkgs.sublime-music ];

- In command line (imperative)::

    nix-env -iA sublime-music

To customize the extra components installed, you need to use the ``override``
function provided by Nix::

    (sublime-music.override {
      serverSupport = true;
      chromecastSupport = true;
    })

The following components are supported:

* ``chromecastSupport``: if you want support for playing on Chromecast devices
  on the LAN. Defaults to ``false``.
* ``serverSupport``: if you want to be able to serve cached files from your
  computer over the LAN to Chromecast devices. Defaults to ``false``.
* ``keyringSupport``: if you want to store your passwords in the system keyring
  instead of in plain-text. Defaults to ``true``.
* ``notifySupport``: if you want to enable notifications when a new song begins
  to play. Defaults to ``true``.
* ``networkSupport``: if you want to change the address used to access the
  server depending on what network you are connected to. Defaults to ``true``.

See `Nix package management`_ for more information.

.. _Nix package management: https://nixos.org/nixos/manual/index.html#sec-package-management

**Via the Debian package**

Sublime Music is not currently in the Debian 'Stable' distribution, but has been
packaged for Debian 'Unstable' and 'Testing'.

If you have these sources in your ``/etc/apt/sources.list``, you can install
the package with::

    sudo apt install sublime-music

**Via PyPi**::

    pip install sublime-music

There are a few optional dependencies that you can install. Here's an example of
how to do that::

    pip install sublime-music[keyring,chromecast,server]

* ``keyring``: if you want to store your passwords in the system keyring instead
  of in plain-text
* ``chromecast``: if you want support for playing on Chromecast devices on the
  LAN.
* ``server``: if you want to be able to serve cached files from your computer
  over the LAN to Chromecast devices

.. note::

   Sublime Music requires Python 3.8. Please make sure that you have that
   installed. You may also need to use ``pip3`` instead of ``pip`` if you are on
   an OS that hasn't deprecated Python 2 yet.

-------------------------------------------------------------------------------

|website|_

.. |website| replace:: **Click HERE for the Sublime Music website.**
.. _website: https://sublimemusic.app

|userdoc|_

.. |userdoc| replace:: **Click HERE for extended user documentation.**
.. _userdoc: https://sublime-music.gitlab.io/sublime-music/

See the |contributing|_ document for how to contribute to this project.

.. |contributing| replace:: ``CONTRIBUTING.md``
.. _contributing: https://gitlab.com/sublime-music/sublime-music/-/blob/master/CONTRIBUTING.md

You can also join the conversation in our Matrix room:
`#sublime-music:matrix.org <https://matrix.to/#/!veTDkgvBExJGKIBYlU:matrix.org?via=matrix.org>`_.