This page describes the internal architecture, deployment workflow, plugin system, and extension mechanisms used by SAMLab. <\/p>\n\n\n\n
Open WAV files, navigate by time, zoom by frequency, adjust dynamic range, and play segments directly from the interface.<\/p>\n<\/div>\n\n\n\n
Select regions in time and frequency, assign categories, edit or delete annotations, and save deployment-level annotation CSV files.<\/p>\n<\/div>\n\n\n\n
Choose one or more automatic analysis plugins, view detected events, and export deployment indicators and detected event tables.<\/p>\n<\/div>\n<\/div>\n\n\n\n
SAMLab is structured around a PySide6 graphical interface, reusable processing modules, and an extensible plugin system. Computational work is moved into Qt worker threads so the interface remains responsive while plugins run.<\/p>\n\n\n\n
Main application<\/strong><\/strong><\/p>\n\n\n\n samlab.py<\/strong> defines the MainWindow class and coordinates the main application workflow, including: menu actions, spectrogram visualisation, deployment navigation, event browsing, audio playback, plugin execution, and manual annotation tools.<\/p>\n\n\n\n The graphical interface integrates matplotlib visualisation widgets with PySide6 controls to provide interactive exploration of large underwater acoustic recordings.<\/p>\n<\/div>\n\n\n\n Core modules<\/strong><\/strong><\/p>\n\n\n\n The modules\/<\/strong> package contains the reusable components used throughout the application, including: graphical dialogs, spectrogram and navigation drawing routines, deployment analysis workflows, shared data models, plugin selection interfaces, status and progress windows, and multithreaded worker classes.<\/p>\n<\/div>\n\n\n\n Workers Threads<\/strong><\/p>\n\n\n\n Long-running computational tasks are executed in Qt worker threads to prevent the graphical interface from freezing during deployment analyses or plugin execution. Worker classes are responsible for: This architecture allows SAMLab to process large deployments while maintaining an interactive user experience.<\/p>\n<\/div>\n<\/div>\n\n\n\n \n Use\u00a0File<\/strong> \u2192 Open File\u2026<\/strong>\u00a0or double click in the Deployment Navigation Graph<\/strong> of a deployment to load a WAV file into SAMLab.\n <\/p>\n<\/div>\n<\/div>\n\n\n\n \n Move through time, zoom into a frequency band of the spectrogram representation, adjust FFT size, dynamic range, etc.\n <\/p>\n<\/div>\n<\/div>\n\n\n\n \n Use Analyze<\/strong> \u2192 Analyze current File\u2026<\/strong> or Analyze Deployment\u2026<\/strong>, choose specific plugins for acoustic event detection, and review automatically detected events.\n <\/p>\n<\/div>\n<\/div>\n\n\n\n \n Use manual annotation tools to draw time-frequency boxes, classify acoustic events, and save annotations.\n <\/p>\n<\/div>\n<\/div>\n<\/div>\n\n\n\n Deployment analysis loads The workflow also supports:<\/p>\n\n\n\n <\/p>\n\n\n\n Analysis plugins are located in the <\/p>\n\n\n\n Each plugin exposes metadata such as:<\/p>\n\n\n\n This metadata is used to automatically populate the plugin selection interface and integrate plugin outputs into deployment analyses and event visualisation workflows.<\/p>\n\n\n\n Plugins can operate either on:<\/p>\n\n\n\n A plugin declares its outputs once in The A SAMLab analysis plugin is a Python class with metadata and an Place your plugin in the If your plugin declares two indicators in , remember to fill the values :<\/p>\n\n\n\n These values become extra columns in \n Start SAMLab and check that your plugin appears in the selector with the right name, description, and version.\n <\/p>\n<\/div>\n<\/div>\n\n\n\n \n Run it on a short WAV file and confirm that the event list, spectrogram boxes, and indicators look correct.\n<\/div>\n<\/div>\n\n\n\n \n Run it on a small deployment folder and check CSV\/HDF5 outputs.\n<\/div>\n<\/div>\n\n\n\n \n For long analyses, verify that interrupted deployment analysis resumes without corrupting results.\n<\/div>\n<\/div>\n<\/div>\n\n\n\n SAMLab is dual-licensed. Users may choose to use the software under the GNU General Public License version 3 (GPLv3) or under a separate commercial license.<\/p>\n\n\n\n GNU General Public License version 3 (GPLv3) <\/strong> Commercial licensing<\/strong><\/strong> Plugin licensing.<\/strong> Developers distributing their own SAMLab plugins should choose an appropriate license for their plugins. Plugins may be released under the GPLv3, under a compatible open-source license, or under a separate commercial or proprietary license, subject to the legal relationship between the plugin and SAMLab.<\/p>\n\n\n\n SAMLab \u2014 Submarine Acoustic Monitoring Laboratory<\/strong> For commercial licensing enquiries, please contact samaruc.info@gmail.com<\/a><\/strong><\/p>\n\n\n\n <\/p>\n\n\n
executing plugins asynchronously, updating progress windows, handling cancellation requests, and returning detected events and indicators back to the main application thread.<\/p>\n\n\n\n
\n\n\n\nSAMLab user Workflow<\/h2>\n\n\n\n
\n 1<\/span>\n Open audio\n <\/h3>\n\n
\n 2<\/span>\n Inspect\n <\/h3>\n\n
\n 3<\/span>\n Analyze\n <\/h3>\n\n
\n 4<\/span>\n Annotate\n <\/h3>\n\n
Deployment Analysis workflow<\/h3>\n\n\n\n
deployment_info.mat<\/code>, scans all *.WAV<\/strong> files within a deployment directory1<\/a><\/sup>, executes the selected analysis plugins on each recording, exports deployment indicators to deployment_indicators.csv<\/strong>, and stores detected events in the HDF5 file detected_events.h5<\/strong>.<\/p>\n\n\n\n\n
Deployment indicators can later be visualised through the deployment navigation interface for rapid inspection of long-term acoustic trends.<\/p>\n\n\n\n
\n\n\n\nPlugin architecture<\/h1>\n\n\n\n
analysis_plugins\/<\/code> package and are dynamically discovered through:<\/p>\n\n\n\nplugin_loader.discover_plugins(analysis_plugins)<\/code><\/p>\n<\/div>\n<\/div>\n\n\n\n\n
\n
outputs<\/code>. <\/p>\n\n\n\n\n
outputs[\"events\"]<\/code> lists the event types the plugin can produce.<\/li>\n\n\n\noutputs[\"indicators\"]<\/code>declares the file-level indicators and their data types.<\/li>\n<\/ul>\n\n\n\nanalyze()<\/code> method returns an event<\/strong> DataFrame<\/code> and an indicator<\/strong> dictionary whose keys match outputs[\"indicators\"]<\/code>. Indicators<\/strong> consist of summarized event information, such as the number of events of a given type, and are used for graphical navigation through the deployment in the Deployment Navigation Graph<\/strong>.<\/p>\n\n\n\nAdding a new analysis plugin<\/h1>\n\n\n\n
analyze()<\/code> method. The method receives the audio array, sampling rate, DSP calibration, band calibration, and a verbosity flag. It returns two objects: events<\/strong> and file-level indicators<\/strong>.<\/p>\n\n\n\n1. Create a new file<\/h3>\n\n\n\n
analysis_plugins\/<\/code> package, for example:<\/p>\n\n\n\nanalysis_plugins\/my_detector.py<\/code><\/pre>\n\n\n\n2. Implement the plugin class<\/h3>\n\n\n\n
import numpy as np\nimport pandas as pd\nimport time\n\nfrom modules.models import EVENT_FIELDS_TYPES\n\n\nclass MyDetector:\n name = \"MyDetector\"\n description = \"Detects a custom acoustic event and reports one indicator.\"\n version = \"1.0.0\"\n\n outputs = {\n \"events\": [\n {\n \"type\": \"MDE\",\n \"tag\": \"My Detector Event\",\n }\n ],\n \"indicators\": {\n \"MyDetector_Count [#]\": int,\n },\n }\n\n def analyze(self, x, fs, dsp, bands, verbose=False):\n \"\"\"\n Returns\n -------\n events : pandas.DataFrame\n Rows describing detected events, or an empty event DataFrame.\n indicators : dict\n File-level values matching outputs[\"indicators\"].\n \"\"\"\n start_time = time.time()\n\n events = pd.DataFrame({\n name: pd.Series(dtype=dtype)\n for name, dtype in EVENT_FIELDS_TYPES\n })\n\n indicators = {\n key: np.nan\n for key in self.outputs[\"indicators\"]\n }\n\n event_type = self.outputs[\"events\"][0][\"type\"]\n event_tag = self.outputs[\"events\"][0][\"tag\"]\n\n if verbose:\n print(\"Running My Detector...\")\n\n x = np.asarray(x, dtype=float)\n threshold = np.mean(np.abs(x)) + 4 * np.std(x)\n hits = np.flatnonzero(np.abs(x) > threshold)\n\n if hits.size:\n start = int(hits[0])\n end = int(hits[-1])\n\n events.loc[len(events)] = {\n \"start\": np.uint32(start),\n \"end\": np.uint32(end),\n \"fmin\": np.float32(0.0),\n \"fmax\": np.float32(fs \/ 2),\n \"f0\": np.float32(np.nan),\n \"BW\": np.float32(np.nan),\n \"ICI\": np.float32(np.nan),\n \"SPL\": np.float32(np.nan),\n \"score\": np.int8(1),\n \"user\": np.float32(np.nan),\n \"type\": event_type,\n \"tag\": event_tag,\n \"Tdata\": np.nan,\n \"Fdata\": np.nan,\n }\n\n indicators[\"MyDetector_Count [#]\"] = int(len(events))\n\n if verbose:\n print(f\"Analysis finished in {time.time()-start_time:.2f} s\")\n\n return events, indicators<\/code><\/pre>\n\n\n\n3. Pandas “events” fields expected by SAMLab<\/h3>\n\n\n\n
Field<\/span><\/td> Meaning<\/span><\/td><\/tr> start<\/code>, end<\/code><\/td>Event limits in samples, not seconds.<\/td><\/tr> fmin<\/code>, fmax<\/code><\/td>Frequency bounds in Hz.<\/td><\/tr> f0<\/code>, BW<\/code>, ICI<\/code>, SPL<\/code><\/td>Event central frequency, Bandwidth, Inter Event Interval, and Sound Pressure level (used by the miniature event navigation graph and combo box).<\/td><\/tr> score<\/code><\/td>Detection score or confidence value.<\/td><\/tr> tag<\/code><\/code><\/td>Human-readable event label shown in the spectrogram.<\/td><\/tr> type<\/code> <\/td>Compact event code used internally and for filtering.<\/td><\/tr> Tdata<\/code>, Fdata<\/code><\/td>Contour points for time-frequency tracks; use np.nan<\/code> if not applicable.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n4. Match returned indicators to declared output<\/h3>\n\n\n\n
outputs<\/code>:<\/p>\n\n\n\n \"indicators\": {
\"Number of events A [#]<\/code>\": int,
\"Number of events B [#]\"<\/code>: int
}<\/code><\/p>\n\n\n\nindicators[\"Number of events A [#]<\/code><\/code>\"] = np.sum(events[\"type\"] == \"A\")
indicators[\"Number of events B [#]<\/code><\/code>\"] = np.sum(events[\"type\"] == \"B\")<\/code><\/p>\n\n\n\ndeployment_indicators.csv<\/code>.<\/p>\n\n\n\n5. Test the plugin<\/h3>\n\n\n\n
\n 1<\/span>\n Import test\n <\/h3>\n\n
\n 2<\/span>\n Single file\n <\/h3>\n\n
\n 3<\/span>\n Deployment\n <\/h3>\n\n
\n 4<\/span>\n Resume\n <\/h3>\n\n
Plugin programming rules<\/h3>\n\n\n\n
\n
x<\/code> in place unless you intentionally want downstream plugins to see the modified signal. Prefer x = np.asarray(x, dtype=float)<\/code>.<\/li>\n\n\n\nDataFrame<\/code> rather than None<\/code> when no events are found.<\/li>\n\n\n\nname<\/code> or indicator names in outputs[\"indicators\"]<\/code> affects deployment resume logic and CSV compatibility.<\/li>\n<\/ul>\n\n\n\n
\n\n\n\nGPLv3 licensing<\/h1>\n\n\n\n
You may use, modify, and distribute SAMLab under the terms of the GNU General Public License version 3 (GPLv3). This means users may run, study, share, and modify the software under the GPLv3 terms.<\/p>\n<\/div>\n\n\n\n
Alternatively, if your intended use cannot comply with the GPLv3 (for example, because you wish to distribute SAMLab as part of a proprietary product), a separate commercial license is available from the copyright holder.<\/p>\n<\/div>\n<\/div>\n\n\n\n
\n\n\n\n
Copyright \u00a9 2026 Universitat Polit\u00e8cnica de Val\u00e8ncia (UPV).
Commercial licensing is offered by the copyright holder.<\/p>\n\n\n\n