Brought back the option to output files for embeddings (#679)

* .

* embeddings documentation

* audio-speed elements are not hidden in the gui after running embeddings

* file output

* cli argument for file output

* gui with en + de translations

* fix sorting for linter

* removed file type when constructing the name for the embedding output file.
progress on the documentation

* .

* more docu and fixed export filename generation in search script

* added more docu

* fixed errors when db directory selection is cancelled

* removed unnecessary required and default for cli

* .

* added missing translations via copilot and slightly modiefied the test to show the missing keys

* .

* fixed the test

Author: max-mauermann

birdnet_analyzer/cli.py

@@ -428,6 +428,10 @@ def embeddings_parser():
         help="Path to input file or folder.",
     )
 
+    parser.add_argument(
+        "--file_output",
+    )
+
     return parser
 
 

birdnet_analyzer/embeddings/core.py

@@ -8,6 +8,7 @@ def embeddings(
     fmax: int = 15000,
     threads: int = 8,
     batch_size: int = 1,
+    file_output: str | None = None,
 ):
     """
     Generates embeddings for audio files using the BirdNET-Analyzer.
@@ -46,7 +47,7 @@ def embeddings(
     from birdnet_analyzer.utils import ensure_model_exists
 
     ensure_model_exists()
-    run(audio_input, database, overlap, audio_speed, fmin, fmax, threads, batch_size)
+    run(audio_input, database, overlap, audio_speed, fmin, fmax, threads, batch_size, file_output)
 
 
 def get_database(db_path: str):

birdnet_analyzer/embeddings/utils.py

@@ -25,6 +25,7 @@ def analyze_file(item, db: sqlite_usearch_impl.SQLiteUsearchDB):
     Args:
         item: (filepath, config)
     """
+
     # Get file path and restore cfg
     fpath: str = item[0]
     cfg.set_config(item[1])
@@ -124,7 +125,44 @@ def check_database_settings(db: sqlite_usearch_impl.SQLiteUsearchDB):
         db.commit()
 
 
-def run(audio_input, database, overlap, audio_speed, fmin, fmax, threads, batchsize):
+def create_file_output(output_path: str, db: sqlite_usearch_impl.SQLiteUsearchDB):
+    """Creates a file output for the database.
+
+    Args:
+        output_path: Path to the output file.
+        db: Database object.
+    """
+    # Check if output path exists
+    if not os.path.exists(output_path):
+        os.makedirs(output_path)
+    # Get all embeddings
+    embedding_ids = db.get_embedding_ids()
+
+    # Write embeddings to file
+    for embedding_id in embedding_ids:
+        embedding = db.get_embedding(embedding_id)
+        source = db.get_embedding_source(embedding_id)
+
+        # Get start and end time
+        start, end = source.offsets
+
+        source_id = source.source_id.rsplit(".", 1)[0]
+
+        filename = f"{source_id}_{start}_{end}.birdnet.embeddings.txt"
+
+        # Get the common prefix between the output path and the filename
+        common_prefix = os.path.commonpath([output_path, os.path.dirname(filename)])
+        relative_filename = os.path.relpath(filename, common_prefix)
+        target_path = os.path.join(output_path, relative_filename)
+
+        # Ensure the target directory exists
+        os.makedirs(os.path.dirname(target_path), exist_ok=True)
+
+        # Write embedding values to a text file
+        with open(target_path, "w") as f:
+            f.write(",".join(map(str, embedding.tolist())))
+
+def run(audio_input, database, overlap, audio_speed, fmin, fmax, threads, batchsize, file_output):
     ### Make sure to comment out appropriately if you are not using args. ###
 
     # Set input and output path
@@ -176,4 +214,7 @@ def run(audio_input, database, overlap, audio_speed, fmin, fmax, threads, batchs
         with Pool(cfg.CPU_THREADS) as p:
             tqdm(p.imap(partial(analyze_file, db=db), flist))
 
+    if file_output:
+        create_file_output(file_output, db)
+
     db.db.close()

birdnet_analyzer/gui/embeddings.py

@@ -10,7 +10,7 @@
 from birdnet_analyzer.search.core import get_database as get_search_database
 
 SCRIPT_DIR = os.path.abspath(os.path.dirname(__file__))
-PAGE_SIZE = 4
+PAGE_SIZE = 6
 
 
 def play_audio(audio_infos):
@@ -37,7 +37,7 @@ def update_export_state(audio_infos, checkbox_value, export_state: dict):
     return export_state
 
 
-def rum_embeddings_with_tqdm_tracking(
+def run_embeddings_with_tqdm_tracking(
     input_path,
     db_directory,
     db_name,
@@ -47,6 +47,7 @@ def rum_embeddings_with_tqdm_tracking(
     audio_speed,
     fmin,
     fmax,
+    file_output,
     progress=gr.Progress(track_tqdm=True),
 ):
     return run_embeddings(
@@ -59,6 +60,7 @@ def rum_embeddings_with_tqdm_tracking(
         audio_speed,
         fmin,
         fmax,
+        file_output,
         progress,
     )
 
@@ -74,6 +76,7 @@ def run_embeddings(
     audio_speed,
     fmin,
     fmax,
+    file_output,
     progress,
 ):
     from birdnet_analyzer.embeddings.utils import run
@@ -97,6 +100,7 @@ def run_embeddings(
             settings["BANDPASS_FMAX"],
             threads,
             batch_size,
+            file_output,
         )
     except Exception as e:
         db.db.close()
@@ -106,11 +110,11 @@ def run_embeddings(
         if fmin is None or fmax is None or fmin < cfg.SIG_FMIN or fmax > cfg.SIG_FMAX or fmin > fmax:
             raise gr.Error(f"{loc.localize('validation-no-valid-frequency')} [{cfg.SIG_FMIN}, {cfg.SIG_FMAX}]") from e
 
-        run(input_path, db_path, overlap, audio_speed, fmin, fmax, threads, batch_size)
+        run(input_path, db_path, overlap, audio_speed, fmin, fmax, threads, batch_size, file_output)
 
     gr.Info(f"{loc.localize('embeddings-tab-finish-info')} {db_path}")
 
-    return gr.Plot(), gr.Slider(visible=False), gr.Number(visible=False), gr.Number(visible=False)
+    return gr.Plot(), gr.Slider(interactive=False), gr.Number(interactive=False), gr.Number(interactive=False)
 
 
 @gu.gui_runtime_error_handler
@@ -275,7 +279,7 @@ def select_directory_and_update_tb(db_name):
                     gr.Number(interactive=True),
                 )
 
-            return None, None, gr.Slider(interactive=True), gr.Number(interactive=True), gr.Number(interactive=True)
+            return None, gr.Textbox(visible=False), gr.Slider(interactive=True), gr.Number(interactive=True), gr.Number(interactive=True)
 
         select_db_directory_btn.click(
             select_directory_and_update_tb,
@@ -284,6 +288,32 @@ def select_directory_and_update_tb(db_name):
             show_progress=False,
         )
 
+        with gr.Accordion(loc.localize("embedding-file-output-accordion-label"), open=False):
+            with gr.Row():
+                select_file_output_directory_btn = gr.Button(loc.localize("embeddings-select-file-output-directory-button-label"))
+
+            with gr.Row():
+                file_output_tb = gr.Textbox(
+                    value=None,
+                    placeholder=loc.localize("embeddings-tab-file-output-directory-textbox-placeholder"),
+                    interactive=True,
+                    label=loc.localize("embeddings-tab-file-output-directory-textbox-label"),
+                )
+
+        def select_file_output_directory_and_update_tb():
+            dir_name = gu.select_directory(state_key="embeddings-file-output-dir", collect_files=False)
+
+            if dir_name:
+                return dir_name
+
+            return None
+
+        select_file_output_directory_btn.click(
+            select_file_output_directory_and_update_tb,
+            inputs=[],
+            outputs=[file_output_tb],
+        )
+
         def check_settings(dir_name, db_name):
             db_path = os.path.join(dir_name, db_name)
 
@@ -316,7 +346,7 @@ def check_settings(dir_name, db_name):
         start_btn = gr.Button(loc.localize("embeddings-tab-start-button-label"), variant="huggingface")
 
         start_btn.click(
-            rum_embeddings_with_tqdm_tracking,
+            run_embeddings_with_tqdm_tracking,
             inputs=[
                 input_directory_state,
                 db_directory_state,
@@ -327,10 +357,10 @@ def check_settings(dir_name, db_name):
                 audio_speed_slider,
                 fmin_number,
                 fmax_number,
+                file_output_tb,
             ],
             outputs=[progress_plot, audio_speed_slider, fmin_number, fmax_number],
             show_progress_on=progress_plot,
-            show_progress=True,
         )
 
 
@@ -409,17 +439,6 @@ def _build_search_tab():
                     value="cosine",
                     interactive=True,
                 )
-                max_samples_number = gr.Number(
-                    label=loc.localize("embeddings-search-max-samples-number-label"),
-                    value=10,
-                    interactive=True,
-                )
-                score_fn_select = gr.Radio(
-                    label=loc.localize("embeddings-search-score-fn-select-label"),
-                    choices=["cosine", "dot", "euclidean"],
-                    value="cosine",
-                    interactive=True,
-                )
                 search_btn = gr.Button(loc.localize("embeddings-search-start-button-label"), variant="huggingface")
 
             with gr.Column():

birdnet_analyzer/lang/de.json

@@ -18,6 +18,10 @@
     "embeddings-db-already-exists-info": "Die Datenbank ist bereits vorhanden, wobei die Optionen für Audiogeschwindigkeit und Bandpassfilter aus den Datenbankeinstellungen verwendet werden.",
     "embeddings-db-dir-validation-message": "Bitte wählen Sie ein Datenbankverzeichnis aus",
     "embeddings-db-name-validation-message": "Bitte geben Sie einen Namen für die Datenbank an",
+    "embedding-file-output-accordion-label": "Dateiausgabe",
+    "embeddings-tab-file-output-directory-textbox-placeholder": "Wenn nicht ausgewählt, werden keine Ausgabedateien erzeugt.",
+    "embeddings-tab-file-output-directory-textbox-label": "Ausgabeverzeichnis",
+    "embeddings-select-file-output-directory-button-label": "Ausgabeverzeichnis auswählen",
     "embeddings-extract-tab-title": "Extrahieren",
     "embeddings-input-dir-validation-message": "Bitte wählen Sie ein Eingabeverzeichnis aus",
     "embeddings-search-crop-mode-radio-info": "Anpassen, wie das Abfrage Beispiel zugeschnitten wird, falls es länger als der Modellinput ist.",

birdnet_analyzer/lang/en.json

@@ -18,6 +18,10 @@
     "embeddings-db-already-exists-info": "Database already exists, using audio speed and bandpass filter options from database settings.",
     "embeddings-db-dir-validation-message": "Please select a directory for the database",
     "embeddings-db-name-validation-message": "Please specify a name for the database",
+    "embedding-file-output-accordion-label": "File output settings",
+    "embeddings-tab-file-output-directory-textbox-placeholder": "If not selected, file output will be omitted.",
+    "embeddings-tab-file-output-directory-textbox-label": "File output directory",
+    "embeddings-select-file-output-directory-button-label": "Select file output directory",
     "embeddings-extract-tab-title": "Extract",
     "embeddings-input-dir-validation-message": "Please select an input directory",
     "embeddings-search-crop-mode-radio-info": "Adjust how to crop the query sample if it is longer than the model input.",

birdnet_analyzer/lang/fi.json

@@ -49,6 +49,10 @@
     "embeddings-tab-select-input-directory-button-label": "Valitse syötehakemisto (rekursiivinen)",
     "embeddings-tab-start-button-label": "Poimi upotukset",
     "embeddings-tab-title": "Upotukset",
+    "embedding-file-output-accordion-label": "Tiedostotulosteen asetukset",
+    "embeddings-tab-file-output-directory-textbox-placeholder": "Jos ei valittu, tiedostotulostetta ei luoda.",
+    "embeddings-tab-file-output-directory-textbox-label": "Tiedostotulosteen hakemisto",
+    "embeddings-select-file-output-directory-button-label": "Valitse tiedostotulosteen hakemisto",
     "eval-tab-accuracy-checkbox-info": "Tarkkuus mittaa mallin oikeiden ennusteiden prosenttiosuutta.",
     "eval-tab-annotation-col-accordion-label": "Merkintäsarakkeet",
     "eval-tab-annotation-selection-button-label": "Valitse merkintäkansio",

birdnet_analyzer/lang/fr.json

@@ -49,6 +49,10 @@
     "embeddings-tab-select-input-directory-button-label": "Sélectionner le répertoire d'entrée (récursif)",
     "embeddings-tab-start-button-label": "Extraire les incorporations",
     "embeddings-tab-title": "Incorporations",
+    "embedding-file-output-accordion-label": "Paramètres de sortie de fichier",
+    "embeddings-tab-file-output-directory-textbox-placeholder": "Si non sélectionné, la sortie de fichier sera omise.",
+    "embeddings-tab-file-output-directory-textbox-label": "Répertoire de sortie de fichier",
+    "embeddings-select-file-output-directory-button-label": "Sélectionner le répertoire de sortie de fichier",
     "eval-tab-accuracy-checkbox-info": "La précision mesure le pourcentage de prédictions correctes faites par le modèle.",
     "eval-tab-annotation-col-accordion-label": "Colonnes d'annotation",
     "eval-tab-annotation-selection-button-label": "Sélectionner le répertoire d'annotations",

birdnet_analyzer/lang/id.json

@@ -49,6 +49,10 @@
     "embeddings-tab-select-input-directory-button-label": "Pilih direktori input (rekursif)",
     "embeddings-tab-start-button-label": "Ekstrak embedding",
     "embeddings-tab-title": "Embedding",
+    "embedding-file-output-accordion-label": "Pengaturan file output",
+    "embeddings-tab-file-output-directory-textbox-placeholder": "Jika tidak dipilih, file output akan diabaikan.",
+    "embeddings-tab-file-output-directory-textbox-label": "Direktori file output",
+    "embeddings-select-file-output-directory-button-label": "Pilih direktori file output",
     "eval-tab-accuracy-checkbox-info": "Akurasi mengukur persentase prediksi benar yang dibuat oleh model.",
     "eval-tab-annotation-col-accordion-label": "Kolom anotasi",
     "eval-tab-annotation-selection-button-label": "Pilih direktori anotasi",

birdnet_analyzer/lang/pt-br.json

@@ -49,6 +49,10 @@
     "embeddings-tab-select-input-directory-button-label": "Selecionar diretório de entrada (recursivo)",
     "embeddings-tab-start-button-label": "Extrair embeddings",
     "embeddings-tab-title": "Embeddings",
+    "embedding-file-output-accordion-label": "Configurações de saída de arquivo",
+    "embeddings-tab-file-output-directory-textbox-placeholder": "Se não selecionado, a saída de arquivo será omitida.",
+    "embeddings-tab-file-output-directory-textbox-label": "Diretório de saída de arquivo",
+    "embeddings-select-file-output-directory-button-label": "Selecionar diretório de saída de arquivo",
     "eval-tab-accuracy-checkbox-info": "A precisão mede a porcentagem de previsões corretas feitas pelo modelo.",
     "eval-tab-annotation-col-accordion-label": "Colunas de anotação",
     "eval-tab-annotation-selection-button-label": "Selecionar diretório de anotações",

birdnet_analyzer/lang/ru.json

@@ -49,6 +49,10 @@
     "embeddings-tab-select-input-directory-button-label": "Выбрать входную папку (рекурсивно)",
     "embeddings-tab-start-button-label": "Извлечь эмбеддинги",
     "embeddings-tab-title": "Эмбеддинги",
+    "embedding-file-output-accordion-label": "Настройки вывода файлов",
+    "embeddings-tab-file-output-directory-textbox-placeholder": "Если не выбрано, вывод файлов будет пропущен.",
+    "embeddings-tab-file-output-directory-textbox-label": "Каталог вывода файлов",
+    "embeddings-select-file-output-directory-button-label": "Выбрать каталог вывода файлов",
     "eval-tab-accuracy-checkbox-info": "Точность измеряет процент правильных прогнозов, сделанных моделью.",
     "eval-tab-annotation-col-accordion-label": "Колонки аннотаций",
     "eval-tab-annotation-selection-button-label": "Выбрать каталог аннотаций",

birdnet_analyzer/lang/se.json

@@ -49,6 +49,10 @@
     "embeddings-tab-select-input-directory-button-label": "Välj indatakatalog (rekursiv)",
     "embeddings-tab-start-button-label": "Extrahera inbäddningar",
     "embeddings-tab-title": "Inbäddningar",
+    "embedding-file-output-accordion-label": "Filutdata-inställningar",
+    "embeddings-tab-file-output-directory-textbox-placeholder": "Om inte vald, kommer filutdata att utelämnas.",
+    "embeddings-tab-file-output-directory-textbox-label": "Filutdatakatalog",
+    "embeddings-select-file-output-directory-button-label": "Välj filutdatakatalog",
     "eval-tab-accuracy-checkbox-info": "Noggrannhet mäter procentandelen korrekta förutsägelser som modellen gör.",
     "eval-tab-annotation-col-accordion-label": "Anteckningskolumner",
     "eval-tab-annotation-selection-button-label": "Välj anteckningskatalog",

birdnet_analyzer/lang/tlh.json

@@ -49,6 +49,10 @@
     "embeddings-tab-select-input-directory-button-label": "wav Daq yIwIv (rap)",
     "embeddings-tab-start-button-label": "qelmey yInob",
     "embeddings-tab-title": "qelmey",
+    "embedding-file-output-accordion-label": "wavmey chu' chut mutlh",
+    "embeddings-tab-file-output-directory-textbox-placeholder": "wIvHa'chugh, wavmey chu'Ha'.",
+    "embeddings-tab-file-output-directory-textbox-label": "wavmey chu' Daq",
+    "embeddings-select-file-output-directory-button-label": "wavmey chu' Daq yIwIv",
     "eval-tab-accuracy-checkbox-info": "qel patlh vIt.",
     "eval-tab-annotation-col-accordion-label": "QInmey",
     "eval-tab-annotation-selection-button-label": "QIn Daq yIwIv",

birdnet_analyzer/lang/zh_TW.json

@@ -49,6 +49,10 @@
     "embeddings-tab-select-input-directory-button-label": "選擇輸入目錄（遞歸）",
     "embeddings-tab-start-button-label": "提取嵌入",
     "embeddings-tab-title": "嵌入",
+    "embedding-file-output-accordion-label": "檔案輸出設定",
+    "embeddings-tab-file-output-directory-textbox-placeholder": "若無選擇，將不進行檔案輸出。",
+    "embeddings-tab-file-output-directory-textbox-label": "檔案輸出資料夾",
+    "embeddings-select-file-output-directory-button-label": "選擇檔案輸出資料夾",
     "eval-tab-accuracy-checkbox-info": "準確度測量模型做出正確預測的百分比。",
     "eval-tab-annotation-col-accordion-label": "註釋欄位",
     "eval-tab-annotation-selection-button-label": "選擇註釋目錄",

birdnet_analyzer/search/core.py

@@ -68,7 +68,7 @@ def search(
         offset = embedding_source.offsets[0] * audio_speed
         duration = cfg.SIG_LENGTH * audio_speed
         sig, rate = audio.open_audio_file(file, offset=offset, duration=duration, sample_rate=None)
-        result_path = os.path.join(output, f"{file[4]:.5f}_{filebasename}_{offset}_{offset + duration}.wav")
+        result_path = os.path.join(output, f"{r.sort_score:.5f}_{filebasename}_{offset}_{offset + duration}.wav")
         audio.save_signal(sig, result_path, rate)
 
 

docs/best-practices.rst

@@ -6,4 +6,5 @@ Best practices
 
    best-practices/species-lists
    best-practices/segment-review
-   best-practices/training
+   best-practices/training
+   best-practices/embeddings