Commit 155b0249 authored by Ciarán Ainsworth's avatar Ciarán Ainsworth
Browse files

Updating documentation for 0.21 release

parent 59e91e76
Features
=========
========
Scope
------
-----
Funkwhale is a web based music server. It is similar in terms of goals and feature set to various existing projects, such as `Sonerezh <https://www.sonerezh.bzh/>`_ or `Airsonic <https://airsonic.github.io/>`_.
Funkwhale is a web based audio server. It is similar in terms of goals and feature set to various existing projects,
such as `Sonerezh <https://www.sonerezh.bzh/>`_ or `Airsonic <https://airsonic.github.io/>`_.
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 discover new content. While some of these features are not currently implemented, our roadmap includes:
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:
- Radios, to discover the music of a given user, artist, or genre
- Playlists
- Favorites
- Broadcasts, as they existed in, for example, Grooveshark
- Recommendations
Music acquisition
------------------
Funkwhale is not bundled with any music, and you'll have to import your own music into the platform.
At the moment, you can feed your existing music library to the server either by uploading it or by using :ref:`in-place-import` from a server-side directory. Assuming the files have the correct tags defined, they will be imported seamlessly.
Content acquisition
-------------------
You can also access music being made available by other Funkwhale instances using :doc:`/federation/index`.
Audio content is uploaded to Funkwhale by users to :doc:`libraries <users/managing>` or :doc:`channels <users/channels>`,
and admins, using a :ref:`server-side import from a directory <in-place-import>`. Content is also made available to
a pod by users following :doc:`libraries <users/follow>` and :doc:`channels <users/followchannel>`.
Metadata
---------
--------
In order to keep your library clean, browsable, and well-stocked with relevant data about artists, albums and tracks, we fetch a lot of metadata from the `MusicBrainz project <http://musicbrainz.org/>`_.
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 <http://musicbrainz.org/>`_. Music uploaded directly to Funkwhale can also be :doc:`tagged
and edited <users/editing>` in the app itself.
Structure
---------
......@@ -37,20 +37,18 @@ 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 Semantic UI
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.
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
----------
Each Funkwhale instance is able to fetch music from other compatible servers,
and share its own library on the network, in a process known as "federation".
Federation is implemented using the ActivityPub protocol, in order to leverage
existing tools and be compatible with other services such as Mastodon.
As of today, federation only targets music acquisition, meaning user
interactions are not shared via ActivityPub. This will be implemented at a later
point.
Funkwhale makes use of the `ActivityPub protocol <https://www.w3.org/TR/activitypub/>`_ to share activities
across the `fediverse <https://en.wikipedia.org/wiki/Fediverse>`_. In particular, content uploaded in :doc:`channels <users/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.
Using Funkwhale from other apps
===============================
As of today, the only official client for using Funkwhale is the web client,
the one you use in your browser.
The only official client for using Funkwhale is the web client, the one you use in your browser.
While the web client works okay, it's still not ready for some use cases, especially:
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 <https://en.wikipedia.org/wiki/Progressive_web_application>`_.
Using Funkwhale as a PWA gives the following benefits:
- Usage on narrow/touch screens (smartphones, tablets)
- Usage on the go, with an intermittent connection
- 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
This pages lists alternative clients you can use to connect to your Funkwhale
instance and enjoy your music.
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
......
Managing Channels
=================
Channels are a collection of audio files published directly on Funkwhale.
While :doc:`libraries <managing>` 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 <create_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 <channel_upload>`
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
......@@ -5,7 +5,7 @@ Before you can start using Funkwhale, you will need to set up an account on an i
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 informations such as version and enabled features can be found
A list of instances along with other useful information such as version and enabled features can be found
`here <https://network.funkwhale.audio/dashboards/d/overview/network-overview>`_. Servers marked with
"Open registrations" are available to sign up to.
......
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"
......@@ -16,6 +16,16 @@ To add a track to your favorites from your library:
- 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
^^^^^^^^^^^^^^^^^^^^^^
......
......@@ -33,13 +33,10 @@ Following Other Libraries
Once you've got the library link, you can start following the library by doing the following:
- Click on the "Add content" menu under "Music" on the left-hand side
- Under "Follow Remote Libraries", select "Get Started"
- In the search bar that appears, paste the library link of the library you wish to follow
- If the URL is valid, the name of the library will appear. Click "Follow" to start following the library
- Once your follow request is approved, the library will be scanned for content (this will be automatic for public libraries)
- Click on "Browse library" under "Music" on the left-hand side to return to the library overview
- The library content should now be visible and playable on your instance
- 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:
......@@ -54,7 +51,8 @@ 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 "Add Content" under the "Music" menu, select "Upload audio content", and click "Detail" under the library you want the code for
- Under the "Followers" tab, you will be able to see information about followers this library currently has. The sharing link will also be visible
- Click on "Copy" to copy the sharing link to your clipboard
- Depending on the visibility settings you have chosen for the library, you will need to approve follow requests for those with whom you share the 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
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 Funwkhale 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
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.
......@@ -13,6 +13,7 @@ Getting Started
create
tagging
upload
editing
Using Funkwhale
......@@ -24,9 +25,11 @@ Using Funkwhale
account
queue
managing
channels
playlists
favorites
radios
followchannel
follow
apps
reports
......
Managing Content and Libraries
==============================
Managing Libraries
==================
Managing your music libraries is an important part of using Funkwhale. In addition to :doc:`uploading new music <upload>`, you may also want to :ref:`edit your library's details <edit_library>`, :ref:`delete a library <delete_library>`, or :ref:`remove content from a library <remove_content>`.
If you are looking to publish content on Funkwhale directly, you can use :doc:`channels <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 <create_library>`, you can start adding files to it. Before you
upload files, it is a good idea to :doc:`tag them correctly <tagging>` 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 "Add Content" under the "Music" menu, select "Upload audio content", and click "Detail" under the library you wish to edit
- 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
......@@ -26,7 +77,9 @@ Deleting a Library
To delete a library:
- Navigate to ``https://your-instance/content/libraries`` or click "Add Content" under the "Music" menu, select "Upload audio content", and click "Detail" under the library you wish to edit
- 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"
......@@ -41,7 +94,8 @@ Removing Content From a Library
To delete content from a library:
- Navigate to ``https://your-instance/content/libraries`` or click "Add Content" under the "Music" menu, select "Upload audio content", and click "Detail" under the library you wish to edit
- Select "Tracks" from the menu that appears
- 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"
......@@ -18,9 +18,11 @@ To create a playlist:
- 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
- **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::
......
......@@ -8,10 +8,10 @@ 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"
- **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
^^^^^^^^^^^^^^^^^^^^^^^
......
......@@ -2,17 +2,12 @@
Using Radios
============
.. note::
Currently, Funkwhale does not implement tags for use in radios. There is a lot of active disucssion
around how to implement them, but in the meantime it is only possible to create artist 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 <favorites>`
- Random - plays random songs from your :doc:`libraries <upload>` or :doc:`libraries you follow <follow>`
- Less Listened - plays songs you listen to less frequently
- **Favorites** - this plays through your :doc:`favorite tracks <favorites>`
- **Random** - plays random songs from your :doc:`libraries <upload>` or :doc:`libraries you follow <follow>`
- **Less Listened** - plays songs you listen to less frequently
Creating a New Radio
--------------------
......@@ -31,9 +26,12 @@ To create a new radio:
- 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" from the drop-down menu. Click "Add Filter" to activate the filter
- To exclude certain artists, toggle the "Exclude" switch so it turns blue and then select the artists from the "Select artists" drop-down menu
- To only include certain artists, toggle the "Exclude" switch so it turns gray and then select the artists from the "Select artists" drop-down menu
- 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
......
......@@ -3,6 +3,8 @@ 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 <https://picard.musicbrainz.org/>`_.
In addition to using an external tagging service, tags can be applied :doc:`directly in Funkwhale <editing>`.
Tagging Items
--------------
......
......@@ -5,7 +5,7 @@ To upload content to any Funkwhale instance, you need:
1. :doc:`An account on that instance <create>`
2. :ref:`Storage space <upload-storage>`
3. :ref:`A library <upload-library>`
3. :ref:`A library <upload-library>` or :ref:`channel <upload-channel>`
4. :ref:`Properly tagged files <upload-tagging>`
5. :ref:`To upload your files <upload-upload>`
......@@ -24,10 +24,26 @@ 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.