AcuDist (Acoustic Distress Dataset)

# AcuDist-LMS Filename Naming Convention ## 1. Naming origin The filenames are created in two stages: 1. raw `.wav` segments are generated from longer recordings;2. each WAV segment is later converted into a log-mel spectrogram image, with the LMS configuration appended to the stem. The parent directory remains the authoritative class label: - `BG/` = non-distress background- `Distress/` = distress-related acoustic content --- ## 2. Raw WAV filename structure The segmentation code generates filenames using: ```text[CLASS]-[SOURCE_CATEGORY]-[ACOUSTIC_SUBTYPE]_[GLOBAL_SAMPLE_ID]_[EXPORT_TIMESTAMP].wav``` The active code is: ```pythonoutput_filename = ( f"{ND}-{COUNTRY}-{LOCATION}_" f"{global_counter:08d}_" f"{timestamp}.wav")``` Therefore, the fields are: | Field | Code variable | Description ||---|---|---|| Class prefix | `ND` | Dataset class prefix, such as `ND` or `Dist` || Source category | `COUNTRY` | Despite the variable name, this is used as a source/location/category code || Acoustic subtype | `LOCATION` | Despite the variable name, this is used as an acoustic subtype code || Global sample ID | `global_counter` | Eight-digit sequential identifier || Export timestamp | `timestamp` | Computer clock time when the segment file was saved | The variable names `COUNTRY` and `LOCATION` are historical and do not always represent literal country and geographic location. --- ## 3. BG / non-distress examples Observed example: ```textND-Unknown-BarRest-NL2_00000203_18h-25m-27s-230_LMS_03_1024_128_64.png``` This filename contains an additional dataset-specific code (`NL2`) in the left metadata block. Earlier versions of the segmentation script could therefore use: ```textND-[SOURCE_CATEGORY]-[ENVIRONMENT]-[VOCAL_CODE]_[GLOBAL_SAMPLE_ID]_[EXPORT_TIMESTAMP].wav``` Observed BG fields: | Field | Example | Interpretation ||---|---|---|| Class prefix | `ND` | Non-distress || Source category | `Unknown` | Source/geographic category unavailable or not assigned || Environment | `BarRest` | Bar/restaurant environment || Vocal-content code | `NL2` | Dataset-specific non-linguistic/background subtype || Global sample ID | `00000203` | Sequential sample ID || Export timestamp | `18h-25m-27s-230` | Computer time when exported || Representation | `LMS` | Log-mel spectrogram || Processing variant | `03` | LMS export configuration identifier || FFT size | `1024` | `n_fft=1024` || Hop length | `128` | hop length = 128 || Mel bands | `64` | `n_mels=64` | Another observed example: ```textND-Unknown-SchoolUni-NL1_00000032_19h-50m-32s-951_LMS_03_1024_128_64.png``` --- ## 4. Distress examples Observed examples: ```textDist-Str_LP01-ST_00001170_12h-59m-09s-720_LMS_03_1024_128_64.pngDist-Str-SS_00000019_10h-08m-56s-038_LMS_03_1024_128_64.png``` General structure: ```textDist-[SOURCE_CATEGORY]-[ACOUSTIC_SUBTYPE]_[GLOBAL_SAMPLE_ID]_[EXPORT_TIMESTAMP]_LMS_03_1024_128_64.png``` Some source-category strings contain an internal underscore, such as `Str_LP01`. Based on the comments in the supplied segmentation code: | Code | Meaning ||---|---|| `SS` | Synthesised scream || `SM` | Scream with music || `ST` | Scream with talking | Observed distress fields: | Field | Example | Interpretation ||---|---|---|| Class prefix | `Dist` | Distress || Source category | `Str` or `Str_LP01` | Dataset-specific source/category code || Acoustic subtype | `SS`, `SM`, or `ST` | Distress acoustic composition || Global sample ID | `00001170` | Sequential sample ID || Export timestamp | `12h-59m-09s-720` | Computer time when exported || LMS suffix | `LMS_03_1024_128_64` | Representation and processing settings | --- ## 5. Critical timestamp clarification The code calculates the position of each two-second window within the original recording: ```pythontime_string = ( f"{hours:02d}h-" f"{minutes:02d}m-" f"{seconds:02d}s-" f"{milliseconds:03d}ms")``` However, `time_string` is **not used** in the output filename. Instead, the filename uses: ```pythoncurrent_time = datetime.now()timestamp = current_time.strftime("%Hh-%Mm-%Ss-%f")[:-3]``` Therefore, a value such as: ```text18h-25m-27s-230``` is the computer clock time at which the segment was exported. It is **not** the segment's temporal position in the original audio recording. This distinction must be preserved in the dataset documentation and manifest. --- ## 6. Segmentation settings The supplied segmentation code uses: | Parameter | Value ||---|---:|| Segment duration | 2.0 seconds || Window shift | 0.5 seconds || Overlap | 1.5 seconds || Overlap percentage | 75% || Audio sampling rate | Original sampling rate (`sr=None`) || Channel handling | Original mono/stereo structure retained || Sample identifier | Global sequential counter | Because adjacent clips overlap by 75%, source-disjoint splitting is essential. Adjacent segments from the same original recording must not be distributed across training, validation, and test sets. --- ## 7. LMS image suffix After WAV segmentation, the LMS generation process appends: ```text_LMS_03_1024_128_64.png``` Interpretation: | Token | Meaning ||---|---|| `LMS` | Log-mel spectrogram || `03` | Processing/export configuration identifier || `1024` | FFT size || `128` | Hop length || `64` | Number of mel bands || `.png` | Image format | --- ## 8. Recommended complete filename schema ### Non-distress ```textND-[SOURCE_CATEGORY]-[ENVIRONMENT]-[VOCAL_CODE]_[GLOBAL_SAMPLE_ID]_[EXPORT_TIMESTAMP]_LMS_03_1024_128_64.png``` ### Distress ```textDist-[SOURCE_CATEGORY]-[ACOUSTIC_SUBTYPE]_[GLOBAL_SAMPLE_ID]_[EXPORT_TIMESTAMP]_LMS_03_1024_128_64.png``` --- ## 9. Recommended parser ```pythonimport refrom pathlib import Path PATTERN = re.compile( r"^(?P<metadata_block>.+)_" r"(?P<sample_id>\d{8})_" r"(?P<export_hour>\d{2})h-" r"(?P<export_minute>\d{2})m-" r"(?P<export_second>\d{2})s-" r"(?P<export_millisecond>\d{3})_" r"(?P<representation>LMS)_" r"(?P<processing_variant>\d+)_" r"(?P<n_fft>\d+)_" r"(?P<hop_length>\d+)_" r"(?P<n_mels>\d+)$") def parse_filename(filename): stem = Path(filename).stem match = PATTERN.match(stem) if not match: raise ValueError(f"Unrecognised filename: {filename}") return match.groupdict()``` --- ## 10. Source-group warning The filename does not contain the original WAV filename or original-source identifier. The global sample ID and export timestamp are not sufficient to reconstruct the source recording reliably. For rigorous source-disjoint evaluation, the dataset should therefore include a separate provenance table linking each LMS image to: - original source recording;- original WAV filename;- source/event identifier;- window start time in the original recording;- window end time in the original recording;- class;- source category;- acoustic subtype. A recommended file is: ```textSOURCE_PROVENANCE.csv``` Without that table, external users cannot independently reproduce the exact source-disjoint split. --- ## 11. Label interpretation - `ND` means non-distress.- `Dist` means distress.- `SS` means synthesised scream.- `SM` means scream with music.- `ST` means scream with talking.- `Unknown` indicates unavailable or unassigned source/geographic metadata.- `NL1` and `NL2` remain dataset-specific codes and should be explicitly defined by the dataset creator.- `Str`, `Fest`, `LP01`, `BarRest`, and `SchoolUni` are controlled source/environment codes and should be described in `CODEBOOK.csv`.