bioacoustic-ai/bacpipe: bacpipe v1.3.5 Release Notes

Résumé fourni par la source

🚀 bacpipe v1.3.5 Release Notes bacpipe v1.3.5 is a flexibility & developer-experience release. The AudioHandler becomes a standalone audio tool that no longer needs a loaded model checkpoint, embedding from raw audio arrays gets properly batched (and much faster on GPU), the dashboard learns to display your own annotation tables, and the whole public API now ships with type stubs for real editor autocompletion. On top of that, the accompanying paper is now published in Methods in Ecology and Evolution. 🔥 Key Highlights 🎧 A much more flexible AudioHandler The audio handler is now usable on its own, without loading a single model checkpoint. This means that just by specifying the name of the model, sample rate and segment_length will be set to the characteristic values, without loading the actual model. This speeds things up dramatically if you call the AudioHandler in different places. Values can also be modified, if you want to change them: from bacpipe import get_audio_files, AudioHandler # no checkpoint download, no model instantiation -> much quicker aud = AudioHandler(model='birdnet', audio_dir=bacpipe/tests/test_data') print(aud.model.sr, aud.model.segment_length) # 48000 144000 # optionally change the sr and sampling rate: aud.model.sr = 32_000 aud.model.segment_length = 10 * aud.model.sr files = get_audio_files('bacpipe/tests/test_data') all_frames = [] for audio_file in files: audio, sr = aud.load_and_resample(audio_file) frames = aud.window_audio(audio) all_frames.extend(frames) all_frames = np.stack(all_frames) Pass a model by name. Sample rate and segment length are read straight from the model module (SAMPLE_RATE / LENGTH_IN_SAMPLES) via a lightweight _ModelStub. The real model is lazily loaded only once model-specific preprocessing is needed (i.e. in prepare_audio()), and only once. Inherited model constants are resolved. Models that only subclass another model (e.g. birdaves_especies → aves_especies) are looked up along their MRO, so their sample rate / segment length are found correctly. Override the model defaults at any time with aud.model.sr and aud.model.segment_length. The overridden values are carried over when the real model is loaded later, so audio is preprocessed exactly the way it was loaded. Bring your own annotations: only_load_annotated_segments(file, annotations_df=df) uses a pandas.DataFrame instead of annotations.csv. If the frame has an audiofilename column it is filtered down to the current file automatically, so the whole table can be passed for every file; duplicate (start, end) windows (e.g. two species in one window) are loaded exactly once for both the CSV and the dataframe path. window_audio() handles all the shapes you'd expect: (1, num_samples) long recordings are split into windows, (num_segments, segment_length) stacks are returned as they are, and (num_segments, num_samples) stacks of shorter/longer segments are padded or split into several windows. Friendlier errors: model names go through confirm_model_name (case-insensitive, typos raise a NameError listing all supported models), a broken model module raises an ImportError pointing at that model's requirements, missing constants raise an AttributeError suggesting to pass the model object, and a missing/invalid annotations_df (e.g. no start/end columns) tells you exactly which columns are missing. file_path may now be a str or a Path. ⚡ Batched embedding from audio arrays (renamed API) Embedder.embeddings_using_multithreading() is now Embedder.generate_embeddings_from_audio_array() — a name that says what it does. It also got a lot better: embed_obj = bacpipe.Embedder('naturebeats') embeds = embed_obj.generate_embeddings_from_audio_array(all_frames) The producer thread now preprocesses whole batches of model.batch_size windows instead of one window at a time and moves them to the model device → significantly faster, especially on GPU. Accepts np.ndarray, torch.Tensor and lists, 1D long recordings as well as pre-stacked 2D segment arrays. The progress bar counts batches instead of windows, and failing batches are now really skipped (a missing continue previously let a failed batch fall through into the generic error handler). 🧭 Type hints for the whole public API (new .pyi stubs) Nine stub files (8 new, workflows.pyi extended) now cover the public API for editors like VS Code/Pylance: core/audio_processor.pyi, core/experiment_manager.pyi, core/workflows.pyi, model_pipelines/runner.pyi, embedding_evaluation/benchmark.pyi, clustering/cluster.pyi, label_embeddings.pyi, probing/probe.pyi, probing/inference_probe.pyi. AudioHandler, Loader, get_audio_files, Embedder, Classifier, benchmark, the clustering/probing pipelines and ~70 label/workflow helpers now have signatures, attribute types and return types. The most frequently used **kwargs (e.g. only_embed_annotations, annotations_filename, annotations_df, device, nr_parallel_workers, dim_reduction_model) are declared explicitly as keyword-only parameters, so they are discoverable while typing instead of hiding inside **kwargs. Docstrings are not duplicated — they are still read from the implementation and rendered on hover. Module-level __getattr__ fallbacks keep dynamically set attributes and private helpers from producing false positives. ⚠️ Purely additive: the stubs have no effect on runtime behaviour whatsoever. 📊 The dashboard can now show your own annotation columns New optional annotations_df kwarg for visualize_using_dashboard() (and plot_embeddings_px()). Just make sure your annotations_df has the columns 'audiofilename' and 'start' to ensure the association is clear. annotations_df = pd.read_csv('annotations.csv') annotations_df['annotator'] = 'reviewer_1' annotations_df['recording_site'] = ... bacpipe.visualize_using_dashboard( models=['birdnet'], audio_dir='bacpipe/tests/test_data', annotations_df=annotations_df, ) Every column that is not needed for plotting (annotator, confidence, site, …) is displayed next to the spectrogram of a clicked point. Rows are matched on audiofilename + start, so unsorted or partial tables are fine, segments without a matching row simply show no value, and anything that cannot be aligned is logged as a warning instead of crashing the dashboard. 🪟 Cross-platform annotation matching Embedding file names (from metadata.yml) and annotation tables are now compared with posix separators (posix_audiofilenames(), ensure_windoof_path_to_posix() accepting Path objects), so annotations written on Windows match embeddings created on Linux/macOS and vice versa. 🧩 Custom models in the dashboard visualize_using_dashboard(models=['birdnet', 'my_model'], CustomModels=[None, MyModel]) now works: one class per model name (None for models integrated in bacpipe), with a clear assertion if the two lists don't line up. Previously the plural CustomModels kwarg was forwarded to the name check and custom model names got rejected. 🐛 Bug Fixes Explicit arguments are no longer overwritten by defaults. DashBoard now prefers the value you passed over the config.yaml/settings.yaml default (_prefer_passed_value). A main_results_dir passed by the user used to be silently replaced by the default bacpipe_results, so no embeddings were found. String labels are back in the hover text. convert_numpy_types() returned None for anything that was not np.int64/np.float32/np.ndarray, which silently dropped all string label values. It now converts numpy arrays to lists, all numpy scalars via np.generic.item() (covering np.int32, np.bool_, np.str_, …) and returns everything else unchanged. Hover/click data can no longer get misaligned. The per-point JSON label strings are built in embedding order before the plot dataframe is sorted by label (whole rows are moved), and label arrays whose length does not match the number of embeddings are dropped with a warning instead of silently truncating (and misaligning) all other labels. only_embed_annotations ground truth mixups fixed. Ground truth files of both modes can co

Ce résumé expose les affirmations des auteurs. BNTIC ne l’interprète pas comme une validation indépendante des résultats.