Настройки транскодирования Ampache

Что такое транскодирование и зачем оно нужно

Транскодирование — это процесс преобразования мультимедиа-файла из одного кодека/формата в другой. В контексте Ampache это важно для совместимости с разными браузерами и клиентами: некоторые требуют MP3, другие — OGG/Vorbis, мобильные устройства могут запрашивать специфические форматы.

Краткое определение: транскодирование преобразует поток или файл с использованием внешней программы (например, avconv), применяя нужный кодек и параметры битрейта.

Важно: Ampache сам по себе не содержит кодеков и программ для конвертации. Он вызывает внешние утилиты, поэтому их нужно установить отдельно и убедиться, что параметры команд совместимы с установленными библиотеками.

TL;DR по шагам

Добавьте репозитории мультимедиа-библиотек.
Установите компилятор, инструменты сборки и нужные dev-пакеты.
Соберите и установите yasm, x264 (опционально), libav/avconv с нужными флагами.
Настройте строки транскодирования в ampache.cfg.php.
Настройте пользователей, ACL/RPC и потоковый доступ.
Проверьте логи и права доступа при проблемах.

Основные понятия и термины

Кодек: компонент, кодирующий или декодирующий аудио/видео (например, libmp3lame, libvorbis).
Контейнер: формат файла, содержащий потоки (mp3, ogg, mp4, ogv).
Битрейт: скорость передачи данных аудио, обычно в kbps (обозначается K в конфиге).
Transcode_cmd: базовая команда, которую вызывает Ampache с указанием исходного файла.
Encode args: аргументы, добавляемые к базовой команде для формирования конкретного вида выходного потока.

Как работает транскодирование в Ampache

Ampache берет исходный файл (%FILE%), передаёт его в программу-транскодер (avconv/ffmpeg) через транскод-команду, а затем добавляет к ней соответствующие параметры (encode args) — для получения запрошенного формата. Браузеры и клиенты могут запрашивать разные форматы. Например, Firefox обычно предпочитает OGG, а Chrome — MP3. Поэтому encode_args для обоих форматов должны быть корректны.

Если вы используете HTML5-плеер, убедитесь, что сервер способен отдать запрашиваемый формат; некоторые старые версии Internet Explorer не поддерживают HTML5-плеер, поэтому используйте Chrome или Firefox.

Конфигурация Ampache: пример строк в конфиге

Ниже — пример строк конфигурации, используемых автором. Найдите соответствующие строки в config php-файле и замените или дополните их. Сохраните резервную копию файла перед изменениями.

max_bit_rate = 576  
min_bit_rate = 48  
transcode_flac = required  
transcode_mp3 = allowed  
encode_target = mp3  
transcode_cmd = "avconv -i %FILE%"  
encode_args_ogg = "-vn -b:a max\(%SAMPLE%K\,49K\) -acodec libvorbis -vcodec libtheora -f ogg pipe:1"  
encode_args_mp3 = "-vn -b:a %SAMPLE%K -acodec libmp3lame -f mp3 pipe:1"  
encode_args_ogv = "-vcodec libtheora -acodec libvorbis -ar 44100 -f ogv pipe:1"  
encode_args_mp4 = "-profile:0 baseline -frag_duration 2 -ar 44100 -f mp4 pipe:1"

Примечания по строкам:

max_bit_rate и min_bit_rate задают пределы в килобитах в секунду.
transcode_flac = required — принудительно транскодировать FLAC.
transcode_cmd указывает базовую команду; %FILE% заменится на путь к файлу.
encodeargs* — конкретные аргументы для целевых контейнеров/кодеков.

Особенность encode_args_ogg: некоторые реализации libvorbis испытывают проблемы при очень низких битрейтах (< ~42K), поэтому в строке добавлен механизм, заставляющий выбирать не меньше ~49K для совместимости. Оставьте это, если наблюдаете артефакты при слишком низком битрейте.

Общие рекомендации по битрейту

Для речи или подкастов 64–128K обычно достаточно.
Для музыки приемлемый диапазон — 128–320K (чем выше — тем лучше качество и больше нагрузка на сеть).
Для мобильной передачи и ограниченного трафика уменьшайте битрейт, но не опускайтесь ниже минимально приемлемого качества.

Установка программ и библиотек транскодирования

Ниже — пошаговые команды и пояснения. Выполняйте их в терминале под root или через sudo. Сохраняйте вывод команд в логи, если планируете отладку.

Добавление репозитория видео/аудио-библиотек

Откройте файл источников apt:

sudo nano  /etc/apt/sources.list

Добавьте две строки:

deb http://download.videolan.org/pub/debian/stable/ /  
deb-src http://download.videolan.org/pub/debian/stable/ /

Сохраните и выйдите (Ctrl+X, затем Y).

Добавьте ключ apt:

wget -O - http://download.videolan.org/pub/debian/videolan-apt.asc|sudo apt-key add -

Установка инструментов компиляции и вспомогательных пакетов

sudo apt-get -y install build-essential checkinstall cvs subversion git git-core mercurial pkg-config apt-file

Установка аудио-библиотек

sudo apt-get -y install lame libvorbis-dev vorbis-tools flac libmp3lame-dev libavcodec-extra*

Установка видео-библиотек (опционально)

sudo apt-get install libfaac-dev libtheora-dev libvpx-dev

Авторы замечают, что поддержка видео в Ampache может быть ограничена, поэтому основной упор сделан на аудио.

Сборка avconv (libav) и зависимостей из исходников

Сборка из исходников типична для Linux: загрузка исходников, конфигурирование, make, затем упаковка и установка при помощи checkinstall (удобно для последующей деинсталляции).

Подготовьте систему — сначала yasm (требуется для оптимизированной сборки):

sudo mkdir /usr/local/src/yasm  
cd ~/downloads  
wget http://www.tortall.net/projects/yasm/releases/yasm-1.2.0.tar.gz

Распакуйте и установите yasm:

tar xzvf yasm-1.2.0.tar.gz  
sudo mv yasm-1.2.0 /usr/local/src/yasm/  
cd /usr/local/src/yasm/yasm-1.2.0  
sudo ./configure  
sudo make  
sudo checkinstall

При появлении запросов: нажмите Enter/Yes и введите yasm как имя пакета.

Опционально: x264 (необходим для H.264-видео и лучшей совместимости видео-транскодирования):

sudo mkdir /usr/local/src/x264  
cd /usr/local/src/  
sudo git clone git://git.videolan.org/x264.git x264  
cd /usr/local/src/x264  
sudo ./configure --enable-shared --libdir=/usr/local/lib/  
sudo make  
sudo checkinstall

При запросах при установке укажите x264 как имя пакета и настройте версию, если потребуется.

Сборка libav/avconv:

cd /usr/local/src/  
sudo git clone git://git.libav.org/libav.git avconv  
cd /usr/local/src/avconv  
sudo LD_LIBRARY_PATH=/usr/local/lib/ ./configure --enable-gpl --enable-libx264 --enable-nonfree --enable-shared --enable-libmp3lame --enable-libvorbis --enable-libtheora --enable-libfaac --enable-libvpx > ~/avconv_configuration.txt

Флаги –enable-libmp3lame и –enable-libvorbis критичны для транскодирования в MP3 и OGG соответственно.

Сборка и установка (процесс может быть долгим):

sudo make -j14  
sudo checkinstall

Значение -j14 ускоряет сборку за счёт параллелизации; подбирайте значение в зависимости от ядра/потоков CPU. После установки выполните:

sudo ldconfig  
sudo /etc/init.d/apache2 restart

Настройка API/RPC и потокового доступа для внешних клиентов

Чтобы внешние устройства (iPhone, Android, клиенты типа Pimpache) могли подключиться, создайте внешний пользователь и настройте ACL/RPC:

Войдите в Ampache через веб-интерфейс.
Нажмите на серую иконку admin (администрирование).
Нажмите «Add user» (Добавить пользователя).
Создайте логин, например external, задайте пароль и уровень доступа user.

Настройка битрейта транскодирования для пользователя:

В разделе администрирования выберите Browse users → Preferences.
В секции Transcode bitrate укажите желаемый дефолт.

Добавление ACL/RPC хоста для внешнего доступа:

В админке нажмите Show acls (Показать ACL).
Нажмите Add API/RPC host (Добавить API/RPC хост).
Задайте имя (например external), уровень access level: read/write; user: external; acl type: API/RPC; start 1.1.1.1 end 255.255.255.255. Нажмите Create ACL.
Создайте второй ACL: такой же, но с типом API/RPC + Stream access (чтобы разрешить стриминг).

Если получите сообщение DUPLICATE ACL DEFINED — это не страшно. Главное — чтобы внешний пользователь имел и API, и потоковый доступ.

URL для клиентов: http://<ваш-сервер-домен>/ampache

Если используете локальные адреса внутри сети, в настройке клиента укажите IP-адрес сервера вместо доменного имени, если ваш маршрутизатор не резолвит локальные имена.

Создание каталога (catalog)

После копирования музыки добавьте каталог в Ampache:

В админке нажмите Add a catalog (Добавить каталог).
Введите имя каталога (например home).
Введите путь к папке с музыкой, например “/home/
/music”.
- Учтите чувствительность к регистру.
- Замените на реальное имя пользователя.
Установите Level catalog type: local.
Оставьте шаблоны имен файлов по умолчанию, если структура у вас стандартная.
Отметьте Gather album art и Build playlists и нажмите Add catalog.

Права доступа и финальная «уборка» безопасности

Ограничьте доступ к исходной папке Ampache веб-серверу:

sudo chown www-data:www-data /usr/local/src/www/ampache-3.6-alpha6  
sudo chmod -R 0700 /usr/local/src/www/ampache-3.6-alpha6/

Если нужно временно перемещаться по папке или вносить правки, можно временно ослабить права:

sudo chmod -R 0777 /usr/local/src/www/ampache-3.6-alpha6/

После завершения не забудьте снова вернуть 0700.

Логи и отладка

Основной источник правды при ошибках — логи Ampache:

cd /var/log/ampache  
dir

Откройте последний лог, например:

 sudo nano /var/log/ampache/yyyymmdd.ampache.log

Ищите ошибки транскодера, ошибки прав доступа, ошибки соединения с базой данных и ошибки при сборке потоков.

Если при копировании в папку музыки возникают ошибки прав, временно разрешите права на папку:

sudo chmod 777 ~/music

Затем вновь сузьте права после проверки.

Полное удаление и восстановление Ampache (сброс к дефолту)

Если нужно начать заново, удалите базу и файлы Ampache:

sudo mysql -u root -p

Введите пароль MySQL и выполните:

drop database ampache;

Выйдите из mysql:

quit

Удалите папку Ampache и разверните оригинальный архив заново:

sudo rm -R /usr/local/src/www/ampache-3.6-alpha6  
cd ~/downloads  
sudo tar zxvf ampache.tar.gz -C /usr/local/src/www  
sudo chmod -R 7777 /usr/local/src/www/ampache-3.6-alpha6

После этого веб-интерфейс при первом заходе предложит начальную настройку.

Частые проблемы и решения

Транскодер не запускается: проверьте, установлен ли avconv (или ffmpeg) и видны ли библиотеки через ldconfig.
Ошибки кодеков: убедитесь, что вы собирали libav с –enable-libmp3lame и –enable-libvorbis или установили соответствующие dev-пакеты.
Плохое качество при низком битрейте: увеличьте минимальный битрейт или используйте другой профайл кодека.
Клиенты не подключаются: проверьте ACL/RPC и правильно ли указали URL/порт и логин/пароль.
Права доступа к файлам: проверьте владельца и права каталога с музыкой и каталогов Ampache.

Практическая методика: быстрая проверка после установки

Проверьте наличие avconv:

avconv -version

Попробуйте вручную запустить транскодирование одного файла в консоли, чтобы увидеть вывод ошибок:

avconv -i /path/to/file.flac -vn -b:a 128K -acodec libmp3lame -f mp3 out.mp3

Если команда успешно создает out.mp3, проверьте аналогичную строку в encode_args_mp3.
Проверьте работу через веб-интерфейс: попытайтесь воспроизвести трек в браузере и смотрите логи.

Чеклисты по ролям

Администратор сервера:

Создать резервную копию конфигурационного файла ampache.cfg.php.
Установить и проверить avconv/ffmpeg.
Настроить ACL/RPC и внешнего пользователя.
Проверить права на каталоги и выполнить chmod/chown.

Разработчик/инженер сборки:

Убедиться, что установлены build-essential и checkinstall.
Собирать yasm, x264, libav с нужными флагами.
Тестировать ручные команды транскодирования.

Пользователь мобильного клиента:

Убедиться, что есть внешний логин и пароль (external).
Указать URL вида http://<ваш-домен>/ampache.
Проверить, доступен ли стрим по мобильной сети.

Критерии приёмки (Acceptance)

Веб-плеер воспроизводит треки в минимально двух целевых форматах (mp3 и ogg).
Внешние клиенты успешно проходят аутентификацию и получают поток.
Логи не содержат ошибок транскодирования при выборе стандартных битрейтов.
Права на каталоги соответствуют практике минимально достаточных привилегий (www-data владелец, 0700 для конфиденциальных папок).

Тестовые случаи и приемочные тесты

Воспроизведение FLAC-файла в Firefox (ожидается транскодирование в ogg).
Воспроизведение FLAC-файла в Chrome (ожидается транскодирование в mp3).
Поток со смартфона под внешним аккаунтом: воспроизведение, пауза, переключение треков.
Проверка ошибки: временно удалите libvorbis и убедитесь, что в логах появляется сообщение о невозможности транскодирования в ogg.

Decision flowchart (Mermaid)

flowchart TD
  A[Нужен поток клиенту?] -->|Да| B{Формат поддерживается сервером?}
  B -->|MP3| C[Использовать encode_args_mp3]
  B -->|OGG| D[Использовать encode_args_ogg]
  B -->|Нет| E[Добавить/собрать кодек]
  E --> F[Собрать libav с нужными флагами]
  F --> C
  F --> D
  A -->|Нет| G[Отдать исходный файл]

Когда транскодирование не работает: альтернативы и обходные пути

Предварительно перекодируйте коллекцию в совместимый формат (MP3) оффлайн и храните уже готовые файлы в отдельном каталоге. Это снимает нагрузку на CPU сервера в режиме онлайн.
Используйте сторонние сервисы или специализированные транс-кодеры в контейнерах/VM при высокой нагрузке.
Если видео-транскодирование важно, подумайте о выделенном сервере с аппаратным ускорением.

Советы по производительности и масштабированию

Транскодирование — CPU- и I/O-интенсивная задача. Для большого парка клиентов используйте очередь транскодирования или выделенный транскодер.
Кешируйте часто запрашиваемые форматы/битрейты, чтобы не перекодировать один и тот же трек многократно.
Мониторьте нагрузку и используйте более низкие битрейты для мобильных пулов клиентов.

Короткая памятка по безопасности

Никогда не давайте права 0777 на постоянной основе.
Ограничьте доступ к admin-интерфейсу по IP, если возможно.
Создавайте отдельные учётки с минимально необходимыми правами для внешних клиентов.

Заключение

Транскодирование в Ampache даёт гибкость и совместимость с большим набором клиентов и браузеров. Однако настройка требует установки внешних утилит и правильной конфигурации кодеков. Следуя шагам этой инструкции, вы сможете установить avconv, собрать нужные библиотеки и настроить строки транскодирования. Используйте чеклисты и тесты, чтобы убедиться в корректности установки, и не забывайте проверять логи при возникновении проблем.

Important: сохраняйте резервные копии конфигураций и пакетов перед изменениями.

Ещё одна вещь: если вы экспериментируете с видеотранскодированием, начните с аудио и добавляйте видеокомпоненты постепенно.

Список полезных ссылок

Официальная страница avconv/libav: http://libav.org/avconv.html
Репозиторий x264: git://git.videolan.org/x264.git

Настройки транскодирования в Ampache