From ff99f3c8586b2b6af6aa9152434b31c574f26b7c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Mon, 13 Apr 2020 20:48:34 +0100 Subject: [PATCH 01/13] Added initial documentation about channels --- docs/users/apps.rst | 19 +++--- docs/users/channels.rst | 119 +++++++++++++++++++++++++++++++++++ docs/users/followchannel.rst | 51 +++++++++++++++ docs/users/index.rst | 1 + docs/users/managing.rst | 68 +++++++++++++++++--- docs/users/upload.rst | 56 +++++++---------- 6 files changed, 265 insertions(+), 49 deletions(-) create mode 100644 docs/users/channels.rst create mode 100644 docs/users/followchannel.rst diff --git a/docs/users/apps.rst b/docs/users/apps.rst index 2eb6c6e44..1c8a93234 100644 --- a/docs/users/apps.rst +++ b/docs/users/apps.rst @@ -1,16 +1,21 @@ 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 `_. +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 diff --git a/docs/users/channels.rst b/docs/users/channels.rst new file mode 100644 index 000000000..76b66dcbd --- /dev/null +++ b/docs/users/channels.rst @@ -0,0 +1,119 @@ +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/followchannel.rst b/docs/users/followchannel.rst new file mode 100644 index 000000000..9919bf958 --- /dev/null +++ b/docs/users/followchannel.rst @@ -0,0 +1,51 @@ +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) +- 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) +- 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 index 557e90782..d17fc62d8 100644 --- a/docs/users/index.rst +++ b/docs/users/index.rst @@ -24,6 +24,7 @@ Using Funkwhale account queue managing + channels playlists favorites radios diff --git a/docs/users/managing.rst b/docs/users/managing.rst index c457f79e0..d2e23340c 100644 --- a/docs/users/managing.rst +++ b/docs/users/managing.rst @@ -1,16 +1,67 @@ -Managing Content and Libraries -============================== +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 +- 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 +- 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 +- 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 +- 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 +- 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/upload.rst b/docs/users/upload.rst index 68238ac18..872c2bcb7 100644 --- a/docs/users/upload.rst +++ b/docs/users/upload.rst @@ -5,7 +5,7 @@ To upload content to any Funkwhale instance, you need: 1. :doc:`An account on that instance ` 2. :ref:`Storage space ` -3. :ref:`A library ` +3. :ref:`A library ` or :ref:`channel ` 4. :ref:`Properly tagged files ` 5. :ref:`To upload your files ` @@ -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. + .. _upload-library: -Creating a 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: @@ -39,8 +55,6 @@ Regardless of visibility settings, you can share the library link to specific us 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. -You can create your first library by visiting ``/content/libraries/`` or clicking the "Add content" link in the sidebar, then visiting the "Upload audio content" section. - 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 @@ -50,6 +64,8 @@ Before you upload your content, you need to know the content audience and licens 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 @@ -129,36 +145,6 @@ software, that works on Windows, MacOS and Linux. Picard is able to automaticall and include non-necessary but nice to have information, such as album covers. For a guide on tagging content with Picard, see :doc:`tagging`. -.. _upload-upload: - -Uploading your files --------------------- - -Once you've chose the library and have properly tagged files, you can start the actual upload. -Simply visit ``/content/libraries/`` or click the "Add content" link in the sidebar, then visit the "Upload audio content" section. Click on -the "Upload" button next to the library of your choice, and follow the instructions. - -You can queue as many files as you want for the upload, simply leave your browser window open on the upload page -until all files are uploaded. - -By default, Funkwhale accepts files up to 100MB in size, but this limit can be increased or reduced -by instance admins. - -Once uploaded, your files should be processed shortly. It's usually a matter of seconds, but -can vary depending on server load. - -.. _upload-remove: - -Removing files --------------- - -If you want to remove some of the files you have uploaded, visit ``/content/libraries/tracks/`` or click "Add content" in the sidebar then "Tracks" in the top menu. -Then select the files you want to delete using the checkboxes on the left ; you can filter the list of files using a search pattern. -Finally, select "Delete" in the "Action" menu and click "Go". - -This operation does *not* remove metadata, meaning that deleted tracks will remain visible in your library. They just won't be playable anymore. - - Common errors during import --------------------------- -- GitLab From fb853d2abda5ffa5c99ffac1de66403c5580c858 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Mon, 13 Apr 2020 23:31:57 +0100 Subject: [PATCH 02/13] Set up env document --- docs/admin/configuration.rst | 3 ++- docs/admin/env.rst | 6 ++++++ docs/admin/index.rst | 1 + 3 files changed, 9 insertions(+), 1 deletion(-) create mode 100644 docs/admin/env.rst diff --git a/docs/admin/configuration.rst b/docs/admin/configuration.rst index c2bbd5f9f..26e1a9ca4 100644 --- a/docs/admin/configuration.rst +++ b/docs/admin/configuration.rst @@ -15,7 +15,8 @@ during installation. A full list of available variables can be seen :ref:`below `. Options from this file are heavily commented, and usually target lower level -and technical aspects of your instance, such as database credentials. +and technical aspects of your instance, such as database credentials. A full +list of these variables can be found :doc:`here `. .. note:: diff --git a/docs/admin/env.rst b/docs/admin/env.rst new file mode 100644 index 000000000..890a8f248 --- /dev/null +++ b/docs/admin/env.rst @@ -0,0 +1,6 @@ +Environment Variables +===================== + +The `.env` file holds several configurable variables which can be used to customize your pod's +setup. + diff --git a/docs/admin/index.rst b/docs/admin/index.rst index 3ce9683c6..cfaef85ee 100644 --- a/docs/admin/index.rst +++ b/docs/admin/index.rst @@ -13,6 +13,7 @@ Setup Guides ../installation/index configuration + env importing-music external-storages migration -- GitLab From b74f610ea088e157cad79e49b89ff0f5f52d1f34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Mon, 20 Apr 2020 12:21:40 +0100 Subject: [PATCH 03/13] Removed separate env docs (see !1095) --- docs/admin/env.rst | 6 ------ docs/admin/index.rst | 1 - 2 files changed, 7 deletions(-) delete mode 100644 docs/admin/env.rst diff --git a/docs/admin/env.rst b/docs/admin/env.rst deleted file mode 100644 index 890a8f248..000000000 --- a/docs/admin/env.rst +++ /dev/null @@ -1,6 +0,0 @@ -Environment Variables -===================== - -The `.env` file holds several configurable variables which can be used to customize your pod's -setup. - diff --git a/docs/admin/index.rst b/docs/admin/index.rst index cfaef85ee..3ce9683c6 100644 --- a/docs/admin/index.rst +++ b/docs/admin/index.rst @@ -13,7 +13,6 @@ Setup Guides ../installation/index configuration - env importing-music external-storages migration -- GitLab From 6c9d553e60015ca24c37fe72821f5ed6cac9b1ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Mon, 20 Apr 2020 12:50:28 +0100 Subject: [PATCH 04/13] Removed reference to .env file --- docs/admin/configuration.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/admin/configuration.rst b/docs/admin/configuration.rst index 26e1a9ca4..c2bbd5f9f 100644 --- a/docs/admin/configuration.rst +++ b/docs/admin/configuration.rst @@ -15,8 +15,7 @@ during installation. A full list of available variables can be seen :ref:`below `. Options from this file are heavily commented, and usually target lower level -and technical aspects of your instance, such as database credentials. A full -list of these variables can be found :doc:`here `. +and technical aspects of your instance, such as database credentials. .. note:: -- GitLab From 77e8aa5efa05911b8916c41dcde97a80ecdaf348 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Mon, 20 Apr 2020 13:06:50 +0100 Subject: [PATCH 05/13] Added info about URL following and updated index --- docs/users/followchannel.rst | 6 ++++-- docs/users/index.rst | 1 + 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/users/followchannel.rst b/docs/users/followchannel.rst index 9919bf958..258f340d0 100644 --- a/docs/users/followchannel.rst +++ b/docs/users/followchannel.rst @@ -16,7 +16,8 @@ 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) +- 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 @@ -25,7 +26,8 @@ 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) +- 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 diff --git a/docs/users/index.rst b/docs/users/index.rst index d17fc62d8..cc21e231c 100644 --- a/docs/users/index.rst +++ b/docs/users/index.rst @@ -28,6 +28,7 @@ Using Funkwhale playlists favorites radios + followchannel follow apps reports -- GitLab From 2b6ae2e4430edf603d496aa2c12f6b82aa836df6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Mon, 20 Apr 2020 13:32:15 +0100 Subject: [PATCH 06/13] Updated library follow guide, added info about editing items --- docs/users/editing.rst | 80 ++++++++++++++++++++++++++++++++++++ docs/users/follow.rst | 20 ++++----- docs/users/followchannel.rst | 2 +- docs/users/tagging.rst | 2 + 4 files changed, 92 insertions(+), 12 deletions(-) create mode 100644 docs/users/editing.rst diff --git a/docs/users/editing.rst b/docs/users/editing.rst new file mode 100644 index 000000000..b99bf9782 --- /dev/null +++ b/docs/users/editing.rst @@ -0,0 +1,80 @@ +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/follow.rst b/docs/users/follow.rst index e7c0afc91..2d4d8a780 100644 --- a/docs/users/follow.rst +++ b/docs/users/follow.rst @@ -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 diff --git a/docs/users/followchannel.rst b/docs/users/followchannel.rst index 258f340d0..c235bdfc7 100644 --- a/docs/users/followchannel.rst +++ b/docs/users/followchannel.rst @@ -20,7 +20,7 @@ If you have the channel's full social network name: URL to the channel - Click "Subscribe" -Following Funwkhale Channels through the fediverse +Following Funwkhale Channels Through the Fediverse -------------------------------------------------- Funkwhale channels can be followed from different ActivityPub-enabled applications diff --git a/docs/users/tagging.rst b/docs/users/tagging.rst index f5276e503..a936fff00 100644 --- a/docs/users/tagging.rst +++ b/docs/users/tagging.rst @@ -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 `_. +In addition to using an external tagging service, tags can be applied :ref:`directly in Funkwhale `. + Tagging Items -------------- -- GitLab From 5a632edfd12164a664308c1d45c843445fb746be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Mon, 20 Apr 2020 13:33:50 +0100 Subject: [PATCH 07/13] Added editing section to navigation menu --- docs/users/index.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/users/index.rst b/docs/users/index.rst index cc21e231c..6b4360d54 100644 --- a/docs/users/index.rst +++ b/docs/users/index.rst @@ -1,5 +1,5 @@ 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 -- GitLab From 75709a66930eb90f6aaed85417ca8bc052ea4f30 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Mon, 20 Apr 2020 14:07:42 +0100 Subject: [PATCH 08/13] Improved wording --- docs/users/managing.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/users/managing.rst b/docs/users/managing.rst index d2e23340c..37b010e68 100644 --- a/docs/users/managing.rst +++ b/docs/users/managing.rst @@ -12,8 +12,8 @@ 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 -- Click on "Get Started" under the "Upload third-party content in a library" section +- 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: @@ -39,8 +39,8 @@ metadata associated with it. To upload content: -- Navigate to ``https://your-instance/content/libraries`` or click on the upload icon in the sidebar -- Click on "Get Started" under the "Upload third-party content in a library" section +- 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 @@ -59,8 +59,8 @@ 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 -- Click on "Get Started" under the "Upload third-party content in a library" section +- 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 @@ -77,8 +77,8 @@ Deleting a Library To delete a library: -- Navigate to ``https://your-instance/content/libraries`` or click on the upload icon in the sidebar -- Click on "Get Started" under the "Upload third-party content in a library" section +- 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" @@ -94,8 +94,8 @@ Removing Content From a Library To delete content from a library: -- Navigate to ``https://your-instance/content/libraries`` or click on the upload icon in the sidebar -- Click on "Get Started" under the "Upload third-party content in a library" section +- 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" -- GitLab From f8689626d0b0ba270002e7cb69043ef60e957a7d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Mon, 20 Apr 2020 14:30:26 +0100 Subject: [PATCH 09/13] Updated features page --- docs/features.rst | 50 +++++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 26 deletions(-) diff --git a/docs/features.rst b/docs/features.rst index 19f36da4e..a4c5bff24 100644 --- a/docs/features.rst +++ b/docs/features.rst @@ -1,35 +1,35 @@ 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 `_ or `Airsonic `_. +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 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 :docs:`libraries ` or :docs:`channels `, +and admins, using a :ref:`server-side import from a directory `. Content is also made available to +a pod by users following :docs:`libraries ` and :docs:`channels `. 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 `_. +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 --------- @@ -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 `_ to share activities +across the `fediverse `_. In particular, content uploaded in :docs:`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. -- GitLab From 3e1cd4f53f379d3a2ef158125fe72a4453e37cb2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Mon, 20 Apr 2020 14:34:47 +0100 Subject: [PATCH 10/13] Corrected links --- docs/features.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/features.rst b/docs/features.rst index a4c5bff24..c270fee81 100644 --- a/docs/features.rst +++ b/docs/features.rst @@ -20,16 +20,16 @@ our roadmap includes: Content acquisition ------------------- -Audio content is uploaded to Funkwhale by users to :docs:`libraries ` or :docs:`channels `, +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 :docs:`libraries ` and :docs:`channels `. +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. +and edited ` in the app itself. Structure --------- @@ -48,7 +48,7 @@ Federation ---------- Funkwhale makes use of the `ActivityPub protocol `_ to share activities -across the `fediverse `_. In particular, content uploaded in :docs:`channels ` +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. -- GitLab From 70e68d465c73b674f55a62278300b22bfc4a6ea8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Mon, 20 Apr 2020 14:48:13 +0100 Subject: [PATCH 11/13] Updated various interface changes/formatting --- docs/users/create.rst | 2 +- docs/users/favorites.rst | 11 +++++++++++ docs/users/playlists.rst | 8 +++++--- docs/users/queue.rst | 8 ++++---- docs/users/radios.rst | 20 +++++++++----------- docs/users/tagging.rst | 2 +- 6 files changed, 31 insertions(+), 20 deletions(-) diff --git a/docs/users/create.rst b/docs/users/create.rst index c185f4b24..0da138798 100644 --- a/docs/users/create.rst +++ b/docs/users/create.rst @@ -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 `_. Servers marked with "Open registrations" are available to sign up to. diff --git a/docs/users/favorites.rst b/docs/users/favorites.rst index 40d277ccf..1c663524a 100644 --- a/docs/users/favorites.rst +++ b/docs/users/favorites.rst @@ -16,6 +16,17 @@ 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 hear icon next to the Play button +- Once the white heart has turned pink, the track will be in your favorites list + + From Currently Playing ^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/users/playlists.rst b/docs/users/playlists.rst index bac20745e..8ab8fab74 100644 --- a/docs/users/playlists.rst +++ b/docs/users/playlists.rst @@ -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:: diff --git a/docs/users/queue.rst b/docs/users/queue.rst index 7df5c4d7f..4a21fb113 100644 --- a/docs/users/queue.rst +++ b/docs/users/queue.rst @@ -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 ^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/users/radios.rst b/docs/users/radios.rst index 76ced8f9a..6b3bf9c43 100644 --- a/docs/users/radios.rst +++ b/docs/users/radios.rst @@ -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 ` -- Random - plays random songs from your :doc:`libraries ` or :doc:`libraries you follow ` -- Less Listened - plays songs you listen to less frequently +- **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 -------------------- @@ -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 diff --git a/docs/users/tagging.rst b/docs/users/tagging.rst index a936fff00..f02143ffc 100644 --- a/docs/users/tagging.rst +++ b/docs/users/tagging.rst @@ -3,7 +3,7 @@ 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 :ref:`directly in Funkwhale `. +In addition to using an external tagging service, tags can be applied :doc:`directly in Funkwhale `. Tagging Items -------------- -- GitLab From adaa626eb2423db3ddc8117385911fcd68cf3f5b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Mon, 20 Apr 2020 15:58:21 +0200 Subject: [PATCH 12/13] Fix typo --- docs/users/favorites.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/users/favorites.rst b/docs/users/favorites.rst index 1c663524a..766e7b39e 100644 --- a/docs/users/favorites.rst +++ b/docs/users/favorites.rst @@ -23,7 +23,7 @@ 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 hear icon next to the Play button +- 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 -- GitLab From 4e7137e67101078313ea6258399351c5f7c96e35 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Mon, 20 Apr 2020 15:59:04 +0200 Subject: [PATCH 13/13] Removed unnecessary space --- docs/users/favorites.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/users/favorites.rst b/docs/users/favorites.rst index 766e7b39e..ac232f0cd 100644 --- a/docs/users/favorites.rst +++ b/docs/users/favorites.rst @@ -26,7 +26,6 @@ To add a track to your favorites from a channel: - 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 ^^^^^^^^^^^^^^^^^^^^^^ -- GitLab