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
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
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"
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
@@ -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>`.