Upload 3 files

features/augmentation.py

@@ -0,0 +1,55 @@
+"""
+===============================================================================
+features/augmentation.py — Data Augmentation for Training
+===============================================================================
+
+"""
+
+import numpy as np
+from config import FREQ_MASK_PARAM, TIME_MASK_PARAM, NOISE_STD, AUGMENT_PROB
+
+AUGMENT_PROB = 0.5         # 50% chance to apply each augmentation independently
+FREQ_MASK_PARAM = 24       # Max number of consecutive frequency bins to mask (out of 128)
+TIME_MASK_PARAM = 40       # Max number of consecutive time frames to mask 
+NOISE_STD = 0.05           # Standard deviation of the Gaussian noise
+
+# note regarding the noise the random noise might push data over the limit we made 
+# in the mel spectro gram to be between 0 and 1 so will need to clip
+
+def apply_augmentation(mel_spec):
+    """
+    Apply data augmentation to a mel spectrogram (training only).
+
+    Notes
+    -----
+    - This function creates a COPY of the input — the original is not modified.
+    - Each call produces a DIFFERENT augmentation due to randomness.
+      So each epoch, the same sample looks slightly different → diversity.
+    - The augmentation is seeded by numpy's global RNG. For reproducibility
+      across runs, set np.random.seed() in the training script.
+
+    """
+    augmented = mel_spec.copy()
+    n_mels, time_frames = augmented.shape
+
+    # Frequency Masking (SpecAugment) 
+    if np.random.random() < AUGMENT_PROB:
+        f = np.random.randint(0, FREQ_MASK_PARAM)  # Width of freq mask
+        f0 = np.random.randint(0, n_mels - f)      # Starting freq bin
+        augmented[f0:f0 + f, :] = 0.0              # Zero out the horizontal band
+
+    # Time Masking (SpecAugment) 
+    if np.random.random() < AUGMENT_PROB:
+        t = np.random.randint(0, TIME_MASK_PARAM)    # Width of time mask
+        t0 = np.random.randint(0, time_frames - t)   # Starting time frame
+        augmented[:, t0:t0 + t] = 0.0                # Zero out the vertical block
+
+    # Gaussian Noise Injection 
+    if np.random.random() < AUGMENT_PROB:
+        noise = np.random.normal(0, NOISE_STD, augmented.shape)
+        augmented = augmented + noise
+        
+        # Safety clip to ensure noise doesn't break the [0, 1] normalization bounds
+        augmented = np.clip(augmented, 0.0, 1.0)
+
+    return augmented

features/mel_spectrogram.py

@@ -0,0 +1,66 @@
+"""
+===============================================================================
+features/mel_spectrogram.py — Mel Spectrogram Extraction
+===============================================================================
+
+"""
+
+import numpy as np
+import librosa
+from config import N_MELS, N_FFT, HOP_LENGTH, FMAX, MEL_POWER
+
+N_MELS = 128
+N_FFT = 1024
+HOP_LENGTH = 512
+FMAX = 8000
+MEL_POWER = 2.0  # 2.0 = power spectrogram (standard), 1.0 = energy spectrogram
+
+# Toggle whether to scale the final output dB array to exactly [0.0, 1.0]
+# HIGHLY RECOMMENDED for CNN inputs to keep gradients stable.
+# why did I choose to use min-max scaling here? 
+# because the log-mel spectrogram can have a wide range of values depending on the loudness of the audio, 
+# and scaling it to [0.0, 1.0] ensures that the CNN receives inputs in a consistent range
+# which will make the weights explode in different directions when The data is fed to the CNN
+# all weights will be standradized 
+APPLY_MIN_MAX_SCALING = True
+
+def extract_mel_spectrogram(audio, sr):
+    """
+    Extract a log-mel spectrogram from an audio waveform.
+
+    Notes
+    -----
+    - The output is in log (dB) scale, normalized per-sample.
+    - ref=np.max in power_to_db means 0 dB = the loudest point in this sample.
+      All other values are negative dB below the peak.
+    - This per-sample normalization is important because sala7's augmentation
+      thresholds and EL sir's CNN batch normalization depend on consistent
+      value ranges.
+
+    """
+    mel_spec = librosa.feature.melspectrogram(
+          y=audio,
+          sr=sr,
+          n_fft=N_FFT,
+          hop_length=HOP_LENGTH,
+          n_mels=N_MELS,
+          fmax=FMAX,
+          power=MEL_POWER
+      )
+
+      # Convert to log scale (dB)
+      # Using ref=np.max sets the absolute loudest point in this file to 0 dB, 
+      # making all other values negative relative to the peak.
+    log_mel_spec = librosa.power_to_db(mel_spec, ref=np.max) # so here I get the loudest point in the array and make it my refrence to be the zero decibel
+
+      # Per-sample normalization to [0.0, 1.0]
+    if APPLY_MIN_MAX_SCALING:
+        # Prevent division by zero if the file is completely silent
+        ptp = log_mel_spec.max() - log_mel_spec.min()
+        if ptp > 1e-6:
+            log_mel_spec = (log_mel_spec - log_mel_spec.min()) / ptp
+        else:
+            # If the file is just silent static, zero it out entirely
+            log_mel_spec = np.zeros_like(log_mel_spec)
+
+    return log_mel_spec

features/padding.py

@@ -0,0 +1,73 @@
+"""
+===============================================================================
+features/padding.py — Fixed-Size Spectrogram Padding / Trimming
+===============================================================================
+
+"""
+
+import numpy as np
+
+# we will use (top_db=40), trimmed clips average ~8.5 to 9.0 seconds.
+# Calculation: 9.0 seconds * 16000 Hz / 512 hop_length = ~281 frames.
+DEFAULT_FIXED_FRAMES = 281 
+
+# Padding strategy. Options: "constant" (fill with a number) or "edge" (repeat last frame)
+PAD_MODE = "constant" 
+
+# Log-mel spectrograms use negative numbers for silence (e.g., -80.0). 
+# Padding with absolute 0.0 might accidentally represent maximum volume.
+# Setting this to True forces the pad to use the quietest part of the current file.
+USE_MIN_VALUE = True  
+CONSTANT_PAD_VALUE = 0.0
+
+
+def pad_or_trim_spectrogram(mel_spec, target_length=None):
+    """
+    Pad or trim a mel spectrogram to a fixed number of time frames.
+
+    Notes
+    -----
+    - Zero-padding doesn't add energy — padded regions are "silence" in the
+      spectrogram and the CNN will learn to ignore them.
+    - Trimming from the right assumes the important machine sound is at the
+      beginning. After silence removal, this is guaranteed.
+   
+    """
+    if target_length is None:
+        target_length = DEFAULT_FIXED_FRAMES
+
+    n_mels, current_length = mel_spec.shape
+
+    if current_length < target_length:
+        # --- PAD: Add values on the right ---
+        pad_width = target_length - current_length
+        
+        if PAD_MODE == "constant":
+            # Decide what "silence" means mathematically
+            # so here I try to use the lowest possible sound in the current spectrogram as the padding value, which is more realistic than using a fixed constant like 0.0 that might not represent silence in log-mel space.
+            pad_val = mel_spec.min() if USE_MIN_VALUE else CONSTANT_PAD_VALUE
+            
+            
+            mel_spec = np.pad(
+                mel_spec,
+                pad_width=((0, 0), (0, pad_width)),  # Only pad the time axis, not the mel axis
+                mode="constant",
+                constant_values=pad_val
+            )
+        else:
+            # Fallback for other numpy pad modes "edge"
+            # so in this method we just repeat the last frame of the spectrogram, which is a common padding strategy that doesn't introduce new values but extends the existing pattern. 
+            # This can be useful if the end of the spectrogram contains relevant information that we want to preserve.
+            # also depending on the CNN we need to try and error for this as in the CNN it might see the sudden 
+            # silience as a FEATURE 
+            mel_spec = np.pad(
+                mel_spec,
+                pad_width=((0, 0), (0, pad_width)),
+                mode=PAD_MODE
+            )
+            
+    elif current_length > target_length:
+        # --- TRIM: Cut from the right ---
+        mel_spec = mel_spec[:, :target_length]
+
+    return mel_spec