novaburst/funquail
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Overhaul end user documentation

Browse source
This commit is contained in:
Ciarán Ainsworth 2022-01-19 18:49:46 +00:00
commit 1ec7e1e8e5
97 changed files with 3240 additions and 1553 deletions
Download patch file Download diff file Expand all files Collapse all files

51
docs/user_documentation/libraries/create_library.md Normal file
View file

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

41
docs/user_documentation/libraries/delete_content.md Normal file
View file

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

35
docs/user_documentation/libraries/delete_library.md Normal file
View file

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

136
docs/user_documentation/libraries/edit_content.md Normal file
View file

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

37
docs/user_documentation/libraries/edit_library.md Normal file
View file

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

50
docs/user_documentation/libraries/follow_library.md Normal file
View file

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

45
docs/user_documentation/libraries/index.md Normal file
View file

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

51
docs/user_documentation/libraries/share_library.md Normal file
View file

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

71
docs/user_documentation/libraries/tag_music.md Normal file
View file

@ -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.<br><br>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. <br><br>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.

36
docs/user_documentation/libraries/upload_content.md Normal file
View file

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