Обработка медиа

media работает с файлами изображений, аудио и видео. Параметры зависят от операции и выбранного плагина.

Параметры

Параметр	Назначение	По умолчанию
operation	image_process; новые операции — в таблице охвата	Обязательно
file	FileRef исходного файла	Обязательно
format	Целевой формат, разрешённый операцией	Сохранить поддерживаемый
quality	1–100 для JPEG/WebP	Не задано
max_width, max_height	Предельные размеры изображения	Не заданы
auto_orient	Учесть EXIF	true
strip_metadata	Удалить метаданные изображения	true

Другие типы медиа получают свои параметры операции, а не неограниченный список флагов.

Пример

YAMLФрагмент формата v2

- id: cover
  block: media
  params:
    operation: image_process
    file: "{inputs.photo}"
    format: webp
    max_width: 1200
    max_height: 1200
    quality: 85

Результат

image_process: file, width, height, format, size, re_encoded. Между шагами передаётся FileRef, не массив байтов. Схемы аудио/видео включают длительность, кодеки и характеристики соответствующего потока.

Поведение

Для изображений пропорции сохраняются, увеличения нет. quality с PNG — ошибка. При JPEG прозрачность накладывается на белый фон. re_encoded показывает перекодирование. Повреждённый файл завершает шаг ошибкой.

Неподдержанные типы и сочетания параметров отклоняются явно. Кодек и формат выбираются из списка возможностей установки.

Базовый охват

Тип	Операции	Популярные сценарии
Все три типа	probe	Формат, размер, длительность и параметры потоков
Изображения	image_process	JPEG/PNG/WebP, размеры, качество, EXIF и метаданные
Аудио	audio_process	MP3/WAV/Opus, преобразование, обрезка, частота дискретизации, каналы
Видео	video_process	MP4/WebM, преобразование, обрезка, размеры, удаление аудиодорожки
Видео	extract_audio, thumbnail	Извлечь звук в аудиофайл; получить кадр-превью

Для аудио/видео используется общий адаптер FFmpeg, подключаемый соответствующими плагинами; доступные кодеки зависят от поставки. Произвольные shell-команды и флаги не становятся интерфейсом media.

Распознавание речи, генерация и сложный монтаж не входят в этот стартовый набор. PDF и офисные документы требуют отдельного решения о границах блока.

Параметры операций

У всех операций один файловый вход и явный выбор операции; специальные параметры привязаны к типу медиа:

Операция	Специальные параметры начального контракта
probe	Только file; чтение характеристик без преобразования
image_process	format, quality, max_width, max_height, auto_orient, strip_metadata
audio_process	format, start_seconds=0, end_seconds=null, sample_rate, channels, bitrate, strip_metadata=true
video_process	format, start_seconds=0, end_seconds=null, max_width, max_height, fps, keep_audio=true, strip_metadata=true
extract_audio	format=wav, sample_rate, channels
thumbnail	at_seconds=0, format=jpeg, max_width, max_height

Незаданные параметры потоков сохраняют свойства исходника. end_seconds должен быть больше начала; время — конечное неотрицательное число. quality изображения и bitrate аудио не объединяем: это разные величины. Для длительности и кодеков нужны отдельные схемы результата каждой операции.

Pillow и FFmpeg подключаются опционально по общей схеме. Объявленный формат не снимает ограничения файлового хранилища.

Плагины и установка

В составе блока: Общий контракт и FileRef. Обработчиков по умолчанию нет.

Плагин	Возможности
images	Характеристики и обработка изображений
audio	Характеристики и обработка аудио
video	Обработка видео, извлечение звука и превью

probe работает для типов установленных плагинов. Аудио и видео используют общую интеграцию FFmpeg; бинарник и доступные кодеки определяются окружением. video включает извлечение звука и кадра без обязательной установки плагинов audio/images.