License

Open Source (MIT)

Author

Gob Mink

Code

This code is released into the wild with good intent. No warranty. No gatekeepers. If you break the signal, fix it!

Frequency Damage

FreqDmg is an audio-integrity platform that detects manipulation and corruption in digital audio.

Features

• Validates WAV files based on specific criteria:
  • Must be 24-bit.
  • Must have a sample rate of 48 kHz.
  • Supports mono and stereo channels.
• Detects unwanted silence at the beginning of audio files.
• Can be configured to show failures for each check.
• Each test can be run independently.

Running the script in python

Requirements

To ensure the script runs smoothly and has the correct dependencies, it's recommended to create a new Conda environment specifically for this purpose. Here’s how to set up the environment and install the required packages:

conda create -n sound-check-env python=3.10
conda activate sound-check-env

Alternatively, If you prefer to streamline this process you can install the Conda environment in this repo using a the .yaml file.

conda env create -f sound-check.yaml

Install Packages from requirements.txt

To build the executable, you will need to have the following Python packages installed in your Conda environment:

• NumPy
• SciPy
• PyDub

To streamline package installation, you can use pip to install all required packages at once by referencing a requirements.txt file.

pip install -r requirements.txt

Creating the Executable

To create the standalone executable, use PyInstaller with the --onefile option. Run the following command in your terminal:

pyinstaller --onefile sound_check.py

Usage

After building the executable, you can run it directly from the terminal using the following command:

./dist/sound_check <path/to/audio/content> --marker <type> [--show-failures]

Detailed Examples

To run the script, specify the directory containing your audio files, the --marker option, and (optionally) --show-failures to display all failures

./dist/sound_check "/path/to/your/audio/files" --marker format --show-failures

To check for silence issues and save the results to a log file:

./dist/sound_check "/path/to/audio" --marker tyst --show-failures > silence_check.log

This command:

• Scans the specified directory (/path/to/audio),
• Uses the silence marker to detect unwanted silence at the start of each .wav file,
• Displays each failure (if any) in the console output,
• Writes all console output to a log file named silence_check.log.

Explanation of Markers

The --marker argument in the script allows you to specify the type of check to perform on each audio file. There are three possible options:

format: This marker checks each audio file's format to ensure it meets the following criteria:

• File must be a .wav format.
• Bit depth must be 24-bit.
• Sample rate must be exactly 48 kHz.
• The audio file can be either mono or stereo.

silence: This marker identifies unwanted silence at the beginning of a .wav audio file by analyzing its volume levels and detecting whether the start of the file remains too quiet:

• The function examines the initial segment of the audio file to determine if the volume remains below a specified silence threshold (default: -69 dBFS).
• Silence is flagged if the beginning of the file remains below this threshold for a set duration (default: 0 ms, meaning any detected silence at the start will be flagged).
• A fade-in detection mechanism checks if the volume gradually increases at the beginning—if a fade-in is present, the file passes the test.
• Unwanted silence at the start of a file can result from improper editing, rendering issues, or accidental recording gaps.
• If silence is detected without a fade-in, the file is flagged as failed..

click: This marker identifies unwanted clicks, transient artifacts, or abrupt amplitude changes in .wav audio files by analyzing sudden spikes across small sections:

• The audio file is scanned in short segments (a moving window of 20 samples by default) to detect sudden amplitude spikes that may indicate clicks.
• A click is flagged if the amplitude difference between consecutive samples in a segment exceeds a specified threshold (default is 300,000).
• Detected clicks are considered audio artifacts, and the file will be flagged as failed if any are found.
• Clicking typically results from digital artifacts, improper editing, or recording errors, causing sharp, unintended changes in the waveform.

clip: This marker identifies clipping in .wav audio files by detecting continuous samples that reach the maximum or minimum amplitude, indicating signal distortion:

• The function analyzes all samples in the audio file to check if they hit the digital peak, which suggests clipping.
• In mono files, the entire waveform is checked, while stereo files are analyzed per channel to detect clipping separately.
• Clipping is flagged if any sample reaches the maximum or minimum amplitude of its data type (e.g., ±32767 for 16-bit audio).
• Clipping occurs when an audio signal exceeds the dynamic range of the recording format, leading to distortion and loss of audio fidelity..

full: This marker combines both checks:

• The file is first checked for format compliance.
• If the format is valid, it then checks for unwanted silence.
• Files that fail either the format check or the silence check will be marked as failed.

Test Files

To ensure the functionality of the script, several test files were created to verify the scripts functionality.

Summary of Test Results

This script checks audio files within a directory for specific quality markers, including format, silence, and click artifacts. At the end of the tests, the script generates a summary report that provides an overview of the test results. This summary helps identify any issues in the audio files, with specific details for each type of test.

Running tests in directory: [your_directory]

Summary of tests:
Total files scanned: [number of files scanned]
Files failed: [number of files that failed at least one test]
Files passed: [number of files that passed all tests]

Detailed failure summary:
Format failures: [number of format failures]
Silence (offset) failures: [number of silence failures]
Click (artefakt) failures: [number of click artifact failures]

Example usage:

python sound_check.py /path/to/audio/files --marker full --show-failures

or if the python script as an executable.

./dist/sound_check /path/to/audio/files --marker full --show-failures

Audio Test Files

The audio_test_files directory contains the audio files that were used to validate the various tests within the script.