diff --git a/api/funkwhale_api/contrib/listenbrainz/funkwhale_startup.py b/api/funkwhale_api/contrib/listenbrainz/funkwhale_startup.py index c785aec13..0175f45dc 100644 --- a/api/funkwhale_api/contrib/listenbrainz/funkwhale_startup.py +++ b/api/funkwhale_api/contrib/listenbrainz/funkwhale_startup.py @@ -5,6 +5,7 @@ PLUGIN = plugins.get_plugin_config( name="listenbrainz", label="ListenBrainz", description="A plugin that allows you to submit your listens to ListenBrainz.", + homepage="https://docs.funkwhale.audio/users/builtinplugins.html#listenbrainz-plugin", # noqa version="0.1", user=True, conf=[ diff --git a/api/funkwhale_api/contrib/scrobbler/funkwhale_startup.py b/api/funkwhale_api/contrib/scrobbler/funkwhale_startup.py index 2be2a842e..38b0c1a73 100644 --- a/api/funkwhale_api/contrib/scrobbler/funkwhale_startup.py +++ b/api/funkwhale_api/contrib/scrobbler/funkwhale_startup.py @@ -7,7 +7,7 @@ PLUGIN = plugins.get_plugin_config( "A plugin that enables scrobbling to ListenBrainz and Last.fm. " "It must be configured on the server if you use Last.fm." ), - homepage="https://dev.funkwhale.audio/funkwhale/funkwhale/-/blob/develop/api/funkwhale_api/contrib/scrobbler/README.rst", # noqa + homepage="https://docs.funkwhale.audio/users/builtinplugins.html#scrobbler-plugin", # noqa version="0.1", user=True, conf=[ diff --git a/changes/changelog.d/plugins.doc b/changes/changelog.d/plugins.doc new file mode 100644 index 000000000..801fe5881 --- /dev/null +++ b/changes/changelog.d/plugins.doc @@ -0,0 +1 @@ +User documentation for built-in plugins \ No newline at end of file diff --git a/docs/users/builtinplugins.rst b/docs/users/builtinplugins.rst new file mode 100644 index 000000000..5c295eb3e --- /dev/null +++ b/docs/users/builtinplugins.rst @@ -0,0 +1,74 @@ +Built-in plugins +================ + +Funkwhale by default includes some plugins each user can configure and use. +Plugins can be configured in your settings with the :guilabel:`Manage plugins` button. + + +.. _scrobbler-plugin: + +Scrobbler +--------- + +The Scrobbler plugin allows you to submit your listenings to Audioscrobbler +compatible services, such as `Last.fm `_ or free alternatives like +`Libre.fm `_ or `ListenBrainz `_. +To use this plugin enable it and configure it for the scrobbler service of your choice as +described below. Note that you need an account for the respective service. + +**Last.fm:** This is the default service being used. Leave the scrobble service URL empty or set it +to ``http://post.audioscrobbler.com`` and set your Last.fm username and password as the scrobbler +username and scrobbler password. + +.. note:: + + If you want to scrobble to Last.fm, you or your server's administrator will need to create a + `Last.fm API account `_ and add + the following two variables to your Funkwhale server ``.env`` file:: + + FUNKWHALE_PLUGIN_SCROBBLER_LASTFM_API_KEY=apikey + FUNKWHALE_PLUGIN_SCROBBLER_LASTFM_API_SECRET=apisecret + +**Libre.fm:** To use Libre.fm set the scrobble service URL to ``https://turtle.libre.fm/`` and set +your libre.fm username and password as the scrobbler username and scrobbler password. + +**ListenBrainz:** To use ListenBrainz set the scrobble service URL to ``http://proxy.listenbrainz.org/``. +For the username use your ListenBrainz username, for the password use your ListenBrainz user token. +You can find the user token on your `ListenBrainz profile `_. + +.. note:: + + It is recommended to use the :ref:`ListenBrainz plugin ` instead of the + Scrobbler plugin. The ListenBrainz plugin uses the native ListenBrainz API and submits more + details for the listened songs, while the Scrobbler plugin uses the legacy Audioscrobbler API. + + +.. _listenbrainz-plugin: + +ListenBrainz +------------ + +This plugin allows you to submit your listenings to `ListenBrainz `_, +a free service to track your music listening habits. To use ListenBrainz you need to +`sign in `_ with a `MusicBrainz account `_. +If you don't have a MusicBrainz account, you can `create one `_. + +To submit your listenings from Funkwhale to ListenBrainz enable the plugin and set your +ListenBrainz user token. You can find the user token on your +`ListenBrainz profile `_. + + +.. _maloja-plugin: + +Maloja +------ + +This plugin allows you to submit your listenings to your own `Maloja `_ +instance. Maloja is a personal scrobble service similar to Last.fm or ListenBrainz, but only for yourself. +You can self-host your own Maloja instance, please see the +`Maloja documentation `_ for details. + +To submit your listenings to your own Maloja instance enable the plugin, then set the Maloja server URL +to the URL of your instance and enter your Maloja API key. An API key is created on initial setup +of your Maloja instance, but you can setup additional API keys in the file ``authenticated_machines.tsv`` in the +``/etc/maloja/clients`` folder. diff --git a/docs/users/index.rst b/docs/users/index.rst index 0cdcba347..fb881d0e1 100644 --- a/docs/users/index.rst +++ b/docs/users/index.rst @@ -34,6 +34,7 @@ Using Funkwhale apps reports cli + builtinplugins Troubleshooting Issues ----------------------