From 5ef1e657b5292a68b9ca0116bd56f5baa58e65cf Mon Sep 17 00:00:00 2001 From: allholy Date: Mon, 14 Apr 2025 18:21:24 +0200 Subject: [PATCH 1/5] Add API documentation for category field and minor corrections --- _docs/api/source/resources.rst | 19 +++++++++++++------ apiv2/examples.py | 10 +++++----- 2 files changed, 18 insertions(+), 11 deletions(-) diff --git a/_docs/api/source/resources.rst b/_docs/api/source/resources.rst index 6c5c1259cc..7f9a0c54de 100644 --- a/_docs/api/source/resources.rst +++ b/_docs/api/source/resources.rst @@ -60,15 +60,17 @@ Filter name Type Description ``username`` string Username of the sound uploader (not tokenized). ``created`` date Date in which the sound was added to Freesound (see date example filters below). ``original_filename`` string Name given to the sound (tokenized). +``category`` string Category name (top-level category) from the `Broad Sound Taxonomy `_. +``subcategory`` string Subategory name (second-level category) from the `Broad Sound Taxonomy `_. Note that it is recommended to select a (top-level) category first. +``tag`` string Tag of the sound. ``description`` string Textual description given to the sound (tokenized). -``tag`` string Tag -``license`` string Name of the Creative Commons license, one of["Attribution", "Attribution NonCommercial", "Creative Commons 0"]. +``license`` string Name of the Creative Commons license, one of ["Attribution", "Attribution NonCommercial", "Creative Commons 0"]. ``is_remix`` boolean Whether the sound is a remix of another Freesound sound. ``was_remixed`` boolean Whether the sound has remixes in Freesound. ``pack`` string Pack name (not tokenized). ``pack_tokenized`` string Pack name (tokenized). ``is_geotagged`` boolean Whether the sound has geotag information. -``type`` string Original file type, one off ["wav", "aiff", "ogg", "mp3", "m4a", "flac"]. +``type`` string Original file type, one of ["wav", "aiff", "ogg", "mp3", "m4a", "flac"]. ``duration`` numerical Duration of sound in seconds. ``bitdepth`` integer Encoding bitdepth. WARNING is not to be trusted right now. ``bitrate`` numerical Encoding bitrate. WARNING is not to be trusted right now. @@ -80,7 +82,7 @@ Filter name Type Description ``avg_rating`` numerical Average rating for the sound in the range [0, 5]. ``num_ratings`` integer Number of times the sound has been rated. ``comment`` string Textual content of the comments of a sound (tokenized). The filter is satisfied if sound contains the filter value in at least one of its comments. -``num_comments`` integer Number of times the sound has been commented. +``num_comments`` integer Number of times the sound has been commented. ====================== ============= ==================================================== @@ -490,6 +492,8 @@ Name Type Description ``name`` string The name user gave to the sound. ``tags`` array[strings] An array of tags the user gave to the sound. ``description`` string The description the user gave to the sound. +``category`` array[strings] A two-element array containing the sound's category and subcategory from the `Broad Sound Taxonomy `_ (if it is not given by the user, it is computed by an algorithm). +``category_code`` string The category ID from the `Broad Sound Taxonomy `_ (e.g. "fx-a", with the prefix indicating the category and the suffix indicating the subcategory). ``geotag`` string Latitude and longitude of the geotag separated by spaces (e.g. "41.0082325664 28.9731252193", only for sounds that have been geotagged). ``created`` string The date when the sound was uploaded (e.g. "2014-04-16T20:07:11.145"). ``license`` string The license under which the sound is available to you. @@ -688,6 +692,7 @@ Additionally, the request can include the following POST parameters to provide a Name Type Description ==================== ================ ==================================================================================== ``name`` string (OPTIONAL) The name that will be given to the sound. If not provided, filename will be used. +``bst_category`` string The category code that will be assigned to the sound. Must be one of the subcategory IDs from the `Broad Sound Taxonomy `_. ``tags`` string The tags that will be assigned to the sound. Separate tags with spaces and join multi-words with dashes (e.g. "tag1 tag2 tag3 cool-tag4"). ``description`` string A textual description of the sound. ``license`` string The license of the sound. Must be either "Attribution", "Attribution NonCommercial" or "Creative Commons 0". @@ -695,8 +700,8 @@ Name Type Description ``geotag`` string (OPTIONAL) Geotag information for the sound. Latitude, longitude and zoom values in the form lat,lon,zoom (e.g. "2.145677,3.22345,14"). ==================== ================ ==================================================================================== -Note that ``tags``, ``description`` and ``license`` parameters are REQUIRED when providing a description for the file, but can be omitted if no description is provided. -In other words, you can either only provide the ``audiofile`` parameter, or provide ``audiofile`` plus ``tags``, ``description``, ``license`` and any of the other optional parameters. +Note that ``bst_category``, ``tags``, ``description`` and ``license`` parameters are REQUIRED when providing a description for the file, but can be omitted if no description is provided. +In other words, you can either only provide the ``audiofile`` parameter, or provide ``audiofile`` plus ``bst_category``, ``tags``, ``description``, ``license`` and any of the other optional parameters. In the first case, a file will be uploaded but not described (you will need to describe it later), and in the second case a file will both be uploaded and described. @@ -761,6 +766,7 @@ Name Type Description ==================== ================ ==================================================================================== ``upload_filename`` string The filename of the sound to describe. Must match with one of the filenames returned in :ref:`sound-pending-uploads` resource. ``name`` string (OPTIONAL) The name that will be given to the sound. If not provided, filename will be used. +``bst_category`` string The category code that will be assigned to the sound. Must be one of the subcategory IDs from the `Broad Sound Taxonomy `_. ``tags`` string The tags that will be assigned to the sound. Separate tags with spaces and join multi-words with dashes (e.g. "tag1 tag2 tag3 cool-tag4"). ``description`` string A textual description of the sound. ``license`` string The license of the sound. Must be either "Attribution", "Attribution NonCommercial" or "Creative Commons 0". @@ -877,6 +883,7 @@ A request to the Edit Sound Description resource must include mostly the same PO Name Type Description ==================== ================ ==================================================================================== ``name`` string (OPTIONAL) The new name that will be given to the sound. +``bst_category`` string (OPTIONAL) The new category code that will be assigned to the sound. Must be one of the subcategory IDs from the `Broad Sound Taxonomy `_. ``tags`` string (OPTIONAL) The new tags that will be assigned to the sound. Note that if this parameter is filled, old tags will be deleted. Separate tags with spaces and join multi-words with dashes (e.g. "tag1 tag2 tag3 cool-tag4"). ``description`` string (OPTIONAL) The new textual description for the sound. ``license`` string (OPTIONAL) The new license of the sound. Must be either "Attribution", "Attribution NonCommercial" or "Creative Commons 0". diff --git a/apiv2/examples.py b/apiv2/examples.py index 30709c5225..c7db766e5f 100644 --- a/apiv2/examples.py +++ b/apiv2/examples.py @@ -71,16 +71,16 @@ ], 'UploadSound': [ ('Upload a sound (audiofile only, no description)', ['curl -X POST -H "Authorization: Bearer {{access_token}}" -F audiofile=@"/path/to/your_file.wav" \'%s/apiv2/sounds/upload/\'']), - ('Upload and describe a sound all at once', ['curl -X POST -H "Authorization: Bearer {{access_token}}" -F audiofile=@"/path/to/your_file.wav" -F "tags=field-recording birds nature h4n" -F "description=This sound was recorded...
bla bla bla..." -F "license=Attribution" \'%s/apiv2/sounds/upload/\'']), - ('Upload and describe a sound with name, pack and geotag', ['curl -X POST -H "Authorization: Bearer {{access_token}}" -F audiofile=@"/path/to/your_file.wav" -F "name=Another cool sound" -F "tags=field-recording birds nature h4n" -F "description=This sound was recorded...
bla bla bla..." -F "license=Attribution" -F "pack=A birds pack" -F "geotag=2.145677,3.22345,14" \'%s/apiv2/sounds/upload/\'']), + ('Upload and describe a sound all at once', ['curl -X POST -H "Authorization: Bearer {{access_token}}" -F audiofile=@"/path/to/your_file.wav" -F "tags=field-recording birds nature h4n" -F "description=This sound was recorded...
bla bla bla..." -F "bst_category=fx-a" -F "license=Attribution" \'%s/apiv2/sounds/upload/\'']), + ('Upload and describe a sound with name, pack and geotag', ['curl -X POST -H "Authorization: Bearer {{access_token}}" -F audiofile=@"/path/to/your_file.wav" -F "name=Another cool sound" -F "tags=field-recording birds nature h4n" -F "description=This sound was recorded...
bla bla bla..." -F "bst_category=fx-a" -F "license=Attribution" -F "pack=A birds pack" -F "geotag=2.145677,3.22345,14" \'%s/apiv2/sounds/upload/\'']), ], 'PendingUploads': [ ('Get uploaded sounds that are pending description, processing or moderation', ['curl -H "Authorization: Bearer {{access_token}}" \'%s/apiv2/sounds/pending_uploads/\'']), ], 'DescribeSound': [ - ('Describe a sound (only with required fields)', ['curl -X POST -H "Authorization: Bearer {{access_token}}" --data "upload_filename=your_file.wav&tags=field-recording birds nature h4n&description=This sound was recorded...
bla bla bla...&license=Attribution" \'%s/apiv2/sounds/describe/\'']), - ('Also add a name to the sound', ['curl -X POST -H "Authorization: Bearer {{access_token}}" --data "upload_filename=your_file.wav&name=A cool bird sound&tags=field-recording birds nature h4n&description=This sound was recorded...
bla bla bla...&license=Attribution" \'%s/apiv2/sounds/describe/\'']), - ('Include geotag and pack information', ['curl -X POST -H "Authorization: Bearer {{access_token}}" --data "upload_filename=your_file.wav&name=A cool bird sound&tags=field-recording birds nature h4n&description=This sound was recorded...
bla bla bla...&license=Attribution&pack=A birds pack&geotag=2.145677,3.22345,14" \'%s/apiv2/sounds/describe/\'']), + ('Describe a sound (only with required fields)', ['curl -X POST -H "Authorization: Bearer {{access_token}}" --data "upload_filename=your_file.wav&tags=field-recording birds nature h4n&description=This sound was recorded...
bla bla bla...&bst_category=fx-a&license=Attribution" \'%s/apiv2/sounds/describe/\'']), + ('Also add a name to the sound', ['curl -X POST -H "Authorization: Bearer {{access_token}}" --data "upload_filename=your_file.wav&name=A cool bird sound&tags=field-recording birds nature h4n&description=This sound was recorded...
bla bla bla...&bst_category=fx-a&license=Attribution" \'%s/apiv2/sounds/describe/\'']), + ('Include geotag and pack information', ['curl -X POST -H "Authorization: Bearer {{access_token}}" --data "upload_filename=your_file.wav&name=A cool bird sound&tags=field-recording birds nature h4n&description=This sound was recorded...
bla bla bla...&bst_category=fx-a&license=Attribution&pack=A birds pack&geotag=2.145677,3.22345,14" \'%s/apiv2/sounds/describe/\'']), ], #'EditSoundDescription': [ # ('Setting tags of an existing sound to be "new tags for the sound" and description to "New sound description..."', ['curl -X POST -H "Authorization: Bearer {{access_token}}" --data "tags=new tags for the sound&description=New sound description..." \'%s/apiv2/sounds/1234/edit/\'']), From e140fcd3f732c2ae5d7262f34c9a900ea428cc7b Mon Sep 17 00:00:00 2001 From: allholy Date: Mon, 14 Apr 2025 18:23:56 +0200 Subject: [PATCH 2/5] Update definition of Music in BST --- freesound/settings.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/freesound/settings.py b/freesound/settings.py index 5df0a44156..e70d019e34 100644 --- a/freesound/settings.py +++ b/freesound/settings.py @@ -414,7 +414,7 @@ # Broad Sound Taxonomy definition BROAD_SOUND_TAXONOMY = { - "m": {"level": 1, "name": "Music", "description": "Music excerpts, melodies, loops, fillers, drones and short musical snippets."}, + "m": {"level": 1, "name": "Music", "description": "Music excerpts, including melodies, singing, loops, fillers, drones and short musical snippets."}, "m-sp": {"level": 2, "name": "Solo percussion", "description": "Music excerpts with solo percussive instruments."}, "m-si": {"level": 2, "name": "Solo instrument", "description": "Music excerpts with only one instrument, excluding percussion."}, "m-m": {"level": 2, "name": "Multiple instruments", "description": "Music excerpts with more than one instrument."}, From aa63bce8c11b7bb319e3765fcd92833d9beca0fd Mon Sep 17 00:00:00 2001 From: allholy Date: Mon, 14 Apr 2025 20:21:30 +0200 Subject: [PATCH 3/5] WIP add extra category fields --- apiv2/serializers.py | 13 ++++++++++- sounds/models.py | 5 +++++ sounds/templatetags/bst_category.py | 34 ++++++++++++++++++++++++++--- 3 files changed, 48 insertions(+), 4 deletions(-) diff --git a/apiv2/serializers.py b/apiv2/serializers.py index 4c553d033a..5e19590eff 100644 --- a/apiv2/serializers.py +++ b/apiv2/serializers.py @@ -39,7 +39,7 @@ ################### DEFAULT_FIELDS_IN_SOUND_LIST = 'id,name,tags,username,license' # Separated by commas (None = all) -DEFAULT_FIELDS_IN_SOUND_DETAIL = 'id,url,name,tags,description,category,geotag,created,license,type,channels,filesize,bitrate,' + \ +DEFAULT_FIELDS_IN_SOUND_DETAIL = 'id,url,name,tags,description,category,category_code,geotag,created,license,type,channels,filesize,bitrate,' + \ 'bitdepth,duration,samplerate,username,pack,pack_name,download,bookmark,previews,images,' + \ 'num_downloads,avg_rating,num_ratings,rate,comments,num_comments,comment,similar_sounds,' + \ 'analysis,analysis_frames,analysis_stats,is_explicit' # All except for analyzers @@ -90,6 +90,8 @@ class Meta: 'tags', 'description', 'category', + 'category_code', + 'category_is_user_provided', 'geotag', 'created', 'license', @@ -169,6 +171,15 @@ def get_category(self, obj): if category is None and subcategory is None: return None return [category, subcategory] + + category_code = serializers.SerializerMethodField() + def get_category_code(self, obj): + return obj.category_code or None + + category_is_user_provided = serializers.SerializerMethodField() + def get_category_is_user_provided(self, obj): + category, _ = obj.category_names + return bool(category) # Returns False if category is None, i.e not user-provided pack = serializers.SerializerMethodField() def get_pack(self, obj): diff --git a/sounds/models.py b/sounds/models.py index b4c61bc1ee..51e0156a04 100644 --- a/sounds/models.py +++ b/sounds/models.py @@ -1299,6 +1299,11 @@ def category_names(self): pass return [None, None] return bst_taxonomy_category_key_to_category_names(self.bst_category) + + @property + def category_code(self): + if self.bst_category is None: + return bst_taxonomy_category_key_to_category_names(self.bst_category) @property def get_top_level_category_search_url(self): diff --git a/sounds/templatetags/bst_category.py b/sounds/templatetags/bst_category.py index df84717b91..9854382935 100644 --- a/sounds/templatetags/bst_category.py +++ b/sounds/templatetags/bst_category.py @@ -7,17 +7,17 @@ def bst_taxonomy_category_key_to_category_names(category_key): """ Get the category names for the given category key. - This includes both the top level and the sub level category names. + This includes both the top-level and the second-level category names. E.g.: "m-sp" -> ("Music", "Solo percussion"), "m" -> ("Music", None) """ if category_key is None: return (None, None) if '-' in category_key: - # Sub level category key + # Second-level category key top_level_key = category_key.split('-')[0] second_level_key = category_key else: - # Only top level category spcifcied, sub level is unknown + # Only top-level category spcifcied, second-level is unknown top_level_key = category_key second_level_key = None try: @@ -32,6 +32,34 @@ def bst_taxonomy_category_key_to_category_names(category_key): second_level_category_name = None return (top_level_category_name, second_level_category_name) +def bst_taxonomy_category_names_to_category_key(top_level_name, second_level_name): + """ + Get the category key for the given category names. + This is the reverse of bst_taxonomy_category_key_to_category_names. + E.g.: ("Music", "Solo percussion") -> "m-sp", ("Music", None) -> "m" + """ + if top_level_name is None: + return None + + # Find the top-level key + top_level_key = None + for category_key, val in settings.BROAD_SOUND_TAXONOMY.items(): + if val.get("level") == 1 and val.get('name') == top_level_name: + top_level_key = category_key + break + if top_level_key is None: + return None + + if second_level_name is None: + return top_level_key + + # Find second-level key under the correct top-level category + for category_key, val in settings.BROAD_SOUND_TAXONOMY.items(): + if category_key.startswith(f"{top_level_key}-") and val.get('name') == second_level_name: + return category_key + + # If no matching second-level category, return just the top-level key + return top_level_key @register.filter def get_bst_taxonomy_top_level_category_key(value): From 847be5b6a47392ee4a13d749b97f4d078cddb989 Mon Sep 17 00:00:00 2001 From: ffont Date: Tue, 15 Apr 2025 11:37:29 +0200 Subject: [PATCH 4/5] Minor fixes in docs --- _docs/api/source/resources.rst | 89 +++++++++++++++++----------------- 1 file changed, 45 insertions(+), 44 deletions(-) diff --git a/_docs/api/source/resources.rst b/_docs/api/source/resources.rst index 7f9a0c54de..6554b231ad 100644 --- a/_docs/api/source/resources.rst +++ b/_docs/api/source/resources.rst @@ -60,8 +60,8 @@ Filter name Type Description ``username`` string Username of the sound uploader (not tokenized). ``created`` date Date in which the sound was added to Freesound (see date example filters below). ``original_filename`` string Name given to the sound (tokenized). -``category`` string Category name (top-level category) from the `Broad Sound Taxonomy `_. -``subcategory`` string Subategory name (second-level category) from the `Broad Sound Taxonomy `_. Note that it is recommended to select a (top-level) category first. +``category`` string Category name (top-level category) from the `Broad Sound Taxonomy `_ (e.g. "Instrument samples"). +``subcategory`` string Subategory name (second-level category) from the `Broad Sound Taxonomy `_ (e.g. "Piano / Keyboard instruments"). For optimal results, it is recommended to use this filter in combination with the ``category`` filter. ``tag`` string Tag of the sound. ``description`` string Textual description given to the sound (tokenized). ``license`` string Name of the Creative Commons license, one of ["Attribution", "Attribution NonCommercial", "Creative Commons 0"]. @@ -484,45 +484,46 @@ Response (sound instance) The Sound Instance response is a dictionary including the following properties/fields: -==================== ================ ==================================================================================== -Name Type Description -==================== ================ ==================================================================================== -``id`` number The sound's unique identifier. -``url`` URI The URI for this sound on the Freesound website. -``name`` string The name user gave to the sound. -``tags`` array[strings] An array of tags the user gave to the sound. -``description`` string The description the user gave to the sound. -``category`` array[strings] A two-element array containing the sound's category and subcategory from the `Broad Sound Taxonomy `_ (if it is not given by the user, it is computed by an algorithm). -``category_code`` string The category ID from the `Broad Sound Taxonomy `_ (e.g. "fx-a", with the prefix indicating the category and the suffix indicating the subcategory). -``geotag`` string Latitude and longitude of the geotag separated by spaces (e.g. "41.0082325664 28.9731252193", only for sounds that have been geotagged). -``created`` string The date when the sound was uploaded (e.g. "2014-04-16T20:07:11.145"). -``license`` string The license under which the sound is available to you. -``type`` string The type of sound (wav, aif, aiff, mp3, m4a or flac). -``channels`` number The number of channels. -``filesize`` number The size of the file in bytes. -``bitrate`` number The bit rate of the sound in kbps. -``bitdepth`` number The bit depth of the sound. -``duration`` number The duration of the sound in seconds. -``samplerate`` number The samplerate of the sound. -``username`` string The username of the uploader of the sound. -``pack`` URI If the sound is part of a pack, this URI points to that pack's API resource. -``download`` URI The URI for retrieving the original sound. -``bookmark`` URI The URI for bookmarking the sound. -``previews`` object Dictionary containing the URIs for mp3 and ogg versions of the sound. The dictionary includes the fields ``preview-hq-mp3`` and ``preview-lq-mp3`` (for ~128kbps quality and ~64kbps quality mp3 respectively), and ``preview-hq-ogg`` and ``preview-lq-ogg`` (for ~192kbps quality and ~80kbps quality ogg respectively). -``images`` object Dictionary including the URIs for spectrogram and waveform visualizations of the sound. The dictionary includes the fields ``waveform_l`` and ``waveform_m`` (for large and medium waveform images respectively), and ``spectral_l`` and ``spectral_m`` (for large and medium spectrogram images respectively). -``num_downloads`` number The number of times the sound was downloaded. -``avg_rating`` number The average rating of the sound. -``num_ratings`` number The number of times the sound was rated. -``rate`` URI The URI for rating the sound. -``comments`` URI The URI of a paginated list of the comments of the sound. -``num_comments`` number The number of comments. -``comment`` URI The URI to comment the sound. -``similar_sounds`` URI URI pointing to the similarity resource (to get a list of similar sounds). -``analysis`` object Dictionary containing requested descriptors information according to the ``descriptors`` request parameter (see below). This field will be null if no descriptors were specified (or invalid descriptor names specified) or if the analysis data for the sound is not available. -``analysis_stats`` URI URI pointing to the complete analysis results of the sound (see :ref:`analysis-docs`). -``analysis_frames`` URI The URI for retrieving a JSON file with analysis information for each frame of the sound (see :ref:`analysis-docs`). -``ac_analysis`` object Dictionary containing the results of the AudioCommons analysis for the given sound. -==================== ================ ==================================================================================== +============================== ================ ==================================================================================== +Name Type Description +============================== ================ ==================================================================================== +``id`` number The sound's unique identifier. +``url`` URI The URI for this sound on the Freesound website. +``name`` string The name user gave to the sound. +``tags`` array[strings] An array of tags the user gave to the sound. +``description`` string The description the user gave to the sound. +``category`` array[strings] A two-element array containing the sound's category and subcategory names from the `Broad Sound Taxonomy `_. Note that categories are filled-out by an algorithm if not provided by the original author of the sound. +``category_code`` string The category ID from the `Broad Sound Taxonomy `_ (e.g. "fx-a", with the prefix indicating the category and the suffix indicating the subcategory). Note that categories are filled-out by an algorithm if not provided by the original author of the sound. +``category_is_user_provided`` boolean Whether the ``category`` (and ``category_code``) were provided by the author of the sound or assigned automatically by an algorithm. +``geotag`` string Latitude and longitude of the geotag separated by spaces (e.g. "41.0082325664 28.9731252193", only for sounds that have been geotagged). +``created`` string The date when the sound was uploaded (e.g. "2014-04-16T20:07:11.145"). +``license`` string The license under which the sound is available to you. +``type`` string The type of sound (wav, aif, aiff, mp3, m4a or flac). +``channels`` number The number of channels. +``filesize`` number The size of the file in bytes. +``bitrate`` number The bit rate of the sound in kbps. +``bitdepth`` number The bit depth of the sound. +``duration`` number The duration of the sound in seconds. +``samplerate`` number The samplerate of the sound. +``username`` string The username of the uploader of the sound. +``pack`` URI If the sound is part of a pack, this URI points to that pack's API resource. +``download`` URI The URI for retrieving the original sound. +``bookmark`` URI The URI for bookmarking the sound. +``previews`` object Dictionary containing the URIs for mp3 and ogg versions of the sound. The dictionary includes the fields ``preview-hq-mp3`` and ``preview-lq-mp3`` (for ~128kbps quality and ~64kbps quality mp3 respectively), and ``preview-hq-ogg`` and ``preview-lq-ogg`` (for ~192kbps quality and ~80kbps quality ogg respectively). +``images`` object Dictionary including the URIs for spectrogram and waveform visualizations of the sound. The dictionary includes the fields ``waveform_l`` and ``waveform_m`` (for large and medium waveform images respectively), and ``spectral_l`` and ``spectral_m`` (for large and medium spectrogram images respectively). +``num_downloads`` number The number of times the sound was downloaded. +``avg_rating`` number The average rating of the sound. +``num_ratings`` number The number of times the sound was rated. +``rate`` URI The URI for rating the sound. +``comments`` URI The URI of a paginated list of the comments of the sound. +``num_comments`` number The number of comments. +``comment`` URI The URI to comment the sound. +``similar_sounds`` URI URI pointing to the similarity resource (to get a list of similar sounds). +``analysis`` object Dictionary containing requested descriptors information according to the ``descriptors`` request parameter (see below). This field will be null if no descriptors were specified (or invalid descriptor names specified) or if the analysis data for the sound is not available. +``analysis_stats`` URI URI pointing to the complete analysis results of the sound (see :ref:`analysis-docs`). +``analysis_frames`` URI The URI for retrieving a JSON file with analysis information for each frame of the sound (see :ref:`analysis-docs`). +``ac_analysis`` object Dictionary containing the results of the AudioCommons analysis for the given sound. +============================== ================ ==================================================================================== The contents of the field ``analysis`` of the Sound Instance response can be determined using an additional request parameter ``descriptors``. @@ -692,7 +693,7 @@ Additionally, the request can include the following POST parameters to provide a Name Type Description ==================== ================ ==================================================================================== ``name`` string (OPTIONAL) The name that will be given to the sound. If not provided, filename will be used. -``bst_category`` string The category code that will be assigned to the sound. Must be one of the subcategory IDs from the `Broad Sound Taxonomy `_. +``bst_category`` string The ID of a category to be assigned to the sound. Must be one of the subcategory IDs from the `Broad Sound Taxonomy `_. ``tags`` string The tags that will be assigned to the sound. Separate tags with spaces and join multi-words with dashes (e.g. "tag1 tag2 tag3 cool-tag4"). ``description`` string A textual description of the sound. ``license`` string The license of the sound. Must be either "Attribution", "Attribution NonCommercial" or "Creative Commons 0". @@ -766,7 +767,7 @@ Name Type Description ==================== ================ ==================================================================================== ``upload_filename`` string The filename of the sound to describe. Must match with one of the filenames returned in :ref:`sound-pending-uploads` resource. ``name`` string (OPTIONAL) The name that will be given to the sound. If not provided, filename will be used. -``bst_category`` string The category code that will be assigned to the sound. Must be one of the subcategory IDs from the `Broad Sound Taxonomy `_. +``bst_category`` string The ID of a category to be assigned to the sound. Must be one of the subcategory IDs from the `Broad Sound Taxonomy `_. ``tags`` string The tags that will be assigned to the sound. Separate tags with spaces and join multi-words with dashes (e.g. "tag1 tag2 tag3 cool-tag4"). ``description`` string A textual description of the sound. ``license`` string The license of the sound. Must be either "Attribution", "Attribution NonCommercial" or "Creative Commons 0". @@ -883,7 +884,7 @@ A request to the Edit Sound Description resource must include mostly the same PO Name Type Description ==================== ================ ==================================================================================== ``name`` string (OPTIONAL) The new name that will be given to the sound. -``bst_category`` string (OPTIONAL) The new category code that will be assigned to the sound. Must be one of the subcategory IDs from the `Broad Sound Taxonomy `_. +``bst_category`` string (OPTIONAL) The new category ID that will be assigned to the sound. Must be one of the subcategory IDs from the `Broad Sound Taxonomy `_. ``tags`` string (OPTIONAL) The new tags that will be assigned to the sound. Note that if this parameter is filled, old tags will be deleted. Separate tags with spaces and join multi-words with dashes (e.g. "tag1 tag2 tag3 cool-tag4"). ``description`` string (OPTIONAL) The new textual description for the sound. ``license`` string (OPTIONAL) The new license of the sound. Must be either "Attribution", "Attribution NonCommercial" or "Creative Commons 0". From 092583ca98fa50e1954b7d0040320c3cb8a1bb4a Mon Sep 17 00:00:00 2001 From: allholy Date: Tue, 15 Apr 2025 15:21:00 +0200 Subject: [PATCH 5/5] Fixes in additional category fields --- apiv2/serializers.py | 5 ++--- sounds/models.py | 7 +++---- sounds/templatetags/bst_category.py | 23 +++++++++-------------- 3 files changed, 14 insertions(+), 21 deletions(-) diff --git a/apiv2/serializers.py b/apiv2/serializers.py index 5e19590eff..bb57a81c61 100644 --- a/apiv2/serializers.py +++ b/apiv2/serializers.py @@ -39,7 +39,7 @@ ################### DEFAULT_FIELDS_IN_SOUND_LIST = 'id,name,tags,username,license' # Separated by commas (None = all) -DEFAULT_FIELDS_IN_SOUND_DETAIL = 'id,url,name,tags,description,category,category_code,geotag,created,license,type,channels,filesize,bitrate,' + \ +DEFAULT_FIELDS_IN_SOUND_DETAIL = 'id,url,name,tags,description,category,category_code,category_is_user_provided,geotag,created,license,type,channels,filesize,bitrate,' + \ 'bitdepth,duration,samplerate,username,pack,pack_name,download,bookmark,previews,images,' + \ 'num_downloads,avg_rating,num_ratings,rate,comments,num_comments,comment,similar_sounds,' + \ 'analysis,analysis_frames,analysis_stats,is_explicit' # All except for analyzers @@ -178,8 +178,7 @@ def get_category_code(self, obj): category_is_user_provided = serializers.SerializerMethodField() def get_category_is_user_provided(self, obj): - category, _ = obj.category_names - return bool(category) # Returns False if category is None, i.e not user-provided + return obj.bst_category is not None pack = serializers.SerializerMethodField() def get_pack(self, obj): diff --git a/sounds/models.py b/sounds/models.py index 51e0156a04..6a905b0121 100644 --- a/sounds/models.py +++ b/sounds/models.py @@ -60,7 +60,7 @@ from geotags.models import GeoTag from ratings.models import SoundRating from general.templatetags.util import formatnumber -from sounds.templatetags.bst_category import bst_taxonomy_category_key_to_category_names +from sounds.templatetags.bst_category import bst_taxonomy_category_key_to_category_names, bst_taxonomy_category_names_to_category_key from tags.models import SoundTag, Tag from tickets import TICKET_STATUS_CLOSED, TICKET_STATUS_NEW from tickets.models import Ticket, TicketComment @@ -1289,7 +1289,7 @@ def get_similarity_search_target_vector(self, analyzer=settings.SEARCH_ENGINE_DE @property def category_names(self): if self.bst_category is None: - # If the sound category has not be defind by user, return estimated precomputed category. + # If the sound category has not been defind by user, return estimated precomputed category. try: for analysis in self.analyses.all(): if analysis.analyzer == settings.BST_ANALYZER_NAME: @@ -1302,8 +1302,7 @@ def category_names(self): @property def category_code(self): - if self.bst_category is None: - return bst_taxonomy_category_key_to_category_names(self.bst_category) + return bst_taxonomy_category_names_to_category_key(*self.category_names) @property def get_top_level_category_search_url(self): diff --git a/sounds/templatetags/bst_category.py b/sounds/templatetags/bst_category.py index 9854382935..97585f4e48 100644 --- a/sounds/templatetags/bst_category.py +++ b/sounds/templatetags/bst_category.py @@ -41,25 +41,20 @@ def bst_taxonomy_category_names_to_category_key(top_level_name, second_level_nam if top_level_name is None: return None - # Find the top-level key - top_level_key = None - for category_key, val in settings.BROAD_SOUND_TAXONOMY.items(): - if val.get("level") == 1 and val.get('name') == top_level_name: - top_level_key = category_key - break - if top_level_key is None: + try: + top_level_code = [key for key, value in settings.BROAD_SOUND_TAXONOMY.items() if value['level'] == 1 and value['name'] == top_level_name][0] + except IndexError: return None if second_level_name is None: - return top_level_key + return top_level_code - # Find second-level key under the correct top-level category - for category_key, val in settings.BROAD_SOUND_TAXONOMY.items(): - if category_key.startswith(f"{top_level_key}-") and val.get('name') == second_level_name: - return category_key + try: + second_level_code = [key for key, value in settings.BROAD_SOUND_TAXONOMY.items() if value['level'] == 2 and value['name'] == second_level_name and key.startswith(f'{top_level_code}-')][0] + except IndexError: + return None - # If no matching second-level category, return just the top-level key - return top_level_key + return second_level_code @register.filter def get_bst_taxonomy_top_level_category_key(value):