diff --git a/_docs/api/source/resources.rst b/_docs/api/source/resources.rst index 6c5c1259c..6554b231a 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 `_ (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). -``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. ====================== ============= ==================================================== @@ -482,43 +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. -``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``. @@ -688,6 +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 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". @@ -695,8 +701,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 +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 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". @@ -877,6 +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 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". diff --git a/apiv2/examples.py b/apiv2/examples.py index 30709c522..c7db766e5 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/\'']), diff --git a/apiv2/serializers.py b/apiv2/serializers.py index 4c553d033..bb57a81c6 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,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 @@ -90,6 +90,8 @@ class Meta: 'tags', 'description', 'category', + 'category_code', + 'category_is_user_provided', 'geotag', 'created', 'license', @@ -169,6 +171,14 @@ 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): + return obj.bst_category is not None pack = serializers.SerializerMethodField() def get_pack(self, obj): diff --git a/freesound/settings.py b/freesound/settings.py index 5df0a4415..e70d019e3 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."}, diff --git a/sounds/models.py b/sounds/models.py index b4c61bc1e..6a905b012 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: @@ -1299,6 +1299,10 @@ def category_names(self): pass return [None, None] return bst_taxonomy_category_key_to_category_names(self.bst_category) + + @property + def category_code(self): + 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 df84717b9..97585f4e4 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,29 @@ 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 + + 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_code + + 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 + + return second_level_code @register.filter def get_bst_taxonomy_top_level_category_key(value):