How to Batch Normalize Bitrate and Sample Rate of Legacy Game Audio Files

Background

The game project had a collection of MP3 audio files with inconsistent sample rates and bitrates, making playback and resource management cumbersome. An offline Python script was added to convert these old files to a standard format.

Target Format

Sample rate: 44100 Hz<br/>Bitrate: 128 kbps<br/>Container: MP3

Script Location

The script resides in the backend repository:

xxxxxxx-backend/scripts/normalize_mp3_directory.py

It recursively scans the specified root directory for .mp3 files, including regular game audio and tutorial resources under the xxx folder.

Usage

Navigate to the backend directory: cd D:\Project\xxxxxxx-backend Run a small‑scale test on three files first:

C:\Users\xxx\.conda\envs\虚拟环境\python.exe scripts
ormalize_mp3_directory.py --root D:\Project\xxxxxxx-backend\upload_path\prod_game --apply --yes --force --limit 3

If the test succeeds, execute the full conversion:

C:\Users\xxx\.conda\envs\虚拟环境\python.exe scripts
ormalize_mp3_directory.py --root D:\Project\xxxxxxx-backend\upload_path\prod_game --apply --yes --force

Optional flags: --game-id 503 – process only the directory for game ID 503. --include-znt-only – process only tutorial resources in the znt folder.

Parameter Explanation

--root

– root directory of audio files to process. --apply – actually perform conversion; without it the script only scans. --yes – confirm execution to avoid accidental runs. --force – re‑encode regardless of current parameters; uses the project‑bundled imageio-ffmpeg if ffprobe is unavailable. --limit 3 – limit processing to the first three files for verification. --game-id <id> – restrict processing to a specific game directory. --include-znt-only – restrict processing to the znt tutorial resources.

Backup Mechanism

Before overwriting a file, the script creates a backup in a timestamped directory while preserving the original relative path:

xxxxx-backend/upload_path/audio_backup/20260707_102400/...

Example: original prod_game\503\xxx\503_xxx.mp3 is backed up as audio_backup\20260707_102400\xxx\503_xxx.mp3. This allows restoration if issues are discovered later.

Execution Report

After each run, a JSON report is generated, e.g.:

xxxxxxx-backend/logs/mp3_normalize_directory_20260707_102400.json

The report records the number of scanned MP3s, how many were successfully converted, skipped, or failed, per‑file results, and the backup directory used. The console also prints a summary:

Scanned MP3 files: 7962
Counts: {'converted': 7962}
Backup dir: D:\Project\xxxxx-backend\upload_path\audio_backup\20260707_102400
Report: D:\Project\xxxxx-backend\logs\mp3_normalize_directory_20260707_102419.json

Precautions

Run with --limit 3 first to verify correct conversion.

Do not open or play MP3 files while they are being processed; Windows may lock the file and cause overwrite failures.

The script does not rename or move files; it overwrites the original MP3 with the re‑encoded version.

After conversion, re‑package the directory and upload it back to the server.