Xilu010 Db Profile

src.xil_pipeline.XILU010_db_profile

Profile the audio loudness of MP3 files: peak, average, and minimum dBFS.

Loads each MP3 with pydub and reports three measurements per file::

peak_dBFS — loudest single sample moment (segment.max_dBFS) avg_dBFS — RMS loudness across the whole file (segment.dBFS) min_dBFS — quietest 500 ms window that is not pure silence

dBFS values are always ≤ 0.0; 0.0 means full-scale clipping, −60 is quiet.

Usage:

xil db-profile                          # scan workspace SFX/ folder
xil db-profile SFX/                     # explicit path
xil db-profile stems/the413/S04E02/     # scan one episode's stems
xil db-profile some.mp3                 # single-file mode
xil db-profile SFX/ --json             # machine-readable output
xil db-profile SFX/ --output report.csv
xil db-profile SFX/ --absolute

logger module-attribute

logger = get_logger(__name__)

get_parser

get_parser() -> argparse.ArgumentParser

Source code in src/xil_pipeline/XILU010_db_profile.py

def get_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        prog="xil-db-profile",
        description="Profile MP3 audio levels: peak, average, and minimum dBFS",
    )
    parser.add_argument(
        "path",
        nargs="?",
        default="__sfx_default__",
        help="MP3 file or directory to scan recursively (default: workspace SFX/ folder)",
    )
    parser.add_argument(
        "--output", "-o",
        default=None,
        metavar="FILE",
        help="Write results to FILE as CSV in addition to logging",
    )
    parser.add_argument(
        "--absolute",
        action="store_true",
        help="Print absolute paths (default: relative to scan root)",
    )
    parser.add_argument(
        "--json",
        action="store_true",
        help="Output a JSON array to stdout — no banner, safe to pipe to jq",
    )
    return parser

main

main() -> None

CLI entry point for MP3 dBFS profiling.

Source code in src/xil_pipeline/XILU010_db_profile.py

def main() -> None:
    """CLI entry point for MP3 dBFS profiling."""
    args = get_parser().parse_args()
    if args.json:
        _run(args)
    else:
        configure_logging()
        with run_banner():
            _run(args)