---
referenceVersion: 2
---

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

`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 и офисные документы требуют отдельного решения о границах блока.

<span id="решения-по-параметрам"></span>

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

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

| Операция | Специальные параметры начального контракта |
| --- | --- |
| `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 подключаются опционально по <a href="/doc/store" target="_self">общей схеме</a>. Объявленный формат не снимает ограничения файлового хранилища.

<span id="модули-и-поставка"></span>

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

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

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

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