# Стоки: видео, фото, иллюстрации, музыка

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

```bash
# Найти и посмотреть глазами
python scripts/stock_media.py "нейросеть обучение" --kind video \
  --orientation portrait --count 12 --duration 4-12 --sheet candidates.jpg

# Скачать только выбранное
python scripts/stock_media.py "нейросеть обучение" --kind video \
  --orientation portrait --count 12 --duration 4-12 \
  --ids pexels:35158244,pixabay:286689 --out project/assets/stock
```

## Провайдеры

| Провайдер | Виды | Ключ | Лицензия |
|---|---|---|---|
| Pexels | видео, фото | `PEXELS_API_KEY` | Pexels License, атрибуция не обязательна |
| Pixabay | видео, фото, иллюстрации | `PIXABAY_API_KEY` | Pixabay Content License |
| Openverse | фото, аудио | не нужен | CC0 / CC-BY / PDM, у каждого своя |
| Jamendo | музыка | `JAMENDO_CLIENT_ID` | Creative Commons, у каждого трека своя |

Публичный API Pixabay **не отдаёт музыку** — только изображения и видео. Не называй
визуальную категорию `music` музыкальным API. Для музыки: Jamendo через API, либо
трек с музыкального каталога Pixabay, скачанный вручную и зарегистрированный через
`scripts/register_music_asset.py`.

Pexels понимает русские запросы: «нейросеть обучение» даёт 1060 результатов.

## Поиск никогда не скачивает

Скачивание требует явных `provider:id`. «То, что API отдал первым» — не редакторское
решение. Идентификаторы действительны только для того же самого запроса, и скрипт
скажет об этом, если попросить чужой id.

## Выбор глазами, а не по JSON

Сток невозможно выбрать по метаданным. `--sheet` скачивает превью и раскладывает их в
сетку с подписями `провайдер:id`, размером и длительностью. Это и есть решение.

## Ранжирование

Балл считается по пригодности для монтажа: разрешение (до 4 очков), совпадение
ориентации (+2 или −2), попадание в желаемую длительность (+2). Ниже `--min-pixels`
— штраф 6 очков.

Ориентация у Pixabay ненадёжна: фильтр `vertical` возвращает клипы 3872×2160.
Штраф за несовпадение ориентации это учитывает, поэтому в смешанном рейтинге
вертикальные клипы Pexels обычно выигрывают честно.

## Дедупликация

Провайдеры зеркалят загрузки друг друга. Подпись строится из вида, автора,
округлённой длительности и начала тегов; остаётся копия с большим разрешением.

## Провенанс, который переживёт проект

Ничего не скачивается без записи: автор, ссылка на автора, страница источника,
лицензия и её URL, поисковый запрос, время загрузки, размер в байтах и SHA-256.
Для видео и аудио дополнительно прогоняется `ffprobe` — так проверяется, что файл
действительно читается, а не пришёл битым.

`manifest.json` накопительный: следующий поиск добавляет записи, а не заменяет их.

## Кэш

Ответы API кэшируются на 24 часа в `cache/stock/`. Ключ кэша **никогда** не включает
API-ключ. Превью кэшируются в `cache/stock/thumbs/`.

## Правила использования в монтаже

1. Сток не заменяет пользовательский исходник и не выдавливает уникальный кадр без
   смысловой причины.
2. Б-ролл выбирается **после** транскрипта, под конкретную мысль, а не «чтобы было
   динамичнее».
3. В первые 5 секунд не больше двух склеек, первый установочный план 2–4 секунды.
4. Сетевой кадр вставляется только при доказанном смысловом пробеле.
5. Найденный, но не подошедший клип не вставляется только потому, что уже скачан.