Merge pull request #2124 from MTG/bst-improvements

Broad Sound Taoxnomy improvements

Author: ffont

_docs/bst_description_v1.1_250725.csv

@@ -0,0 +1,34 @@
+class_key,class_key_long,top_level,second_level,description,examples
+m,M,Music,,"Music excerpts, including melodies, singing, loops, fillers, drones, and short musical snippets.",
+m-sp,M/Solo-perc.,Music,Solo percussion,Music excerpts with solo percussive instruments.,"rhythmic patterns, unpitched percussion excerpt, drum passage, drum loop"
+m-si,M/Solo-instr.,Music,Solo instrument,"Music excerpts with only one instrument, excluding percussion.","isolated melody or sequence of notes, solo singing, chords from one instrument"
+m-m,M/Multi,Music,Multiple instruments,Music excerpts with more than one instrument.,"orchestra, band, duet, multi-instrument composition or loop"
+m-other,M/Other,Music,Other,Music that doesn't belong to any of the above categories.,
+is,Is,Instrument samples,,"Single notes from musical instruments, various versions of the same note, and scales.",
+is-p,Is/Perc.,Instrument samples,Percussion,Instrument samples that are percussive (idiophones or membraphones).,"drum, snare, gong, bell, xylophone"
+is-s,Is/String,Instrument samples,String,Instrument samples that belong to the string instrument family.,"guitar, violin, harp, mandolin"
+is-w,Is/Wind,Instrument samples,Wind,Instrument samples that belong to the wind instrument family (aerophones).,"woodwind, brass, flute, trumpet, saxophone"
+is-k,Is/Keyb.,Instrument samples,Piano / Keyboard instruments,"Instrument samples of piano or other keyboard instruments, not synthesized.","piano, harspichord, organ"
+is-e,Is/Electr.,Instrument samples,Synths / Electronic,Instrument samples synthesized or produced by electronic means.,"synthesizers (analog/digital), synthesized or electronic samples"
+is-other,Is/Other,Instrument samples,Other,Instrument samples that don't belong to any of the above categories.,
+sp,Sp,Speech,,Sounds where human voice is prominent.,
+sp-s,Sp/Solo,Speech,Solo speech,"Recording of a single voice speaking, excluding singing.","talking, script reading"
+sp-c,Sp/Crowd,Speech,Conversation / Crowd,"Several people talking, having a conversation or dialogue.","playground, people talking in public places, conversations"
+sp-p,Sp/Proc.,Speech,Processed / Synthetic,"Voice(s) from an indirect source (e.g. radio), heavily processed, or synthesized.","phone/radio recordings, robotic voice, text-to-speech"
+sp-other,Sp/Other,Speech,Other,Voice-predominant recordings that don't belong to any of the above categories.,
+fx,Fx,Sound effects,,"Isolated sound effects or sound events, each happening one at a time.",
+fx-o,Fx/Objects,Sound effects,Objects / House appliances,"Everyday objects, inside the home or smaller in size.","daily or small objects, tools, weapons, clothes, iron"
+fx-v,Fx/Vehicles,Sound effects,Vehicles,Sounds produced from a vehicle.,"car passing by, car screeching, wiper, car break, bike, plane, ship"
+fx-m,Fx/Machines,Sound effects,"Other mechanisms, engines, machines","Machine-like sounds, except vehicles and small house electric devices.","drill, lawn mower, gear, electric chainsaw"
+fx-h,Fx/Human,Sound effects,Human sounds and actions,"Sounds from the human body, excluding speech.","breath, heartbeat, sneeze, crying, walking, clapping"
+fx-a,Fx/Animals,Sound effects,Animals,Animal vocalizations or sounds.,"cat, insect, sheep, animal walk, growl, purr"
+fx-n,Fx/Natural,Sound effects,Natural elements and explosions,Sound events occuring by natural processes.,"single gusts of wind, fire flames, ice cracks, rocks, water splash, stones, explosions"
+fx-ex,Fx/Exper.,Sound effects,Experimental,Experimental sounds or heavily processed audio recordings.,"reversed sounds, weird effects, unusual record techniques or processing"
+fx-el,Fx/Electr.,Sound effects,Electronic / Design,Sound effects that are computer-made or designed for user interfaces or animations.,"sci-fi, laser, whoosh, boink, cartoon, ui, sound alerts or notifications"
+fx-other,Fx/Other,Sound effects,Other,Sound effects that don't belong to any of the above categories.,
+ss,Ss,Soundscapes,,"Ambiances, field-recordings with multiple events and sound environments.",
+ss-n,Ss/Nature,Soundscapes,Nature,Soundscapes from natural habitats.,"forest ambiance, seaside, river with surrounding nature, farmland"
+ss-i,Ss/Indoors,Soundscapes,Indoors,Soundscapes from closed or indoor spaces.,"closed room ambience, room tone, office, factory, bar"
+ss-u,Ss/Urban,Soundscapes,Urban,Soundscapes from cityscapes or outdoor places with human intervention.,"city ambience, outside airport, busy road"
+ss-s,Ss/Synth.,Soundscapes,Synthetic / Artificial,Soundscapes that are synthesized or computer-made ambiences.,"artificially-created soundscapes, soundscapes from imaginary places"
+ss-other,Ss/Other,Soundscapes,Other,Soundscapes that don't belong to any of the above categories.,

freesound/settings.py

@@ -417,194 +417,33 @@
 ANNOUNCEMENT_CACHE_KEY = "announcement_cache"
 
 # -------------------------------------------------------------------------------
-# Broad Sound Taxonomy definition (internal v1.1 of BST description)
-
-BROAD_SOUND_TAXONOMY = {
-    "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.",
-        "examples": "rhythmic patterns, unpitched percussion excerpts, drum passages",
-    },
-    "m-si": {
-        "level": 2,
-        "name": "Solo instrument",
-        "description": "Music excerpts with only one instrument, excluding percussion.",
-        "examples": "isolated melody or sequence of notes, solo singing, chords from one instrument",
-    },
-    "m-m": {
-        "level": 2,
-        "name": "Multiple instruments",
-        "description": "Music excerpts with more than one instrument.",
-        "examples": "orchestra, band, dueto, multi-instrument composition, multi-instrument loops",
-    },
-    "m-other": {
-        "level": 2,
-        "name": "Other",
-        "description": "Music that doesn't belong to any of the above categories.",
-    },
-    "is": {
-        "level": 1,
-        "name": "Instrument samples",
-        "description": "Single notes from musical instruments, various versions of the same note, and scales.",
-    },
-    "is-p": {
-        "level": 2,
-        "name": "Percussion",
-        "description": "Instrument samples that are percussive (idiophones or membraphones).",
-        "examples": "drum, snare, gong, bell, xylophone",
-    },
-    "is-s": {
-        "level": 2,
-        "name": "String",
-        "description": "Instrument samples that belong to the string instrument family.",
-        "examples": "guitar, violin, harp, mandolin",
-    },
-    "is-w": {
-        "level": 2,
-        "name": "Wind",
-        "description": "Instrument samples that belong to the wind instrument family (aerophones).",
-        "examples": "woodwind, brass, flute, trumpet, saxophone",
-    },
-    "is-k": {
-        "level": 2,
-        "name": "Piano / Keyboard instruments",
-        "description": "Instrument samples of piano or other keyboard instruments, not synthesized.",
-        "examples": "piano, harspichord, organ",
-    },
-    "is-e": {
-        "level": 2,
-        "name": "Synths / Electronic",
-        "description": "Instrument samples synthesized or produced by electronic means.",
-        "examples": "synthesizers (analog/digital), synthesized or electronic samples",
-    },
-    "is-other": {
-        "level": 2,
-        "name": "Other",
-        "description": "Instrument samples that don't belong to any of the above categories.",
-    },
-    "sp": {"level": 1, "name": "Speech", "description": "Sounds where human voice is prominent."},
-    "sp-s": {
-        "level": 2,
-        "name": "Solo speech",
-        "description": "Recording of a single voice speaking, excluding singing.",
-        "examples": "talking, script reading",
-    },
-    "sp-c": {
-        "level": 2,
-        "name": "Conversation / Crowd",
-        "description": "Several people talking, having a conversation or dialogue.",
-        "examples": "playground, people talking in public places, conversations",
-    },
-    "sp-p": {
-        "level": 2,
-        "name": "Processed / Synthetic",
-        "description": "Voice(s) from an indirect source (e.g. radio), heavily processed, or synthesized.",
-        "examples": "phone/radio recordings, robotic voice, text-to-speech",
-    },
-    "sp-other": {
-        "level": 2,
-        "name": "Other",
-        "description": "Voice-predominant recordings that don't belong to any of the above categories.",
-    },
-    "fx": {
-        "level": 1,
-        "name": "Sound effects",
-        "description": "Isolated sound effects or sound events, each happening one at a time.",
-    },
-    "fx-o": {
-        "level": 2,
-        "name": "Objects / House appliances",
-        "description": "Everyday objects, inside the home or smaller in size.",
-        "examples": "daily or small objects, tools, weapons, clothes, iron",
-    },
-    "fx-v": {
-        "level": 2,
-        "name": "Vehicles",
-        "description": "Sounds produced from a vehicle.",
-        "examples": "car passing by, car screeching, wiper, car brake, bike, plane, ship",
-    },
-    "fx-m": {
-        "level": 2,
-        "name": "Other mechanisms, engines, machines",
-        "description": "Machine-like sounds, except vehicles and small house electric devices.",
-        "examples": "drill, lawn mower, gear, electric chainsaw",
-    },
-    "fx-h": {
-        "level": 2,
-        "name": "Human sounds and actions",
-        "description": "Sounds from the human body, excluding speech.",
-        "examples": "breath, hearthbeat, sneeze, crying, walking, clapping",
-    },
-    "fx-a": {
-        "level": 2,
-        "name": "Animals",
-        "description": "Animal vocalizations or sounds.",
-        "examples": "cat, insect, sheep, animal walk, growl, purr",
-    },
-    "fx-n": {
-        "level": 2,
-        "name": "Natural elements and explosions",
-        "description": "Sound events occurring by natural processes.",
-        "examples": "wind, fire, ice, rocks, water, stones, explosions",
-    },
-    "fx-ex": {
-        "level": 2,
-        "name": "Experimental",
-        "description": "Experimental sounds or heavily processed audio recordings.",
-        "examples": "reversed sounds, weird effects, unusual recording techniques or processing",
-    },
-    "fx-el": {
-        "level": 2,
-        "name": "Electronic / Design",
-        "description": "Sound effects that are computer-made or designed for user interfaces or animations.",
-        "examples": "sci-fi, laser, whoosh, boink, cartoon, ui, sound alerts or notifications",
-    },
-    "fx-other": {
-        "level": 2,
-        "name": "Other",
-        "description": "Sound effects that don't belong to any of the above categories.",
-    },
-    "ss": {
-        "level": 1,
-        "name": "Soundscapes",
-        "description": "Ambiances, field-recordings with multiple events and sound environments.",
-    },
-    "ss-n": {
-        "level": 2,
-        "name": "Nature",
-        "description": "Soundscapes from natural habitats.",
-        "examples": "forest ambiance, seaside, river with surrounding nature, farmland",
-    },
-    "ss-i": {
-        "level": 2,
-        "name": "Indoors",
-        "description": "Soundscapes from closed or indoor spaces.",
-        "examples": "closed room ambience, room tone, office, factory, bar",
-    },
-    "ss-u": {
-        "level": 2,
-        "name": "Urban",
-        "description": "Soundscapes from cityscapes or outdoor places with human intervention.",
-        "examples": "city ambience, outside airport, busy road",
-    },
-    "ss-s": {
-        "level": 2,
-        "name": "Synthetic / Artificial",
-        "description": "Soundscapes that are synthesized or computer-made ambiences.",
-        "examples": "artificially-created soundscapes, soundscapes from imaginary places",
-    },
-    "ss-other": {
-        "level": 2,
-        "name": "Other",
-        "description": "Soundscapes that don't belong to any of the above categories.",
-    },
-}
+# Broad Sound Taxonomy definition
+
+
+def load_broad_sound_taxonomy_from_csv(path):
+    import csv
+
+    taxonomy = {}
+    with open(path, newline="", encoding="utf-8") as csvfile:
+        reader = csv.DictReader(csvfile)
+        for row in reader:
+            key = row["class_key"]
+            taxonomy[key] = {
+                "level": 2 if "-" in key else 1,
+                "name": row["second_level"] if "-" in key else row["top_level"],
+                "top_level": row["top_level"],
+                "second_level": row["second_level"],
+                "description": row["description"],
+                "examples": row.get("examples", ""),
+            }
+    return taxonomy
+
+
+BROAD_SOUND_TAXONOMY_CSV_FILENAME = "bst_description_v1.1_250725.csv"
+BROAD_SOUND_TAXONOMY_CSV_DEFINITION_PATH = os.path.join(
+    os.path.dirname(__file__), "../_docs/", BROAD_SOUND_TAXONOMY_CSV_FILENAME
+)
+BROAD_SOUND_TAXONOMY = load_broad_sound_taxonomy_from_csv(BROAD_SOUND_TAXONOMY_CSV_DEFINITION_PATH)
 
 BST_CATEGORY_CHOICES = [
     (key, value["name"]) for key, value in BROAD_SOUND_TAXONOMY.items() if "-" not in key

freesound/static/bw-frontend/styles/pages/index.scss

@@ -12,3 +12,4 @@
 @import 'upload';
 @import 'bulkDescribe';
 @import 'moderation';
+@import 'taxonomy';

freesound/static/bw-frontend/styles/pages/taxonomy.scss

@@ -0,0 +1,40 @@
+.bst-taxonomy{
+    .node {
+
+        padding: 5px;
+        border-radius: 5px;
+        margin: 5px;
+        text-align: center;
+
+        &.topcat {
+            color: white;
+            font-weight: bold;
+            font-size: 120%;
+            padding: 10px;
+            
+        }
+
+        &.subcat {
+            position: relative;
+            overflow: hidden;
+            color: black;
+
+            // Apply brightness only to a background layer, not to text.
+            &::before {
+                content: "";
+                position: absolute;
+                inset: 0;
+                background-color: inherit;
+                border-radius: inherit;
+                filter: brightness(160%);
+                pointer-events: none;
+            }
+ 
+            .label {
+                position: relative;
+                z-index: 1;
+            }
+        }
+    }
+}
+

freesound/urls.py

@@ -136,6 +136,7 @@
     ),
     path("", include("ratings.urls")),
     path("comments/", include("comments.urls")),
+    path("help/broad-sound-taxonomy/", sounds.views.broad_sound_taxonomy_info_page, name="bst-info-page"),
     path("help/", include("wiki.urls")),
     path("forum/", include("forum.urls")),
     path("geotags/", include("geotags.urls")),

general/templatetags/util.py

@@ -119,6 +119,11 @@ def element_at_index(l, index):
     return l[index]
 
 
+@register.filter
+def dict_element(d, key):
+    return d[key]
+
+
 @register.filter
 def strip_unnecessary_br(value):
     # In HTMLCleaningFields some HTML tags are allowed. When the contents of these fields are passed to Django's |linebreaks

sounds/forms.py

@@ -274,7 +274,7 @@ class SoundEditAndDescribeForm(forms.Form):
     bst_category = forms.ChoiceField(
         choices=settings.BST_SUBCATEGORY_CHOICES,
         help_text="Choose the most appropriate <i>Category</i> and <i>Subcategory</i> for the sound. "
-        'These categories come from the <a class="bw-link--grey" href="/help/faq/#the-broad-sound-taxonomy">Broad Sound Taxonomy</a>, '
+        'These categories come from the <a class="bw-link--grey" href="/help/broad-sound-taxonomy">Broad Sound Taxonomy</a>, '
         "and are used to improve Freesound search capabilities.",
         error_messages={"invalid_choice": "Please select a valid category and a subcategory."},
         required=True,

sounds/templatetags/bst_category.py

@@ -71,8 +71,7 @@ def bst_taxonomy_category_names_to_category_key(top_level_name, second_level_nam
 @register.filter
 def get_bst_taxonomy_top_level_category_key(value):
     """
-    Extract the top level category key from the given value.
-    The top level category is the part before the '-' in value.
+    Extract the top level category key from the given value. The top level category is the part before the '-' in value.
     E.g.: "m-sp" -> "m"
     """
     return value.split("-")[0] if "-" in value else value
@@ -81,7 +80,10 @@ def get_bst_taxonomy_top_level_category_key(value):
 @register.filter
 def get_bst_taxonomy_description(value):
     """
-    Return BST taxonomy class description for a given taxonomy
-    cateogory/subcategory key.
+    Return BST taxonomy class description for a given taxonomy category/subcategory key.
     """
-    return settings.BROAD_SOUND_TAXONOMY[value]["description"]
+    bst_node_data = settings.BROAD_SOUND_TAXONOMY[value]
+    if bst_node_data["examples"]:
+        return f'{bst_node_data["description"]} <span class="text-light-grey">E.g. {bst_node_data["examples"]}.</span>'
+    else:
+        return bst_node_data["description"]

sounds/views.py

@@ -1279,3 +1279,24 @@ def pack_downloaders(request, username, pack_id):
     tvars = {"username": username, "pack": pack, "download_list": download_list}
     tvars.update(pagination)
     return render(request, "sounds/modal_downloaders.html", tvars)
+
+
+def broad_sound_taxonomy_info_page(request):
+    # Note: the colors below are currently hard-coded here, but in the future they should be
+    # added to the CSV file that defines the taxonomy and loaded from there.
+    taxonomy_node_colors = {
+        "m": "rgb(228,34,30)",
+        "is": "rgb(249,164,48)",
+        "sp": "rgb(39,161,132)",
+        "fx": "rgb(20,107,173)",
+        "ss": "rgb(50,167,40)",
+    }
+    taxonomy = settings.BROAD_SOUND_TAXONOMY
+    for key, node in taxonomy.items():
+        if key in taxonomy_node_colors:
+            node["color"] = taxonomy_node_colors[key]
+    tvars = {
+        "bst": taxonomy,
+        "bst_top_level_categories": settings.BST_CATEGORY_CHOICES,
+    }
+    return render(request, "sounds/broad_sound_taxonomy_info_page.html", tvars)

templates/molecules/bst_category_form_field.html

@@ -21,7 +21,7 @@
             {% for value, label in form.fields.bst_category.choices %}
                 <button type="button" class="btn no-hover {% if value == form.bst_category.value %}btn-primary{% else %}btn-inverse{% endif %} btn-subcategory tooltip_top" top_level="{{ value|get_bst_taxonomy_top_level_category_key }}" data_value="{{ value }}">
                     {{ label }}
-                    <span class="tooltiptext">{{ value|get_bst_taxonomy_description }}</span>
+                    <span class="tooltiptext">{{ value|get_bst_taxonomy_description|safe }}</span>
                 </button>
             {% endfor %}
         </div>