From 1ec7e1e8e514bfd5336f960e610f5b9e99fa411d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Wed, 19 Jan 2022 18:49:46 +0000 Subject: [PATCH] Overhaul end user documentation --- .gitlab-ci.yml | 4 +- docs/Dockerfile | 2 +- docs/conf.py | 26 ++- docs/features.rst | 54 ----- docs/glossary.md | 34 +++ docs/index.md | 156 ++++++++++++++ docs/index.rst | 30 --- docs/third-party.rst | 17 -- .../accounts/activity_visibility.md | 33 +++ .../user_documentation/accounts/add_avatar.md | 27 +++ .../accounts/change_email.md | 29 +++ .../accounts/change_password.md | 33 +++ .../accounts/check_quota.md | 27 +++ .../accounts/create_account.md | 44 ++++ .../accounts/delete_account.md | 45 ++++ .../accounts/delete_avatar.md | 25 +++ docs/user_documentation/accounts/index.md | 31 +++ .../channels/create_channel.md | 99 +++++++++ .../channels/delete_artist.md | 81 +++++++ .../channels/delete_channel.md | 33 +++ .../channels/delete_podcast.md | 81 +++++++ .../channels/edit_channel.md | 103 +++++++++ .../channels/follow_channel.md | 58 +++++ docs/user_documentation/channels/index.md | 46 ++++ .../channels/subscribe_rss.md | 30 +++ .../channels/upload_artist.md | 147 +++++++++++++ .../channels/upload_podcast.md | 147 +++++++++++++ .../favorites/add_favorites.md | 57 +++++ docs/user_documentation/favorites/index.md | 14 ++ .../favorites/remove_favorites.md | 82 ++++++++ docs/user_documentation/index.md | 39 ++++ .../info}/cli.rst | 0 .../libraries/create_library.md | 51 +++++ .../libraries/delete_content.md | 41 ++++ .../libraries/delete_library.md | 35 ++++ .../libraries/edit_content.md | 136 ++++++++++++ .../libraries/edit_library.md | 37 ++++ .../libraries/follow_library.md | 50 +++++ docs/user_documentation/libraries/index.md | 45 ++++ .../libraries/share_library.md | 51 +++++ .../user_documentation/libraries/tag_music.md | 71 +++++++ .../libraries/upload_content.md | 36 ++++ .../playlists/add_content.md | 76 +++++++ .../playlists/create_playlist.md | 36 ++++ .../playlists/delete_playlist.md | 32 +++ .../playlists/edit_playlist.md | 32 +++ docs/user_documentation/playlists/index.md | 28 +++ .../playlists/listen_playlist.md | 57 +++++ .../playlists/remove_content.md | 32 +++ .../playlists/reorder_content.md | 29 +++ docs/user_documentation/plugins/index.md | 19 ++ .../plugins/listenbrainz_plugin.md | 33 +++ .../plugins/maloja_plugin.md | 37 ++++ .../plugins/scrobbler_plugin.md | 47 +++++ docs/user_documentation/queue/add_album.md | 32 +++ docs/user_documentation/queue/add_artist.md | 32 +++ docs/user_documentation/queue/add_playlist.md | 32 +++ docs/user_documentation/queue/add_series.md | 15 ++ docs/user_documentation/queue/add_tracks.md | 15 ++ docs/user_documentation/queue/index.md | 21 ++ .../queue/rearrange_content.md | 14 ++ .../queue/remove_content.md | 52 +++++ .../user_documentation/radios/create_radio.md | 48 +++++ .../user_documentation/radios/delete_radio.md | 27 +++ docs/user_documentation/radios/edit_radio.md | 32 +++ docs/user_documentation/radios/index.md | 24 +++ .../user_documentation/radios/listen_radio.md | 78 +++++++ docs/user_documentation/reports/index.md | 23 ++ .../reports/report_account.md | 17 ++ .../reports/report_album.md | 18 ++ .../reports/report_artist.md | 18 ++ .../reports/report_channel.md | 18 ++ .../reports/report_library.md | 18 ++ .../reports/report_playlist.md | 42 ++++ .../reports/report_track.md | 18 ++ .../subsonic/disable_subsonic.md | 29 +++ docs/user_documentation/subsonic/index.md | 19 ++ .../subsonic/reset_subsonic.md | 33 +++ .../subsonic/subsonic_password.md | 27 +++ docs/users/account.rst | 14 -- docs/users/apps.rst | 198 ------------------ docs/users/builtinplugins.rst | 74 ------- docs/users/channels.rst | 119 ----------- docs/users/create.rst | 23 -- docs/users/editing.rst | 80 ------- docs/users/favorites.rst | 51 ----- docs/users/follow.rst | 58 ----- docs/users/followchannel.rst | 53 ----- docs/users/index.rst | 45 ---- docs/users/managing.rst | 101 --------- docs/users/playlists.rst | 123 ----------- docs/users/queue.rst | 63 ------ docs/users/radios.rst | 50 ----- docs/users/reports.rst | 54 ----- docs/users/tagging.rst | 61 ------ docs/users/troubleshooting.rst | 107 ---------- docs/users/upload.rst | 172 --------------- 97 files changed, 3240 insertions(+), 1553 deletions(-) delete mode 100644 docs/features.rst create mode 100644 docs/glossary.md create mode 100644 docs/index.md delete mode 100644 docs/index.rst delete mode 100644 docs/third-party.rst create mode 100644 docs/user_documentation/accounts/activity_visibility.md create mode 100644 docs/user_documentation/accounts/add_avatar.md create mode 100644 docs/user_documentation/accounts/change_email.md create mode 100644 docs/user_documentation/accounts/change_password.md create mode 100644 docs/user_documentation/accounts/check_quota.md create mode 100644 docs/user_documentation/accounts/create_account.md create mode 100644 docs/user_documentation/accounts/delete_account.md create mode 100644 docs/user_documentation/accounts/delete_avatar.md create mode 100644 docs/user_documentation/accounts/index.md create mode 100644 docs/user_documentation/channels/create_channel.md create mode 100644 docs/user_documentation/channels/delete_artist.md create mode 100644 docs/user_documentation/channels/delete_channel.md create mode 100644 docs/user_documentation/channels/delete_podcast.md create mode 100644 docs/user_documentation/channels/edit_channel.md create mode 100644 docs/user_documentation/channels/follow_channel.md create mode 100644 docs/user_documentation/channels/index.md create mode 100644 docs/user_documentation/channels/subscribe_rss.md create mode 100644 docs/user_documentation/channels/upload_artist.md create mode 100644 docs/user_documentation/channels/upload_podcast.md create mode 100644 docs/user_documentation/favorites/add_favorites.md create mode 100644 docs/user_documentation/favorites/index.md create mode 100644 docs/user_documentation/favorites/remove_favorites.md create mode 100644 docs/user_documentation/index.md rename docs/{users => user_documentation/info}/cli.rst (100%) create mode 100644 docs/user_documentation/libraries/create_library.md create mode 100644 docs/user_documentation/libraries/delete_content.md create mode 100644 docs/user_documentation/libraries/delete_library.md create mode 100644 docs/user_documentation/libraries/edit_content.md create mode 100644 docs/user_documentation/libraries/edit_library.md create mode 100644 docs/user_documentation/libraries/follow_library.md create mode 100644 docs/user_documentation/libraries/index.md create mode 100644 docs/user_documentation/libraries/share_library.md create mode 100644 docs/user_documentation/libraries/tag_music.md create mode 100644 docs/user_documentation/libraries/upload_content.md create mode 100644 docs/user_documentation/playlists/add_content.md create mode 100644 docs/user_documentation/playlists/create_playlist.md create mode 100644 docs/user_documentation/playlists/delete_playlist.md create mode 100644 docs/user_documentation/playlists/edit_playlist.md create mode 100644 docs/user_documentation/playlists/index.md create mode 100644 docs/user_documentation/playlists/listen_playlist.md create mode 100644 docs/user_documentation/playlists/remove_content.md create mode 100644 docs/user_documentation/playlists/reorder_content.md create mode 100644 docs/user_documentation/plugins/index.md create mode 100644 docs/user_documentation/plugins/listenbrainz_plugin.md create mode 100644 docs/user_documentation/plugins/maloja_plugin.md create mode 100644 docs/user_documentation/plugins/scrobbler_plugin.md create mode 100644 docs/user_documentation/queue/add_album.md create mode 100644 docs/user_documentation/queue/add_artist.md create mode 100644 docs/user_documentation/queue/add_playlist.md create mode 100644 docs/user_documentation/queue/add_series.md create mode 100644 docs/user_documentation/queue/add_tracks.md create mode 100644 docs/user_documentation/queue/index.md create mode 100644 docs/user_documentation/queue/rearrange_content.md create mode 100644 docs/user_documentation/queue/remove_content.md create mode 100644 docs/user_documentation/radios/create_radio.md create mode 100644 docs/user_documentation/radios/delete_radio.md create mode 100644 docs/user_documentation/radios/edit_radio.md create mode 100644 docs/user_documentation/radios/index.md create mode 100644 docs/user_documentation/radios/listen_radio.md create mode 100644 docs/user_documentation/reports/index.md create mode 100644 docs/user_documentation/reports/report_account.md create mode 100644 docs/user_documentation/reports/report_album.md create mode 100644 docs/user_documentation/reports/report_artist.md create mode 100644 docs/user_documentation/reports/report_channel.md create mode 100644 docs/user_documentation/reports/report_library.md create mode 100644 docs/user_documentation/reports/report_playlist.md create mode 100644 docs/user_documentation/reports/report_track.md create mode 100644 docs/user_documentation/subsonic/disable_subsonic.md create mode 100644 docs/user_documentation/subsonic/index.md create mode 100644 docs/user_documentation/subsonic/reset_subsonic.md create mode 100644 docs/user_documentation/subsonic/subsonic_password.md delete mode 100644 docs/users/account.rst delete mode 100644 docs/users/apps.rst delete mode 100644 docs/users/builtinplugins.rst delete mode 100644 docs/users/channels.rst delete mode 100644 docs/users/create.rst delete mode 100644 docs/users/editing.rst delete mode 100644 docs/users/favorites.rst delete mode 100644 docs/users/follow.rst delete mode 100644 docs/users/followchannel.rst delete mode 100644 docs/users/index.rst delete mode 100644 docs/users/managing.rst delete mode 100644 docs/users/playlists.rst delete mode 100644 docs/users/queue.rst delete mode 100644 docs/users/radios.rst delete mode 100644 docs/users/reports.rst delete mode 100644 docs/users/tagging.rst delete mode 100644 docs/users/troubleshooting.rst delete mode 100644 docs/users/upload.rst diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 58855d486..a6143ac90 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -76,7 +76,7 @@ review_docs: - cd docs - apt-get update - apt-get install -y graphviz - - pip install sphinx sphinx_rtd_theme django-environ django + - pip install sphinx sphinx_rtd_theme django-environ django myst-parser sphinx-panels script: - ./build_docs.sh cache: @@ -246,7 +246,7 @@ pages: - cd docs - apt-get update - apt-get install -y graphviz - - pip install sphinx sphinx_rtd_theme django-environ django + - pip install sphinx sphinx_rtd_theme django-environ django myst-parser sphinx-panels script: - ./build_docs.sh cache: diff --git a/docs/Dockerfile b/docs/Dockerfile index e1ea73495..342f1dc47 100644 --- a/docs/Dockerfile +++ b/docs/Dockerfile @@ -1,5 +1,5 @@ FROM python:3.6 RUN apt-get update && apt-get install -y graphviz -RUN pip install sphinx livereload sphinx_rtd_theme django-environ django myst-parser +RUN pip install sphinx livereload sphinx_rtd_theme django-environ django myst-parser sphinx-panels WORKDIR /app/docs diff --git a/docs/conf.py b/docs/conf.py index c20c28af6..b5db24b58 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -46,7 +46,12 @@ for key, value in FUNKWHALE_CONFIG.items(): # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ["sphinx.ext.graphviz", "sphinx.ext.autodoc", "myst_parser"] +extensions = [ + "sphinx.ext.graphviz", + "sphinx.ext.autodoc", + "myst_parser", + "sphinx_panels", +] autodoc_mock_imports = [ "celery", "django_auth_ldap", @@ -204,13 +209,28 @@ redirect_files = [ ("upgrading/index.html", "../admin/upgrading.html"), ("upgrading/0.17.html", "../admin/0.17.html"), ("users/django.html", "../admin/django.html"), - ("cli/index.html", "../users/cli.html"), - ("cli/examples.html", "../users/cli.html#examples"), + ("cli/index.html", "../user_documentation/info/cli.html"), + ("cli/examples.html", "../user_documentation/info/cli.html#examples"), ("installation/ldap.html", "../admin/ldap.html"), ("installation/optimization.html", "../admin/optimization.html"), ("installation/external_dependencies.html", "debian.html"), ("installation/systemd.html", "debian.html#systemd-unit-file"), ("backup.html", "../admin/backup.html"), + ("users/create.html", "../user_documentation/accounts/create_account.html"), + ("users/tagging.html", "../user_documentation/libraries/tag_music.html"), + ("users/upload.html", "../user_documentation/libraries/upload_content.html"), + ("users/editing.html", "../user_documentation/libraries/edit_content.html"), + ("users/account.html", "../user_documentation/accounts/index.html"), + ("users/queue.html", "../user_documentation/queue/index.html"), + ("users/managing.html", "../user_documentation/libraries/index.html"), + ("users/channels.html", "../user_documentation/channels/index.html"), + ("users/playlists.html", "../user_documentation/radios/index.html"), + ("users/favorites.html", "../user_documentation/favorites/index.html"), + ("users/radios.html", "../user_documentation/radios/index.html"), + ("users/followchannel.html", "../user_documentation/channels/follow_channel.html"), + ("users/follow.html", "../user_documentation/libraries/follow_library.html"), + ("users/reports.html", "../user_documentation/reports/index.html"), + ("users/builtinplugins.html", "../user_documentation/plugins/index.html"), ] # Generate redirect template diff --git a/docs/features.rst b/docs/features.rst deleted file mode 100644 index c270fee81..000000000 --- a/docs/features.rst +++ /dev/null @@ -1,54 +0,0 @@ -Features -======== - -Scope ------ - -Funkwhale is a web based audio server. It is similar in terms of goals and feature set to various existing projects, -such as `Sonerezh `_ or `Airsonic `_. - -A social platform ------------------- - -However, Funkwhale is better-suited for small to medium communities and was designed to be not only a music server and player, -but also a place to socialize around music and podcasts and discover new content. While some of these features are not currently implemented, -our roadmap includes: - -- Broadcasts, as they existed in, for example, Grooveshark -- Recommendations - -Content acquisition -------------------- - -Audio content is uploaded to Funkwhale by users to :doc:`libraries ` or :doc:`channels `, -and admins, using a :ref:`server-side import from a directory `. Content is also made available to -a pod by users following :doc:`libraries ` and :doc:`channels `. - -Metadata --------- - -In order to keep your library clean, browse-able, and well-stocked with relevant data about artists, albums and tracks, we fetch a -lot of metadata from the `MusicBrainz project `_. Music uploaded directly to Funkwhale can also be :doc:`tagged -and edited ` in the app itself. - -Structure ---------- - -The project itself is split in two parts: - -1. The backend, a REST API developed using Python3 and Django -2. The frontend, that consumes the API, built as a single page application with VueJS and Fomantic UI - -While the main interface to the server and API is the bundled front-end, the project itself is agnostic in the way you connect to it. -Therefore, desktop clients or apps could be developed and could implement the same (or even more) features as the bundled frontend. - -This modularity also makes it possible to deploy only a single component from the system. - -Federation ----------- - -Funkwhale makes use of the `ActivityPub protocol `_ to share activities -across the `fediverse `_. In particular, content uploaded in :doc:`channels ` -is shared publicly with other Funkwhale users as well as other ActivityPub enabled applications such as Reel2Bits -and Mastodon, and can be followed using each application's interface. Content shared in users' libraries can be -followed by users of other pods. diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 000000000..d5ba433ba --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,34 @@ +# Glossary of terms + +## Funkwhale glossary + +```{glossary} + +Pod + A pod is an instance of Funkwhale running on a server. Pods can communicate with one another across the {term}`Fediverse`. + +``` + +## Channel glossary + +```{glossary} + +Fediverse + A term used to refer to a collection of federated (interconnected) servers. These servers run software that enables users to publish and host their own content. + +Podcatcher + A podcatcher is a piece of software that can read podcast feeds. Podcatchers enable listeners to follow and listen to podcast content. + +``` + +## Plugin glossary + +```{glossary} + +Plugin + A plugin is a piece of software that extends the functionality of another piece of software. + +Scrobbling + Scrobbling is the act of recording listen data. Services use this information to keep track of listening preferences and recommend music. + +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..1c08abbe9 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,156 @@ +# Welcome to Funkwhale's documentation + +Funkwhale is a self-hosted audio player and publication platform. It enables users to build libraries of existing content and publish their own. + +Funkwhale uses the [ActivityPub protocol](https://www.w3.org/TR/activitypub/) to talk to other apps across the {term}`Fediverse`. Users can share content between {term}`Funkwhale pods ` or with other Fediverse software. + +```{toctree} +--- +maxdepth: 1 +hidden: true +caption: User documentation +--- + +user_documentation/index +user_documentation/accounts/index +user_documentation/channels/index +user_documentation/libraries/index +user_documentation/queue/index +user_documentation/playlists/index +user_documentation/radios/index +user_documentation/favorites/index +user_documentation/reports/index +user_documentation/subsonic/index +user_documentation/plugins/index +user_documentation/info/cli + +``` + +```{toctree} +--- +maxdepth: 1 +caption: Admin documentation +hidden: true +--- + +admin/index + +``` + +```{toctree} +--- +maxdepth: 1 +caption: Moderator documentation +hidden: true +--- + +moderator/index + +``` + +```{toctree} +--- +maxdepth: 1 +caption: Developer documentation +hidden: true +--- + +contributing +developers/index + +``` + +```{toctree} +--- +maxdepth: 1 +caption: Contributor documentation +hidden: true +--- + +documentation/index +translators + +``` + +```{toctree} +--- +caption: Reference +maxdepth: 1 +hidden: true +--- + +glossary + +``` + +```{toctree} +--- +caption: Changes +maxdepth: 1 +hidden: true +--- + +changelog + +``` + +````{panels} +:body: text-left +:header: text-center + +{fa}`user` Users +^^^^^^^^^^^^ + +Looking to use Funkwhale for your content? Read through our guides to master the app! + ++++ + +```{link-button} user_documentation/index +:type: ref +:text: Get started +:classes: btn-outline-primary btn-block stretched-link +``` + +--- + +{fa}`wrench` Admins +^^^^^^^^^^^^^^^^ + +Want to host your own Funkwhale pod? Our admin documentation guides you through the process. + ++++ + +```{link-button} admin/index +:type: ref +:text: Get started +:classes: btn-outline-primary btn-block stretched-link + +--- + +{fa}`code` Developers +^^^^^^^^^^^^^^^^^ + +Want to use Funkwhale's API or help with the project? Our developer docs give you what you need to get started. + ++++ + +```{link-button} developers/index +:type: ref +:text: Get started +:classes: btn-outline-primary btn-block stretched-link + +--- + +{fa}`users` Contributors +^^^^^^^^^^^^^^^^^^ + +Want to help make Funkwhale even better? Check out these guides for some ideas. + ++++ + +```{link-button} contributing +:type: ref +:text: Get started +:classes: btn-outline-primary btn-block stretched-link + +```` diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 497bb1966..000000000 --- a/docs/index.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. funkwhale documentation root file, created by - sphinx-quickstart on Sun Jun 25 18:49:23 2017. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Funkwhale's documentation -===================================== - -Funkwhale is a self-hosted, modern free and open-source music server, heavily inspired by Grooveshark. - -.. toctree:: - :maxdepth: 2 - - features - users/index - moderator/index - admin/index - developers/index - third-party - documentation/index - contributing - translators - changelog - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/third-party.rst b/docs/third-party.rst deleted file mode 100644 index 0335f8c71..000000000 --- a/docs/third-party.rst +++ /dev/null @@ -1,17 +0,0 @@ -Third party projects -==================== - -This page lists all known projects that are maintained by third-parties -and integrate or relates to Funkwhale. - -.. note:: - - If you want your project to be added or removed from this page, - please open an issue on our issue tracker. - - -API Clients ------------ - -- `libfunkwhale `_: a Funkwhale API written in Vala -- `Funkwhale-javalib `_: a Funkwhale API client written in Java diff --git a/docs/user_documentation/accounts/activity_visibility.md b/docs/user_documentation/accounts/activity_visibility.md new file mode 100644 index 000000000..659763556 --- /dev/null +++ b/docs/user_documentation/accounts/activity_visibility.md @@ -0,0 +1,33 @@ +# Change your activity visibility + +Your __activity visibility__ determines who can see your listening activity on Funkwhale. There are three visibility options: + +- __Nobody except me__ – only you can see your listening activity. +- __Everyone on this instance__ – users who have an account on the same {term}`pod` as you can see your listening activity. +- __Everyone, across all instances__ – anybody can see your listening activity. + +To change your activity visibility: + +```{tabbed} Desktop + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your avatar to expand the user menu. +3. Select {guilabel}`Settings`. +4. Find {guilabel}`Activity visibility` in the {guilabel}`Account settings` section. +5. Select your visibility level from the dropdown menu. +6. Select {guilabel}`Update settings` to save your changes. + +``` + +```{tabbed} Mobile + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your avatar to open the {guilabel}`Options` menu. +3. Select {guilabel}`Settings`. +4. Find {guilabel}`Activity visibility` in the {guilabel}`Account settings` section. +5. Select your visibility level from the dropdown menu. +6. Select {guilabel}`Update settings` to save your changes. + +``` + +That's it! You've updated your activity visibility. This change takes effect as soon as you update your settings. diff --git a/docs/user_documentation/accounts/add_avatar.md b/docs/user_documentation/accounts/add_avatar.md new file mode 100644 index 000000000..92f780ba0 --- /dev/null +++ b/docs/user_documentation/accounts/add_avatar.md @@ -0,0 +1,27 @@ +# Add your avatar + +You can upload an avatar to your account. Other users can see this when they visit your profile. To add an avatar: + +```{tabbed} Desktop + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your existing avatar to expand the user menu. +3. Select {guilabel}`Settings`. +4. Scroll down to the {guilabel}`Avatar` section. +5. Select {guilabel}`Browse…` to open the file picker. +6. Select the image you want to use as your avatar and confirm. + +``` + +```{tabbed} Mobile + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your existing avatar to open the {guilabel}`Options` menu. +3. Select {guilabel}`Settings`. +4. Scroll down to the {guilabel}`Avatar` section. +5. Select {guilabel}`Choose File` to open the file picker. +6. Select the image you want to use as your avatar and confirm. + +``` + +Congratulations! You've updated your avatar. diff --git a/docs/user_documentation/accounts/change_email.md b/docs/user_documentation/accounts/change_email.md new file mode 100644 index 000000000..adaee9e2d --- /dev/null +++ b/docs/user_documentation/accounts/change_email.md @@ -0,0 +1,29 @@ +# Change your email address + +You can update your email address whenever you need to. To do this: + +```{tabbed} Desktop + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your avatar to expand the user menu. +3. Select {guilabel}`Settings`. +4. Scroll to the {guilabel}`Change my e-mail address` section. +5. Enter your {guilabel}`New e-mail address`. +6. Enter your {guilabel}`Password`. +7. Select {guilabel}`Update`. + +``` + +```{tabbed} Mobile + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your avatar to open the {guilabel}`Options` menu. +3. Select {guilabel}`Settings`. +4. Scroll to the {guilabel}`Change my e-mail address` section. +5. Enter your {guilabel}`New e-mail address`. +6. Enter your {guilabel}`Password`. +7. Select {guilabel}`Update`. + +``` + +That's it! If your pod admin has email verification enabled, you'll receive a confirmation email. Follow the instructions in this email to finish changing your email address. diff --git a/docs/user_documentation/accounts/change_password.md b/docs/user_documentation/accounts/change_password.md new file mode 100644 index 000000000..667547840 --- /dev/null +++ b/docs/user_documentation/accounts/change_password.md @@ -0,0 +1,33 @@ +# Change your password + +```{warning} +Changing your account password also changes your Subsonic API password. If you are using a Subsonic app, you need to update your password in the app as well. +``` + +You can update your account password whenever you need to. To do this: + +```{tabbed} Desktop + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your avatar to expand the user menu. +3. Select {guilabel}`Settings`. +4. Scroll to the {guilabel}`Change my password` section. +5. Enter your {guilabel}`Current password`. +6. Enter your {guilabel}`New password`. +7. Select {guilabel}`Change password`. + +``` + +```{tabbed} Mobile + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your avatar to open the {guilabel}`Options` menu. +3. Select {guilabel}`Settings`. +4. Scroll to the {guilabel}`Change my password` section. +5. Enter your {guilabel}`Current password`. +6. Enter your {guilabel}`New password`. +7. Select {guilabel}`Change password`. + +``` + +That's it! Your password is reset. You need to use your new password to log in from now on. diff --git a/docs/user_documentation/accounts/check_quota.md b/docs/user_documentation/accounts/check_quota.md new file mode 100644 index 000000000..a5722cb64 --- /dev/null +++ b/docs/user_documentation/accounts/check_quota.md @@ -0,0 +1,27 @@ +# Check your upload quota + +Your {term}`pod` admin can assign users an __upload quota__. This is the amount of storage you have access to. Pod admins can assign a default quota to all users. They can also increase or decrease quotas for individual users. Your upload quota applies to content in [libraries](../libraries/index.md) and [channels](../channels/index.md). + +If you run out of space, you can contact your pod admin to request more. + +To check your upload quota: + +```{tabbed} Desktop + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Upload third-party content in a library`. +4. The {guilabel}`My libraries` screen appears showing your upload quota and your libraries. +5. The {guilabel}`Current usage` section shows you how much of your quota you are using. + +``` + +```{tabbed} Mobile + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) at the top of the screen +3. Select {guilabel}`Get started` under {guilabel}`Upload third-party content in a library`. +4. The {guilabel}`My libraries` screen appears showing your upload quota and your libraries. +5. The {guilabel}`Current usage` section shows you how much of your quota you are using. + +``` diff --git a/docs/user_documentation/accounts/create_account.md b/docs/user_documentation/accounts/create_account.md new file mode 100644 index 000000000..599e2ba0f --- /dev/null +++ b/docs/user_documentation/accounts/create_account.md @@ -0,0 +1,44 @@ +# Create your Funkwhale account + +```{tip} +Use our [Pod Picker tool](https://network.funkwhale.audio/dashboards/d/overview/network-overview) to find the perfect pod for you! +``` + +To use Funkwhale, you need to create an account on a {term}`Funkwhale pod `. Signing up to a pod requires the following information: + +- A valid email address. Administrators can use this to verify you are not a bot. +- A username. +- A password. + +## Check your pod's policies + +Before you sign up to a pod, you should check its __policies__. You can find these by navigating to the pod's {guilabel}`About this pod` page. + +1. Navigate to the pod. +2. Select the {guilabel}`About this pod` link in the sidebar. +3. Select the {guilabel}`Learn more` button in the {guilabel}`About this pod` section. + +Administrators can add a pod's {guilabel}`Rules` and {guilabel}`Terms and privacy policy` to this page. Make sure to read through them before signing up. Also check the {guilabel}`Upload quota` to see how much space users have access to. + +## Sign up + +Once you've found an instance you like the look of, you can create your account. + +1. Select the {guilabel}`Create an account` button in the sidebar. +2. Enter the {guilabel}`Username` you have chosen. +3. Enter your {guilabel}`Email` address. +4. Enter your {guilabel}`Password`. +5. Pod administrators can add extra requirements for new accounts. Fields marked with an asterisk ({guilabel}`*`) are required. +6. Select {guilabel}`Create my account`. +7. Pod administrators may require you to verify your email address before you can use your account. Check your email for more instructions. + +## Log in + +When you've created and activated your account, you can log in. + +1. Select the {guilabel}`Login` button in the sidebar. +2. Enter your {guilabel}`Username or e-mail address`. +3. Enter your {guilabel}`Password`. +4. Select {guilabel}`Login`. + +Congratulations! You've set up your Funkwhale account. Check out what you can do now in our user documentation. diff --git a/docs/user_documentation/accounts/delete_account.md b/docs/user_documentation/accounts/delete_account.md new file mode 100644 index 000000000..93532fa30 --- /dev/null +++ b/docs/user_documentation/accounts/delete_account.md @@ -0,0 +1,45 @@ +# Delete your Funkwhale account + +If you have decided you no longer want your Funkwhale account, you can delete it. This action removes your profile and all your data from your {term}`pod`, including: + +- Your user avatar. +- Your email address. +- The list of your followers. +- Music files you have uploaded. +- Radios you have created. +- Playlists you have created. +- Your favorites. + +When you delete your account, your pod sends a message to other Funkwhale pods notifying them. If these pods hold any of your data, they should also delete it. + +```{note} +Other pods should delete local copies of your data in compliance with your request. There is no guarantee that they will do so, and some data may remain available. This can happen if a pod is offline or unavailable when your pod sends out the deletion message. +``` + +To delete your account: + +```{tabbed} Desktop + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your avatar to expand the user menu. +3. Select {guilabel}`Settings`. +4. Scroll to the {guilabel}`Delete my account` section. +5. Enter your {guilabel}`Password`. +6. Select {guilabel}`Delete my account…`. +7. Select {guilabel}`Delete my account` on the warning notice that appears. + +``` + +```{tabbed} Mobile + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your avatar to open the {guilabel}`Options` menu. +3. Select {guilabel}`Settings`. +4. Scroll to the {guilabel}`Delete my account` section. +5. Enter your {guilabel}`Password`. +6. Select {guilabel}`Delete my account…`. +7. Select {guilabel}`Delete my account` on the warning notice that appears. + +``` + +That's it! You've deleted your account. You can [create another account](create_account.md) at any time. diff --git a/docs/user_documentation/accounts/delete_avatar.md b/docs/user_documentation/accounts/delete_avatar.md new file mode 100644 index 000000000..5df5af1b6 --- /dev/null +++ b/docs/user_documentation/accounts/delete_avatar.md @@ -0,0 +1,25 @@ +# Remove your avatar + +If you don't want to have an avatar any more, you can remove it. To do this: + +```{tabbed} Desktop + +1. Log in to your account. +2. Select your avatar to expand the user menu. +3. Select {guilabel}`Settings`. +4. Scroll down to the {guilabel}`Avatar` section. +5. Select {guilabel}`Remove`. + +``` + +```{tabbed} Mobile + +1. Log in to your account. +2. Select your avatar to open the {guilabel}`Options` menu. +3. Select {guilabel}`Settings`. +4. Scroll down to the {guilabel}`Avatar` section. +5. Select {guilabel}`Remove`. + +``` + +That's it! You've removed your avatar from your account. Other users will only see the initials of your username when they visit your profile. diff --git a/docs/user_documentation/accounts/index.md b/docs/user_documentation/accounts/index.md new file mode 100644 index 000000000..e58e6c7a8 --- /dev/null +++ b/docs/user_documentation/accounts/index.md @@ -0,0 +1,31 @@ +# Your account + +Your Funkwhale account is the key to your Funkwhale experience. Creating an account on a {term}`pod` gives you the ability to upload content, follow channels, and listen to audio. + +Follow the guides in this section to manage your Funkwhale account. + +```{toctree} +--- +maxdepth: 1 +caption: Manage your account +--- + +create_account +check_quota +delete_account + +``` + +```{toctree} +--- +maxdepth: 1 +caption: Change account settings +--- + +change_email +change_password +add_avatar +delete_avatar +activity_visibility + +``` diff --git a/docs/user_documentation/channels/create_channel.md b/docs/user_documentation/channels/create_channel.md new file mode 100644 index 000000000..be58b7905 --- /dev/null +++ b/docs/user_documentation/channels/create_channel.md @@ -0,0 +1,99 @@ +# Create a channel + +```{warning} +Your channel's __Fediverse handle__ needs to be unique. This is how other {term}`Fediverse` software identifies your channel. You can't change the __Fediverse handle__ once you've created your channel. +``` + +Create a channel to start publishing your content on your {term}`Funkwhale pod `. Users can access channel content from Funkwhale or other Fediverse software. + +You can create two types of channel: + +```{contents} +:local: +``` + +## Artist discography + +To create an __Artist discography__ channel: + +```{tabbed} Desktop + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select {guilabel}`+ Add new` next to the {guilabel}`Channels` header. A {guilabel}`Create channel` pop-up window appears. +5. Select {guilabel}`Artist discography` and select {guilabel}`Next step`. The {guilabel}`Artist channel` form appears. +6. Enter the {guilabel}`Name` of your channel. Users see this when they visit your channel page. +7. Enter the {guilabel}`Fediverse handle` of your channel. This is how other Fediverse software identifies your channel. +8. __Optional__ – upload a {guilabel}`Channel picture`. Users see this when they visit your channel page. Select {guilabel}`Browse…` to open a file picker. +9. __Optional__ – add {guilabel}`Tags` that describe your channel. Start typing in the {guilabel}`Search…` input box to find existing tags. You can also create new tags by typing them in and selecting them or hitting {kbd}`⏎ Return`. +10. __Optional__ – enter a {guilabel}`Description` of your channel. You can {guilabel}`Write` using [Markdown](https://www.markdownguide.org/) syntax and {guilabel}`Preview` how it will look. Users see this when they visit your channel page. +11. Select {guilabel}`Create channel` to create your channel. + +``` + +```{tabbed} Mobile + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select {guilabel}`+ Add new` next to the {guilabel}`Channels` header. A {guilabel}`Create channel` pop-up window appears. +5. Select {guilabel}`Artist discography` and select {guilabel}`Next step`. The {guilabel}`Artist channel` form appears. +6. Enter the {guilabel}`Name` of your channel. Users see this when they visit your channel page. +7. Enter the {guilabel}`Fediverse handle` of your channel. This is how other Fediverse software identifies your channel. +8. __Optional__ – upload a {guilabel}`Channel picture`. Users see this when they visit your channel page. Select {guilabel}`Browse…` to open a file picker. +9. __Optional__ – add {guilabel}`Tags` that describe your channel. Start typing in the {guilabel}`Search…` input box to find existing tags. You can also create new tags by typing them in and selecting them or hitting {kbd}`⏎ Return`. +10. __Optional__ – enter a {guilabel}`Description` of your channel. You can {guilabel}`Write` using [Markdown](https://www.markdownguide.org/) syntax and {guilabel}`Preview` how it will look. Users see this when they visit your channel page. +11. Select {guilabel}`Create channel` to create your channel. + +``` + +That's it! You've created your artist channel. You can now [add some music to it](upload_artist.md). + +## Podcast + +To create a __Podcast__ channel: + +```{tabbed} Desktop + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select {guilabel}`+ Add new` next to the {guilabel}`Channels` header. A {guilabel}`Create channel` pop-up window appears. +5. Select {guilabel}`Podcasts` and select {guilabel}`Next step`. The {guilabel}`Podcast channel` form appears. +6. Enter the {guilabel}`Name` of your channel. Users see this when they visit your channel page. +7. Enter the {guilabel}`Fediverse handle` of your channel. This is how other Fediverse software identifies your channel. +8. __Optional__ – upload a {guilabel}`Channel picture`. Users see this when they visit your channel page. Select {guilabel}`Browse…` to open a file picker. +9. __Optional__ – add {guilabel}`Tags` that describe your channel. Start typing in the {guilabel}`Search…` input box to find existing tags. You can also create new tags by typing them in and selecting them or hitting {kbd}`⏎ Return`. +10. Choose the {guilabel}`Language` of your podcast. +11. __Optional__ – enter a {guilabel}`Description` of your channel. You can {guilabel}`Write` using [Markdown](https://www.markdownguide.org/) syntax and {guilabel}`Preview` how it will look. Users see this when they visit your channel page. +12. Select the {guilabel}`Category` of your podcast. {term}`Podcatchers` use this information to sort your podcast content. +13. __Optional__ – select the {guilabel}`Subcategory` of your podcast. +14. __Optional__ – enter the {guilabel}`Owner e-mail address`. This populates the ``itunes:email`` field of your podcast's {abbr}`RSS (Really Simple Syndication)` feed. +15. __Optional__ – enter the {guilabel}`Owner name`. This populates the ``itunes:name`` field of your podcast's {abbr}`RSS (Really Simple Syndication)` feed. +16. Select {guilabel}`Create channel` to create your channel. + +``` + +```{tabbed} Mobile + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select {guilabel}`+ Add new` next to the {guilabel}`Channels` header. A {guilabel}`Create channel` pop-up window appears. +5. Select {guilabel}`Podcasts` and select {guilabel}`Next step`. The {guilabel}`Podcast channel` form appears. +6. Enter the {guilabel}`Name` of your channel. Users see this when they visit your channel page. +7. Enter the {guilabel}`Fediverse handle` of your channel. This is how other Fediverse software identifies your channel. +8. __Optional__ – upload a {guilabel}`Channel picture`. Users see this when they visit your channel page. Select {guilabel}`Browse…` to open a file picker. +9. __Optional__ – add {guilabel}`Tags` that describe your channel. Start typing in the {guilabel}`Search…` input box to find existing tags. You can also create new tags by typing them in and selecting them or hitting {kbd}`⏎ Return`. +10. Choose the {guilabel}`Language` of your podcast. +11. __Optional__ – enter a {guilabel}`Description` of your channel. You can {guilabel}`Write` using [Markdown](https://www.markdownguide.org/) syntax and {guilabel}`Preview` how it will look. Users see this when they visit your channel page. +12. Select the {guilabel}`Category` of your podcast. {term}`Podcatchers` use this information to sort your podcast content. +13. __Optional__ – select the {guilabel}`Subcategory` of your podcast. +14. __Optional__ – enter the {guilabel}`Owner e-mail address`. This populates the ``itunes:email`` field of your podcast's {abbr}`RSS (Really Simple Syndication)` feed. +15. __Optional__ – enter the {guilabel}`Owner name`. This populates the ``itunes:name`` field of your podcast's {abbr}`RSS (Really Simple Syndication)` feed. +16. Select {guilabel}`Create channel` to create your channel. + +``` + +You're done! You've created your podcast channel. Now you can [add some episodes to it](upload_podcast.md). diff --git a/docs/user_documentation/channels/delete_artist.md b/docs/user_documentation/channels/delete_artist.md new file mode 100644 index 000000000..255e29fa6 --- /dev/null +++ b/docs/user_documentation/channels/delete_artist.md @@ -0,0 +1,81 @@ +# Delete content from an Artist channel + +You can delete content from your artist channel. This means that your followers won't be able to listen to the deleted content any more. + +```{contents} +:local: +``` + +## Delete a track + +```{warning} +Deleting a track also deletes the file from your {term}`Funkwhale pod `. This action is irreversible. +``` + +To delete a single track from a channel: + +```{tabbed} Desktop + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel containing the content under the {guilabel}`Channels` header. The channel's page opens. +5. Select the kebab menu ({fa}`ellipsis-v`) next to the track in question. This opens the track options menu. +6. Select {guilabel}`ℹ︎ Track details`. The track details page opens. +7. Select the kebab menu ({fa}`ellipsis-v`) at the top of the page. +8. Select {guilabel}`Delete…`. A {guilabel}`Delete this track?` warning appears. +9. Select {guilabel}`Delete` to delete the track. + +``` + +```{tabbed} Mobile + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel containing the content under the {guilabel}`Channels` header. The channel's page opens. +5. Select the kebab menu ({fa}`ellipsis-v`) next to the track in question. This opens the track options menu. +6. Select {guilabel}`ℹ︎ Track details`. The track details page opens. +7. Select the kebab menu ({fa}`ellipsis-v`) at the top of the page. +8. Select {guilabel}`Delete…`. A {guilabel}`Delete this track?` warning appears. +9. Select {guilabel}`Delete` to delete the track. + +``` + +That's it! You've deleted your track. You can add it again by [uploading it to your channel](upload_artist.md). + +## Delete an album + +```{warning} +Deleting an album also deletes all tracks in the album and removes the files from the server. This action is irreversible. +``` + +Delete an album to remove all tracks it contains. To do this: + +```{tabbed} Desktop + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel containing the content under the {guilabel}`Channels` header. The channel's page opens. +5. Select your album in the {guilabel}`Albums` section. The album detail page opens. +6. Select the kebab menu ({fa}`ellipsis-v`) to open the options menu. +7. Select {guilabel}`Delete…`. A {guilabel}`Delete this album?` warning appears. +8. Select {guilabel}`Delete` to delete the album. + +``` + +```{tabbed} Mobile + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel containing the content under the {guilabel}`Channels` header. The channel's page opens. +5. Select your album in the {guilabel}`Albums` section. The album detail page opens. +6. Select the kebab menu ({fa}`ellipsis-v`) to open the options menu. +7. Select {guilabel}`Delete…`. A {guilabel}`Delete this album?` warning appears. +8. Select {guilabel}`Delete` to delete the album. + +``` + +You're done! You've deleted the album and all the tracks it contained. You can add them again by [uploading it to your channel](upload_artist.md). diff --git a/docs/user_documentation/channels/delete_channel.md b/docs/user_documentation/channels/delete_channel.md new file mode 100644 index 000000000..8ae961ca6 --- /dev/null +++ b/docs/user_documentation/channels/delete_channel.md @@ -0,0 +1,33 @@ +# Delete a channel + +```{warning} +Deleting a channel is irreversible. If you delete a channel you also delete the content associated with it. Users won't be able to access the channel any more. You can't re-use the channel's __Fediverse handle__ for another channel. +``` + +If you want to delete your channel, follow these steps: + +```{tabbed} Desktop + +1. Log in to your {term}`pod`. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel you want to delete under the {guilabel}`Channels` header. The channel's page opens. +5. Select the kebab menu ({fa}`ellipsis-v`) to show the channel options. +6. Select {guilabel}`Delete…`. A {guilabel}`Delete this Channel?` warning message appears +7. Select {guilabel}`Delete`. + +``` + +```{tabbed} Mobile + +1. Log in to your {term}`pod`. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel you want to delete under the {guilabel}`Channels` header. The channel's page opens. +5. Select the kebab menu ({fa}`ellipsis-v`) to show the channel options. +6. Select {guilabel}`Delete…`. A {guilabel}`Delete this Channel?` warning message appears +7. Select {guilabel}`Delete`. + +``` + +That's it! You deleted your channel. diff --git a/docs/user_documentation/channels/delete_podcast.md b/docs/user_documentation/channels/delete_podcast.md new file mode 100644 index 000000000..88b16f477 --- /dev/null +++ b/docs/user_documentation/channels/delete_podcast.md @@ -0,0 +1,81 @@ +# Delete content from a Podcast channel + +You can delete content from your podcast channel. This means that your followers won't be able to listen to the deleted content any more. + +```{contents} +:local: +``` + +## Delete an episode + +```{warning} +Deleting an episode also deletes the file from the {term}`pod`. This action is irreversible. +``` + +To delete a single episode from a channel: + +```{tabbed} Desktop + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel containing the content under the {guilabel}`Channels` header. The channel's page opens. +5. Select the kebab menu ({fa}`ellipsis-v`) next to the episode in question. This opens the track options menu. +6. Select {guilabel}`ℹ︎ Episode details`. The episode details page opens. +7. Select the kebab menu ({fa}`ellipsis-v`) at the top of the page. +8. Select {guilabel}`Delete…`. A {guilabel}`Delete this track?` warning appears. +9. Select {guilabel}`Delete` to delete the episode. + +``` + +```{tabbed} Mobile + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel containing the content under the {guilabel}`Channels` header. The channel's page opens. +5. Select the kebab menu ({fa}`ellipsis-v`) next to the episode in question. This opens the track options menu. +6. Select {guilabel}`ℹ︎ Episode details`. The episode details page opens. +7. Select the kebab menu ({fa}`ellipsis-v`) at the top of the page. +8. Select {guilabel}`Delete…`. A {guilabel}`Delete this track?` warning appears. +9. Select {guilabel}`Delete` to delete the episode. + +``` + +That's it! You've deleted your episode. You can add it again by [uploading it to your channel](upload_podcast.md). + +## Delete a series + +```{warning} +Deleting a series also deletes all episodes in the series and deletes the files from the {term}`pod`. This action is irreversible. +``` + +Delete a series to remove all episodes it contains. To do this: + +```{tabbed} Desktop + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel containing the content under the {guilabel}`Channels` header. The channel's page opens. +5. Select your series in the {guilabel}`Series` section. The series detail page opens. +6. Select the kebab menu ({fa}`ellipsis-v`) to open the options menu. +7. Select {guilabel}`Delete…`. A {guilabel}`Delete this album?` warning appears. +8. Select {guilabel}`Delete` to delete the series. + +``` + +```{tabbed} Mobile + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel containing the content under the {guilabel}`Channels` header. The channel's page opens. +5. Select your series in the {guilabel}`Series` section. The series detail page opens. +6. Select the kebab menu ({fa}`ellipsis-v`) to open the options menu. +7. Select {guilabel}`Delete…`. A {guilabel}`Delete this album?` warning appears. +8. Select {guilabel}`Delete` to delete the series. + +``` + +You're done! You've deleted the series and all the episodes it contained. You can add them again by [uploading it to your channel](upload_podcast.md). diff --git a/docs/user_documentation/channels/edit_channel.md b/docs/user_documentation/channels/edit_channel.md new file mode 100644 index 000000000..598aa9f51 --- /dev/null +++ b/docs/user_documentation/channels/edit_channel.md @@ -0,0 +1,103 @@ +# Edit a channel + +```{note} +You can't change a channel's __Fediverse handle__. +``` + +Channels are like user profiles on other {term}`Fediverse` software. This means you can edit their details at any time to reflect changes you've made. + +You can change different details depending on what type of channel you are editing: + +```{contents} +:local: +``` + +## Edit an Artist channel + +To edit an __Artist channel__: + +```{tabbed} Desktop + +1. Log in to your {term}`pod`. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel you want to delete under the {guilabel}`Channels` header. The channel's page opens. +5. Select the kebab menu ({fa}`ellipsis-v`) to show the channel options. +6. Select {guilabel}`Edit…`. The {guilabel}`Artist channel` form appears. +7. Change the details in any of these fields: + - {guilabel}`Name` + - {guilabel}`Channel Picture` + - {guilabel}`Tags` + - {guilabel}`Description` +8. Select {guilabel}`Update channel` to save your changes. + +``` + +```{tabbed} Mobile + +1. Log in to your {term}`pod`. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel you want to delete under the {guilabel}`Channels` header. The channel's page opens. +5. Select the kebab menu ({fa}`ellipsis-v`) to show the channel options. +6. Select {guilabel}`Edit…`. The {guilabel}`Artist channel` form appears. +7. Change the details in any of these fields: + - {guilabel}`Name` + - {guilabel}`Channel Picture` + - {guilabel}`Tags` + - {guilabel}`Description` +8. Select {guilabel}`Update channel` to save your changes. + +``` + +That's it! You've updated your channel details. Users see the new details when they visit your channel page. + +## Edit a Podcast channel + +To edit a __Podcast channel__: + +```{tabbed} Desktop + +1. Log in to your {term}`pod`. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel you want to delete under the {guilabel}`Channels` header. The channel's page opens. +5. Select the kebab menu ({fa}`ellipsis-v`) to show the channel options. +6. Select {guilabel}`Edit…`. The {guilabel}`Artist channel` form appears. +7. Change the details in any of these fields: + - {guilabel}`Name` + - {guilabel}`Channel Picture` + - {guilabel}`Tags` + - {guilabel}`Language` + - {guilabel}`Description` + - {guilabel}`Category` + - {guilabel}`Subcategory` + - {guilabel}`Owner e-mail address` + - {guilabel}`Owner name` +8. Select {guilabel}`Update channel` to save your changes. + +``` + +```{tabbed} Mobile + +1. Log in to your {term}`pod`. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel you want to delete under the {guilabel}`Channels` header. The channel's page opens. +5. Select the kebab menu ({fa}`ellipsis-v`) to show the channel options. +6. Select {guilabel}`Edit…`. The {guilabel}`Artist channel` form appears. +7. Change the details in any of these fields: + - {guilabel}`Name` + - {guilabel}`Channel Picture` + - {guilabel}`Tags` + - {guilabel}`Language` + - {guilabel}`Description` + - {guilabel}`Category` + - {guilabel}`Subcategory` + - {guilabel}`Owner e-mail address` + - {guilabel}`Owner name` +8. Select {guilabel}`Update channel` to save your changes. + +``` + +You're done! Users see the new details when they visit your channel page. The changes also reflect on your podcast's {abbr}`RSS (Really Simple Syndication)` feed. diff --git a/docs/user_documentation/channels/follow_channel.md b/docs/user_documentation/channels/follow_channel.md new file mode 100644 index 000000000..52b7c1ecd --- /dev/null +++ b/docs/user_documentation/channels/follow_channel.md @@ -0,0 +1,58 @@ +# Follow a channel + +Get access to a channel's content by following it. Following a channel makes its content visible to all users on your {term}`pod`. + +You can follow channels in a few different ways: + +```{contents} +:local: +```` + +## Follow a channel on your pod + +If a user on your pod follows a channel or has published a channel, you can follow it from your pod. To do this: + +1. Select the channel you want to follow. The channel details page opens. +2. Select the {guilabel}`Subscribe` button. The label changes to {guilabel}`Subscribed`. + +That's it! You've subscribed to the channel. You can see the channel in the {guilabel}`Channels` page. + +## Follow a remote channel + +To follow a channel located on another pod, you need its __Federation handle__. A __Federation handle__ uses the following format: ``@{username}@{domain}``. Once you have the channel's __Federation handle__, you can follow it from the {guilabel}`Channels` page. To do this: + +```{tabbed} Desktop + +1. Select {guilabel}`Channels` in the sidebar. The {guilabel}`Channels` page opens. +2. Select {guilabel}`+ Add new` at the top of the page. The {guilabel}`Subscriptions` screen appears. +3. Select {guilabel}`Fediverse`. +4. Enter the channel's __Federation handle__ in the {guilabel}`Fediverse object` input. +5. Select {guilabel}`Subscribe`. The channel details page appears. +6. Select the {guilabel}`Subscribe}` button. The label changes to {guilabel}`Subscribed`. + +``` + +```{tabbed} Mobile + +1. Select the hamburger menu ({fa}`bars`) to open the menu bar. +2. Select {guilabel}`Channels`. The {guilabel}`Channels` page opens. +3. Select {guilabel}`+ Add new` at the top of the page. The {guilabel}`Subscriptions` screen appears. +4. Select {guilabel}`Fediverse`. +5. Enter the channel's __Federation handle__ in the {guilabel}`Fediverse object` input. +6. Select {guilabel}`Subscribe`. The channel details page appears. +7. Select the {guilabel}`Subscribe}` button. The label changes to {guilabel}`Subscribed`. + +``` + +That's it! You can now see the channel's content on your pod. Other users of your pod can also see this channel. + +## Follow a Funkwhale podcast with a podcatcher + +You can follow podcasts published in channels using a standard podcatcher. To do this: + +1. Select the channel you want to follow. The channel details page opens. +2. Select the feed button ({fa}`feed`). The {guilabel}`Subscribe to this channel` window appears. +3. Select {guilabel}`Copy` under the {guilabel}`Subscribe via RSS` to copy the channel's {abbr}`RSS (Really Simple Syndication)` feed URL. +4. Paste the URL in your podcatcher. + +That's it! Your podcatcher fetches the podcast details from Funkwhale. diff --git a/docs/user_documentation/channels/index.md b/docs/user_documentation/channels/index.md new file mode 100644 index 000000000..ddb6acad8 --- /dev/null +++ b/docs/user_documentation/channels/index.md @@ -0,0 +1,46 @@ +# Channels + +Use channels to publish your own audio content on Funkwhale. Channels enable you to create and share your creations with the whole {term}`Fediverse`. + +Funkwhale supports two types of channel: + +- __Podcasts__ – broadcast your podcast over the Fediverse. Listeners can also use their favorite {term}`podcatcher` to listen to podcasts using {abbr}`RSS (Really Simple Syndication)`. +- __Artist Discography__ – upload your own music and create a following. + +Follow the guides in this section to get started. + +```{toctree} +--- +caption: Manage your channels +maxdepth: 1 +--- + +create_channel +edit_channel +delete_channel + +``` + +```{toctree} +--- +caption: Manage channel content +maxdepth: 1 +--- + +upload_artist +upload_podcast +delete_artist +delete_podcast + +``` + +```{toctree} +--- +caption: Follow channels +maxdepth: 1 +--- + +follow_channel +subscribe_rss + +``` diff --git a/docs/user_documentation/channels/subscribe_rss.md b/docs/user_documentation/channels/subscribe_rss.md new file mode 100644 index 000000000..4a1be895f --- /dev/null +++ b/docs/user_documentation/channels/subscribe_rss.md @@ -0,0 +1,30 @@ +# Subscribe to an RSS feed + +```{note} +Other users on your pod can't see podcasts you import using RSS. They need to subscribe to the feed themselves. +``` + +You can use Funkwhale as a {term}`podcatcher` to listen to your favorite podcasts. Funkwhale can read {abbr}`RSS (Really Simple Syndication)` feeds to import podcasts. To add an RSS feed to Funkwhale: + +```{tabbed} Desktop + +1. Select {guilabel}`Channels` in the sidebar. The {guilabel}`Channels` page opens. +2. Select {guilabel}`+ Add new` at the top of the page. The {guilabel}`Subscriptions` screen appears. +3. Select {guilabel}`RSS`. +4. Enter the URL of the RSS feed in the {guilabel}`RSS feed location` input. +5. Select {guilabel}`Subscribe`. + +``` + +```{tabbed} Mobile + +1. Select the hamburger menu ({fa}`bars`) to open the menu bar. +2. Select {guilabel}`Channels`. The {guilabel}`Channels` page opens. +3. Select {guilabel}`+ Add new` at the top of the page. The {guilabel}`Subscriptions` screen appears. +4. Select {guilabel}`RSS`. +5. Enter the URL of the RSS feed in the {guilabel}`RSS feed location` input. +6. Select {guilabel}`Subscribe`. + +``` + +That's it! Your favorite podcast is now available in the {guilabel}`Channels` page. Funkwhale updates the feed to make sure you always have the latest episodes. diff --git a/docs/user_documentation/channels/upload_artist.md b/docs/user_documentation/channels/upload_artist.md new file mode 100644 index 000000000..035ddd672 --- /dev/null +++ b/docs/user_documentation/channels/upload_artist.md @@ -0,0 +1,147 @@ +# Upload content to an Artist channel + +Once you have [created a channel](create_channel.md), you can start to add content to it. Users who follow your channel can see and play your content from their {term}`pods `. + +You can also create albums to organize your channel content. + +```{contents} +:local: +``` + +## Create an album (optional) + +Albums are a good way of organizing your content. You can create as many albums as you want. To create a new album: + +```{tabbed} Desktop + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel you want to add an album to under the {guilabel}`Channels` header. The channel's page opens. +5. Select {guilabel}`+ Add new` next to the {guilabel}`Albums` section. A {guilabel}`New album` screen appears. +6. Enter the {guilabel}`Title` of your album. +7. Select {guilabel}`Create` to create your new album. The album appears on the screen. + +``` + +```{tabbed} Mobile + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel you want to add an album to under the {guilabel}`Channels` header. The channel's page opens. +5. Select {guilabel}`+ Add new` next to the {guilabel}`Albums` section. A {guilabel}`New album` screen appears. +6. Enter the {guilabel}`Title` of your album. +7. Select {guilabel}`Create` to create your new album. The album appears on the screen. + +``` + +Once you've created your album, you can add some details to it. To do this: + +1. Select the album. The album details screen opens. +2. Select the kebab menu ({fa}`ellipsis-v`) to show the album options. +3. Select {guilabel}`Edit`. The {guilabel}`Edit this album` screen opens. +4. Change the details in any of these fields: + - {guilabel}`Title` – the title of the album. + - {guilabel}`Description` – a description of the album. + - {guilabel}`Release date` – the release date of the album. + - {guilabel}`Cover` – the cover art of the album. + - {guilabel}`Tags` – the genre of the album. +5. __Optional__ – enter a {guilabel}`Summary` of your changes. +6. Select {guilabel}`Submit and apply edit` to save your changes. + +That's it! You can now add content to your album. + +## Add your content + +To add content to your channel: + +```{tabbed} Desktop + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel you want to add content to under the {guilabel}`Channels` header. The channel's page opens. +5. Select {guilabel}`⇧ Upload`. The {guilabel}`Publish audio` screen appears. +6. Select the {guilabel}`Channel` you want to publish your audio in. This populates with the channel you selected by default. +7. __Optional__ – choose which [{guilabel}`Album`](#create-an-album-optional) you want to publish the music in. +8. __Optional__ – choose a {guilabel}`License` to apply to your music. Funkwhale supports [Creative Commons](https://creativecommons.org/) licenses. +9. Select {guilabel}`Next step`. The {guilabel}`Files to upload` screen appears. +10. Click on the section marked {guilabel}`Browse…` to open a file picker, or drag and drop your files on to it. + - If you opened the file picker, select the files you want to upload and confirm. +11. The files appear at the top when you upload them. Select {guilabel}`Remove` to remove them. + +``` + +```{tabbed} Mobile + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel you want to add content to under the {guilabel}`Channels` header. The channel's page opens. +5. Select {guilabel}`⇧ Upload`. The {guilabel}`Publish audio` screen appears. +6. Select the {guilabel}`Channel` you want to publish your audio in. This populates with the channel you selected by default. +7. __Optional__ – choose which [{guilabel}`Album`](#create-an-album-optional) you want to publish the music in. +8. __Optional__ – choose a {guilabel}`License` to apply to your music. Funkwhale supports [Creative Commons](https://creativecommons.org/) licenses. +9. Select {guilabel}`Next step`. The {guilabel}`Files to upload` screen appears. +10. Click on the section marked {guilabel}`Browse…` to open a file picker. Select the files you want to upload and confirm. +11. The files appear at the top when you upload them. Select {guilabel}`Remove` to remove them. + +``` + +### Edit your uploads + +Once you have uploaded your files, you can change their details. To do this: + +1. Select the edit icon ({fa}`edit`) to edit the track details. The {guilabel}`Upload details` screen appears. +2. Change the details in any of these fields: + - {guilabel}`Title` – the title of the track + - {guilabel}`Track Picture` – the picture that shows up next to the track. + - {guilabel}`Tags` – the genre of the track. + - {guilabel}`Position` – the position of the track in the album. + - {guilabel}`Description` – a description of the track. +3. Select {guilabel}`Update` to save the track details. +4. Do this for all tracks you want to publish. +5. Select {guilabel}`Publish` to publish the content. To save the content to [upload later](#continue-your-upload-later), select {menuselection}`Down arrow --> Finish later`. + +That's it! You've added content to your channel. Your followers can now listen to your content from their pods. + +## Continue your upload later + +If you selected {guilabel}`Finish later`, Funkwhale saves your files and edits. You can continue your upload later by doing the following: + +```{tabbed} Desktop + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel you want to add content to under the {guilabel}`Channels` header. The channel's page opens. +5. Select {guilabel}`⇧ Upload`. The {guilabel}`Publish audio` screen appears. +6. Select the {guilabel}`Channel` you want to publish your audio in. This populates with the channel you selected by default. +7. __Optional__ – choose which [{guilabel}`Album`](#create-an-album-optional) you want to publish the music in. +8. __Optional__ – choose a {guilabel}`License` to apply to your music. Funkwhale supports [Creative Commons](https://creativecommons.org/) licenses. +9. Select {guilabel}`Next step`. The {guilabel}`Files to upload` screen appears. +10. If there are pending uploads, a {guilabel}`You have some draft uploads pending publication` note shows. Select {guilabel}`Resume` to resume your upload. +11. [Add new files](#add-your-content) or [edit the pending files](#edit-your-uploads). +12. Once you're finished, select {guilabel}`Publish` to publish your music. + +``` + +```{tabbed} Mobile + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel you want to add content to under the {guilabel}`Channels` header. The channel's page opens. +5. Select {guilabel}`⇧ Upload`. The {guilabel}`Publish audio` screen appears. +6. Select the {guilabel}`Channel` you want to publish your audio in. This populates with the channel you selected by default. +7. __Optional__ – choose which [{guilabel}`Album`](#create-an-album-optional) you want to publish the music in. +8. __Optional__ – choose a {guilabel}`License` to apply to your music. Funkwhale supports [Creative Commons](https://creativecommons.org/) licenses. +9. Select {guilabel}`Next step`. The {guilabel}`Files to upload` screen appears. +10. If there are pending uploads, a {guilabel}`You have some draft uploads pending publication` note shows. Select {guilabel}`Resume` to resume your upload. +11. [Add new files](#add-your-content) or [edit the pending files](#edit-your-uploads). +12. Once you're finished, select {guilabel}`Publish` to publish your music. + +``` + +Congratulations! You've finished uploading the saved content. Your followers can now listen to your content from their pods. diff --git a/docs/user_documentation/channels/upload_podcast.md b/docs/user_documentation/channels/upload_podcast.md new file mode 100644 index 000000000..dca2d6234 --- /dev/null +++ b/docs/user_documentation/channels/upload_podcast.md @@ -0,0 +1,147 @@ +# Upload content to an Podcast channel + +Once you have [created a channel](create_channel.md), you can start to add content to it. Users who follow your channel can see and play your content from their {term}`pods `. + +You can also create series to organize your channel content. + +```{contents} +:local: +``` + +## Create a series (optional) + +Series are a good way of organizing your content. You can create as many series as you want. To create a new series: + +```{tabbed} Desktop + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel you want to add a series to under the {guilabel}`Channels` header. The channel's page opens. +5. Select {guilabel}`+ Add new` next to the {guilabel}`Series` section. A {guilabel}`New album` screen appears. +6. Enter the {guilabel}`Title` of your series. +7. Select {guilabel}`Create` to create your new series. The series appears on the screen. + +``` + +```{tabbed} Mobile + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel you want to add a series to under the {guilabel}`Channels` header. The channel's page opens. +5. Select {guilabel}`+ Add new` next to the {guilabel}`Series` section. A {guilabel}`New album` screen appears. +6. Enter the {guilabel}`Title` of your series. +7. Select {guilabel}`Create` to create your new series. The series appears on the screen. + +``` + +Once you've created your series, you can add some details to it. To do this: + +1. Select the series. The series details screen opens. +2. Select the kebab menu ({fa}`ellipsis-v`) to show the album options. +3. Select {guilabel}`✎ Edit`. The {guilabel}`Edit this album` screen opens. +4. Change the details in any of these fields: + - {guilabel}`Title` – the title of the series. + - {guilabel}`Description` – a description of the series. + - {guilabel}`Release date` – the date on which the series aired. + - {guilabel}`Cover` – a cover image for the series. + - {guilabel}`Tags` – tags relating to the series' content. +5. __Optional__ – enter a {guilabel}`Summary` of your changes. +6. Select {guilabel}`Submit and apply edit` to save your changes. + +That's it! Your series is ready to use. + +## Add your content + +To add content to your channel: + +```{tabbed} Desktop + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel you want to add content to under the {guilabel}`Channels` header. The channel's page opens. +5. Select {guilabel}`⇧ Upload`. The {guilabel}`Publish audio` screen appears. +6. Select the {guilabel}`Channel` you want to publish your audio in. This populates with the channel you selected by default. +7. __Optional__ – choose which [{guilabel}`Series`](#create-a-series-optional) you want to publish the content in. +8. __Optional__ – choose a {guilabel}`License` to apply to your music. Funkwhale supports [Creative Commons](https://creativecommons.org/) licenses. +9. Select {guilabel}`Next step`. The {guilabel}`Files to upload` screen appears. +10. Click on the section marked {guilabel}`Browse…` to open a file picker, or drag and drop your files on to it. + - If you opened the file picker, select the files you want to upload and confirm. +11. The files appear at the top when you upload them. Select {guilabel}`Remove` to remove them. + +``` + +```{tabbed} Mobile + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel you want to add content to under the {guilabel}`Channels` header. The channel's page opens. +5. Select {guilabel}`⇧ Upload`. The {guilabel}`Publish audio` screen appears. +6. Select the {guilabel}`Channel` you want to publish your audio in. This populates with the channel you selected by default. +7. __Optional__ – choose which [{guilabel}`Series`](#create-a-series-optional) you want to publish the content in. +8. __Optional__ – choose a {guilabel}`License` to apply to your music. Funkwhale supports [Creative Commons](https://creativecommons.org/) licenses. +9. Select {guilabel}`Next step`. The {guilabel}`Files to upload` screen appears. +10. Click on the section marked {guilabel}`Browse…` to open a file picker. Select the files you want to upload and confirm. +11. The files appear at the top when you upload them. Select {guilabel}`Remove` to remove them. + +``` + +### Edit your uploads + +Once you have uploaded your files, you can change their details. To do this: + +1. Select the edit icon ({fa}`edit`) to edit the track details. The {guilabel}`Upload details` screen appears. +2. Change the details in any of these fields: + - {guilabel}`Title` – the title of the episode + - {guilabel}`Track Picture` – the picture that shows up next to the episode. + - {guilabel}`Tags` – tags relating to the episode content. + - {guilabel}`Position` – the position of the track in the series. + - {guilabel}`Description` – a description of the track. +3. Select {guilabel}`Update` to save the track details. +4. Do this for all episodes you want to publish. +5. Select {guilabel}`Publish` to publish the content. To save the content to upload later, select {menuselection}`Down arrow --> Finish later`. + +That's it! You've added content to your channel. Your followers can now listen to your content from their pods or podcatchers. + +## Continue your upload later + +If you selected {guilabel}`Finish later`, Funkwhale saves your files and edits. You can continue your upload later by doing the following: + +```{tabbed} Desktop + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel you want to add content to under the {guilabel}`Channels` header. The channel's page opens. +5. Select {guilabel}`⇧ Upload`. The {guilabel}`Publish audio` screen appears. +6. Select the {guilabel}`Channel` you want to publish your audio in. This populates with the channel you selected by default. +7. __Optional__ – choose which [{guilabel}`Series`](#create-a-series-optional) you want to publish the content in. +8. __Optional__ – choose a {guilabel}`License` to apply to your music. Funkwhale supports [Creative Commons](https://creativecommons.org/) licenses. +9. Select {guilabel}`Next step`. The {guilabel}`Files to upload` screen appears. +10. If there are pending uploads, a {guilabel}`You have some draft uploads pending publication` note shows. Select {guilabel}`Resume` to resume your upload. +11. [Add new files](#add-your-content) or [edit the pending files](#edit-your-uploads). +12. Once you're finished, select {guilabel}`Publish` to publish your music. + +``` + +```{tabbed} Mobile + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Publish your work in a channel`. Your user profile opens. +4. Select the channel you want to add content to under the {guilabel}`Channels` header. The channel's page opens. +5. Select {guilabel}`⇧ Upload`. The {guilabel}`Publish audio` screen appears. +6. Select the {guilabel}`Channel` you want to publish your audio in. This populates with the channel you selected by default. +7. __Optional__ – choose which [{guilabel}`Series`](#create-a-series-optional) you want to publish the content in. +8. __Optional__ – choose a {guilabel}`License` to apply to your music. Funkwhale supports [Creative Commons](https://creativecommons.org/) licenses. +9. Select {guilabel}`Next step`. The {guilabel}`Files to upload` screen appears. +10. If there are pending uploads, a {guilabel}`You have some draft uploads pending publication` note shows. Select {guilabel}`Resume` to resume your upload. +11. [Add new files](#add-your-content) or [edit the pending files](#edit-your-uploads). +12. Once you're finished, select {guilabel}`Publish` to publish your music. + +``` + +Congratulations! You've finished uploading the saved content. Your followers can now listen to your content from their pods. diff --git a/docs/user_documentation/favorites/add_favorites.md b/docs/user_documentation/favorites/add_favorites.md new file mode 100644 index 000000000..a85cf8354 --- /dev/null +++ b/docs/user_documentation/favorites/add_favorites.md @@ -0,0 +1,57 @@ +# Add tracks to your favorites + +You can add tracks to your favorites list at any time. There are a few ways you can add tracks to your favorites: + +```{contents} +:local: +``` + +## Add the currently playing track + +To add the currently playing track to your favorites, do one of the following: + +```{tabbed} Desktop + +- Select the gray heart icon ({fa}`heart`) on the player bar. The heart turns pink to show that the track is in your favorites. +- Hit the {kbd}`l` key on your keyboard. The heart icon on the player turns pink to show that the track is in your favorites. + +``` + +```{tabbed} Mobile + +- Select the player at the bottom of the screen to expand it. Select the gray heart icon ({fa}`heart`) under the track art. The heart turns pink to show that the track is in your favorites. + +``` + +That's all there is to it! The currently playing track is now in your favorites list. + +## Add a track from a track table + +You can favorite tracks on any page with a track table. This includes artist pages, album pages, and the search page. To favorite tracks on the track table: + +```{tabbed} Desktop + +1. Find your track in a track table. +2. Hover over the track row. A gray heart icon ({fa}`heart`) appears. +3. Select the heart icon. The heart turns pink to show that the track is in your favorites. + +``` + +```{tabbed} Mobile + +1. Find your track in a track table. +2. Tap on the kebab menu ({fa}`ellipsis-v`) on the track row. The track menu opens. +3. Select {guilabel}`Add to favorites`. The heart turns pink to show that the track is in your favorites. + +``` + +You're done! The track is in your favorites. + +## Add a track from the track details page + +You can add a track to your favorites from its details page. To do this: + +1. Go to the track's details page. +2. Select the gray heart icon ({fa}`heart`) at the top of the screen. The heart turns pink to show that the track is in your favorites. + +That's it! The track is in your favorites. diff --git a/docs/user_documentation/favorites/index.md b/docs/user_documentation/favorites/index.md new file mode 100644 index 000000000..141418920 --- /dev/null +++ b/docs/user_documentation/favorites/index.md @@ -0,0 +1,14 @@ +# Favorites + +Your favorites is a list of tracks you've liked while listening on Funkwhale. Follow the guides in this section to manage your favorites. + +```{toctree} +--- +caption: Manage your favorites +maxdepth: 1 +--- + +add_favorites +remove_favorites + +``` diff --git a/docs/user_documentation/favorites/remove_favorites.md b/docs/user_documentation/favorites/remove_favorites.md new file mode 100644 index 000000000..c936141d0 --- /dev/null +++ b/docs/user_documentation/favorites/remove_favorites.md @@ -0,0 +1,82 @@ +# Remove tracks from your favorites + +If you no longer want a track in your favorites list, you can remove it. There are a few ways to do this. + +```{contents} +:local: +``` + +## Remove tracks from your favorites page + +The easiest way to remove tracks from your favorites is using the __Favorites__ page. This page includes a list of all your favorites. To remove a track from this page: + +```{tabbed} Desktop + +1. Select {guilabel}`Favorites` under the {guilabel}`My Library` section in the sidebar. The {guilabel}`Favorites` page opens. +2. Use the filters to find the track you want to remove. +3. Select the pink heart icon ({fa}`heart`) next to the track you want to remove. The heart turns gray to show that the track isn't in your favorites. + +``` + +```{tabbed} Mobile + +1. Select the hamburger menu ({fa}`bars`) to open the menu bar. +2. Select {guilabel}`My Library`. +3. Select {guilabel}`Favorites`. The {guilabel}`Favorites` page opens. +4. Use the filters to find the track you want to remove. +5. Tap on the kebab menu ({fa}`ellipsis-v`) on the track row. The track menu opens. +6. Select {guilabel}`Remove from favorites`. The heart turns gray to show that the track isn't in your favorites. + +``` + +That's all there is to it! You've removed the track from your favorites. + +## Remove the currently playing track from your favorites + +If you favorited the current track and want to remove it from your favorites, do one of the following: + +```{tabbed} Desktop + +- Select the pink heart icon ({fa}`heart`) on the player bar. The heart turns gray to show that the track isn't in your favorites. +- Hit the {kbd}`l` key on your keyboard. The heart icon on the player turns gray to show that the track isn't in your favorites. + +``` + +```{tabbed} Mobile + +- Select the player at the bottom of the screen to expand it. Select the pink heart icon ({fa}`heart`) under the track art. The heart turns gray to show that the track isn't in your favorites. + +``` + +That's it! You've removed the currently playing track from your favorites. + +## Remove a track from a track table + +You can remove tracks on track tables from your favorites. You can find track tables on artist pages, album pages, and the search page. To remove a track on a track table from your favorites: + +```{tabbed} Desktop + +1. Find your track in a track table. +2. A pink heart icon ({fa}`heart`) shows next to all tracks in your favorites. +3. Select the heart icon on the track you want to remove. The heart turns gray to show that the track isn't in your favorites. + +``` + +```{tabbed} Mobile + +1. Find your track in a track table. +2. Tap on the kebab menu ({fa}`ellipsis-v`) on the track row. The track menu opens. +3. Select {guilabel}`Remove from favorites`. The heart turns gray to show that the track isn't in your favorites. + +``` + +You're done! You've removed the track from your favorites. + +## Remove a track from the track details page + +You can remove a track from your favorites from its details page. To do this: + +1. Go to the track's details page. +2. Select the pink heart icon ({fa}`heart`) at the top of the screen. The heart turns gray to show that the track isn't your favorites. + +That's it! You've removed the track from your favorites. diff --git a/docs/user_documentation/index.md b/docs/user_documentation/index.md new file mode 100644 index 000000000..d900778f9 --- /dev/null +++ b/docs/user_documentation/index.md @@ -0,0 +1,39 @@ +# Get started + +Follow the guides in our user documentation to get started using Funkwhale. + +```{contents} +:local: +``` + +## Set up your Funkwhale account + +Some {term}`Funkwhale pods ` allow you to listen to music without signing up. To get the most out of Funkwhale, you should create an account. Check out [Your account](accounts/index.md) to get started. + +## Publish your content on Funkwhale + +Got a podcast you want to share with the world? Working on a new album? Funkwhale gives you the tools you need to share your creativity with the {term}`Fediverse`. Publish your work in [Channels](channels/index.md) to start building up your following. + +## Upload your collection to Funkwhale + +Want to listen to your private collection using Funkwhale? Upload your files to [Libraries](libraries/index.md) to store your collection on your pod and share it with others. + +## Start listening + +Want to listen to something new or enjoy an old favorite? Follow the guides in the sections linked below to master playback in Funkwhale: + +- Learn how to use the [Queue](queue/index.md) to organize playback. +- Build [Playlists](playlists/index.md) to personalize how you enjoy your favorite content. +- Create new [Radios](radios/index.md) to automate your listening experience. + +## Report content and users + +If you've come across something that doesn't abide by a pod's rules or the law, you can report it. Follow the guides in the [Reporting](reports/index.md) section to see how. + +## Access Funkwhale from other apps + +Funkwhale supports a subset of the Subsonic API. This means you can play your Funkwhale content on Subsonic apps. Learn more about how to do this in the [Subsonic](subsonic/index.md) section. + +## Enhance your experience with plugins + +Funkwhale supports plugins to extend its features or to add new features. Check out our [Plugins](plugins/index.md) section for details about our plugins and how to use them. diff --git a/docs/users/cli.rst b/docs/user_documentation/info/cli.rst similarity index 100% rename from docs/users/cli.rst rename to docs/user_documentation/info/cli.rst diff --git a/docs/user_documentation/libraries/create_library.md b/docs/user_documentation/libraries/create_library.md new file mode 100644 index 000000000..e5cfe798b --- /dev/null +++ b/docs/user_documentation/libraries/create_library.md @@ -0,0 +1,51 @@ +# Create a library + +```{tip} +Want to publish your own content on your {term}`pod`? Take a look at [channels](../channels/index). +``` + +To start uploading your collection to your pod, you need to create a library. You can create as many libraries as you need. + +To create a library: + +```{tabbed} Desktop + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Upload third-party content in a library`. +4. A screen appears showing your upload quota. If you have created any libraries, these are also shown. +5. Select {guilabel}`Create a new library`. +6. Enter a {guilabel}`Name` for your library (required). +7. Enter {guilabel}`Description` for your library. +8. Set the {guilabel}`Visibility` of your library. This determines who can access the content. + - {guilabel}`Everyone, across all instances` – the library's content is available to everybody who interacts with your pod. This includes users of other pods. + - {guilabel}`Everyone on this instance` – the library's content is available to all users on your pod. This does not include users of other pods. + - {guilabel}`Nobody except me` – the library's content is only available to you and people you share the library with. +9. Select {guilabel}`Create library`. +10. A screen appears showing you a summary of your library. + +``` + +```{tabbed} Mobile + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Upload third-party content in a library`. +4. A screen appears showing your upload quota. If you have created any libraries, these are also shown. +5. Select {guilabel}`Create a new library`. +6. Enter a {guilabel}`Name` for your library (required). +7. Enter {guilabel}`Description` for your library. +8. Set the {guilabel}`Visibility` of your library. This determines who can access the content. + - {guilabel}`Everyone, across all instances` – the library's content is available to everybody who interacts with your pod. This includes users of other pods. + - {guilabel}`Everyone on this instance` – the library's content is available to all users on your pod. This does not include users of other pods. + - {guilabel}`Nobody except me` – the library's content is only available to you and people you share the library with. +9. Select {guilabel}`Create library`. +10. A screen appears showing you a summary of your library. + +``` + +```{warning} +Select {guilabel}`Nobody except me` if you don't own the copyright for the content or it isn't freely licensed. +``` + +Well done! You've created your library. Now you can add some content to it. diff --git a/docs/user_documentation/libraries/delete_content.md b/docs/user_documentation/libraries/delete_content.md new file mode 100644 index 000000000..52054a950 --- /dev/null +++ b/docs/user_documentation/libraries/delete_content.md @@ -0,0 +1,41 @@ +# Delete content from a library + +```{warning} +When you delete content from a library you delete the audio files from your {term}`pod`. Make sure you have a backup of any files you want to keep. +``` + +You can delete content from a library at any time. To do this: + +```{tabbed} Desktop + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Upload third-party content in a library`. +4. A screen appears showing your upload quota and your libraries. +5. Select {guilabel}`Library Details` under the library you want to edit. +6. Select the {guilabel}`✎ Edit` button at the top of the screen. +7. Scroll down to the {guilabel}`Library contents` section. A list of tracks is shown. +8. Select the checkbox ({fa}`square`) next to the tracks you want to delete. Selected tracks show a tick ({fa}`check-square`). +9. Select {menuselection}`Actions --> Delete`. +10. Select {guilabel}`Go`. +11. Select {guilabel}`Launch` on the warning message that appears. + +``` + +```{tabbed} Mobile + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Upload third-party content in a library`. +4. A screen appears showing your upload quota and your libraries. +5. Select {guilabel}`Library Details` under the library you want to edit. +6. Select the {guilabel}`✎ Edit` button at the top of the screen. +7. Scroll down to the {guilabel}`Library contents` section. A list of tracks is shown. +8. Select the checkbox ({fa}`square`) next to the tracks you want to delete. Selected tracks show a tick ({fa}`check-square`). +9. Select {menuselection}`Actions --> Delete`. +10. Select {guilabel}`Go`. +11. Select {guilabel}`Launch` on the warning message that appears. + +``` + +That's it! You've successfully deleted the content from your library. diff --git a/docs/user_documentation/libraries/delete_library.md b/docs/user_documentation/libraries/delete_library.md new file mode 100644 index 000000000..44557ebf4 --- /dev/null +++ b/docs/user_documentation/libraries/delete_library.md @@ -0,0 +1,35 @@ +# Delete a library + +```{warning} +Deleting a library also deletes all content in the library. +``` + +You can delete a library at any time. To do this: + +```{tabbed} Desktop + +1. Log in to your {term}`pod`. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Upload third-party content in a library`. +4. A screen appears showing your upload quota and your libraries. +5. Select {guilabel}`Library Details` under the library you want to edit. +6. Select the {guilabel}`✎ Edit` button at the top of the screen. +7. Select {guilabel}`Delete`. +8. Select {guilabel}`Delete library` on the warning notice that appears. + +``` + +```{tabbed} Mobile + +1. Log in to your {term}`pod`. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Upload third-party content in a library`. +4. A screen appears showing your upload quota and your libraries. +5. Select {guilabel}`Library Details` under the library you want to edit. +6. Select the {guilabel}`✎ Edit` button at the top of the screen. +7. Select {guilabel}`Delete`. +8. Select {guilabel}`Delete library` on the warning notice that appears. + +``` + +That's it! You've deleted your library and all its content. diff --git a/docs/user_documentation/libraries/edit_content.md b/docs/user_documentation/libraries/edit_content.md new file mode 100644 index 000000000..f81e61602 --- /dev/null +++ b/docs/user_documentation/libraries/edit_content.md @@ -0,0 +1,136 @@ +# Edit library content + +```{note} +You can only edit content in libraries you own. {term}`Pod` admins can edit all content. +``` + +You can edit library content after you have uploaded it. This is helpful if the content isn't [tagged](tag_music). + +```{contents} +:local: +``` + +## Edit artist + +To edit an artist: + +```{tabbed} Desktop + +1. Search for the artist in the sidebar or go to the {guilabel}`Artists` page in {guilabel}`My Library` and search there. +2. Select the artist you want to edit. The artist details page opens. +3. Select the {guilabel}`More…` button. The artist options menu opens. +4. Select {guilabel}`✎ Edit`. The {guilabel}`Edit this artist` screen opens. +5. Change the details in any of these fields: + - {guilabel}`Name` – the name of the artist. + - {guilabel}`Description` – a description of the artist. This appears on the artist details page. + - {guilabel}`Cover` – the cover image for the artist. This appears on the artist details page. + - {guilabel}`Tags` – the genre(s) the artist fits in. +6. __Optional__ – enter a {guilabel}`Summary` of your edits. +7. Select {guilabel}`Submit and apply edit` to save your changes. + +``` + +```{tabbed} Mobile + +1. Select the hamburger menu ({fa}`bars`) to open the menu bar. +2. Use the search bar to search for your artist. You can also select {menuselection}`My Library --> Artists` to open the artist search page. +3. Select the artist you want to edit. The artist details page opens. +4. Select the {guilabel}`More…` button. The artist options menu opens. +5. Select {guilabel}`✎ Edit`. The {guilabel}`Edit this artist` screen opens. +6. Change the details in any of these fields: + - {guilabel}`Name` – the name of the artist. + - {guilabel}`Description` – a description of the artist. This appears on the artist details page. + - {guilabel}`Cover` – the cover image for the artist. This appears on the artist details page. + - {guilabel}`Tags` – the genre(s) the artist fits in. +7. __Optional__ – enter a {guilabel}`Summary` of your edits. +8. Select {guilabel}`Submit and apply edit` to save your changes. + +``` + +That's it! You've edited the artist's details. You can see these details by visiting the artist page. + +## Edit album + +To edit an album: + +```{tabbed} Desktop + +1. Search for the album in the sidebar or go to the {guilabel}`Albums` page in {guilabel}`My Library` and search there. +2. Select the album you want to edit. The album details page opens. +3. Select the kebab menu ({fa}`ellipsis-v`) to show the album options. +4. Select {guilabel}`✎ Edit`. The {guilabel}`Edit this album` screen opens. +5. Change the details in any of these fields: + - {guilabel}`Title` – the title of the album. + - {guilabel}`Description` – a description of the album. This appears on the album details page. + - {guilabel}`Release date` – the release date of the album. + - {guilabel}`Cover` – the album cover art. + - {guilabel}`Tags` – the genre(s) associated with the album. +6. __Optional__ – enter a {guilabel}`Summary` of your edits. +7. Select {guilabel}`Submit and apply edit` to save your changes. + +``` + +```{tabbed} Mobile + +1. Select the hamburger menu ({fa}`bars`) to open the menu bar. +2. Use the search bar to search for your album. You can also select {menuselection}`My Library --> Albums` to open the album search page. +3. Select the album you want to edit. The album details page opens. +4. Select the kebab menu ({fa}`ellipsis-v`) to show the album options. +5. Select {guilabel}`✎ Edit`. The {guilabel}`Edit this album` screen opens. +6. Change the details in any of these fields: + - {guilabel}`Title` – the title of the album. + - {guilabel}`Description` – a description of the album. This appears on the album details page. + - {guilabel}`Release date` – the release date of the album. + - {guilabel}`Cover` – the album cover art. + - {guilabel}`Tags` – the genre(s) associated with the album. +7. __Optional__ – enter a {guilabel}`Summary` of your edits. +8. Select {guilabel}`Submit and apply edit` to save your changes. + +``` + +That's it! You've edited the album's details. You can see these details by visiting the album page. + +## Edit track + +To edit a track: + +```{tabbed} Desktop + +1. Search for the track in the sidebar. +2. Select the track you want to edit. The track details page opens. +3. Select the kebab menu ({fa}`ellipsis-v`) to show the track options. +4. Select {guilabel}`✎ Edit`. The {guilabel}`Edit this track` screen opens. +5. Change the details in any of these fields: + - {guilabel}`Title` – the title of the track. + - {guilabel}`Description` – a description of the track. This appears on the track details page. + - {guilabel}`Cover` – the track cover art. This appears on the track details page. + - {guilabel}`Position` – the position of the track in its album. + - {guilabel}`Copyright` – the name of the copyright holder. + - {guilabel}`License` – the license of the track. Funkwhale supports [Creative Commons](https://creativecommons.org) licenses. Leave this blank if you aren't sure. + - {guilabel}`Tags` – the genre(s) associated with the track. +6. __Optional__ – enter a {guilabel}`Summary` of your edits. +7. Select {guilabel}`Submit and apply edit` to save your changes. + +``` + +```{tabbed} Mobile + +1. Select the hamburger menu ({fa}`bars`) to open the menu bar. +2. Use the search bar to search for your track. +3. Select the track you want to edit. The track details page opens. +4. Select the kebab menu ({fa}`ellipsis-v`) to show the track options. +5. Select {guilabel}`✎ Edit`. The {guilabel}`Edit this track` screen opens. +6. Change the details in any of these fields: + - {guilabel}`Title` – the title of the track. + - {guilabel}`Description` – a description of the track. This appears on the track details page. + - {guilabel}`Cover` – the track cover art. This appears on the track details page. + - {guilabel}`Position` – the position of the track in its album. + - {guilabel}`Copyright` – the name of the copyright holder. + - {guilabel}`License` – the license of the track. Funkwhale supports [Creative Commons](https://creativecommons.org) licenses. Leave this blank if you aren't sure. + - {guilabel}`Tags` – the genre(s) associated with the track. +7. __Optional__ – enter a {guilabel}`Summary` of your edits. +8. Select {guilabel}`Submit and apply edit` to save your changes. + +``` + +That's it! You've edited the track's details. You can see these details by visiting the track details page. diff --git a/docs/user_documentation/libraries/edit_library.md b/docs/user_documentation/libraries/edit_library.md new file mode 100644 index 000000000..3d0d64d37 --- /dev/null +++ b/docs/user_documentation/libraries/edit_library.md @@ -0,0 +1,37 @@ +# Edit a library + +You can update the details of your libraries at any time. To do this: + +```{tabbed} Desktop + +1. Log in to your {term}`pod`. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Upload third-party content in a library`. +4. A screen appears showing your upload quota and your libraries. +5. Select {guilabel}`Library Details` under the library you want to edit. +6. Select the {guilabel}`✎ Edit` button at the top of the screen. +7. Change any of the following: + - {guilabel}`Name`. + - {guilabel}`Description`. + - {guilabel}`Visibility`. +8. Select {guilabel}`Update Library` to save your changes. A toast notification appears at the bottom of the screen to confirm your changes. + +``` + +```{tabbed} Mobile + +1. Log in to your {term}`pod`. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Upload third-party content in a library`. +4. A screen appears showing your upload quota and your libraries. +5. Select {guilabel}`Library Details` under the library you want to edit. +6. Select the {guilabel}`✎ Edit` button at the top of the screen. +7. Change any of the following: + - {guilabel}`Name`. + - {guilabel}`Description`. + - {guilabel}`Visibility`. +8. Select {guilabel}`Update Library` to save your changes. A toast notification appears at the bottom of the screen to confirm your changes. + +``` + +That's it! You've updated your library's details. diff --git a/docs/user_documentation/libraries/follow_library.md b/docs/user_documentation/libraries/follow_library.md new file mode 100644 index 000000000..a91fcc13f --- /dev/null +++ b/docs/user_documentation/libraries/follow_library.md @@ -0,0 +1,50 @@ +# Follow a library + +Follow a library to get access to its content. There are two ways to follow a library: + +```{contents} +:local: +``` + +## Use a sharing link + +If you've received a sharing link, you can use this to follow a library. To do this: + +```{tabbed} Desktop + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Follow remote libraries`. A screen appears showing you the libraries you are following. +4. Paste the sharing link into the {guilabel}`Search a remote library` search bar. +5. Select the {guilabel}`Search` icon or hit {kbd}`⏎ Return` to search for the library. If the library exists, a library card appears. +6. Select {guilabel}`Follow` on the library card. If the library's privacy level is {guilabel}`Nobody except me`, the owner needs to approve the request. + +``` + +```{tabbed} Mobile + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) at the top of the screen +3. Select {guilabel}`Get started` under {guilabel}`Follow remote libraries`. A screen appears showing you the libraries you are following. +4. Paste the sharing link into the {guilabel}`Search a remote library` search bar. +5. Select the {guilabel}`Search` icon or hit {kbd}`⏎ Return` to search for the library. If the library exists, a library card appears. +6. Select {guilabel}`Follow` on the library card. If the library's privacy level is {guilabel}`Nobody except me`, the owner needs to approve the request. + +``` + +That's it! The server then scans the content and you can see it on your {term}`pod`. + +## Follow from content on your pod + +```{note} +You can only follow a library from content pages if its privacy level is not {guilabel}`Nobody except me`. +``` + +If a user on your {term}`pod` has already followed a library, you can find it by selecting content from that library. To do this: + +1. Log in to your pod. +2. Select a track, album, or artist from the library you want to follow. +3. Scroll to the bottom of the page. The library card appears in the {guilabel}`User libraries` section. +4. Select {guilabel}`Follow` on the library card. + +You're done! The content will remain on the server even if the other user stops following the library. diff --git a/docs/user_documentation/libraries/index.md b/docs/user_documentation/libraries/index.md new file mode 100644 index 000000000..533a4b9db --- /dev/null +++ b/docs/user_documentation/libraries/index.md @@ -0,0 +1,45 @@ +# Libraries + +Libraries enable you to organize audio content you upload to your {term}`pod`. You can set the privacy level on libraries to control who can access them. Choose from the available privacy levels: + +- __Everyone, across all instances__ – the library's content is available to everybody who interacts with your pod. This includes users of other pods. +- __Everyone on this instance__ – the library's content is available to all users on your pod. This does not include users of other pods. +- __Nobody except me__ – the library's content is only available to you and people you share the library with. + +Use libraries for private collections or freely licensed music you want to share. + +```{toctree} +--- +caption: Manage your libraries +maxdepth: 1 +--- + +create_library +edit_library +delete_library + +``` + +```{toctree} +--- +caption: Manage library content +maxdepth: 1 +--- + +tag_music +upload_content +edit_content +delete_content + +``` + +```{toctree} +--- +caption: Share and follow libraries +maxdepth: 1 +--- + +share_library +follow_library + +``` diff --git a/docs/user_documentation/libraries/share_library.md b/docs/user_documentation/libraries/share_library.md new file mode 100644 index 000000000..3cfa5efbb --- /dev/null +++ b/docs/user_documentation/libraries/share_library.md @@ -0,0 +1,51 @@ +# Share a library + +Sharing a library gives another user access to the library's content. When a user follows your library, they'll be able to play and download any content it contains from their {term}`pod`. Share private libraries with friends and family or share public libraries with everyone! + +To share a library you own: + +```{tabbed} Desktop + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Upload third-party content in a library`. +4. A screen appears showing your upload quota and your libraries. +5. Select {guilabel}`Library Details` under the library you want to share. +6. The {guilabel}`Sharing link` appears on the library details page. Select {guilabel}`Copy` to copy the sharing link to your clipboard. A label appears letting you know you've copied the link. +7. Send the link to whomever you want to share the library with. + +``` + +```{tabbed} Mobile + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Upload third-party content in a library`. +4. A screen appears showing your upload quota and your libraries. +5. Select {guilabel}`Library Details` under the library you want to share. +6. The {guilabel}`Sharing link` appears on the library details page. Select {guilabel}`Copy` to copy the sharing link to your clipboard. A label appears letting you know you've copied the link. +7. Send the link to whomever you want to share the library with. + +``` + +If you have set the library's privacy level to {guilabel}`Nobody except me`, you need to approve followers. You receive a notification when a user follows your library. To approve a follow request: + +```{tabbed} Desktop + +1. Log in to your pod. +2. Select the cog icon ({fa}`cog`) or your avatar to expand the user menu. +3. Select {guilabel}`Notifications`. The notifications screen opens. +4. Notifications show the username of the user who wants to follow the library as well as the library name. Select {guilabel}`Accept` to approve the follow request or {guilabel}`Reject` to reject the request. + +``` + +```{tabbed} Mobile + +1. Log in to your pod. +2. Select the cog icon ({fa}`cog`) or your avatar to open the {guilabel}`Options` menu. +3. Select {guilabel}`Notifications`. The notifications screen opens. +4. Notifications show the username of the user who wants to follow the library as well as the library name. Select {guilabel}`Accept` to approve the follow request or {guilabel}`Reject` to reject the request. + +``` + +That's it! You've shared your library. The invited users can now listen to its content. diff --git a/docs/user_documentation/libraries/tag_music.md b/docs/user_documentation/libraries/tag_music.md new file mode 100644 index 000000000..56a0014df --- /dev/null +++ b/docs/user_documentation/libraries/tag_music.md @@ -0,0 +1,71 @@ +# Tag your content with Picard + +Funkwhale relies on [ID3 tags](https://id3.org/) to sort audio content. ID3 tags tell Funkwhale information about your files. Funkwhale uses this information to display your content in your {term}`pod`. + +We recommend using [MusicBrainz Picard](https://picard.musicbrainz.org/) to tag your content. MusicBrainz Picard is free and open source software that connects to [MusicBrainz](https://musicbrainz.org). Funkwhale uses MusicBrainz as its primary data source. + +This guide shows you how to tag your content with MusicBrainz Picard. + +```{contents} +:local: +``` + +```{dropdown} Supported tags + +| Name | Example value | Description | +|-------------------------------|-------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `Title`* | `Letting you` | The track title. | +| `Artist`* | `Nine Inch Nails` | The artist name. | +| `Album` | `The Slip` | The album title. If none is provided, an `[Unknown Album]` entry is created. | +| `Album artist` | `Trent Reznor` | The album artist name (can be different than the track artist). | +| `Genre` | `Industrial, Metal` | A comma separated list of tags to associate with the track.

Other supported separators: `;` and `/` | +| `Track number` | `4` | The position of the track in the album/release. | +| `Disc number` | `1` | The disc number (in case of multi-disc albums). | +| `Date` | `2019` | The release date of the track or album. | +| `License` | `CC-BY 3.0: http://creativecommons.org/licenses/cc-by/3.0/` | The license associated with this work. The first URL found is checked against our list of supported licenses. | +| `Copyright` | `CC-BY 3.0: http://creativecommons.org/licenses/cc-by/3.0/` | The license associated with this work. The first URL found is checked against our list of supported licenses.

Used if no license found in the `License` tag. | +| `Pictures` | | The first embeded picture found is used as the album cover. | +| `MusicBrainz Recording ID` | `99244237-850b-4a93-904d-57305bcadb4e` | The MusicBrainz ID for the recording. | +| `MusicBrainz Album ID` | `bca982fd-ab73-3c9f-ad07-9104a4f53a32` | The MusicBrainz ID for the album | +| `MusicBrainz Artist ID` | `b7ffd2af-418f-4be2-bdd1-22f8b48613da` | The MusicBrainz ID for the artist | +| `MusicBrainz Album Artist ID` | `b7ffd2af-418f-4be2-bdd1-22f8b48613da` | The MusicBrainz ID for the album artist | +``` + +## Tag content + +To tag content using MusicBrainz Picard: + +1. Select {guilabel}`Add Files` to add individual files or {guilabel}`Add Folder` to add a directory of files. +2. Select the files or directory you want to tag. +3. Picard shows the files in the left panel. Picard moves files to the right panel as it tags them. If Picard doesn't tag a file automatically, select {guilabel}`Scan`. +4. Check a file's tags by highlighting it and looking at the details in the bottom panel. If Picard has applied the wrong tags, look for [alternative versions](#alternative-versions). +5. Select {guilabel}`Save` or hit {kbd}`ctrl+s` ({kbd}`cmd+s` on macOS) to save the tags to the files. + +That's it! You've added ID3 tags to your files. You can now [add these to a library](upload_content.md) + +## Alternative versions + +Picard will choose tags based on details included in your file. Sometimes it chooses a different version of a release than the one you want. You can choose an alternative version of your content to get the right tags. + +### Alternative albums + +If Picard has selected a different version of the album you are tagging: + +1. Right-click on the album and hover your mouse over {guilabel}`Other versions`. A dropdown list of alternative versions appears. +2. Select the correct release from the list. +3. Select {guilabel}`Save` or hit {kbd}`ctrl+s` ({kbd}`cmd+s` on macOS) to save the tags to the files. + +### Alternative tracks + +If Picard can't find a release for a track: + +1. Right-click on the track and select {guilabel}`Search for Similar Tracks…`. A search screen appears. +2. Search for your track. Use [MusicBrainz's search syntax](https://musicbrainz.org/doc/Indexed_Search_Syntax) for the best results. +3. Select the correct track and click on {guilabel}`Load into Picard`. +4. Select {guilabel}`Save` or hit {kbd}`ctrl+s` ({kbd}`cmd+s` on macOS) to save the tags to the files. + +## Add items to MusicBrainz + +If Picard can't find your content, you can add it to MusicBrainz yourself. To get started, check out [MusicBrainz's guide](https://musicbrainz.org/doc/How_to_Add_a_Release/). + +Once you have added the content to MusicBrainz, Picard can tag your files. diff --git a/docs/user_documentation/libraries/upload_content.md b/docs/user_documentation/libraries/upload_content.md new file mode 100644 index 000000000..c2fa0a075 --- /dev/null +++ b/docs/user_documentation/libraries/upload_content.md @@ -0,0 +1,36 @@ +# Upload content to a library + +```{note} +Access to a library's content is set at a __library level__. You can't change the privacy level of content within the library. +``` + +Once you have [created a library](create_library.md), you can start uploading content to it. Funkwhale reads information about your content from its metadata. For the best results, make sure to [tag your files well](tag_music.md). + +To upload content to a library: + +```{tabbed} Desktop + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) in the top of the sidebar. +3. Select {guilabel}`Get started` under {guilabel}`Upload third-party content in a library`. +4. A screen appears showing your upload quota and your libraries. +5. Select {guilabel}`Upload` under the library you want to add content to. +6. Click on the section marked {guilabel}`Click to select files` to open a file picker, or drag and drop your files on to it. + - If you opened the file picker, select the files you want to upload and confirm. +7. The screen shows you the status of each upload. Once the upload queue is empty, your upload is complete. + +``` + +```{tabbed} Mobile + +1. Log in to your pod. +2. Select the upload icon ({fa}`upload`) at the top of the screen. +3. Select {guilabel}`Get started` under {guilabel}`Upload third-party content in a library`. +4. A screen appears showing your upload quota and your libraries. +5. Select {guilabel}`Upload` under the library you want to add content to. +6. Click on the section marked {guilabel}`Click to select files` to open a file picker Select the files you want to upload and confirm. +7. The screen shows you the status of each upload. Once the upload queue is empty, your upload is complete. + +``` + +Congratulations! You added some content to your library. You can now listen to your tracks on your {term}`Funkwhale pod `. diff --git a/docs/user_documentation/playlists/add_content.md b/docs/user_documentation/playlists/add_content.md new file mode 100644 index 000000000..59a7a12d5 --- /dev/null +++ b/docs/user_documentation/playlists/add_content.md @@ -0,0 +1,76 @@ +# Add content to a playlist + +To build a playlist, you need to add content to it. You can add content in a few different ways: + +```{contents} +:local: +``` + +## Add the currently playing track + +If you want to add the currently playing track to a playlist: + +```{tabbed} Desktop + +1. Select the playlist icon ({fa}`list`) on the player. The {guilabel}`Manage playlists` screen appears. +2. Select {guilabel}`+ Add track` next to the playlist you want to add the track to. + +``` + +```{tabbed} Mobile + +1. Select the player at the bottom of the screen to expand it. +2. Select the playlist icon ({fa}`list`) under the track art. The {guilabel}`Manage playlists` screen appears. +3. Select {guilabel}`+ Add track` next to the playlist you want to add the track to. + +``` + +That's it! The currently playing track is now in your playlist. + +## Add content from queue + +You can add all content that is currently in your [player queue](../queue/index.md). To do this: + +```{tabbed} Desktop + +1. Select {guilabel}`Playlists` under the {guilabel}`My Library` section of the sidebar. The {guilabel}`Browsing playlists` screen opens. +2. Select {guilabel}`Manage your playlists`. The {guilabel}`Manage playlists` screen appears. +3. Select the edit icon ({fa}`edit`) next to the playlist you want to edit. The playlist edit screen appears. +4. Select {guilabel}`+ Insert from queue`. Your tracks appear in the playlist. The changes save to the server. +5. Select {guilabel}`Stop editing` to stop editing. + +``` + +```{tabbed} Mobile + +1. Select the hamburger menu ({fa}`bars`) to open the menu bar. +2. Select {menuselection}`My Library --> Playlists`. The {guilabel}`Browsing playlists` screen opens. +3. Select {guilabel}`Manage your playlists`. The {guilabel}`Manage playlists` screen appears. +4. Select the edit icon ({fa}`edit`) next to the playlist you want to edit. The playlist edit screen appears. +5. Select {guilabel}`+ Insert from queue`. Your tracks appear in the playlist. The changes save to the server. +6. Select {guilabel}`Stop editing` to stop editing. + +``` + +That's it! You've added the contents from your queue to a playlist. + +## Add track from track details page + +You can add a track to a playlist from the track details page. To do this: + +1. Go to the track details page of the track you want to add. +2. Select the playlist icon ({fa}`list`) at the top of the screen. The {guilabel}`Manage playlists` screen appears. +3. Select {guilabel}`+ Add track` next to the playlist you want to add the track to. + +That's it! The track is available in your playlist. + +## Add track from track table + +You can add tracks from any page with a track table. This includes artist pages, album pages, and the search page. To add tracks from the track table: + +1. Find your track in a track table. +2. Select the kebab menu ({fa}`ellipsis-v`) next to the track to open the track options menu. +3. Select {guilabel}`Add to playlist…`. The {guilabel}`Manage playlists` screen appears. +4. Select {guilabel}`+ Add track` next to the playlist you want to add the track to. + +Well done! You've added the track to your playlist. diff --git a/docs/user_documentation/playlists/create_playlist.md b/docs/user_documentation/playlists/create_playlist.md new file mode 100644 index 000000000..31e8464e4 --- /dev/null +++ b/docs/user_documentation/playlists/create_playlist.md @@ -0,0 +1,36 @@ +# Create a playlist + +Create playlists to share your favorite tracks with other Funkwhale users. + +To create a playlist: + +```{tabbed} Desktop + +1. Log in to your account. +2. Select {guilabel}`Playlists` under the {guilabel}`My Library` section of the sidebar. The {guilabel}`Browsing playlists` screen opens. +3. Select {guilabel}`Manage your playlists`. The {guilabel}`Manage playlists` screen appears. +4. Enter a {guilabel}`Playlist name` for your new playlist. +5. Select the {guilabel}`Playlist visibility` for your playlist. Choose from the following options: + - {guilabel}`Everyone, across all instances` – the playlist is available to everybody who interacts with your {term}`pod`. This includes users of other pods. + - {guilabel}`Everyone on this instance` – the playlist is available to all users on your pod. This does not include users of other pods. + - {guilabel}`Nobody except me` – the playlist is only available to you and people you share it with. +6. Select {guilabel}`Create playlist`. A {guilabel}`Playlist created` message appears. + +``` + +```{tabbed} Mobile + +1. Log in to your account. +2. Select the hamburger menu ({fa}`bars`) to open the menu bar. +3. Select {menuselection}`My Library --> Playlists`. The {guilabel}`Browsing playlists` screen opens. +4. Select {guilabel}`Manage your playlists`. The {guilabel}`Manage playlists` screen appears. +5. Enter a {guilabel}`Playlist name` for your new playlist. +6. Select the {guilabel}`Playlist visibility` for your playlist. Choose from the following options: + - {guilabel}`Everyone, across all instances` – the playlist is available to everybody who interacts with your pod. This includes users of other pods. + - {guilabel}`Everyone on this instance` – the playlist is available to all users on your pod. This does not include users of other pods. + - {guilabel}`Nobody except me` – the playlist is only available to you and people you share it with. +7. Select {guilabel}`Create playlist`. A {guilabel}`Playlist created` message appears. + +``` + +Congratulations! You've created your playlist. Now you can [add some content to it](add_content.md). diff --git a/docs/user_documentation/playlists/delete_playlist.md b/docs/user_documentation/playlists/delete_playlist.md new file mode 100644 index 000000000..cd9ea136b --- /dev/null +++ b/docs/user_documentation/playlists/delete_playlist.md @@ -0,0 +1,32 @@ +# Delete a playlist + +```{warning} +Deleting a playlist removes the playlist for all users. This action is irreversible. +``` + +You can delete a playlist if you no longer want it. To do this: + +```{tabbed} Desktop + +1. Log in to your account. +2. Select {guilabel}`Playlists` under the {guilabel}`My Library` section of the sidebar. The {guilabel}`Browsing playlists` screen opens. +3. Select {guilabel}`Manage your playlists`. The {guilabel}`Manage playlists` screen appears. +4. Select the playlist from the {guilabel}`Available playlists` list. The playlist details screen opens. +5. Select {guilabel}`Delete`. A {guilabel}`Do you want to delete the playlist?` warning appears. +6. Select {guilabel}`Delete playlist`. + +``` + +```{tabbed} Mobile + +1. Log in to your account. +2. Select the hamburger menu ({fa}`bars`) to open the menu bar. +3. Select {menuselection}`My Library --> Playlists`. The {guilabel}`Browsing playlists` screen opens. +4. Select {guilabel}`Manage your playlists`. The {guilabel}`Manage playlists` screen appears. +5. Select the playlist from the {guilabel}`Available playlists` list. The playlist details screen opens. +6. Select {guilabel}`Delete`. A {guilabel}`Do you want to delete the playlist?` warning appears. +7. Select {guilabel}`Delete playlist`. + +``` + +That's it! You've deleted your playlist. diff --git a/docs/user_documentation/playlists/edit_playlist.md b/docs/user_documentation/playlists/edit_playlist.md new file mode 100644 index 000000000..3f0740dbd --- /dev/null +++ b/docs/user_documentation/playlists/edit_playlist.md @@ -0,0 +1,32 @@ +# Edit a playlist + +You can edit the details of your playlists at any time. To do this: + +```{tabbed} Desktop + +1. Log in to your account. +2. Select {guilabel}`Playlists` under the {guilabel}`My Library` section of the sidebar. The {guilabel}`Browsing playlists` screen opens. +3. Select {guilabel}`Manage your playlists`. The {guilabel}`Manage playlists` screen appears. +4. Select the edit icon ({fa}`edit`) next to the playlist you want to edit. The playlist edit screen appears. +5. Update the following fields: + - {guilabel}`Playlist name`. + - {guilabel}`Playlist visibility`. +6. Select {guilabel}`Update playlist` to save your changes. A message displays {guilabel}`Playlist updated`. + +``` + +```{tabbed} Mobile + +1. Log in to your account. +2. Select the hamburger menu ({fa}`bars`) to open the menu bar. +3. Select {menuselection}`My Library --> Playlists`. The {guilabel}`Browsing playlists` screen opens. +4. Select {guilabel}`Manage your playlists`. The {guilabel}`Manage playlists` screen appears. +5. Select the edit icon ({fa}`edit`) next to the playlist you want to edit. The playlist edit screen appears. +6. Update the following fields: + - {guilabel}`Playlist name`. + - {guilabel}`Playlist visibility`. +7. Select {guilabel}`Update playlist` to save your changes. A message displays {guilabel}`Playlist updated`. + +``` + +That's it! You've edited your playlist. diff --git a/docs/user_documentation/playlists/index.md b/docs/user_documentation/playlists/index.md new file mode 100644 index 000000000..2c7f60422 --- /dev/null +++ b/docs/user_documentation/playlists/index.md @@ -0,0 +1,28 @@ +# Playlists + +You can create and share playlists with the {term}`Fediverse`. Add content from all over the network to build playlists you love. + +```{toctree} +--- +caption: Manage your playlists +maxdepth: 1 +--- + +create_playlist +edit_playlist +listen_playlist +delete_playlist + +``` + +```{toctree} +--- +caption: Manage playlist content +maxdepth: 1 +--- + +add_content +reorder_content +remove_content + +``` diff --git a/docs/user_documentation/playlists/listen_playlist.md b/docs/user_documentation/playlists/listen_playlist.md new file mode 100644 index 000000000..31308066d --- /dev/null +++ b/docs/user_documentation/playlists/listen_playlist.md @@ -0,0 +1,57 @@ +# Listen to a playlist + +```{note} +You can only listen to content in libraries you have access to. For more information, see [Follow a library](../libraries/follow_library). +``` + +You can listen to your playlists or playlists created by other users of your {term}`pod`. + +```{contents} +:local: +``` + +## Listen to your playlists + +To listen to playlists you created: + +```{tabbed} Desktop + +1. Select {menuselection}`My Library --> Playlists` in the sidebar. The {guilabel}`Browsing playlists` screen opens. +2. Use the filters to search for your playlist. +3. Select the orange play icon ({fa}`play`) on your playlist to start playing the content. + +``` + +```{tabbed} Mobile + +1. Select the hamburger menu ({fa}`bars`) to open the menu bar. +2. Select {menuselection}`My Library --> Playlists`. The {guilabel}`Browsing playlists` screen opens. +3. Use the filters to search for your playlist. +4. Select the orange play icon ({fa}`play`) on your playlist to start playing the content. + +``` + +You're done! Your playlist's content appears in your [queue](../queue/index.md). + +## Listen to public playlists from your pod + +To listen to public playlists other users created: + +```{tabbed} Desktop + +1. Select {menuselection}`Explore --> Playlists` in the sidebar. The {guilabel}`Browsing playlists` screen opens. +2. Use the filters to search for a playlist. +3. Select the orange play icon ({fa}`play`) on your selected playlist to start playing the content. + +``` + +```{tabbed} Mobile + +1. Select the hamburger menu ({fa}`bars`) to open the menu bar. +2. Select {menuselection}`Explore --> Playlists`. The {guilabel}`Browsing playlists` screen opens. +3. Use the filters to search for a playlist. +4. Select the orange play icon ({fa}`play`) on your selected playlist to start playing the content. + +``` + +That's it! The playlist's content appears in your [queue](../queue/index.md). diff --git a/docs/user_documentation/playlists/remove_content.md b/docs/user_documentation/playlists/remove_content.md new file mode 100644 index 000000000..3a03646aa --- /dev/null +++ b/docs/user_documentation/playlists/remove_content.md @@ -0,0 +1,32 @@ +# Remove content from a playlist + +```{warning} +Removing content from a playlist removes it for anybody who follows the playlist. +``` + +You can remove content from a playlist at any time. To do this: + +```{tabbed} Desktop + +1. Log in to your account. +2. Select {guilabel}`Playlists` under the {guilabel}`My Library` section of the sidebar. The {guilabel}`Browsing playlists` screen opens. +3. Select {guilabel}`Manage your playlists`. The {guilabel}`Manage playlists` screen appears. +4. Select the edit icon ({fa}`edit`) next to the playlist you want to edit. The playlist edit screen appears. +5. Select the delete icon ({fa}`trash`) next to the content you want to remove. Select {guilabel}`Clear playlist` to remove all content at once. +6. Select {guilabel}`Stop Editing` to finish editing. + +``` + +```{tabbed} Mobile + +1. Log in to your account. +2. Select the hamburger menu ({fa}`bars`) to open the menu bar. +3. Select {menuselection}`My Library --> Playlists`. The {guilabel}`Browsing playlists` screen opens. +4. Select {guilabel}`Manage your playlists`. The {guilabel}`Manage playlists` screen appears. +5. Select the edit icon ({fa}`edit`) next to the playlist you want to edit. The playlist edit screen appears. +6. Select the delete icon ({fa}`trash`) next to the content you want to remove. Select {guilabel}`Clear playlist` to remove all content at once. +7. Select {guilabel}`Stop Editing` to finish editing. + +``` + +That's it! You've removed the content from your playlist. diff --git a/docs/user_documentation/playlists/reorder_content.md b/docs/user_documentation/playlists/reorder_content.md new file mode 100644 index 000000000..7a445ecb0 --- /dev/null +++ b/docs/user_documentation/playlists/reorder_content.md @@ -0,0 +1,29 @@ +# Reorder content in a playlist + +You can change the order of the tracks in a playlist. To do this: + +```{tabbed} Desktop + +1. Log in to your account. +2. Select {guilabel}`Playlists` under the {guilabel}`My Library` section of the sidebar. The {guilabel}`Browsing playlists` screen opens. +3. Select {guilabel}`Manage your playlists`. The {guilabel}`Manage playlists` screen appears. +4. Select the edit icon ({fa}`edit`) next to the playlist you want to edit. The playlist edit screen appears. +5. Drag and drop the tracks in the playlist into the order you want. The position number of each track appears on the left side. +6. Select {guilabel}`Stop Editing` to finish editing. + +``` + +```{tabbed} Mobile + +1. Log in to your account. +2. Select the hamburger menu ({fa}`bars`) to open the menu bar. +3. Select {menuselection}`My Library --> Playlists`. The {guilabel}`Browsing playlists` screen opens. +4. Select {guilabel}`Manage your playlists`. The {guilabel}`Manage playlists` screen appears. +5. Select the edit icon ({fa}`edit`) next to the playlist you want to edit. The playlist edit screen appears. +6. Drag and drop the tracks in the playlist into the order you want. The position number of each track appears on the left side. +7. Select {guilabel}`Stop Editing` to finish editing. + + +``` + +You're done! You've updated the order of the tracks in your playlist. diff --git a/docs/user_documentation/plugins/index.md b/docs/user_documentation/plugins/index.md new file mode 100644 index 000000000..061170df4 --- /dev/null +++ b/docs/user_documentation/plugins/index.md @@ -0,0 +1,19 @@ +# User plugins + +```{note} +Your {term}`pod's ` admin needs to enable plugins for you to use them. If you can't find the plugins mentioned here, contact your pod admin. +``` + +Use plugins to extend Funkwhale's features. The Funkwhale collective maintains core plugins to make your listening experience even better. Developers can create extra plugins to add features to a pod. + +```{toctree} +--- +maxdepth: 1 +caption: Core plugins +--- + +scrobbler_plugin +listenbrainz_plugin +maloja_plugin + +``` diff --git a/docs/user_documentation/plugins/listenbrainz_plugin.md b/docs/user_documentation/plugins/listenbrainz_plugin.md new file mode 100644 index 000000000..9cad213fd --- /dev/null +++ b/docs/user_documentation/plugins/listenbrainz_plugin.md @@ -0,0 +1,33 @@ +# ListenBrainz plugin + +The __ListenBrainz__ plugin enables you to submit ({term}`scrobble`) listens to your [ListenBrainz](https://listenbrainz.org) account. Scrobbling listens helps you build up a profile of your music tastes. It also enables you to keep a record of your listens. To set up the __ListenBrainz plugin__: + +```{tabbed} Desktop + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your avatar to expand the user menu. +3. Select {guilabel}`Settings`. +4. Scroll down to the {guilabel}`Plugins` section. +5. Select {guilabel}`Manage plugins`. +6. Find the {guilabel}`ListenBrainz` plugin. +7. Toggle the {guilabel}`Enabled` switch. +8. Enter {guilabel}`Your ListenBrainz user token`. You can find this on your ListenBrainz profile. +9. Select {guilabel}`Save`. + +``` + +```{tabbed} Mobile + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your avatar to open the {guilabel}`Options` menu. +3. Select {guilabel}`Settings`. +4. Scroll down to the {guilabel}`Plugins` section. +5. Select {guilabel}`Manage plugins`. +6. Find the {guilabel}`ListenBrainz` plugin. +7. Toggle the {guilabel}`Enabled` switch. +8. Enter {guilabel}`Your ListenBrainz user token`. You can find this on your ListenBrainz profile. +9. Select {guilabel}`Save`. + +``` + +That's it! You've set up the __ListenBrainz__ plugin. When you listen to tracks, the plugin sends the information to ListenBrainz. diff --git a/docs/user_documentation/plugins/maloja_plugin.md b/docs/user_documentation/plugins/maloja_plugin.md new file mode 100644 index 000000000..68b878f7a --- /dev/null +++ b/docs/user_documentation/plugins/maloja_plugin.md @@ -0,0 +1,37 @@ +# Maloja plugin + +The __Maloja__ plugin enables you to submit ({term}`scrobble `) listens to your Maloja server. [Maloja](https://github.com/krateng/maloja) is a self-hosted scrobbling service similar to [Last.fm](https://last.fm) and [ListenBrainz](https://listenbrainz.org). Check out [their documentation](https://github.com/krateng/maloja#how-to-install) to set up your own server. + +Scrobbling listens helps you build up a profile of your music tastes. It also enables you to keep a record of your listens. To set up the __Maloja plugin__: + +```{tabbed} Desktop + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your avatar to expand the user menu. +3. Select {guilabel}`Settings`. +4. Scroll down to the {guilabel}`Plugins` section. +5. Select {guilabel}`Manage plugins`. +6. Find the {guilabel}`Maloja` plugin. +7. Toggle the {guilabel}`Enabled` switch. +8. Enter your {guilabel}`Maloja server URL`. This is the URL you set up for your Maloja server. +9. Enter {guilabel}`Your Maloja API key`. Check out [Maloja's documentation](https://github.com/krateng/maloja#how-to-scrobble) for more information. +10. Select {guilabel}`Save`. + +``` + +```{tabbed} Mobile + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your avatar to open the {guilabel}`Options` menu. +3. Select {guilabel}`Settings`. +4. Scroll down to the {guilabel}`Plugins` section. +5. Select {guilabel}`Manage plugins`. +6. Find the {guilabel}`Maloja` plugin. +7. Toggle the {guilabel}`Enabled` switch. +8. Enter your {guilabel}`Maloja server URL`. This is the URL you set up for your Maloja server. +9. Enter {guilabel}`Your Maloja API key`. Check out [Maloja's documentation](https://github.com/krateng/maloja#how-to-scrobble) for more information. +10. Select {guilabel}`Save`. + +``` + +That's it! You've set up the __Maloja__ plugin. When you listen to tracks, the plugin sends the information to your Maloja server. diff --git a/docs/user_documentation/plugins/scrobbler_plugin.md b/docs/user_documentation/plugins/scrobbler_plugin.md new file mode 100644 index 000000000..f085d481f --- /dev/null +++ b/docs/user_documentation/plugins/scrobbler_plugin.md @@ -0,0 +1,47 @@ +# Scrobbler plugin + +```{note} +If you want to use [Last.fm](https://last.fm) to scrobble your listens, your pod admin needs to set up an API account. Contact your {term}`pod` admin if you have any questions. +``` + +The __Scrobbler__ plugin enables you to submit ({term}`scrobble`) listens to a scrobbler service. Scrobbling listens helps you build up a profile of your music tastes. It also enables you to keep a record of your listens. + +```{tip} +Using ListenBrainz or Maloja? Check out the [ListenBrainz](listenbrainz_plugin) and [Maloja](maloja_plugin) plugins! +``` + +The __Scrobbler__ plugin supports any scrobbling service that uses the Audioscrobbler protocol. To set up the __Scrobbler plugin__: + +```{tabbed} Desktop + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your avatar to expand the user menu. +3. Select {guilabel}`Settings`. +4. Scroll down to the {guilabel}`Plugins` section. +5. Select {guilabel}`Manage plugins`. +6. Find the {guilabel}`Scrobbler` plugin. +7. Toggle the {guilabel}`Enabled` switch. +8. Enter the {guilabel}`URL of the scrobbler service`. If you leave this field blank, the plugin defaults to __Last.fm__. +9. Enter {guilabel}`Your scrobbler username`. You can set this up on your scrobbler service. +10. Enter {guilabel}`Your scrobbler password`. You can set this up on your scrobbler service. +11. Select {guilabel}`Save`. + +``` + +```{tabbed} Mobile + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your avatar to open the {guilabel}`Options` menu. +3. Select {guilabel}`Settings`. +4. Scroll down to the {guilabel}`Plugins` section. +5. Select {guilabel}`Manage plugins`. +6. Find the {guilabel}`Scrobbler` plugin. +7. Toggle the {guilabel}`Enabled` switch. +8. Enter the {guilabel}`URL of the scrobbler service`. If you leave this field blank, the plugin defaults to __Last.fm__. +9. Enter {guilabel}`Your scrobbler username`. You can set this up on your scrobbler service. +10. Enter {guilabel}`Your scrobbler password`. You can set this up on your scrobbler service. +11. Select {guilabel}`Save`. + +``` + +That's it! You've set up the __Scrobbler__ plugin. When you listen to tracks, the plugin sends the information to your scrobbler service. diff --git a/docs/user_documentation/queue/add_album.md b/docs/user_documentation/queue/add_album.md new file mode 100644 index 000000000..199153bba --- /dev/null +++ b/docs/user_documentation/queue/add_album.md @@ -0,0 +1,32 @@ +# Add albums to your queue + +Add entire albums to your queue to start listening to them. Choose from the following __Play options__: + +- __Play__ – remove all content from the queue and play the selected album. +- __Add to queue__ – add the selected album to the end of the queue. +- __Play next__ – add the selected album to the next position in the queue. +- __Play now__ – play the selected album immediately but do not clear the queue. + +You can add albums from the following places: + +```{contents} +:local: +``` + +## From the album details page + +To add an album to the queue from the album details page: + +1. Go to the album's details page. +2. Select the orange play button ({fa}`play`) to __Play__ the album. Select the dropdown icon ({fa}`caret-down`) to select a different __Play option__. + +You're done! You've added the album to your queue. + +## From an album card + +To add an album from its album card: + +1. Find the album card in the interface. +2. Select the orange play button ({fa}`play`) to __Play__ the album. Select the kebab menu ({fa}`ellipsis-v`) to select a different __Play option__. + +That's it! You've added the album to your queue. diff --git a/docs/user_documentation/queue/add_artist.md b/docs/user_documentation/queue/add_artist.md new file mode 100644 index 000000000..cf5117b16 --- /dev/null +++ b/docs/user_documentation/queue/add_artist.md @@ -0,0 +1,32 @@ +# Add artist discographies to your queue + +Add an artist's entire discography to your queue to start listening to it. Choose from the following __Play options__: + +- __Play__ – remove all content from the queue and play the artist's discography. +- __Add to queue__ – add the selected artist's discography to the end of the queue. +- __Play next__ – add the selected artist's discography to the next position in the queue. +- __Play now__ – play the artist's discography immediately but do not clear the queue. + +You can add an artist's discography from the following places: + +```{contents} +:local: +``` + +## From the artist details page + +To add an artist's discography to the queue from the artist details page: + +1. Go to the artist's details page. +2. Select the orange play button ({fa}`play`) to __Play__ the album. Select the {guilabel}`More…` to select a different __Play option__. + +You're done! You've added the artist's discography to your queue. + +## From an artist card + +To add an artist's discography from their artist card: + +1. Find the artist card in the interface. +2. Select the orange play button ({fa}`play`) to __Play__ the album. Select the kebab menu ({fa}`ellipsis-v`) to select a different __Play option__. + +That's it! You've added the artist's discography to your queue. diff --git a/docs/user_documentation/queue/add_playlist.md b/docs/user_documentation/queue/add_playlist.md new file mode 100644 index 000000000..16fff4ac7 --- /dev/null +++ b/docs/user_documentation/queue/add_playlist.md @@ -0,0 +1,32 @@ +# Add playlists to your queue + +Add entire playlists to your queue to start listening to them. Choose from the following __Play options__: + +- __Play__ – remove all content from the queue and play the selected playlist. +- __Add to queue__ – add the selected playlist to the end of the queue. +- __Play next__ – add the selected playlist to the next position in the queue. +- __Play now__ – play the selected playlist immediately but do not clear the queue. + +You can add playlists from the following places: + +```{contents} +:local: +``` + +## From the playlist details page + +To add an playlist to the queue from the playlist details page: + +1. Go to the playlist's details page. +2. Select {guilabel}`Play all` to __Play__ the playlist. Select the dropdown icon ({fa}`caret-down`) to select a different __Play option__. + +You're done! You've added the playlist to your queue. + +## From an playlist card + +To add an playlist from its playlist card: + +1. Find the playlist card in the interface. +2. Select the orange play button ({fa}`play`) to __Play__ the playlist. Select the kebab menu ({fa}`ellipsis-v`) to select a different __Play option__. + +That's it! You've added the playlist to your queue. diff --git a/docs/user_documentation/queue/add_series.md b/docs/user_documentation/queue/add_series.md new file mode 100644 index 000000000..d57bebd6c --- /dev/null +++ b/docs/user_documentation/queue/add_series.md @@ -0,0 +1,15 @@ +# Add series to your queue + +Add entire series to your queue to start listening to them. Choose from the following __Play options__: + +- __Play__ – remove all content from the queue and play the selected series. +- __Add to queue__ – add the selected series to the end of the queue. +- __Play next__ – add the selected series to the next position in the queue. +- __Play now__ – play the selected series immediately but do not clear the queue. + +To add a series to the queue from the album details page: + +1. Go to the series' details page. +2. Select the orange play button ({fa}`play`) to __Play__ the series. Select the dropdown icon ({fa}`caret-down`) to select a different __Play option__. + +You're done! You've added the series to your queue. diff --git a/docs/user_documentation/queue/add_tracks.md b/docs/user_documentation/queue/add_tracks.md new file mode 100644 index 000000000..9d34c6685 --- /dev/null +++ b/docs/user_documentation/queue/add_tracks.md @@ -0,0 +1,15 @@ +# Add tracks to your queue + +Add tracks to your queue to start listening to them. Choose from the following __Play options__: + +- __Play__ – remove all content from the queue and play the selected track. +- __Add to queue__ – add the selected track to the end of the queue. +- __Play next__ – add the selected track to the next position in the queue. +- __Play now__ – play the selected track immediately but do not clear the queue. + +To add a track to the queue: + +1. Find your track in a track table. +2. Select the orange play button ({fa}`play`) to __Play__ the track. Select the kebab menu ({fa}`ellipsis-v`) to select a different __Play option__. + +That's it! You've added the track to your queue. diff --git a/docs/user_documentation/queue/index.md b/docs/user_documentation/queue/index.md new file mode 100644 index 000000000..31bed81bd --- /dev/null +++ b/docs/user_documentation/queue/index.md @@ -0,0 +1,21 @@ +# Queue + +Use the audio queue to manage audio playback. You can add tracks, albums, series, artist discographies, and playlists to your queue. + +Follow the guides in this section to get started. + +```{toctree} +--- +caption: Manage your queue +maxdepth: 1 +--- + +add_tracks +add_album +add_series +add_artist +add_playlist +rearrange_content +remove_content + +``` diff --git a/docs/user_documentation/queue/rearrange_content.md b/docs/user_documentation/queue/rearrange_content.md new file mode 100644 index 000000000..d559bcf44 --- /dev/null +++ b/docs/user_documentation/queue/rearrange_content.md @@ -0,0 +1,14 @@ +# Rearrange content in your queue + +```{note} +Rearranging content is currently only supported on the desktop. +``` + +You can change the order of content in your queue at any time. To do this: + +1. Select the up arrow ({fa}`caret-up`) on the queue menu to expand the queue. +2. Pick up tracks by selecting the grip lines on the left. Your mouse pointer shows a hand ({fa}`hand-grab-o`). +3. Drop the tracks in their new position in the queue. +4. Select {guilabel}`Close` to close the queue. + +That's it! You've rearranged the content in your queue. diff --git a/docs/user_documentation/queue/remove_content.md b/docs/user_documentation/queue/remove_content.md new file mode 100644 index 000000000..ae17a5a1a --- /dev/null +++ b/docs/user_documentation/queue/remove_content.md @@ -0,0 +1,52 @@ +# Remove content from your queue + +```{note} +If you remove the currently playing track, the next item in the queue plays. If you remove all items, the queue closes. +``` + +You can remove content from your queue at any time. You can choose between the following options: + +```{contents} +:local: +``` + +## Remove individual tracks from the queue + +To remove individual tracks from the queue: + +```{tabbed} Desktop + +1. Select the up arrow ({fa}`caret-up`) on the queue menu to expand the queue. +2. Select the delete icon ({fa}`times`) next to the track you want to remove. + +``` + +```{tabbed} Mobile + +1. Select the player bar at the bottom of the screen to expand the player. +2. Select the up arrow ({fa}`caret-up`) on the queue menu to expand the queue. +3. Select the delete icon ({fa}`times`) next to the track you want to remove. + +``` + +That's it! You've removed tracks from your queue. + +## Remove all content from the queue + +To remove all content from your queue at once: + +```{tabbed} Desktop + +1. Select the up arrow ({fa}`caret-up`) on the queue menu to expand the queue. +2. Select {guilabel}`Clear` to remove all content from the queue. + +``` + +```{tabbed} Mobile + +1. Select the player bar at the bottom of the screen to expand the player. +2. Select the up arrow ({fa}`caret-up`) on the queue menu to expand the queue. +3. Select {guilabel}`Clear` to remove all content from the queue. +``` + +That's it! You've removed all content from your queue. diff --git a/docs/user_documentation/radios/create_radio.md b/docs/user_documentation/radios/create_radio.md new file mode 100644 index 000000000..78435fd1b --- /dev/null +++ b/docs/user_documentation/radios/create_radio.md @@ -0,0 +1,48 @@ +# Create a radio + +```{note} +If you add content from a __private__ library to a __public__ radio, users can see the tracks but can't play them. +``` + +Create a new radio to create a dynamic playlist of content based on filters. You can filter tracks by __Artist__ and __Tag__. + +To create a new radio: + +```{tabbed} Desktop + +1. Select {guilabel}`Radios` in the sidebar. The {guilabel}`Browsing radios` screen opens. +2. Select {guilabel}` Create your own radio` under the {guilabel}`User radios` section. The {guilabel}`Builder` screen opens. +3. Enter a {guilabel}`Radio name`. +4. __Optional__ – enter a {guilabel}`Description` for your radio. +5. To make your radio available to other users on your {term}`pod`, enable the {guilabel}`Display publicly` switch. If you disable this switch, only you can see the radio. +6. Select {guilabel}`Artist` or {guilabel}`Tag` from the {guilabel}`Select a filter` dropdown. +7. Select {guilabel}`Add filter` to add the filter to your radio. +8. Configure your filter: + 1. Enable the {guilabel}`Exclude` switch to exclude results from your selection in the radio. Disable this switch to include results from your selection in the radio. + 2. Choose your __Artists__ or __Tags__ in the {guilabel}`Config` dropdown menu. + 3. The {guilabel}`Candidates` column shows the number of tracks included. Select the {guilabel}`{count} tracks matching filter` option to view some of these tracks. +9. Check the tracks under the {guilabel}`{count} tracks matching combined filters` section. +10. Select {guilabel}`Save` to save your radio. + +``` + +```{tabbed} Mobile + +1. Select the hamburger menu ({fa}`bars`) to open the menu bar. +2. Select {menuselection}`Explore --> Radios` or {menuselection}`My Library --> Radios`. The {guilabel}`Browsing radios` screen opens. +3. Select {guilabel}` Create your own radio` under the {guilabel}`User radios` section. The {guilabel}`Builder` screen opens. +4. Enter a {guilabel}`Radio name`. +5. __Optional__ – enter a {guilabel}`Description` for your radio. +6. To make your radio available to other users on your {term}`pod`, enable the {guilabel}`Display publicly` switch. If you disable this switch, only you can see the radio. +7. Select {guilabel}`Artist` or {guilabel}`Tag` from the {guilabel}`Select a filter` dropdown. +8. Select {guilabel}`Add filter` to add the filter to your radio. +9. Configure your filter: + 1. Enable the {guilabel}`Exclude` switch to exclude results from your selection in the radio. Disable this switch to include results from your selection in the radio. + 2. Choose your __Artists__ or __Tags__ in the {guilabel}`Config` dropdown menu. + 3. The {guilabel}`Candidates` column shows the number of tracks included. Select the {guilabel}`{count} tracks matching filter` option to view some of these tracks. +10. Check the tracks under the {guilabel}`{count} tracks matching combined filters` section. +11. Select {guilabel}`Save` to save your radio. + +``` + +You're done! You can now play your radio. diff --git a/docs/user_documentation/radios/delete_radio.md b/docs/user_documentation/radios/delete_radio.md new file mode 100644 index 000000000..b94d51ab6 --- /dev/null +++ b/docs/user_documentation/radios/delete_radio.md @@ -0,0 +1,27 @@ +# Delete a radio + +```{warning} +Users who have access to your radio won't be able to access it when you delete it. This action is irreversible. +``` + +If you no longer want a radio, you can delete it. To do this: + +```{tabbed} Desktop + +1. Select {guilabel}`Radios` in the sidebar. The {guilabel}`Browsing radios` screen opens. +2. Select your radio under the {guilabel}`User radios` section. The radio details screen opens. +3. Select {guilabel}`Delete`. A {guilabel}`Do you want to delete the radio` warning appears. +4. Select {guilabel}`Delete radio`. + +``` + +```{tabbed} Mobile + +1. Select the hamburger menu ({fa}`bars`) to open the menu bar. +2. Select {menuselection}`Explore --> Radios` or {menuselection}`My Library --> Radios`. The {guilabel}`Browsing radios` screen opens.2. 3. Select your radio under the {guilabel}`User radios` section. The radio details screen opens. +4. Select {guilabel}`Delete`. A {guilabel}`Do you want to delete the radio` warning appears. +5. Select {guilabel}`Delete radio`. + +``` + +That's it! You've deleted your radio. You can [create a new one](create_radio.md) at any time. diff --git a/docs/user_documentation/radios/edit_radio.md b/docs/user_documentation/radios/edit_radio.md new file mode 100644 index 000000000..8718fecd1 --- /dev/null +++ b/docs/user_documentation/radios/edit_radio.md @@ -0,0 +1,32 @@ +# Edit a radio + +You can edit a radio at any time to change its details, its filters, or both. To do this: + +```{tabbed} Desktop + +1. Select {guilabel}`Radios` in the sidebar. The {guilabel}`Browsing radios` screen opens. +2. Find your radio under the {guilabel}`User radios` section. Select {guilabel}`Edit`. The {guilabel}`Builder` screen opens. +3. Edit any of the following: + - {guilabel}`Radio name`. + - {guilabel}`Description`. + - {guilabel}`Display publicly`. +4. Select {guilabel}`Add filter` to add new filters. Select {guilabel}`Remove` to remove existing filters. +5. Select {guilabel}`Save` to save your radio. + +``` + +```{tabbed} Mobile + +1. Select the hamburger menu ({fa}`bars`) to open the menu bar. +2. Select {menuselection}`Explore --> Radios` or {menuselection}`My Library --> Radios`. The {guilabel}`Browsing radios` screen opens. +3. Find your radio under the {guilabel}`User radios` section. Select {guilabel}`Edit`. The {guilabel}`Builder` screen opens. +4. Edit any of the following: + - {guilabel}`Radio name`. + - {guilabel}`Description`. + - {guilabel}`Display publicly`. +5. Select {guilabel}`Add filter` to add new filters. Select {guilabel}`Remove` to remove existing filters. +6. Select {guilabel}`Save` to save your radio. + +``` + +That's it! You've updated your radio's details. diff --git a/docs/user_documentation/radios/index.md b/docs/user_documentation/radios/index.md new file mode 100644 index 000000000..c6e7d93f5 --- /dev/null +++ b/docs/user_documentation/radios/index.md @@ -0,0 +1,24 @@ +# Radios + +Radios are a great way to discover new music or rediscover old favorites. A radio builds a dynamic playlist of content based on selected criteria. Create genre and artist radios, or tune in to one of Funkwhale's built-in radios. + +Funkwhale offers the following radios out of the box: + +- __Your content__ – listen to content from [libraries](../libraries/index.md) you own. +- __Favorites__ – listen to tracks from your [favorites](../favorites/index.md) list. +- __Random__ – discover something new by letting Funkwhale choose tracks at random. +- __Recently Added__ – listen to the latest content added to your {term}`pod`. +- __Less listened__ – check out tracks you've not heard, or things you haven't given as much attention. + +```{toctree} +--- +caption: Manage your radios +maxdepth: 1 +--- + +create_radio +edit_radio +listen_radio +delete_radio + +``` diff --git a/docs/user_documentation/radios/listen_radio.md b/docs/user_documentation/radios/listen_radio.md new file mode 100644 index 000000000..88d24d495 --- /dev/null +++ b/docs/user_documentation/radios/listen_radio.md @@ -0,0 +1,78 @@ +# Listen to a radio + +```{note} +You can only listen to content in libraries you have access to. For more information, see [Follow a library](../libraries/follow_library). +``` + +You can listen to your radios or public radios created by other users of your {term}`pod`. + +```{contents} +:local: +``` + +## Listen to your radios + +To listen to radios you created: + +```{tabbed} Desktop + +1. Select {menuselection}`My Library --> Radios` in the sidebar. The {guilabel}`Browsing radios` screen opens. +2. Use the filters in the {guilabel}`User radios` section to search for your radio. +3. Select {guilabel}`Play radio` on your radio to start playing the content. + +``` + +```{tabbed} Mobile + +1. Select the hamburger menu ({fa}`bars`) to open the menu bar. +2. Select {menuselection}`My Library --> Radios`. The {guilabel}`Browsing radios` screen opens. +3. Use the filters in the {guilabel}`User radios` section to search for your radio. +4. Select {guilabel}`Play radio` on your radio to start playing the content. + +``` + +You're done! Your radio starts playing. + +## Listen to public radios from your pod + +To listen to public radios other users created: + +```{tabbed} Desktop + +1. Select {menuselection}`Explore --> Radios` in the sidebar. The {guilabel}`Browsing radios` screen opens. +2. Use the filters in the {guilabel}`User radios` section to search for a radio. +3. Select {guilabel}`Play radio` on the selected radio to start playing the content. + +``` + +```{tabbed} Mobile + +1. Select the hamburger menu ({fa}`bars`) to open the menu bar. +2. Select {menuselection}`Explore --> Radios`. The {guilabel}`Browsing radios` screen opens. +3. Use the filters in the {guilabel}`User radios` section to search for a radio. +4. Select {guilabel}`Play radio` on the selected radio to start playing the content. + +``` + +That's it! The radio starts playing. + +## Stop a radio + +Radios continue to play until there is no more content matching their criteria. You can stop radios whenever you want. To do this: + +```{tabbed} Desktop + +1. Select the up arrow ({fa}`caret-up`) on the queue menu to expand the [queue](../queue/index.md). +2. Select {guilabel}`Stop Radio` at the bottom of the queue. + +``` + +```{tabbed} Mobile + +1. Select the player bar at the bottom of the screen to expand the player. +2. Select the up arrow ({fa}`caret-up`) on the queue menu to expand the [queue](../queue/index.md). +3. Select {guilabel}`Stop Radio` at the bottom of the queue. + +``` + +That's it! The radio stops playing. The radio's content remains in the queue. diff --git a/docs/user_documentation/reports/index.md b/docs/user_documentation/reports/index.md new file mode 100644 index 000000000..23baa84ad --- /dev/null +++ b/docs/user_documentation/reports/index.md @@ -0,0 +1,23 @@ +# Reporting + +```{note} +{term}`Pod ` admins and moderators are responsible for handling reports. Pod admins can choose to allow anonymous (logged out) users to send reports. If you cannot send reports anonymously, contact the pod admin. +``` + +Funkwhale provides tools for reporting all content and accounts. You can report content for being objectionable or illegal. You can also report stolen content. Check out the guides in this section to see how to send a report. + +```{toctree} +--- +caption: Submit reports +maxdepth: 1 +--- + +report_account +report_channel +report_library +report_track +report_album +report_artist +report_playlist + +``` diff --git a/docs/user_documentation/reports/report_account.md b/docs/user_documentation/reports/report_account.md new file mode 100644 index 000000000..c78de1511 --- /dev/null +++ b/docs/user_documentation/reports/report_account.md @@ -0,0 +1,17 @@ +# Report an account + +You can report a user account if the user is breaking the {term}`pod's ` rules. To do this: + +1. Select the user's username to go to their profile page. +2. Select the kebab menu ({fa}`ellipsis-v`) to open the options menu. +3. Select {guilabel}`Report {username}`. A {guilabel}`Do you want to report this object?` menu appears. +4. Select a {guilabel}`Category`. Choose one of the following: + - __Takedown request__ – request removal of copyrighted material. + - __Illegal content__ – report an account that features illegal content. + - __Offensive content__ – report an account that features offensive or abusive content. + - __Other__ – submit details of your report in the {guilabel}`Message` field. +5. __If you are not logged in__ – enter your {guilabel}`Email`. Pod moderators use this address to contact you. +6. Enter details of your report in the {guilabel}`Message` field. Provide as much detail as possible here to help the moderators action the report. +7. Select {guilabel}`Submit report` to send your report to the pod moderators. + +That's it! The pod's moderators can now action the report or contact you for clarification. diff --git a/docs/user_documentation/reports/report_album.md b/docs/user_documentation/reports/report_album.md new file mode 100644 index 000000000..612ecd967 --- /dev/null +++ b/docs/user_documentation/reports/report_album.md @@ -0,0 +1,18 @@ +# Report an album + +If an album violates a {term}`pod's ` rules or the law, you can report it. To do this: + +1. Go to the album details page. +2. Select the kebab menu ({fa}`ellipsis-v`) to open the options menu. +3. Select {guilabel}`Report this album`. A {guilabel}`Do you want to report this object?` menu appears. +4. Select a {guilabel}`Category`. Choose one of the following: + - __Takedown request__ – request removal of copyrighted material. + - __Illegal content__ – report an album that features illegal content. + - __Offensive content__ – report an album that features offensive or abusive content. + - __Invalid metadata__ – report that an album features invalid metadata. + - __Other__ – submit details of your report in the {guilabel}`Message` field. +5. __If you are not logged in__ – enter your {guilabel}`Email`. Pod moderators use this address to contact you. +6. Enter details of your report in the {guilabel}`Message` field. Provide as much detail as possible here to help the moderators action the report. +7. Select {guilabel}`Submit report` to send your report to the pod moderators. + +That's it! The pod's moderators can now action the report or contact you for clarification. diff --git a/docs/user_documentation/reports/report_artist.md b/docs/user_documentation/reports/report_artist.md new file mode 100644 index 000000000..1c837568d --- /dev/null +++ b/docs/user_documentation/reports/report_artist.md @@ -0,0 +1,18 @@ +# Report an artist + +If an artist's content violates a {term}`pod's ` rules or the law, you can report it. To do this: + +1. Go to the artist details page. +2. Select {guilabel}`More…` to open the options menu. +3. Select {guilabel}`Report this artist`. A {guilabel}`Do you want to report this object?` menu appears. +4. Select a {guilabel}`Category`. Choose one of the following: + - __Takedown request__ – request removal of copyrighted material. + - __Illegal content__ – report an artist that features illegal content. + - __Offensive content__ – report an artist that features offensive or abusive content. + - __Invalid metadata__ – report that an artist's content features invalid metadata. + - __Other__ – submit details of your report in the {guilabel}`Message` field. +5. __If you are not logged in__ – enter your {guilabel}`Email`. Pod moderators use this address to contact you. +6. Enter details of your report in the {guilabel}`Message` field. Provide as much detail as possible here to help the moderators action the report. +7. Select {guilabel}`Submit report` to send your report to the pod moderators. + +That's it! The pod's moderators can now action the report or contact you for clarification. diff --git a/docs/user_documentation/reports/report_channel.md b/docs/user_documentation/reports/report_channel.md new file mode 100644 index 000000000..3bce12be1 --- /dev/null +++ b/docs/user_documentation/reports/report_channel.md @@ -0,0 +1,18 @@ +# Report a channel + +If a channel's content violates a {term}`pod's ` rules or the law, you can report it. To do this: + +1. Go to the channel's details page. +2. Select the kebab menu ({fa}`ellipsis-v`) to open the options menu. +3. Select {guilabel}`Report this channel`. A {guilabel}`Do you want to report this object?` menu appears. +4. Select a {guilabel}`Category`. Choose one of the following: + - __Takedown request__ – request removal of copyrighted material. + - __Illegal content__ – report a channel that features illegal content. + - __Offensive content__ – report a channel that features offensive or abusive content. + - __Invalid metadata__ – report that a channel's content features invalid metadata. + - __Other__ – submit details of your report in the {guilabel}`Message` field. +5. __If you are not logged in__ – enter your {guilabel}`Email`. Pod moderators use this address to contact you. +6. Enter details of your report in the {guilabel}`Message` field. Provide as much detail as possible here to help the moderators action the report. +7. Select {guilabel}`Submit report` to send your report to the pod moderators. + +That's it! The pod's moderators can now action the report or contact you for clarification. diff --git a/docs/user_documentation/reports/report_library.md b/docs/user_documentation/reports/report_library.md new file mode 100644 index 000000000..e2410ea01 --- /dev/null +++ b/docs/user_documentation/reports/report_library.md @@ -0,0 +1,18 @@ +# Report a library + +If a channel's content violates a {term}`pod's ` rules or the law, you can report it. To do this: + +1. Go to the library's details page. +2. Select the kebab menu ({fa}`ellipsis-v`) to open the options menu. +3. Select {guilabel}`Report this library`. A {guilabel}`Do you want to report this object?` menu appears. +4. Select a {guilabel}`Category`. Choose one of the following: + - __Takedown request__ – request removal of copyrighted material. + - __Illegal content__ – report a library that features illegal content. + - __Offensive content__ – report a library that features offensive or abusive content. + - __Invalid metadata__ – report that a library's content features invalid metadata. + - __Other__ – submit details of your report in the {guilabel}`Message` field. +5. __If you are not logged in__ – enter your {guilabel}`Email`. Pod moderators use this address to contact you. +6. Enter details of your report in the {guilabel}`Message` field. Provide as much detail as possible here to help the moderators action the report. +7. Select {guilabel}`Submit report` to send your report to the pod moderators. + +That's it! The pod's moderators can now action the report or contact you for clarification. diff --git a/docs/user_documentation/reports/report_playlist.md b/docs/user_documentation/reports/report_playlist.md new file mode 100644 index 000000000..405d48f7e --- /dev/null +++ b/docs/user_documentation/reports/report_playlist.md @@ -0,0 +1,42 @@ +# Report a playlist + +If a playlist's content violates a {term}`pod's ` rules or the law, you can report it. To do this: + +```{tabbed} Desktop + +1. Select {menuselection}`Explore --> Playlists` in the sidebar. The {guilabel}`Browsing playlists` screen opens. +2. Use the filters to search for a playlist. +3. Select the three dot menu ({fa}`ellipsis-h`) to open the options menu. +4. Select {guilabel}`Report this playlist`. A {guilabel}`Do you want to report this object?` menu appears. +5. Select a {guilabel}`Category`. Choose one of the following: + - __Takedown request__ – request removal of copyrighted material. + - __Illegal content__ – report a playlist that features illegal content. + - __Offensive content__ – report a playlist that features offensive or abusive content. + - __Invalid metadata__ – report that a playlist's content features invalid metadata. + - __Other__ – submit details of your report in the {guilabel}`Message` field. +6. __If you are not logged in__ – enter your {guilabel}`Email`. Pod moderators use this address to contact you. +7. Enter details of your report in the {guilabel}`Message` field. Provide as much detail as possible here to help the moderators action the report. +8. Select {guilabel}`Submit report` to send your report to the pod moderators. + +``` + +```{tabbed} Mobile + +1. Select the hamburger menu ({fa}`bars`) to open the menu bar. +2. Select {menuselection}`Explore --> Playlists`. The {guilabel}`Browsing playlists` screen opens. +3. Use the filters to search for a playlist. +4. Select the three dot menu ({fa}`ellipsis-h`) to open the options menu. +5. Select {guilabel}`Report this playlist`. A {guilabel}`Do you want to report this object?` menu appears. +6. Select a {guilabel}`Category`. Choose one of the following: + - __Takedown request__ – request removal of copyrighted material. + - __Illegal content__ – report a playlist that features illegal content. + - __Offensive content__ – report a playlist that features offensive or abusive content. + - __Invalid metadata__ – report that a playlist's content features invalid metadata. + - __Other__ – submit details of your report in the {guilabel}`Message` field. +7. __If you are not logged in__ – enter your {guilabel}`Email`. Pod moderators use this address to contact you. +8. Enter details of your report in the {guilabel}`Message` field. Provide as much detail as possible here to help the moderators action the report. +9. Select {guilabel}`Submit report` to send your report to the pod moderators. + +``` + +That's it! The pod's moderators can now action the report or contact you for clarification. diff --git a/docs/user_documentation/reports/report_track.md b/docs/user_documentation/reports/report_track.md new file mode 100644 index 000000000..946465152 --- /dev/null +++ b/docs/user_documentation/reports/report_track.md @@ -0,0 +1,18 @@ +# Report a track + +If a track violates a {term}`pod's ` rules or the law, you can report it. To do this: + +1. Go to the track details page or locate the track in a track table. +2. Select the kebab menu ({fa}`ellipsis-v`) to open the options menu. +3. Select {guilabel}`Report this track`. A {guilabel}`Do you want to report this object?` menu appears. +4. Select a {guilabel}`Category`. Choose one of the following: + - __Takedown request__ – request removal of copyrighted material. + - __Illegal content__ – report a track that features illegal content. + - __Offensive content__ – report a track that features offensive or abusive content. + - __Invalid metadata__ – report that a track features invalid metadata. + - __Other__ – submit details of your report in the {guilabel}`Message` field. +5. __If you are not logged in__ – enter your {guilabel}`Email`. Pod moderators use this address to contact you. +6. Enter details of your report in the {guilabel}`Message` field. Provide as much detail as possible here to help the moderators action the report. +7. Select {guilabel}`Submit report` to send your report to the pod moderators. + +That's it! The pod's moderators can now action the report or contact you for clarification. diff --git a/docs/user_documentation/subsonic/disable_subsonic.md b/docs/user_documentation/subsonic/disable_subsonic.md new file mode 100644 index 000000000..7b696b684 --- /dev/null +++ b/docs/user_documentation/subsonic/disable_subsonic.md @@ -0,0 +1,29 @@ +# Disable Subsonic access + +If you don't want to use Subsonic any more, you can disable access. This stops any Subsonic apps being able to log in to your account. To do this: + +```{tabbed} Desktop + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your avatar to expand the user menu. +3. Select {guilabel}`Settings`. +4. Scroll to the {guilabel}`Subsonic API password` section. +5. Select {guilabel}`Disable Subsonic access`. +6. Select {guilabel}`Disable access` in the warning message that appears. +7. The Subsonic password field shows {guilabel}`Access disabled`. + +``` + +```{tabbed} Mobile + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your avatar to open the {guilabel}`Options` menu. +3. Select {guilabel}`Settings`. +4. Scroll to the {guilabel}`Subsonic API password` section. +5. Select {guilabel}`Disable Subsonic access`. +6. Select {guilabel}`Disable access` in the warning message that appears. +7. The Subsonic password field shows {guilabel}`Access disabled`. + +``` + +You're done! Subsonic apps can no longer access your account. You can re-enable the API at any time by [requesting a new password](subsonic_password). diff --git a/docs/user_documentation/subsonic/index.md b/docs/user_documentation/subsonic/index.md new file mode 100644 index 000000000..9eef75fd6 --- /dev/null +++ b/docs/user_documentation/subsonic/index.md @@ -0,0 +1,19 @@ +# Subsonic access + +```{note} +{term}`Pod` admins can choose to disable access to the Subsonic API. If the Subsonic password option isn't available, contact your pod admin. +``` + +Funkwhale supports a subset of the [Subsonic API](http://www.subsonic.org/pages/index.jsp). This enables you to use Subsonic apps to stream your Funkwhale content. Check out the guides in this section to manage your Subsonic access. + +```{toctree} +--- +maxdepth: 1 +caption: Manage your Subsonic access +--- + +subsonic_password +reset_subsonic +disable_subsonic + +``` diff --git a/docs/user_documentation/subsonic/reset_subsonic.md b/docs/user_documentation/subsonic/reset_subsonic.md new file mode 100644 index 000000000..95c17a802 --- /dev/null +++ b/docs/user_documentation/subsonic/reset_subsonic.md @@ -0,0 +1,33 @@ +# Reset your Subsonic password + +```{warning} +Changing your Subsonic password logs you out of any Subsonic apps you are using. You need to log back in using your new password. +``` + +You can reset your Subsonic password at any time. To do this: + +```{tabbed} Desktop + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your avatar to expand the user menu. +3. Select {guilabel}`Settings`. +4. Scroll to the {guilabel}`Subsonic API password` section. +5. Select {guilabel}`Request a new password`. +6. Select {guilabel}`Request a new password` in the warning message that appears. The server generates a new password for you. +7. Select the {guilabel}`copy` icon next to the password field to copy your password. + +``` + +```{tabbed} Mobile + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your avatar to open the {guilabel}`Options` menu. +3. Select {guilabel}`Settings`. +4. Scroll to the {guilabel}`Subsonic API password` section. +5. Select {guilabel}`Request a new password`. +6. Select {guilabel}`Request a new password` in the warning message that appears. The server generates a new password for you. +7. Select the {guilabel}`copy` icon next to the password field to copy your password. + +``` + +That's it! Your new password is ready to use. diff --git a/docs/user_documentation/subsonic/subsonic_password.md b/docs/user_documentation/subsonic/subsonic_password.md new file mode 100644 index 000000000..ae014b784 --- /dev/null +++ b/docs/user_documentation/subsonic/subsonic_password.md @@ -0,0 +1,27 @@ +# Request your Subsonic password + +To access the Subsonic API, you need to request a Subsonic password. To do this: + +```{tabbed} Desktop + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your avatar to expand the user menu. +3. Select {guilabel}`Settings`. +4. Scroll to the {guilabel}`Subsonic API password` section. +5. Select {guilabel}`Request a password`. The server generates your password for you. +6. Select the {guilabel}`copy` icon next to the password field to copy your password. + +``` + +```{tabbed} Mobile + +1. Log in to your account. +2. Select the cog icon ({fa}`cog`) or your avatar to open the {guilabel}`Options` menu. +3. Select {guilabel}`Settings`. +4. Scroll to the {guilabel}`Subsonic API password` section. +5. Select {guilabel}`Request a password`. The server generates your password for you. +6. Select the {guilabel}`copy` icon next to the password field to copy your password. + +``` + +Congratulations! You've got your Subsonic password. You can now enter this in your Subsonic app to start listening to Funkwhale content. diff --git a/docs/users/account.rst b/docs/users/account.rst deleted file mode 100644 index 54dbfab3b..000000000 --- a/docs/users/account.rst +++ /dev/null @@ -1,14 +0,0 @@ -Manage your account -=================== - -Delete your account -------------------- - -You can delete your Funkwhale account by visiting your settings. The deletion form is found at the bottom of the page. You will need to input your password to confirm the deletion. - -Once the deletion request is submitted, your account and associated data will be removed from the server within a few minutes. This includes, but isn't limited to your avatar, e-mail address, music, favorites, radios, followers and playlists. - -Your server will also broadcast a message to other server on the federation to inform them about the deletion. - -Please note that while these servers are supposed to comply and delete any local copy of your data, this isn't a strong guarantee and some data may remain available, especially on servers -that are offline or unreachable when the deletion message is broadcasted. diff --git a/docs/users/apps.rst b/docs/users/apps.rst deleted file mode 100644 index 1c8a93234..000000000 --- a/docs/users/apps.rst +++ /dev/null @@ -1,198 +0,0 @@ -Using Funkwhale from other apps -=============================== - -The only official client for using Funkwhale is the web client, the one you use in your browser. - -As of 0.21, the web client has seen major improvements as a standalone app -with changes to player design to make it a more mobile-first experience as -well as the introduction of `PWA functionality `_. -Using Funkwhale as a PWA gives the following benefits: - -- Allows users to install the web player as a standalone app on mobile and desktop -- Greatly improves background performance on mobile devices -- Allows you to interact with the player using media keys on desktop -- Allows users to perform updates as soon as they roll out on the server - at the click of a button - -In addition to the web player, this page lists alternative clients you can -use to connect to your Funkwhale instance and enjoy your music. - - -Subsonic-compatible clients ---------------------------- - -Since version 0.12, Funkwhale implements a subset of the `Subsonic API `_. -This API is a de-facto standard for a lot of projects out there, and many clients -are available that works with this API. - -These Subsonic features are supported in Funkwhale: - -- Search (artists, albums, tracks) -- Common library browsing using ID3 tags (list artists, albums, etc.) -- Playlist management -- Stars (which is mapped to Funkwhale's favorites) - -These features are missing: - -- Transcoding/streaming with different bitrates -- Album covers -- Artist info (this data is not available in Funkwhale) -- Library browsing that relies music directories -- Bookmarks -- Admin -- Chat -- Shares - -.. note:: - - If you know or use some recent, well-maintained Subsonic clients, - please get in touch so we can add them to this list. - - In particular we're still lacking an iOS client! - - -Enabling Subsonic on your Funkwhale account -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. note:: - - Accessing Funkwhale from third party apps requires the instance administrator - to enable the Subsonic API setting. If you are unable to use Subsonic, please - contact your administrator. - -To log-in on your Funkwhale account from Subsonic clients, you will need to -set a separate Subsonic API password by visiting your settings page. - -Then, when using a client, you'll have to input some information about your server: - -1. Your Funkwhale instance URL (e.g. https://demo.funkwhale.audio) -2. Your Funkwhale username (e.g. demo) -3. Your Subsonic API password (the one you set earlier in this section) - -In your client configuration, please double check the "ID3" or "Browse with tags" -setting is enabled. - -Ultrasonic (Android) -^^^^^^^^^^^^^^^^^^^^ - -- Price: free -- F-Droid: https://f-droid.org/en/packages/org.moire.ultrasonic/ -- Google Play: https://play.google.com/store/apps/details?id=org.moire.ultrasonic -- Sources: https://github.com/ultrasonic/ultrasonic - -Ultrasonic is a full-featured Subsonic client with Playlists, Stars, Search, -Offline mode, etc. - -It's one of the recommended Android client to use with Funkwhale, as we are doing -our Android tests on this one. - -To enable playback from Funkwhale, enter the following information in the server settings: - -- Server address: the root URL of your instance -- Username: your username on the instance -- Password: this will be your subsonic password - -Then in the general settings select "Browse Using ID3 Tags" - -DSub (Android) -^^^^^^^^^^^^^^ - -- Price: free (on F-Droid) -- F-Droid: https://f-droid.org/en/packages/github.daneren2005.dsub/ -- Google Play: https://play.google.com/store/apps/details?id=github.daneren2005.dsub -- Sources: https://github.com/daneren2005/Subsonic - -DSub is a full-featured Subsonic client that works great, and has a lot of features: - -- Playlists -- Stars -- Search -- Offline cache (with configurable size, playlist download, queue prefetching, etc.) - -It's one of the recommended Android client to use with Funkwhale, as we are doing -our Android tests on this one. - -To enable playback from Funkwhale, enter the following information in the server settings: - -- Server address: the root URL of your instance -- Username: your username on the instance -- Password: this will be your subsonic password -- Browse By Tags: enabled - -play:Sub (iOS) -^^^^^^^^^^^^^^ - -- Price: $4,99 -- App Store: https://itunes.apple.com/us/app/play-sub-subsonic-music-streamer/id955329386 -- Website: http://michaelsapps.dk/playsubapp/ - -Although paid, this app is known to work great with Funkwhale as the maintainer, Michael Bech Hansen, implements Funkwhale-specific logic and checks. - -Substreamer (iOS) -^^^^^^^^^^^^^^^^^ - -- Price: free -- App Store: https://itunes.apple.com/us/app/substreamer/id1012991665 - - -Clementine (Desktop) -^^^^^^^^^^^^^^^^^^^^ -- Price: free -- Website: https://www.clementine-player.org/fr/ - -This desktop client works on Windows, Mac OS X and Linux and is able to stream -music from your Funkwhale instance. However, it does not implement advanced -features such as playlist management, search or stars. - -This is the client we use for our desktop tests. - -To enable playback from Funkwhale, enter the following information in the Internet -> subsonic settings: - -- Server address: the root URL of your instance -- Username: your username on the instance -- Password: this will be your subsonic password - -Mopidy (CLI) -^^^^^^^^^^^^ -- Price: free -- Website: https://www.mopidy.com/ - -Mopidy is a Python-based music server which you can run on your machine in order -to access your music through a CLI such as `ncmpcpp `_. - -In order to use Mopidy to stream from the CLI, you will need to install the following dependencies: - -- Mopidy -- mopidy-subidy: a plugin for Subsonic https://github.com/Prior99/mopidy-subidy -- ncmpcpp - -Once installed, add the following to your /etc/mopidy/mopidy.conf:: - - [subidy] - enabled=True - url=https://path.to/your/funkwhale/server - username=your_funkwhale_username - password=your_subsonic_password - #legacy_auth=(optional - setting to yes may solve some connection errors) - #api_version=(optional - specify which API version to use. Subsonic 6.2 uses 1.14.0) - -Then in your .config/ncmpcpp/config, change the startup_screen value so that it doesn't default to the built-in media library:: - - startup_screen = browser - -This will show your artists, albums, and playlists when you start ncmpcpp. - -[Optional]: enable and start mopidy as a service to start the server at boot. - -.. note:: - - This also works with the `mopidy-funkwhale plugin `_ - -Mobydick (Desktop) -^^^^^^^^^^^^^^^^^^ - -- Price: free -- Website: https://github.com/AnaGelez/mobydick - -Mobydick is a free and open-source desktop application for linux (based on GTK+) to easily download -tracks, albums and discography from a Funkwhale instance. diff --git a/docs/users/builtinplugins.rst b/docs/users/builtinplugins.rst deleted file mode 100644 index 5c295eb3e..000000000 --- a/docs/users/builtinplugins.rst +++ /dev/null @@ -1,74 +0,0 @@ -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/channels.rst b/docs/users/channels.rst deleted file mode 100644 index 76b66dcbd..000000000 --- a/docs/users/channels.rst +++ /dev/null @@ -1,119 +0,0 @@ -Managing Channels -================= - -Channels are a collection of audio files published directly on Funkwhale. -While :doc:`libraries ` are used to store collections of music such as -your personal music collection or a collection of publicly available music, channels -come in two forms: - -- **Podcasts** - A podcast published on Funkwhale -- **Artist Discography** - A collection of music by a specific artist - -While libraries come with different privacy levels due to the type of content they host, -channels are public and are designed to be followed by others across the fediverse. - -.. _create_channel: - -Creating a Channel ------------------- - -.. note:: - - Channel social network names need to be unique as these are used for federation. They - also cannot be altered at a later date, so make sure you're happy with what you choose - -To create a channel: - -- Click or tap on the upload button in the sidebar -- Select "Get Started" in the "Publish your work in a channel" section -- Click or tap on the "Add New" option next to the Channels header -- Select whether you are creating a "Podcasts" channel or an "Artist Discography channel" - and click "Next Step" -- Give your channel a name and a Social Network Name. The social network name will be filled - in with the channel name by default -- Upload a cover image for the channel -- Add tags and languages for podcasts, or just tags for artist discographies -- Write a description of your channel -- If the channel is for podcasts, assign a category and a subcategory -- When all details have been filled in, click "Create Channel" - -.. _channel_upload: - -Uploading Files to a Channel ----------------------------- - -Once you have :ref:`created a channel `, you can start uploading content to -it. - -- Click or tap on the upload button in the sidebar -- Select "Get Started" in the "Publish your work in a channel" section -- Select the channel you would like to publish your work in - - - If you would like to create a new series or add a new album, click on the "Add New" - button under the "Albums" or "Series" section and enter an album/series name - -- Click on the "Upload" button to bring up the upload wizard -- Select the album/series from the drop down menu (or leave this blank if not required) -- Select a License to publish the work under and click "Next Step" -- Drag and drop your file(s) or click on the "Browse" button to open your file browser -- Once the file is uploaded, you can click on the pencil icon to edit details such as tags - and position -- When you're finished with the update, click "Publish" to publish the new track or select - "Finish Later" from the drop-down arrow menu to store your changes for later publication - -If you have saved files for later publication, these will be shown the next time you go through -the upload process with the option to "Ignore" or "Resume" the file upload - -.. _edit_channel: - -Editing a Channel ------------------ - -If you would like to change the details of a channel, such as the name, tags, language, picture -or description, you can easily do this by doing the following: - -- Click or tap on the upload button in the sidebar -- Select "Get Started" in the "Publish your work in a channel" section -- Select the channel you would like to edit -- Click on the three dot menu and select "Edit" -- In the screen that appears, make your changes then click "Update Channel" to save them - -.. _delete_channel_tracks: - -Deleting Content From a Channel -------------------------------- - -.. warning:: - - Deleting a series or album also deletes all associated tracks. Deleting tracks/episodes - removes the files from the server and is not reversible. If you delete something and want - to add it to the channel again, you will need to go through the :ref:`uploading process ` - again - -If you no longer want an episode/track or series/album in a channel, you can remove them. - -- Click or tap on the upload button in the sidebar -- Select "Get Started" in the "Publish your work in a channel" section -- Select the channel you would like to remove content from -- Click on the track/episode or album/series you would like to remove to bring up its details -- Click on the three dot menu and select "Delete..." -- A warning will appear. If you want to continue, click "Delete" to remove the item - -.. _delete_channel: - -Deleting a Channel ------------------- - -.. warning:: - - Deleting a channel is irreversible. If you delete a channel all content will be removed - and the channel will be unavailable to other users. The name of the channel will not be - re-usable as these are used for federation - -If you want to remove your channel entirely, do the following: - -- Click or tap on the upload button in the sidebar -- Select "Get Started" in the "Publish your work in a channel" section -- Select the channel you would like to delete -- Click on the three dot menu and select "Delete" -- A warning will appear. If you want to continue, click "Delete" to remove the channel diff --git a/docs/users/create.rst b/docs/users/create.rst deleted file mode 100644 index 8c734f78c..000000000 --- a/docs/users/create.rst +++ /dev/null @@ -1,23 +0,0 @@ -Creating a Funkwhale Account -============================ - -Before you can start using Funkwhale, you will need to set up an account on an instance. While -some instances allow you to listen to public music anonymously, you will need to create an account -to benefit from the full Funkwhale experience. - -A list of instances along with other useful information such as version and enabled features can be found -`here `_. Servers marked with -"Open registrations" are available to sign up to. - -Signing up to an Instance -------------------------- - -Once you have chosen the instance you would like to sign up to, creating an account is easy. - -1. Click on the "Create an account" option on the left-hand side -2. Enter your preferred username, e-mail address, and password -3. [Optional] enter an Invitation code if you received an invite from an existing user -4. Click on "Create my Account" -5. Once you have created your account, you will be required to log in. - -Now that you've created your account, you can go ahead and :doc:`start uploading content to your library `. diff --git a/docs/users/editing.rst b/docs/users/editing.rst deleted file mode 100644 index b99bf9782..000000000 --- a/docs/users/editing.rst +++ /dev/null @@ -1,80 +0,0 @@ -Editing Uploaded Content -======================== - -Content uploaded to Funkwhale can be edited to update details such as album art, -item descriptions, tags, song positions, copyright notices, licenses and titles. -This can be helpful if an upload was not tagged correctly during upload and needs -to be corrected afterwards, or if content you've published through Funkwhale needs -to be changed at a later date. - -.. _artist-edit: - -Editing Artists ---------------- - -.. note:: - - You will only be able to edit artists in your own library unless you are a pod admin - -To edit an artist on Funkwhale: - -- Search for the artist in question and click on the result to get to the details - page -- Click on the "More..." drop-down menu and select "Edit" -- Edit any of the following details: - - - **Name** - The name of the artist - - **Description** - A free text description of the artist. Markdown syntax is supported - - **Cover** - A cover image for the artist. By default, this will be taken from album art, - but setting it here will override the value on the artist card and the details page - - **Tags**: The genre tags associated with the artist. These will be used in radios and searches - -- Write a summary of your changes and click "Submit and apply edit" - -.. _album-edit: - -Editing Albums --------------- - -.. note:: - - You will only be able to edit albums in your own library unless you are a pod admin - -To edit an album on Funkwhale: - -- Search for the album in question and click on the result to get to the details page -- Click on the three-dot menu next to the Play button and select "Edit" -- Edit any of the following details: - - - **Title**: The title of the album - - **Description**: A free text description of the album. Markdown syntax is supported - - **Release Date**: The release date of the album - - **Cover**: The cover art of the album. This will be shown on the album card and details page - - **Tags**: The genre tags associated with the album. These will be used in radios and searches - -- Write a summary of your changes and click "Submit and apply edit" - -.. _track-edit: - -Editing Tracks --------------- - -.. note:: - - You will only be able to edit tracks in your own library unless you are a pod admin - -To edit a track on Funkwhale: - -- Search for the track in question and click on the result to get to the details page -- Click on the three-dot menu next to the download button and select "Edit" -- Edit any of the following details: - - - **Title**: The title of the track - - **Description**: A free text description of the track. Markdown syntax is supported - - **Cover**: The cover art of the track. This will be shown on and details page - - **Copyright**: The name of the copyright holder - - **License**: The license under which the track was released. Funkwhale only accepts - free licenses, so anything under a non-free license should be left blank - - **Tags**: The genre tags associated with the track. These will be used in radios and searches - -- Write a summary of your changes and click "Submit and apply edit" diff --git a/docs/users/favorites.rst b/docs/users/favorites.rst deleted file mode 100644 index ac232f0cd..000000000 --- a/docs/users/favorites.rst +++ /dev/null @@ -1,51 +0,0 @@ -Managing Favorites -================== - -Like any media player, Funkwhale allows you to favorite tracks to keep tabs on -the tracks you've enjoyed - -Adding Favorites ----------------- - -From a Library -^^^^^^^^^^^^^^ - -To add a track to your favorites from your library: - -- Search for the song or navigate to its album page -- Click on the gray heart icon next to the track -- Once the gray heart has turned pink, the song will be in your favorites list - -From a Channel -^^^^^^^^^^^^^^ - -To add a track to your favorites from a channel: - -- Click on the channel in question and find the track you would like to favorite -- Click on the track to open its overview page -- Click on the white heart icon next to the Play button -- Once the white heart has turned pink, the track will be in your favorites list - -From Currently Playing -^^^^^^^^^^^^^^^^^^^^^^ - -To add the currently playing track to your favorites - -- Click on the white heart icon underneath the track title in the player window -- Once the white heart has turned pink, the song will be in your favorites list - -Removing Favorites ------------------- - -If you no longer want a track to appear in your favorites list: - -- Search for the song or navigate to its album page -- Click on the pink heart icon next to the song -- Once clicked, the heart will disappear and the track will no longer be in your favorites - -Viewing Favorites ------------------ - -Once you've favorited some tracks, you can view them any time by clicking on -"Favorites" under the "Music" menu on the left-hand side. From here you'll be -able to :doc:`add your favorite tracks to playlists ` or :doc:`start a radio of your favorite tracks `. diff --git a/docs/users/follow.rst b/docs/users/follow.rst deleted file mode 100644 index 2d4d8a780..000000000 --- a/docs/users/follow.rst +++ /dev/null @@ -1,58 +0,0 @@ -Following Libraries -==================== - -Funkwhale's major strength is its focus on federated sharing of music. Users can share -music with one another through the network using library links. - -Library Permissions -------------------- - -Libraries are set up with specific permissions that determine their visibility to users on the local instance -and wider federated network. These permissions also determine whether or not follow requests need to be accepted -by the library owner. These permissions are as follows: - -- **Everyone, across all instances** - the library will automatically accept follows from all users -- **Everyone on this instance** - the library will automatically accept follows from users on the same instance, but external users will need to be accepted by the library owner -- **Nobody Except Me** - all follows will need to be approved by the library owner - -Getting Library Links ---------------------- - -The first step to following a library is getting a valid library link. These links typically look like -``https://instance-url/federation/music/libraries/a-random-string-of-numbers-and-letters``. Users can -share their library links with you directly, or you can find the library links for public libraries by -visiting their instance. To do this: - -- Visit the instance containing the library you wish to follow -- Select an item contained within the library -- Scroll down to the "User libraries" section. You should see the name of the library in question -- The library link will be under "Sharing link". Click on "Copy" to copy the link to your clipboard - -Following Other Libraries --------------------------- - -Once you've got the library link, you can start following the library by doing the following: - -- Click on the upload icon on the side bar -- Select "Get Started" under the "Follow Remote Libraries" section -- Paste the library link in the search bar and click on the magnifying glass -- Click on the "Follow" button when the library card appears - -If another user on your instance has followed a library, you can follow it as well in case the user -leaves or stops following it. To do this: - -- Select an item contained within the library on your instance -- Scroll down to the "User libraries" section. You should see the name of the library in question -- Click on "Follow" - -Sharing Your Libraries ----------------------- - -As well as being able to follow other users, you can also share your libraries with friends, family, and -the network at large. To find your library link: - -- Navigate to ``https://your-instance/content/libraries`` or click the upload button and select "Get Started" - under the "Upload third-party content in a library" section to access your libraries -- Find the library in question and click on the "Details" button -- The sharing link should be shown on under the library details. Click on the "Copy" button to copy the link -- Share this link with other users \ No newline at end of file diff --git a/docs/users/followchannel.rst b/docs/users/followchannel.rst deleted file mode 100644 index e664a1c19..000000000 --- a/docs/users/followchannel.rst +++ /dev/null @@ -1,53 +0,0 @@ -Following Channels -================== - -Following Funkwhale Channels on Funkwhale ------------------------------------------ - -If a channel was created on a Funkwhale pod, you can easily follow it from another pod -or from the same pod like a user account. - -If you know the name of the channel: - -- Search for the channel name and select it from the results -- Click on the "Subscribe" button to start following - -If you have the channel's full social network name: - -- Go the the "Channels" tab on the left hand side -- Click "Add new" -- Paste the full address of the channel (in the format @name@pod.extension) or the - URL to the channel -- Click "Subscribe" - -Following Funkwhale Channels Through the Fediverse --------------------------------------------------- - -Funkwhale channels can be followed from different ActivityPub-enabled applications -such as Mastodon and Reel2Bits. To do this: - -- Get the channel name (in the format @name@pod.extension) or the - URL to the channel -- Search for the account and follow it in the same way as any other account - -Following Funkwhale Channels through podcast apps -------------------------------------------------- - -If you want to listen to a podcast published on Funkwhale through another podcasting app, -you can find the channel's RSS feed and paste it in to the application of your choice. To -get the RSS feed of a channel: - -- Find the channel in question and click on the RSS icon next to the three dot menu -- Copy the RSS feed under the "Subscribe via RSS" and paste this in to your application - -Following RSS Feeds on Funkwhale --------------------------------- - -As a podcast platform, Funkwhale supports following podcasts hosted externally -using RSS feeds. To follow an external podcast: - -- Copy the RSS feed link from the podcast (this will usually end with `.xml`, `.rss` or `feed` -- Enter the URL into the search bar and click "Subscribe to podcast via RSS" or go to the "Channels" - tab on the left hand side, click "Add new", paste the URL and click "Subscribe" - -The podcast will then be loaded in to your pod diff --git a/docs/users/index.rst b/docs/users/index.rst deleted file mode 100644 index fb881d0e1..000000000 --- a/docs/users/index.rst +++ /dev/null @@ -1,45 +0,0 @@ -User Documentation -================== - -This documentation is targeted at Funkwhale users. In here you'll find guides for interacting with -Funkwhale, uploading your music, and building a musical social network. - -Getting Started ---------------- - -.. toctree:: - :maxdepth: 2 - - create - tagging - upload - editing - - -Using Funkwhale ---------------- - -.. toctree:: - :maxdepth: 2 - - account - queue - managing - channels - playlists - favorites - radios - followchannel - follow - apps - reports - cli - builtinplugins - -Troubleshooting Issues ----------------------- - -.. toctree:: - :maxdepth: 2 - - troubleshooting diff --git a/docs/users/managing.rst b/docs/users/managing.rst deleted file mode 100644 index 37b010e68..000000000 --- a/docs/users/managing.rst +++ /dev/null @@ -1,101 +0,0 @@ -Managing Libraries -================== - -Managing your music libraries is an important part of using Funkwhale. In addition to :doc:`uploading new music `, you may also want to :ref:`edit your library's details `, :ref:`delete a library `, or :ref:`remove content from a library `. - -If you are looking to publish content on Funkwhale directly, you can use :doc:`channels ` instead - -.. _create_library: - -Creating a Library ------------------- - -To upload content to a library, you will first need to create one. To do this: - -- Navigate to ``https://your-instance/content/libraries`` or click on the upload icon and - click on "Get Started" under the "Upload third-party content in a library" section -- Click on the "Create a new library" option under the "My Libraries" header to bring up the creation screen -- Enter the name, description, and privacy level of the library. The privacy level can be one of the following: - - - Public: anyone can follow the library to automatically access its content (including users on other instances) - - Local: other users from your instance can follow the library to automatically access its content - - Private: nobody apart from you can access the library content - -- Click "Create Library" to save your changes - -.. _upload_library: - -Uploading Content to a Library ------------------------------- - -.. note:: - - Content you upload to a library will inherit the privacy level of the library itself. Content not - distributed under a permissive library should only be placed in private libraries - -Once you have :ref:`created a library `, you can start adding files to it. Before you -upload files, it is a good idea to :doc:`tag them correctly ` to make sure they have the right -metadata associated with it. - -To upload content: - -- Navigate to ``https://your-instance/content/libraries`` or click on the upload icon in the sidebar and - click on "Get Started" under the "Upload third-party content in a library" section -- Click "Upload" under the library you wish to edit -- You will see a summary of the upload date and information. Click "Proceed" to continue -- Drag and drop the files you would like to upload or click on the upload section to open the file picker - and open the files -- The "Processing" tab will show the status of the uploads including any errors or warnings - -.. note:: - - If you try to navigate away from the upload screen before everything has finished uploading, you will - be asked to confirm the navigation - -.. _edit_library: - -Editing a Library ------------------ - -To change details about a library: - -- Navigate to ``https://your-instance/content/libraries`` or click on the upload icon in the sidebar and - click on "Get Started" under the "Upload third-party content in a library" section -- Click "Detail" under the library you wish to edit -- Select "Edit" from the menu that appears -- In the edit menu, you will be able to change the name, description, and visibility of your library -- Make the changes you wish to make, then select "Update library" to save the changes - -.. _delete_library: - -Deleting a Library ------------------- - -.. warning:: - - Deleting a library will also delete any content within the library. Make sure that content is backed up before continuing. - -To delete a library: - -- Navigate to ``https://your-instance/content/libraries`` or click on the upload icon in the sidebar and - click on "Get Started" under the "Upload third-party content in a library" section -- Click "Detail" under the library you wish to edit -- Select "Edit" from the menu that appears -- Select "Delete" from the bottom of the menu. A pop up will appear warning of the consequences of deleting the library. If you want to continue, click "Delete library" - -.. _remove_content: - -Removing Content From a Library -------------------------------- - -.. warning:: - - Removing content from your library deletes the file from the server. Make sure you have a backup of any files you want to keep. - -To delete content from a library: - -- Navigate to ``https://your-instance/content/libraries`` or click on the upload icon in the sidebar and - click on "Get Started" under the "Upload third-party content in a library" section -- Click "Detail" under the library you wish to edit- Select "Tracks" from the menu that appears -- Select all tracks you wish to remove by selecting the checkboxes next to them -- In the "Actions" drop down menu, select "Delete" and click "Go". A pop up will appear warning of the consequences of deleting the library. If you want to continue, click "Launch" diff --git a/docs/users/playlists.rst b/docs/users/playlists.rst deleted file mode 100644 index 8ab8fab74..000000000 --- a/docs/users/playlists.rst +++ /dev/null @@ -1,123 +0,0 @@ -Creating and Managing Playlists -=============================== - -Playlists are an important part of any music collection, and Funkwhale is no different. Funkwhale -allows you to create playlists for yourself, for other users on your server, or for the entire federated -network. - -Creating a New Playlist ------------------------ - -Once you've :doc:`uploaded some content to your instance `, or have -:doc:`followed some public libraries of your choosing `, you can get -started creating new playlists. - -To create a playlist: - -- Click on "Playlists" under the "Music" section on the left-hand side -- A pop-up will appear listing any of your existing playlists -- Enter a name for your playlist under the "Playlist name" section -- Choose a visibility setting: - - - **Nobody except me**: The playlist will be hidden from all users of the instance - - **Everyone on this instance**: The playlist will be visible to local accounts, but not to external users - - **Everyone**: The playlist will be public - -- Click "Create Playlist" to commit your changes - -.. note:: - - If you create a public library with non-public content, users will be able to see all tracks but - will only be able to play those that are accessible by them. - -Add Content to Playlist ------------------------ - -Now that you've created your playlist, you need to put some music in it. Music can be added in a -few different ways: - -Add Currently Playing Song -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To add the currently playing song to a playlist: - -- On the player at the bottom left of the screen, select the list icon to bring up the playlists pop-up -- Find the playlist you would like to add the song to and click "Add track" -- The changes will be saved automatically. Click "Stop Editing" to stop editing the playlist - -Add Music From Library -^^^^^^^^^^^^^^^^^^^^^^^^^ - -To add tracks from anywhere in Funkwhale: - -- Search for the song or album you want to add to the playlist in the Search menu -- Next to the song in question, you will see a list icon. Click on this to bring up the playlists pop-up -- Find the playlist you would like to add the song to -- The changes will be saved automatically. Click "Stop Editing" to stop editing the playlist - -Add Music From Queue -^^^^^^^^^^^^^^^^^^^^^^^ - -To store the music that is currently in your queue: - -- Click on "Playlists" under the "Music" section on the left-hand side -- A pop-up will appear listing any of your existing playlists -- Click on the playlist you want to add your content to -- In the window that appears, select "Edit" to start a new edition -- In the "Playlist editor" that appears, select "Insert from Queue" to add all content -- The changes will be saved automatically. Click "Stop Editing" to stop editing the playlist - -Edit Playlist Contents ----------------------- - -Delete Music From Playlist -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To remove a song or songs from a playlist: - -- Click on "Playlists" under the "Music" section on the left-hand side -- A pop-up will appear listing any of your existing playlists -- Click on the playlist you want to remove content from -- In the window that appears, select "Edit" to start a new edition -- For any track you want to remove, click on the red trash can icon on the right-hand side -- To remove all tracks at once, click "Clear Playlist" -- The changes will save automatically. Click "Stop Editing" to stop editing the playlist - -Reorder Music in a Playlist -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To change the order of songs in a playlist: - -- Click on "Playlists" under the "Music" section on the left-hand side -- A pop-up will appear listing any of your existing playlists -- Click on the playlist you want to reorder -- In the window that appears, select "Edit" to start a new edition -- Drag the songs into the new order you want to store them in -- The changes will save automatically. Click "Stop Editing" to stop editing the playlist - -Edit Playlist Settings ----------------------- - -If you want to change the name or visibility of a playlist, you will need to edit the playlist's settings. - -- Click on "Playlists" under the "Music" section on the left-hand side -- A pop-up will appear listing any of your existing playlists -- Click on the playlist you want to add your content to -- In the window that appears, select "Edit" to start a new edition -- Change the "Playlist name" or "Playlist visibility" to their new values -- Click "Update playlist" to commit your changes -- Click "Stop Editing" to stop editing the playlist - -Delete a Playlist ------------------ - -.. warning:: - - Deleting a playlist is permanent and will remove access for all other users. Only do this if you're sure you want to! - -To delete a playlist: - -- Click on "Playlists" under the "Music" section on the left-hand side -- A pop-up will appear listing any of your existing playlists -- Click on the playlist you want to delete -- Click on "Delete". A pop-up will appear warning you that this action is permanent. If you wish to continue, select "Delete playlist" diff --git a/docs/users/queue.rst b/docs/users/queue.rst deleted file mode 100644 index 4a21fb113..000000000 --- a/docs/users/queue.rst +++ /dev/null @@ -1,63 +0,0 @@ -Managing Your Queue -=================== -Your queue is where you can add tracks to queue them up for listening, arrange music to create a curated list, -and even :doc:`save a list as a playlist `. - -Add Tracks to Your Queue ------------------------- - -There are four options to choose from when adding music to a queue: - -- **Play** - this will start playing the selected item(s) immediately, stopping any currently playing tracks -- **Add to queue** - this adds the selected item(s) to the bottom of the queue. If the queue is empty, it will add them but not start playing -- **Play next** - this adds the selected item(s) just underneath the currently selected track in the queue -- **Play now** - this acts the same as "Play" - -Add a Song to the Queue -^^^^^^^^^^^^^^^^^^^^^^^ - -To add an individual track to the queue: - -- Search for a track, or navigate to its album page in the library -- Click on the track you want to add to bring up its information page -- Click on the down arrow next to "Play" and select "Add to Queue", "Play Next", or "Play Now" - -Add an Album to the Queue -^^^^^^^^^^^^^^^^^^^^^^^^^ - -To add a whole album to the queue: - -- Search for an album, or navigate to its album page in the library -- Click on the down arrow next to "Play" and select "Add to Queue", "Play Next", or "Play Now" - -Add a Playlist to the Queue -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To add a playlist to the queue: - -- Navigate to ``https://your-instance/library/playlists`` or click on "Browse" in the "Music" library on the left-hand side then select "Playlists" along the top -- Find the playlist you wish to add -- Click on the three dot menu to "Play" and select "Add to Queue", "Play Next", or "Play Now" - -Rearrange Tracks in Your Queue ------------------------------- - -To change the order of tracks in a queue - -- Open your queue by clicking on "Queue" underneath the search bar -- Find the track you want to move and click on the number on the left hand side -- Hold and drag the track to the position you want it in -- Release the mouse button to drop the track in place - -Remove Tracks From Your Queue ------------------------------ - -.. note:: - - If you remove the currently playing track from your queue, Funkwhale will automatically start playing the next - item in the queue - -To remove tracks from your queue: - -- Open your queue by clicking on "Queue" underneath the search bar -- Find the item you want to remove and click on the trash can icon to remove it diff --git a/docs/users/radios.rst b/docs/users/radios.rst deleted file mode 100644 index e31878a88..000000000 --- a/docs/users/radios.rst +++ /dev/null @@ -1,50 +0,0 @@ - -Using Radios -============ - -Radios are a great way to discover new music, or even just create a dynamic playlist of songs you like. -By default, all users have access to three build-in radios: - -- **Favorites** - this plays through your :doc:`favorite tracks ` -- **Random** - plays random songs from your :doc:`libraries ` or :doc:`libraries you follow ` -- **Less Listened** - plays songs you listen to less frequently - -Creating a New Radio --------------------- - -.. note:: - - Any music that is in a private collection will appear in public radios but will not be playable unless the user has access to - the containing library - -In addition to the built-in radios, Funkwhale offers users the ability to create their own specific radios. -These radios can be shared with other users on your instance or kept entirely to yourself. - -To create a new radio: - -- Navigate to ``https://your-instance/library/radios`` or click "Browse Library" and select "Radios" along the top of the screen -- Under "User Radios", click "Create your own radio" -- Give your radio a name and description -- If you want to share your radio on your instance, check the "Display publicly" box. Otherwise, uncheck this to keep the radio private -- To set up the filters for your radio, click on "Select a filter" and select "Artist" or "Tag" from the drop-down menu. Click "Add Filter" - to activate the filter -- To exclude certain artists or tags, toggle the "Exclude" switch so it turns blue and then select values from the drop-down - menu -- To only include certain artists or tags, toggle the "Exclude" switch so it turns gray and then select values from the - drop-down menu -- Click "Save" to save your radio - -Listening to a Radio --------------------- - -To start listening to a radio: - -- Navigate to ``https://your-instance/library/radios`` or click "Browse Library" and select "Radios" along the top of the screen -- Find the radio you want to listen to and click on "Play radio" -- Your queue will be populated with the **currently playing** song and the **next song on the radio** - -To stop listening to a radio: - -- Open your :doc:`queue` -- Select "Stop Radio" at the bottom of the queue -- The songs that were queued will stay in your queue, but the radio will stop queueing new songs \ No newline at end of file diff --git a/docs/users/reports.rst b/docs/users/reports.rst deleted file mode 100644 index 802405171..000000000 --- a/docs/users/reports.rst +++ /dev/null @@ -1,54 +0,0 @@ -Reporting content and accounts -============================== - -Funkwhale includes a report feature you can use to contact your pod's moderators. - -If you think some action, such as removal, should be taken toward an account or specific content (like an artist or a library), we encourage you to use -this feature. This is especially recommended if you find illegal or abusive content, or anything that could be an infraction of your pod's rules. - -After submission, your pod moderators will be notified and will be able to :doc:`act on your report `. - -Submit a report ---------------- - -You can submit those reports from various places in the app, depending on what you are reporting (see below). - -You'll need to pick a category for your report. Available categories are: - -- **Takedown request**: to request removal of copyrighted material -- **Illegal content**: to report an account, track, album, artist, library, playlist or account that features illegal content -- **Offensive content**: to report an account, track, album, artist, library, playlist or account that features offensive or abusive content -- **Invalid metadata**: to report a track, album or artist with invalid or incomplete metadata -- **Other**: to report anything else that doesn't fit into one of these categories - -You can also include with your report an additional explanation to ensure moderators can understand and act on the issue. - -Accountless reports -------------------- - -If this feature is enabled on the pod you are browsing, you'll be able to submit reports without an account. - -This works exactly the same, but the report form will have an extra "email" field where you should include a working -e-mail address, in the event moderators need to contact you. - -Reporting an account --------------------- - -Accounts can be reported in two ways. - -- When viewing user activity, such as favorites or listening history, the dropdown menu next to the corresponding activity will include an option to report the account -- When viewing a library the dropdown menu in the top right corner will include an option to report the corresponding account - -Reporting an artist, playlist, album or track ---------------------------------------------- - -Anything you can play can typically be reported using the dropdown menu on the "Play" button. - -Additionally, when viewing the detail page of an artist, playlist, album or track, you can find the -report option under the dropdown menu on the "More…" button. - - -Reporting a library -------------------- - -When viewing a library the dropdown menu in the top right corner will include an option to report the library. diff --git a/docs/users/tagging.rst b/docs/users/tagging.rst deleted file mode 100644 index f02143ffc..000000000 --- a/docs/users/tagging.rst +++ /dev/null @@ -1,61 +0,0 @@ -Tagging Music With MusicBrainz Picard -===================================== - -In order to get the most out of Funkwhale, it is important to tag files correctly. Good tagging makes managing your library much easier and provides Funkwhale with the information necessary to display album art, metadata, and other useful information. The recommended tool for tagging music is `MusicBrainz Picard `_. - -In addition to using an external tagging service, tags can be applied :doc:`directly in Funkwhale `. - -Tagging Items --------------- - -Tagging a File -^^^^^^^^^^^^^^ - -To load a file into MusicBrainz Picard: - -* Click on "Add Files" -* Select the files you want to tag from your computer -* Picard should automatically start scanning the items. If nothing happens, select the item(s) and click on "Scan" -* Picard will start assigning suitable tags -* Hit ctrl+s or click "Save" to save the tags to the file - -Tagging a Directory -^^^^^^^^^^^^^^^^^^^ - -* Click on "Add Folder" -* Select the directory of files you want to tag from your computer -* Picard should automatically start scanning the items. If nothing happens, select the item(s) and click on "Scan" -* Picard will start assigning suitable tags -* Hit ctrl+s or click "Save" to save the tags to the file - - -Alternative Versions --------------------- - -Picard is generally accurate when it comes to determining the release of an album/track, but sometimes it can fail to get the right version. You can force it to use a particular version of an album or track using the following method: - -Alternative Albums -^^^^^^^^^^^^^^^^^^ - -* Load the directory into Picard -* Once it has tagged the full album, right-click on the album and hover over "other versions" -* Select the collect release from the list -* Do this for any duplicate items until all tracks are under the correct release -* Hit ctrl+s or click "Save" to save the tags to the files - -Alternative Tracks -^^^^^^^^^^^^^^^^^^ - -If a track is not picking up its release, do the following: - -* Right-click on the offending track and select "Search for Similar Tracks..." -* Search for your release using `MusicBrainz's search syntax `_ -* Select the correct track from the list and click on "Load into Picard" -* The track will now inherit tags from the selected track. Hit ctrl+s or click "Save" to save the tags to the file - -Adding Items to MusicBrainz ---------------------------- - -MusicBrainz is an ever-growing library of music, but it may not yet have an entry for certain items. You can add these yourself by following their `guide `_. - -Once you've added a new item, Picard should automatically pick up the new details based on the files' metadata. This means that it will tag the music not only for you, but for any other user who tries to tag the same item in the future. diff --git a/docs/users/troubleshooting.rst b/docs/users/troubleshooting.rst deleted file mode 100644 index 57e09cd2e..000000000 --- a/docs/users/troubleshooting.rst +++ /dev/null @@ -1,107 +0,0 @@ -End-User Troubleshooting -======================== - -Various errors and issues can arise on your Funkwhale instance, caused by configuration errors, -deployment/environment specific issues, or bugs in the software itself. - -On this document, you'll find: - -- Tools and commands you can use to better understand the issues -- A list of common pitfalls and errors and how to solve them -- A collection of links and advice to get help from the community and report new issues - -Diagnose problems -^^^^^^^^^^^^^^^^^ - -Funkwhale is made of several components, each one being a potential cause for failure. Having an even basic overview -of Funkwhale's technical architecture can help you understand what is going on. You can refer to :doc:`the technical architecture <../developers/architecture>` for that. - -Problems usually fall into one of those categories: - -- **Frontend**: Funkwhale's interface is not loading, not behaving as expected, music is not playing -- **API**: the interface do not display any data or show errors -- **Import**: uploaded/imported tracks are not imported correctly or at all -- **Federation**: you cannot contact other Funkwhale servers, access their library, play federated tracks -- **Everything else** - -Each category comes with its own set of diagnose tools and/or commands we will detail below. We'll also give you simple -steps for each type of problem. Please try those to see if it fix your issues. If none of those works, please report your issue on our -issue tracker. - -Frontend issues -^^^^^^^^^^^^^^^ - -Diagnostic tools: - -- Javascript and network logs from your browser console (see instructions on how to open it in `Chrome `_ and `Firefox `_ -- Proxy and API access and error logs -- The same operation works from a different browser - -Common problems -*************** - -The front-end is completely blank -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You are visiting Funkwhale, but you don't see anything. - -- Try from a different browser -- Check network errors in your browser console. If you see responses with 40X or 50X statuses, there is probably an issue with the webserver configuration -- If you don't see anything wrong in the network console, check the Javascript console -- Disable your browser extensions (like adblockers) - -Music is not playing -~~~~~~~~~~~~~~~~~~~~ - -You have some tracks in your queue that don't play, or the queue is jumping from one track to the next until -there is no more track available: - -- Try with other tracks. If it works with some tracks but not other tracks, this may means that the failing tracks are not probably imported - or that your browser does not support a specific audio format -- Check the network and javascript console for potential errors - -Tracks are not appending to the queue -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When clicking on "Play", "Play all albums" or "Play all" buttons, some tracks are not appended to the queue. This is -actually a feature of Funkwhale: those tracks have no file associated with them, so we cannot play them. - -Specific pages are loading forever or blank -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When viewing a given page, the page load never ends (you continue to see the spinner), or nothing seems to appear at all: - -- Ensure your internet connection is up and running -- Ensure your instance is up and running -- Check the network and javascript console for potential errors - -Report an issue or get help -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Well be more than happy to help you to debug installation and configuration issues. The main channel -for receiving support about your Funkwhale installation is the `#funkwhale-troubleshooting:matrix.org `_ Matrix channel. - -Before asking for help, we'd really appreciate if you took the time to go through this document and try to diagnose the problem yourself. But if you don't find -anything relevant or don't have the time, we'll be there for you! - -Here are a few recommendations on how to structure and what to include in your help requests: - -- Give us as much context as possible about your installation (OS, version, Docker/non-docker, reverse-proxy type, relevant logs and errors, etc.) -- Including screenshots or small gifs or videos can help us considerably when debugging front-end issues - -You can also open issues on our `issue tracker `_. Please have a quick look for -similar issues before doing that, and use the issue tracker only to report bugs, suggest enhancements (both in the software and the documentation) or new features. - -.. warning:: - - If you ever need to share screenshots or urls with someone else, ensure those do not include your personal token. - This token is binded to your account and can be used to connect and use your account. - - Urls that includes your token looks like: ``https://your.instance/api/v1/uploads/42/serve/?jwt=yoursecrettoken`` - -Improving this documentation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you feel like something should be improved in this document (and in the documentation in general), feel free to :doc:`contribute to the documentation <../documentation/creating>`. -If you're not comfortable contributing or would like to ask somebody else to do it, feel free to :doc:`request a change in documentation <../documentation/identifying>`. - diff --git a/docs/users/upload.rst b/docs/users/upload.rst deleted file mode 100644 index 6e67cde2f..000000000 --- a/docs/users/upload.rst +++ /dev/null @@ -1,172 +0,0 @@ -Uploading Content To Funkwhale -============================== - -To upload content to any Funkwhale instance, you need: - -1. :doc:`An account on that instance `; -2. :ref:`Storage space `; -3. :ref:`A library ` or :ref:`channel `; -4. :ref:`Properly tagged files `; -5. To upload your files :ref:`to a library ` or :ref:`to a channel `. - -.. _upload-storage: - -Storage space -------------- - -Once you have an account on a Funkwhale instance, as a user, you are granted the -default upload quota (1GB by default). This default quota can be increased, -reduced or completely removed by your instance admins depending on their policy. - -Additionally, instance admins can grant you storage space manually. Get in touch with them -if you'd like some additional storage space. - -You can view your current quota and usage at any time by visiting ``/content/libraries/`` on your instance, -or clicking the "Add content" link in the sidebar, then visiting the "Upload audio content" section. - -.. _upload-channel: - -Using a Channel ---------------- - -A channel is a collection of content that is published directly to funkwhale. Channels are always public -and can be followed from different fediverse software such as Mastodon, Reel2Bits or other Funkwhale -pods. - -There are two types of channel: - -- A podcast channel -- An artist discography channel - -See :doc:`channels` for more information on channels. - -.. _upload-library: - -Using a library ---------------- - -In Funkwhale's world, a library is a collection of audio files with an associated visibility level. A library can be: - -- Public: anyone can follow the library to automatically access its content (including users on other instances) -- Local: other users from your instance can follow the library to automatically access its content -- Private: nobody apart from you can access the library content - -Regardless of visibility settings, you can share the library link to specific users -and accept their follow request in order to grant then access to its content. Typically, this -is useful when you have a private library you want to share with friends or family. - -Before you upload your content, you need to know the content audience and license: - -- If the content is under an open license (like Creative Commons licenses), it's usually fine to upload it in a public library -- If you are uploading content purchased from other platforms or stores, you should upload it in a private library - -.. note:: - - As a rule of thumb, only use public and local libraries for content for which you own the copyright or for content you know you can share with a wider audience. - -See :doc:`libraries ` for more information on libraries. - -.. _upload-tagging: - -Tagging files -------------- - -Funkwhale relies on embedded file metadata (also known as tags) to infer the artist, -album and track associated with a given upload. Most stores and platforms include -those tags by default, but it's possible the tags are missing or incomplete, in which case -Funkwhale will not be able to process the upload and display an error. - -The minimum required tags are: - -- Title -- Artist -- Album - -However, Funkwhale can understand and use additional tags to enhance user experience and display more information. The full list of supported tags is available below: - -+----------------------------------+--------------------------------------------+---------------------------------------------------------------+ -| Name | Example value | Description | -+----------------------------------+--------------------------------------------+---------------------------------------------------------------+ -| ``Title`` (required) | ``Letting you`` | The track title | -| | | | -+----------------------------------+--------------------------------------------+---------------------------------------------------------------+ -| ``Artist`` (required) | ``Nine Inch Nails`` | The artist name | -| | | | -+----------------------------------+--------------------------------------------+---------------------------------------------------------------+ -| ``Album`` | ``The Slip`` | The album title. If none is provided, an [Unknown Album] | -| | | entry will be created | -+----------------------------------+--------------------------------------------+---------------------------------------------------------------+ -| ``Album artist`` | ``Trent Reznor`` | The album artist name (can be different than the track | -| | | artist) | -| | | | -+----------------------------------+--------------------------------------------+---------------------------------------------------------------+ -| ``Genre`` | ``Industrial, Metal`` | A comma separated list of tags to associate with the track | -| | | Other supported separators: ``;`` and ``/`` | -+----------------------------------+--------------------------------------------+---------------------------------------------------------------+ -| ``Track number`` | ``4`` | The position of the track in the album/release | -| | | | -+----------------------------------+--------------------------------------------+---------------------------------------------------------------+ -| ``Disc number`` | ``1`` | The disc number (in case of multi-disc albums) | -| | | | -+----------------------------------+--------------------------------------------+---------------------------------------------------------------+ -| ``Date`` | ``2019`` | The release date of the track or album | -| | | | -| | | | -+----------------------------------+--------------------------------------------+---------------------------------------------------------------+ -| ``License`` | ``CC-BY 3.0: http://creativecommons | The license associated with this work. The first found URL | -| | .org/licenses/cc-by/3.0/`` | will be checked against `our list of supported licenses`_ | -| | | | -+----------------------------------+--------------------------------------------+---------------------------------------------------------------+ -| ``Copyright`` | ``CC-BY 3.0: http://creativecommons | The license associated with this work. The first found URL | -| | .org/licenses/cc-by/3.0/`` | will be checked against `our list of supported licenses`_. | -| | | Used if no license found in the License tag | -| | | | -+----------------------------------+--------------------------------------------+---------------------------------------------------------------+ -| ``Pictures`` | | The first embeded picture found will be used as the album | -| | | covers | -| | | | -+----------------------------------+--------------------------------------------+---------------------------------------------------------------+ -| ``MusicBrainz Recording ID`` | ``99244237-850b-4a93-904d-57305bcadb4e`` | The MusicBrainz ID for this recording | -| | | | -+----------------------------------+--------------------------------------------+---------------------------------------------------------------+ -| ``MusicBrainz Album ID`` | ``bca982fd-ab73-3c9f-ad07-9104a4f53a32`` | The MusicBrainz ID for this album | -| | | | -+----------------------------------+--------------------------------------------+---------------------------------------------------------------+ -| ``MusicBrainz Artist ID`` | ``b7ffd2af-418f-4be2-bdd1-22f8b48613da`` | The MusicBrainz ID for this artist | -| | | | -+----------------------------------+--------------------------------------------+---------------------------------------------------------------+ -| ``MusicBrainz Album Artist ID`` | ``b7ffd2af-418f-4be2-bdd1-22f8b48613da`` | The MusicBrainz ID for this album artist | -+----------------------------------+--------------------------------------------+---------------------------------------------------------------+ - -.. _our list of supported licenses: https://dev.funkwhale.audio/funkwhale/funkwhale/blob/develop/api/tests/music/licenses.json - -The easiest way to inspect and edit file tags is with `MusicBrainz Picard `_, a free -software, that works on Windows, MacOS and Linux. Picard is able to automatically tag many files, -and include non-necessary but nice to have information, such as album covers. For a guide on tagging content with Picard, -see :doc:`tagging`. - -Common errors during import ---------------------------- - -.. _invalid_metadata: - -Invalid metadata -:::::::::::::::: - -This error occurs when the uploaded file miss some mandatory tags, or when some tags have -incorrect values (e.g an empty title or artist name). - -To fix this issue, please retag the file properly as described in :ref:`upload-tagging` -and reupload it. - - -.. _unknown_error: - -Unknown error -::::::::::::: - -This error can happen for multiple reasons and likely indicates an issue with the Funkwhale -server (e.g. misconfiguration) or with Funkwhale itself. - -If the issue persists when you relaunch the import, get in touch with our instance admin -or open a support thread on our forum.