upload.rst 11.9 KB
Newer Older
1 2
Uploading Content To Funkwhale
==============================
Agate's avatar
Agate committed
3

4
To upload content to any Funkwhale instance, you need:
Agate's avatar
Agate committed
5

6
1. :doc:`An account on that instance <create>`
Agate's avatar
Agate committed
7
2. :ref:`Storage space <upload-storage>`
8
3. :ref:`A library <upload-library>` or :ref:`channel <upload-channel>`
Agate's avatar
Agate committed
9 10 11 12 13 14 15 16 17 18 19 20
4. :ref:`Properly tagged files <upload-tagging>`
5. :ref:`To upload your files <upload-upload>`

.. _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.

21
Additionally, instance admins can grant you storage space manually. Get in touch with them
22
if you'd like some additional storage space.
Agate's avatar
Agate committed
23 24 25 26

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.

27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42
.. _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.
  
Agate's avatar
Agate committed
43 44
.. _upload-library:

45 46
Using a library
---------------
Agate's avatar
Agate committed
47

48
In Funkwhale's world, a library is a collection of audio files with an associated visibility level. A library can be:
Agate's avatar
Agate committed
49 50 51

- 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
52
- Private: nobody apart from you can access the library content
Agate's avatar
Agate committed
53

54
Regardless of visibility settings, you can share the library link to specific users
Agate's avatar
Agate committed
55 56 57 58 59 60 61 62 63 64 65 66
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.

67 68
See :doc:`libraries <managing>` for more information on libraries.

Agate's avatar
Agate committed
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84
.. _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

85
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:
Agate's avatar
Agate committed
86 87 88 89 90 91 92 93 94 95

+----------------------------------+--------------------------------------------+---------------------------------------------------------------+
| Name                             | Example value                              | Description                                                   |
+----------------------------------+--------------------------------------------+---------------------------------------------------------------+
| ``Title`` (required)             | ``Letting you``                            | The track title                                               |
|                                  |                                            |                                                               |
+----------------------------------+--------------------------------------------+---------------------------------------------------------------+
| ``Artist`` (required)            | ``Nine Inch Nails``                        | The artist name                                               |
|                                  |                                            |                                                               |
+----------------------------------+--------------------------------------------+---------------------------------------------------------------+
96 97 98
| ``Album``                        | ``The Slip``                               | The album title. If none is provided, an [Unknown Album]     |
|                                  |                                            | entry will be created                                         |
+----------------------------------+--------------------------------------------+---------------------------------------------------------------+
Agate's avatar
Agate committed
99 100 101 102
| ``Album artist``                 | ``Trent Reznor``                           | The album artist name (can be different than the track        |
|                                  |                                            | artist)                                                       |
|                                  |                                            |                                                               |
+----------------------------------+--------------------------------------------+---------------------------------------------------------------+
103 104 105
| ``Genre``                        | ``Industrial, Metal``                      | A comma separated list of tags to associate with the track     |
|                                  |                                            | Other supported separators: ``;`` and ``/``                   |
+----------------------------------+--------------------------------------------+---------------------------------------------------------------+
Agate's avatar
Agate committed
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144
| ``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 <https://picard.musicbrainz.org/>`_, a free
software, that works on Windows, MacOS and Linux. Picard is able to automatically tag many files,
145 146
and include non-necessary but nice to have information, such as album covers. For a guide on tagging content with Picard,
see :doc:`tagging`.
Agate's avatar
Agate committed
147

148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164
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:

Agate's avatar
Agate committed
165
Unknown error
166 167 168 169 170 171 172
:::::::::::::

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.