LinuxDev Portal
Назад към каталога
Илюстрация на автоматизация: терминал, зъбчати колела и конвейер от задачи
Автоматизация v1.0.0 • 25.09.2026 г. • 🐚 bash

MP3 Normalizer

Нормализиране на MP3 файлове до стандартно ниво на звука.

Зависимости

ffmpegbash

Употреба

./mp3_normalizer.sh
MP3AudioBash

Един от най-честите проблеми при управлението на лични музикални библиотеки, подкасти или аудио архиви е вариацията в силата на звука (loudness). Различните източници на кодиране често водят до субективно усещане за прекалено тихи или прекалено силни аудио записи. Традиционният подход за преодоляване на този проблем разчита на прекодиране (re-encoding), което неоправдано води до загуба на аудио качество и консумира значителен изчислителен ресурс.

Super MP3 Normalizer е интерактивен Python инструмент с TUI/CLI интерфейс за Linux, който решава този казус, като прилага промени директно върху метаданните на MP3 кадрите или чрез ID3 тагове (ReplayGain standard) — без прекодиране, напълно обратимо и in-place.

Theoretical Framework: Как работи нормализацията без загуба?

За да разберем предимството на Super MP3 Normalizer пред конвенционалните аудио редактори, трябва да разгледаме структурата на MP3 контейнера и спецификацията ReplayGain.

┌─────────────────────────────────────────────────────────┐
│                    MP3 Файл                            │
├─────────────────┬───────────────────────────────────────┤
│ ID3v2 Тагове    │ REPLAYGAIN_TRACK_GAIN = -2.5 dB       │ ◄── Режим 2 (ReplayGain)
├─────────────────┼───────────────────────────────────────┤
│ MP3 Кадър 1     │ Header | global_gain = 168            │ ◄── Режим 1 (mp3gain modification)
│ MP3 Кадър 2     │ Header | global_gain = 168            │
│ ...             │ ...                                   │
└─────────────────┴───────────────────────────────────────┘

1. Модификация на global_gain кадрите (mp3gain)

Всеки MP3 файл се състои от отделни аудио кадри. В хедъра на всеки кадър се съдържа 8-битово поле, наречено global_gain. Промяната на това поле скалира силата на звука при декодиране с стъпки от $1.5\text{ dB}$. Тъй като се променя само числова стойност в хедъра, самите компресирани аудио данни (MDCT коефициенти) остават непокътнати.

2. Прилагане на ReplayGain ID3 тагове

ReplayGain (RFC 7845) е стандарт за психоакустичен анализ. Вместо да променя структурата на MP3 кадрите, инструментът изчислява необходимата психоакустична корекция и я записва като ID3v2 metadata таг (REPLAYGAIN_TRACK_GAIN). Съвместимите плейъри четат този таг и регулират силата на звука в реално време по време на възпроизвеждане.

Основни функционалности

  • Интерактивен Terminal User Interface (TUI): Изграден с библиотеката rich, предлагащ лесна навигация в файловата система и визуализация на промените.

  • Два режима на работа: Поддръжка както на директно модифициране на MP3 кадри (mp3gain), така и на неинвазивно тагване (ReplayGain).

  • Track vs. Album Gain:

  • Track Gain: Всеки файл се нормализира самостоятелно (подходящо за разбъркано възпроизвеждане / shuffle).

  • Album Gain: Изчислява се единен офсет за целия албум, запазвайки субективната динамична разлика между песните (подходящо за класическа музика и концептуални албуми).

  • Система за сигурност: Поддръжка на Undo операция чрез хронология в JSON формат и гъвкаво архивиране (Backup) на оригиналните файлове.

  • Поддръжка на CLI и Автоматизация: Възможност за интеграция в cron задачи, systemd таймери и Bash скриптове.

Архитектура и изисквания

Инструментът работи като обвивка (wrapper) около утвърдени системни комунални услуги и Python библиотеки:

Зависимости

  1. Системен бекенд: mp3gain или модерният му вариант mp3rgain (написан на Rust).

  2. Python среда (3.10+):

    • rich — за визуализация на терминалния интерфейс и прогрес барове.

    • mutagen — за манипулация на ID3 таговете.

Инсталация и конфигуриране

Препоръчителният начин за инсталация в Linux системи е използването на системните пакетни мениджъри за избягване на конфликти с externally-managed-environment (PEP 668).

Стъпка 1: Инсталиране на системните зависимости

Debian / Ubuntu / Linux Mint

sudo apt update
sudo apt install mp3gain python3-rich python3-mutagen git

Arch Linux / Manjaro

sudo pacman -S mp3gain python-rich python-mutagen git

Fedora

sudo dnf install mp3gain python3-rich python3-mutagen git

(Забележка: Алтернативно може да използвате Rust базирания mp3rgain чрез cargo install mp3rgain)

Стъпка 2: Клониране на репозитория

git clone https://github.com/fedya-dev/mp3_normalizer
cd mp3_normalizer
chmod +x mp3_normalizer

Стъпка 3: Проверка на функционалността

./mp3_normalizer --version

Методология на работа и употреба

1. Интерактивен режим (TUI)

Интерактивният режим е подходящ за бърза обработка и визуална настройка. Стартира се без допълнителни аргументи:

./mp3_normalizer

Потребителят преминава през следния работен процес:

  1. Избор на папка: Навигация чрез дървовидна структура.

  2. Конфигурация: Настройка на параметрите (Target dB, Режим Track/Album, Backup).

  3. Анализ (Dry-run): Предварителен преглед на децибеловите корекции без физически запис.

  4. Изпълнение (Start): Стартиране на процеса с проследяване в реално време.

2. Режим на командния ред (CLI)

За интеграция в автоматизирани скриптове инструментът предоставя пълен набор от CLI флагове:

Флаг Кратък Описание
--folder PATH -f Задава път до директорията с MP3 файлове
--target DB -t Задава целево ниво в dB (по подразбиране: 89 dB)
--album -a Активира Album Gain режим
--recursive -r Рекурсивно обхождане на поддиректории
--backup -b Създаване на архивно копие на файловете
--tags Използване само на ReplayGain ID3 тагове
--dry-run -n Симулация без извършване на промени
--yes -y Автоматично потвърждение (non-interactive)

Практически примери

Пример 1: Анализ на папка без нанасяне на промени

Извършва диагностика на нивата на звука в зададената директория:

./mp3_normalizer -f ~/Music/Rock -n

Пример 2: Нормализиране на албум с запазване на динамиката

Прилага Album Gain режим и създава бекъп файлове:

./mp3_normalizer -f ~/Music/Albums/DarkSideOfTheMoon -a -b -t 89 -y

Пример 3: Неинвазивно тагване чрез ReplayGain

Записва ID3 тагове без промяна на MP3 кадрите. Изключително подходящо за модерни плейъри (VLC, foobar2000, mpv, Strawberry):

./mp3_normalizer -f ~/Music/FLAC_and_MP3 --tags -y

Пример 4: Автоматизация с Shell Script (Batch Processing)

Обработка на всички подпапки в музикалната библиотека:

#!/usr/bin/env bash
# batch_normalize.sh

MUSIC_DIR="$HOME/Music"

for dir in "$MUSIC_DIR"/*/; do
    if [ -d "$dir" ]; then
        echo "Обработка на директория: $dir"
        ./mp3_normalizer -f "$dir" -t 89 -r -y
    fi
done

Сигурност на данните: Undo и Backup механизми

Едно от основните предимства на Super MP3 Normalizer е фокусът върху целостта на данните.

Конфигурационни файлове и логове

Инструментът съхранява своите работни файлове съгласно XDG Base Directory спецификацията:

  • Конфигурация и Undo история: ~/.config/mp3_super/undo.json

  • Логове: ~/.config/mp3_super/logs/YYYY-MM-DD.log

  • Резервни копия (Backups): ~/.cache/mp3_super/backups/

Механизъм на Undo (Отмяна)

При изпълнение на операция, метаданните за промените се записват в undo.json. При избор на операция Undo (Опция 8 в TUI):

  • В mp3gain режим: Скриптът подава команда mp3gain -u с оригиналния списък от файлове.

  • В ReplayGain режим: Изтриват се само създадените REPLAYGAIN_* ID3 тагове чрез mutagen.

Отстраняване на неизправности (Troubleshooting)

1. Грешка: externally-managed-environment

При опит за инсталация с pip на съвременни Linux дистрибуции:

  • Решение: Инсталирайте библиотеките през системния пакетен мениджър (python3-rich, python3-mutagen) или използвайте виртуална среда (python3 -m venv).

2. Неправилно визуализиране на символи / кирилица

Ако UI елементите или кирилските имена на песните се показват некоректно:

  • Решение: Уверете се, че системната локализация поддържа UTF-8:

    export LANG=bg_BG.UTF-8
export LC_ALL=bg_BG.UTF-8

3. Грешка за липса на права за писане (Permission Denied)

Ако файловете са копирани от външен носител с ограничени права:

  • Решение: Коригирайте правата за писане на текущия потребител:

    find ~/Music -name "*.mp3" -exec chmod u+w {} \;

Заключение

Super MP3 Normalizer предоставя балансирано решение между мощен команден инструмент и достъпен интерфейс. Чрез използването на технологии без прекодиране, той осигурява бързо и сигурно изравняване на аудио колекции, като запазва автентичното качество на звука.

Всички скриптове