audio_processing_tools

A Python package for processing raw audio signals from Mark-3 devices, with a focus on rain detection and noise estimation. This package provides a flexible framework for batch processing audio files from local storage or remote S3 buckets, applying DSP algorithms, and analyzing results.

This package is designed to handle the complete audio processing pipeline for Mark-3 device audio data:

• Audio I/O: Load and parse Mark-3 binary audio files (.bin) and WAV files from local filesystems or remote S3 storage
• Batch Processing Framework: Orchestrate multiple audio processors across large datasets with configurable batching
• Rain Detection: Advanced algorithms for detecting rain events in audio signals, including false positive/negative handling
• Noise Estimation: SNR calculation and noise floor estimation
• Edge Processing: DSP algorithms optimized for edge devices, including C library integration
• Parameter Tuning: Grid search and visualization tools for optimizing DSP parameters
• Database Integration: Query and store audio metadata using PostgreSQL

The framework uses a protocol-based design where processors implement a simple interface:

• Each processor receives standardized audio buffers (float32, mono, fixed sample rate)
• Processors return metrics (scalar values) and internal state (arrays, diagnostics)
• Results are automatically namespaced to avoid conflicts when running multiple processors

Support for multiple input types:

• LocalPath: Recursively scan local directories for audio files
• RemotePath: Query database for audio keys and fetch from S3
• CsvInput: Load source file list from CSV and hydrate metadata from database
• KeyList: Process a provided list of source files

• Mark-3 Binary Format: Custom binary format with magic bytes (0xADFBCADE)
• WAV Files: Standard WAV format with automatic resampling and channel conversion
• Automatic conversion to normalized float32 mono audio at a specified sample rate

• Process thousands of audio files efficiently with configurable batch sizes
• Memory-efficient design with automatic garbage collection between batches
• Progress tracking and error handling

from audio_processing_tools.audio_processing_framework import process_audio_batches_v2
from audio_processing_tools.processors import RainProcessor, NoiseProcessor
from audio_processing_tools.postprocess.rain import postprocess_rain

# Define processors
rain_proc = RainProcessor(name="rain", fn=your_rain_detection_function)
noise_proc = NoiseProcessor(name="noise", fn=your_noise_estimation_function)

# Configure global parameters
params_global = {
    "sample_rate": 11162,
    "check_duration": 10.0,
    "rain_drop_min_thr": 3,
}

# Process audio files
results_df, states_df_by_proc = process_audio_batches_v2(
    processors=[rain_proc, noise_proc],
    params_global=params_global,
    InputType="LocalPath",
    test_vector_path="/path/to/audio/files",
    batch_size=1000,
)

# Post-process results
test_results_df, feature_df = postprocess_rain(
    results_df,
    states_df_by_proc["rain"],
    params_global,
)

audio_processing_tools/
├── audio_processing_framework.py  # Batch orchestration framework
├── processors.py                   # Base processor classes (RainProcessor, NoiseProcessor)
├── audio_io.py                     # Audio loading and key discovery utilities
├── parse.py                        # Mark-3 binary format parser
├── fetch.py                        # S3/remote audio fetching
├── db_tools.py                     # Database utilities
├── noise_processor.py              # Noise processing
├── alac_utils.py                   # ALAC audio codec helpers
├── transform.py                    # Signal transform utilities
├── labeler.py                      # Clip labeling helpers
├── visualize_audio.py              # Audio/spectrogram plotting
├── visualize_noise_output.py       # Noise-processor output plotting
├── frame_classifier_feature_analysis.py  # Frame-classifier feature analysis
├── edge/                           # Edge device processing (see edge/README.md)
│   ├── dsp_rain_detection.py      # Legacy clip-level rain detection DSP algorithm
│   ├── rain_signal_processor.py   # Frame-level detector + suppressor pipeline
│   ├── rain_frame_classifier.py   # Batch + streaming rain frame classifier
│   ├── feature_extraction.py      # TD/spectral feature extraction (batch + causal-frame)
│   ├── noise_tracker.py           # Standalone causal noise PSD tracker
│   ├── band_noise_estimator.py    # Primary-band DSD noise suppression estimator
│   ├── band_noise_processor.py    # Batch adapter for band_noise_estimator
│   ├── rain_estimator.py          # Per-clip drop-size-distribution rain-rate estimate
│   ├── time_domain_detector.py    # Time-domain detection helpers
│   └── parameter_tuning/          # Parameter optimization tools
├── backend/                        # Unreferenced legacy spectral utilities (disposition undecided)
├── host_analysis/                  # Host-side analysis tooling
└── postprocess/                    # Result formatting utilities
    ├── rain.py                     # Rain detection post-processing
    └── noise.py                    # Noise estimation post-processing

See edge/README.md for the detector/suppressor architecture and rain_algorithm_technical_assessment.md for a detailed technical assessment of the rain detection algorithm.

All processors must implement:

• name property: Short identifier (e.g., "rain", "noise")
• run(audio_data, params) method: Returns (results_dict, state_dict)

• Audio buffers are 1-D float32 NumPy arrays
• Values normalized to [-1, 1] range
• Fixed sample rate and duration as specified in params_global

• Results DataFrame: One row per file with namespaced metrics (e.g., rain__rain_drops, noise__snr_db)
• States DataFrames: Per-processor DataFrames with internal state and diagnostics