docs: add bitrate filter information to spec

Part-of: <https://dev.funkwhale.audio/funkwhale/funkwhale/-/merge_requests/2525>

docs/index.md

@@ -103,6 +103,7 @@ hidden: true
 
 specs/nodeinfo21/index
 specs/offline-mode/index
+specs/quality-filter/index
 
 ```
 

docs/specs/quality-filter/index.md

@@ -1,3 +1,5 @@
+# Quality filter
+
 ## The issue
 
 As raised in [#1469](https://dev.funkwhale.audio/funkwhale/funkwhale/-/issues/1469), the current user experience of Funkwhale can be poor if the content on a pod is of a low quality or is missing essential information. For example:
@@ -7,7 +9,7 @@ As raised in [#1469](https://dev.funkwhale.audio/funkwhale/funkwhale/-/issues/14
 
 ## Proposed solution
 
-To address this, Funkwhale should include a quality filter that enables administrators to put their pod's best quality content front and center when a user navigates to the `Explore` tab. This quality filter should enable the **admin** of a pod to set the following properties in the Funkwhale settings menu:
+To address this, Funkwhale should include a quality filter that enables administrators to put their pod's best quality content front and center when a user navigates to the {guilabel}`Explore` tab. This quality filter should enable the **admin** of a pod to set the following properties in the Funkwhale settings menu:
 
 - The **format** of tracks returned by the API
 - Whether to show or hide albums missing essential metadata
@@ -24,16 +26,24 @@ To give full granular control, the admin should be able to select which of these
 
 ### Frontend
 
-The frontend implementation of this feature should comprise a set of controls in the Funkwhale admin menu. As noted above, this should be split up as follows in a section labeled "Explore page quality filter":
+The frontend implementation of this feature should comprise a set of controls in the Funkwhale admin menu. As noted above, this should be split up as follows in a section labeled {guilabel}`Explore page quality filter`:
 
-- An "Enable" checkbox. If enabled, all options below are made available. If not enabled, no filters are applied to the API calls
+- An {guilabel}`Enable` checkbox. If enabled, all options below are made available. If not enabled, no filters are applied to the API calls
-- A "Formats" multi-select dropdown field that displays the file formats supported by Funkwhale. The admin should be able to select any combination of formats (e.g.: **MP3 + OGG + FLAC + AAC**)
+- A {guilabel}`Formats` multi-select dropdown field that displays the file formats supported by Funkwhale. The admin should be able to select any combination of formats (e.g.: **MP3 + OGG + FLAC + AAC**)
 
-Under a subsection labeled "Required metadata":
+Under a subsection labeled {guilabel}`Required metadata`:
 
-- A checkbox for "Album art". If checked, only albums with associated art should be returned by the API
+- A checkbox for {guilabel}`Album art`. If checked, only albums with associated art should be returned by the API
-- A checkbox for "Release date". If checked, only albums with a properly formatted release date should be returned by the API
+- A checkbox for {guilabel}`Release date`. If checked, only albums with a properly formatted release date should be returned by the API
-- A checkbox for "Genre tags". If checked, only content that is tagged with at least one genre tag should be returned by the API
+- A checkbox for {guilabel}`Genre tags`. If checked, only content that is tagged with at least one genre tag should be returned by the API
+
+The menu should also contain a {guilabel}`Quality filter` slider that allows admins to choose a **minimum** quality level. This level should be abstracted on the backend to apply a sensible value to all supported file formats.
+
+- {guilabel}`Off` - Allows content of **all** bitrates and formats to be displayed on the Explore page.
+- {guilabel}`Low` - Allows only compressed audio formats with a lower bitrate to be displayed on the Explore page.
+- {guilabel}`Medium` - Allows both low- and medium-bitrate compressed audio formats to be displayed on the Explore page.
+- {guilabel}`High` - Allows uncompressed and high-bitrate compressed audio formats to be displayed on the Explore page.
+- {guilabel}`Very high` - Allows only uncompressed files and very high-bitrate opus files to be displayed on the Explore page.
 
 ### Backend
 
@@ -43,12 +53,29 @@ The following configurable filters need to be applied:
 
 - `format`: a comma-separated list of accepted file formats (e.g. `mp3,ogg,vorbis,flac`). Only files matching the formats in the list should be returned if this filter is passed
 - `has_tags`: a boolean value that indicates whether the content should be tagged (`true`) or not (`false`)
+- `quality`: an enum value that filters content based on the file quality. If no value is passed, uploads of any quality should be returned. Accepted values:
+  - `low`
+  - `medium`
+  - `high`
+  - `very_high`
 
-In addition to the above, the Albums endpoint should contain the following filters:
+In addition to the above, the `Albums` endpoint should contain the following filters:
 
 - `has_cover`: a boolean value that indicates whether the album has associated album art (`true`) or not (`false`)
 - `has_release_date`: a boolean value that indicates whether the album is tagged with a properly formatted release date (`true`) or not (`false`)
 
+#### Quality filter mappings
+
+The table below shows a suggested bitrate mapping and behavior for each file type. Bitrate values are shown in **kbps**.
+
+|           | FLAC   | AIF    | AIFF   | Opus   | AAC    | OGG    | MP3    |
+| --------- | ------ | ------ | ------ | ------ | ------ | ------ | ------ |
+| Off       | always | always | always | always | always | always | always |
+| Low       | never  | never  | never  | <= 96  | <= 96  | <= 96  | <= 192 |
+| Medium    | never  | never  | never  | <= 128 | <= 128 | <= 192 | <= 256 |
+| High      | always | always | always | <= 160 | <= 288 | <= 256 | <= 320 |
+| Very high | always | always | always | >= 510 | never  | never  | never  |
+
 ## Availability
 
 - Admin panel