From d714c721b46df1973aee9472af3d283a8ff24bb1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Wed, 16 Aug 2023 21:16:43 +0200 Subject: [PATCH] docs: add bitrate filter information to spec Part-of: --- docs/index.md | 1 + docs/specs/quality-filter/index.md | 45 ++++++++++++++++++++++++------ 2 files changed, 37 insertions(+), 9 deletions(-) diff --git a/docs/index.md b/docs/index.md index bf64532ac..52a9331fa 100644 --- a/docs/index.md +++ b/docs/index.md @@ -103,6 +103,7 @@ hidden: true specs/nodeinfo21/index specs/offline-mode/index +specs/quality-filter/index ``` diff --git a/docs/specs/quality-filter/index.md b/docs/specs/quality-filter/index.md index 00a6e1c1c..5f1ff5d2a 100644 --- a/docs/specs/quality-filter/index.md +++ b/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 -- 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**) +- An {guilabel}`Enable` checkbox. If enabled, all options below are made available. If not enabled, no filters are applied to the API calls +- 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 "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}`Album art`. If checked, only albums with associated art 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 {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