# Папка просмотра — Автоматический импорт мультимедиа

Watch Folder - это автоматизированная система импорта контента. Он отслеживает локальные каталоги (или пульты дистанционного управления rclone) в поисках новых видеофайлов, анализирует их названия для извлечения метаданных (название, год, сезон, серия), ищет в базе данных TMDB обложки и описания и создает записи о фильмах/сериалах в базе данных — и все это без ручного вмешательства.

---

## как это работает

```
┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  Watch Folder    │────▶│   WatchCron       │────▶│  WatchItem       │
│  (directory on   │     │  scans for new    │     │  parses filename │
│   disk / rclone) │     │  files, filters   │     │  queries TMDB    │
│                  │     │  already imported  │     │  creates DB row  │
└──────────────────┘     └──────────────────┘     └──────────────────┘
                                                          │
                                                          ▼
                                                   ┌──────────────────┐
                                                   │  Bouquet update  │
                                                   │  (auto-assign    │
                                                   │   to bouquets)   │
                                                   └──────────────────┘
```

### Шаг за шагом

1. **Администратор создает папку наблюдения** в панели администратора (Папка просмотра → Добавить) или через API (`create_watch_folder`). Конфигурация включает в себя: путь к каталогу, тип контента (фильм/сериал), целевую категорию, букеты, настройки парсера и назначенный сервер.
2. **Задание Cron `cron:watch`** выполняется периодически (регулируется параметром `scan_offset` — секунды между сканированиями). Он запрашивает таблицу `watch_folders` для активных папок, в которых `last_run` превышено смещение.
3. **Обнаружение файлов** — cron использует `find` для локальных каталогов или `rclone lsjson` для облачных/удаленных подключений. Файлы фильтруются по разрешенным расширениям (по умолчанию: `mp4, mkv, avi, mpg, flv, 3gp, m4v, wmv, mov, ts`). Файлы, уже присутствующие в `streams.stream_source`, пропускаются.
4. **Проверка стабильности** — файлы, измененные менее 30 секунд назад, пропускаются (чтобы избежать импорта частично загруженных файлов).
5. **Параллельная обработка** — каждый новый файл отправляется команде `watch_item` (через `shell_exec`), параллельно запуская до `thread_count` элементов с помощью `Multithread`.
6. **Элемент наблюдения** анализирует имя файла с помощью PTN или guessit (смотрите документацию по синтаксическому анализу ниже), преобразует метаданные с помощью TMDB API и вставляет запись в `streams` (для фильмов) или `streams_series` + `streams_episodes` (для сериалов).
7. **Назначение букета** — импортированные элементы автоматически добавляются в настроенные букеты.

---

## Конфигурация

### Просмотр настроек папки (для каждой папки)

|Установка|Описание|
|---------|-------------|
| `directory` |Локальный путь для сканирования (например, `/mnt/media/movies/`)|
| `rclone_dir` |удаленный путь к rclone (альтернатива локальному каталогу)|
| `type` |Тип содержимого: `movie` или `series`|
| `server_id` |Сервер, на котором выполняется сканирование|
| `category_id` |Целевая категория для импортируемого контента|
| `bouquets` |Автоматическое назначение этим букетам|
| `fb_category_id` |Резервная категория (в случае сбоя в сопоставлении жанров TMDB)|
| `fb_bouquets` |Резервные букеты|
| `allowed_extensions` |Расширения файлов для сканирования (пустые = список по умолчанию)|
| `language` |Предпочтительный язык TMDB для метаданных|
| `active` |Включить/отключить эту папку|

### Логические параметры

|Вариант|Описание|
|--------|-------------|
| `disable_tmdb` |Пропустить поиск в TMDB — импортировать файл только с разобранным заголовком|
| `ignore_no_match` |Импорт, даже если TMDB не возвращает результата|
| `auto_subtitles` |Автоматическое определение `.srt`, `.sub`, `.sbv` файлов рядом с видео|
| `fallback_title` |Используйте имя папки в качестве заголовка, если синтаксический анализатор не может ее извлечь|
| `read_native` |Чтение собственного заголовка из TMDB|
| `movie_symlink` |Создавайте символические ссылки вместо ссылок на исходный путь|
| `auto_encode` |Автоматическое кодирование импортированного содержимого|
| `auto_upgrade` |Замените существующую версию более низкого качества, если идентификатор TMDB совпадает|
| `duplicate_tmdb` |Разрешить многократный импорт с одним и тем же идентификатором TMDB|
| `ffprobe_input` |Запустите ffprobe в исходном файле для извлечения метаданных кодека|
| `extract_metadata` |Извлечение дополнительных метаданных из файла|

### Глобальные настройки

|Установка|Где|Описание|
|---------|-------|-------------|
| `tmdb_api_key` |Администратор → Настройки|**Требуемый** — Ключ API TMDB. Без него Watch не будет работать|
| `fallback_parser` |Администратор → Настройки|Синтаксический анализатор, используемый при сбое основного синтаксического анализатора|
| `alternative_titles` |Администратор → Настройки|Поиск альтернативных названий в базе данных TMDB|
| `max_genres` |Администратор → Настройки|Максимальное количество жанров, назначаемых для каждого элемента|

---

## Панель администратора и API

### Страницы панели администратора

|Страница|Описание|
|------|-------------|
|Смотреть папку → Список|Просмотр всех настроенных папок наблюдения со статусом|
|Посмотреть папку → Добавить|Создание/редактирование папки наблюдения|
|Папка просмотра → Настройки|Глобальные настройки просмотра (синтаксический анализатор, конфигурация TMDB)|
|Просмотр папки → Журналы|Просмотр результатов сканирования и ошибок|

### Действия администратора API

|Действие|Описание|
|--------|-------------|
| `get_watch_folders` |Перечислите все папки для просмотра|
| `get_watch_folder` |Получить единую папку по идентификатору|
| `create_watch_folder` |Создайте новую папку наблюдения|
| `edit_watch_folder` |Обновите существующую папку наблюдения|
| `delete_watch_folder` |Удалить папку наблюдения|
| `reload_watch_folder` |Принудительное немедленное повторное сканирование|
| `enable_watch` |Включить все папки наблюдения|
| `disable_watch` |Отключите все папки наблюдения|
| `kill_watch` |Уничтожьте все запущенные процессы наблюдения|

### КЛИ

```bash
# Normal cron execution (usually triggered automatically)
sudo -u xc_vm /home/xc_vm/console.php cron:watch

# Force scan a specific folder (by ID)
sudo -u xc_vm /home/xc_vm/console.php cron:watch 5
```

---

## Анализаторы

Доступны два средства анализа имен файлов. Средство анализа извлекает структурированные метаданные (название, год, сезон, эпизод, разрешение, кодек) из имени видеофайла.

### Выбор синтаксического анализатора

|Синтаксический анализатор|Лучше всего для|
|--------|----------|
| **PTN** | Simple filenames with spaces: `San Andreas 2015 720p.mkv` |
| **guessit** | Dot-separated filenames: `The.Matrix.1999.1080p.BluRay.mkv` |

Установите основной синтаксический анализатор для каждой папки просмотра. Глобальный параметр `fallback_parser` используется, когда основной синтаксический анализатор не возвращает совпадений.

---

## 1️⃣ Синтаксический анализатор PTN

PTN parser поддерживает синтаксический анализ файлов фильмов и телешоу с типичными шаблонами именования.

### Фильмы

|Пример файла|Проанализированные данные|
|-------------|-------------|
| `San Andreas 2015 720p WEB-DL x264 AAC-JYK.mkv` |Название: *San Andreas*, Год выпуска: 2015, Разрешение: 720p, Видео: x264, Аудио: AAC, Группа: JYK|
| `The Martian 2015 540p HDRip KORSUB x264 AAC2 0-FGT.mp4` |Название: "Марсианин", Год выпуска: 2015, Разрешение: 540p, Видео: x264, Аудио: AAC2.0, Группа: FGT|

### Телевизионные шоу

|Пример файла|Проанализированные данные|
|-------------|-------------|
| `friends.s02e01.720p.bluray-sujaidr.mkv` |Название: *Друзья*, Сезон: 2, Серия: 1, Разрешение: 720p, Формат: bluray, Группа: sujaidr|
| `Mr Robot S01E05 HDTV x264-KILLERS[ettv].mp4` |Название: *Мистер Робот*, Сезон: 1, Серия: 5, Формат: HDTV, Видео: x264, Группа: KILLERS|

---

## 2️⃣ синтаксический анализатор догадок

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

### Фильмы

|Пример файла|Проанализированные данные|
|-------------|-------------|
| `The.Matrix.1999.1080p.BluRay.x264.DTS-FGT.mkv` |Название: "Матрица", Год выпуска: 1999, Разрешение: 1080p, Видео: x264, Аудио: DTS, Группа: FGT|
| `Inception.2010.720p.BRRip.x264.AAC-ETRG.mkv` |Название: *Начало*, Год выпуска: 2010, Разрешение: 720p, Видео: x264, Аудио: AAC, Группа: ETRG|

### Телевизионные шоу

|Пример файла|Проанализированные данные|
|-------------|-------------|
| `Breaking.Bad.S03E07.720p.BluRay.x264-REWARD.mkv` |Название: "Во все тяжкие", Сезон: 3, Серия: 7, Разрешение: 720p, Видео: x264, Группа: REWARD|
| `Game.of.Thrones.S05E09.1080p.WEB-DL.DD5.1.H.264-NTb.mkv` |Название: *Игра престолов*, Сезон: 5, Серия: 9, Разрешение: 1080p, Видео: H.264, Аудио: DD5.1, Группа: NTb|

---

### Возврат к имени резервной папки

Если имя файла не содержит отображаемого заголовка, включите **Возврат к имени резервной папки**:

|Пример пути к файлу|Проанализированные данные|
|-----------------|-------------|
| `/path/to/Show Name/S01E01 720p WEB-DL.mkv` |Название: *Название сериала*, Сезон: 1, Серия: 1|
| `/path/to/Show.Name/S01E01.720p.WEB-DL.mkv` |Название: *Название сериала*, Сезон: 1, Серия: 1|

#### Структура сезонных папок

Если вы хотите, чтобы эпизоды были отсортированы по папкам сезонов, имя файла должно содержать название шоу:

|Пример пути к файлу|Проанализированные данные|
|-----------------|-------------|
| `/path/to/Show Name/Season 01/Show Name S01E01 720p WEB-DL.mkv` |Название: *Название сериала*, Сезон: 1, Серия: 1|
| `/path/to/Show.Name/Season.01/Show.Name.S01E01.720p.WEB-DL.mkv` |Название: *Название сериала*, Сезон: 1, Серия: 1|

---

### Языки RTL

Для показов на языках RTL (арабский, иврит и т.д.):

- Имя файла **не должно содержать названия шоу**
- Включить **Возврат к имени резервной папки**

|Пример пути к файлу|Проанализированные данные|
|-----------------|-------------|
| `/path/to/Show Name/S01E01 (year).mp4` |Название: *Название сериала*, Сезон: 1, Серия: 1, Год выпуска: `year`|
| `/path/to/Show Name/Season 01/S01E01 (year).mp4` |Название: *Сезон 01*, Сезон: 1, Серия: 1, Год выпуска: `year`|

> ❗️ Примечание: Для языков RTL название показа берется только из названия папки.

---

### Резюме

- **Анализатор PTN** — простые имена файлов, локальные форматы
- **синтаксический анализатор догадок** — поддерживает имена, разделенные точками, многоязычные заголовки, возврат к имени папки
- **Языки RTL** — необходимо использовать резервную копию имени папки
- **Структура сезонных папок** — отображаемый заголовок должен быть в имени файла для корректной сортировки

---

💡 **Совет:** Используйте согласованные имена файлов и папок для точного анализа и автоматической сортировки по сезонам.