# Documentation / Документация

## EN

### 1) How the bot works

1. Poll Mastodon notifications for `mention` type (`/api/v1/notifications`).
2. For each mention:
   - Extract plain text from HTML content
   - Remove all mentions like `@giffer` / `@giffer@domain` / `@ giffer`
   - Detect `nsfw` keyword
   - Parse remaining text into tags (supports quotes and `-tag`)
3. Query Furbooru (Philomena API) for GIF images:
   - SFW query adds: `safe, animated, gif`
   - NSFW query adds: `animated, gif` (plus `filter_id` if configured)
4. Pick a random candidate GIF result.
5. Upload media to Mastodon:
   - Try GIF representations in descending size: `full → large → medium → small → thumb`
   - If Mastodon rejects GIF with 422 “not supported” / size limits:
     - Convert GIF → MP4 using ffmpeg
     - Upload MP4 instead
6. Wait for Mastodon media processing to finish (poll `/api/v1/media/:id`):
   - prevents 422 “processing not finished” when posting the status
7. Post reply status with uploaded media:
   - SFW: normal reply
   - NSFW: `sensitive=True` and `spoiler_text="NSFW"` (+ configurable visibility)
8. Save state:
   - `last_seen_notif_id`
   - list of processed `status_id` (to avoid replying twice after restarts)

---

### 2) Query syntax

The bot converts the mention text to Furbooru tags:

- Spaces become multiple tags:  
  `cute fluffy tail` → `cute, fluffy, tail`
- Commas are also supported:  
  `cute, fluffy, tail`
- Quoted phrases stay together as one tag:  
  `"rainbow dash"` → `rainbow dash`
- Negative tags are supported:  
  `-gore` → `-gore`
- `random` / `rnd` are ignored and treated as no user tags (random result).

NSFW mode:
- Any mention containing the word `nsfw` enables NSFW mode and removes that word from the tag list.

---

### 3) Furbooru API notes

Endpoint used:
- `GET /api/v1/json/search/images?q=...&per_page=50&page=1`

The bot filters results:
- `format == "gif"`
- has usable `representations` URL(s)
- chooses randomly among candidates

---

### 4) ALT text generation

ALT text is generated from Furbooru tags:
- removes rating/system tags like `safe`, `nsfw`, `animated`, `gif`
- keeps up to 20 tags
- prefix:
  - `Animated GIF: ...`
  - `NSFW animated GIF: ...`

---

### 5) Rate limiting & anti-spam

Two layers:

1) Per-user cooldown:
- If the same user mentions the bot again within `USER_COOLDOWN_SEC`, bot skips.

2) Global token bucket:
- `GLOBAL_RATE_PER_SEC` tokens refill rate
- `GLOBAL_BURST` max burst
- applies to Furbooru requests

---

### 6) Prevent replying twice (state)

The bot persists state to `STATE_FILE` (default `giffer_state.json`):
- `last_seen_notif_id` (so it won’t re-fetch old notifications after restart)
- `processed_status_ids` (cache to skip duplicates even if server repeats notifications)

If you delete the state file, the bot may reply to old mentions again.

---

### 7) Windows reliability notes

This project includes hardening for Windows:
- `socket.setdefaulttimeout(SOCKET_DEFAULT_TIMEOUT)` to prevent rare indefinite hangs
- `requests.Session` with retries
- explicit connect/read timeouts
- Mastodon API calls are wrapped with a watchdog timeout (thread executor)

---

### 8) Troubleshooting

**Bot replies “media processing not finished” / 422**
- Increase `MEDIA_PROCESS_MAX_WAIT` (e.g. 90)
- Your instance may be slow during peak hours

**GIF rejected: “1440x1440 GIF files are not supported”**
- Expected on some instances
- Bot will fallback to smaller GIF representations
- Then fallback to MP4 conversion

**MP4 conversion fails**
- Install bundled ffmpeg:
  - `py -m pip install imageio-ffmpeg`
- Or install system ffmpeg and ensure it’s in PATH

**Bot replies to old mentions after restart**
- Check `STATE_FILE` exists and is writable
- Don’t delete `giffer_state.json`

---

## RU

### 1) Как работает бот

1. Опрос уведомлений Mastodon типа `mention` (`/api/v1/notifications`).
2. Для каждого упоминания:
   - Достаём текст из HTML
   - Удаляем любые упоминания (`@giffer`, `@giffer@домен`, `@ giffer`)
   - Определяем наличие `nsfw`
   - Парсим оставшееся в теги (есть кавычки и `-тег`)
3. Запрос на Furbooru (Philomena API) за GIF:
   - SFW добавляет: `safe, animated, gif`
   - NSFW добавляет: `animated, gif` (и `filter_id`, если задан)
4. Выбор случайного подходящего результата.
5. Загрузка медиа в Mastodon:
   - Пробуем GIF (full → large → medium → small → thumb)
   - Если инстанс отклоняет GIF с 422 (“not supported”/лимиты):
     - Конвертим GIF → MP4 через ffmpeg
     - Заливаем MP4
6. Ждём завершения обработки медиа в Mastodon (`/api/v1/media/:id`):
   - предотвращает 422 “обработка не окончена” при публикации
7. Публикуем ответ:
   - SFW: обычный ответ
   - NSFW: `sensitive=True` и `spoiler_text="NSFW"` (+ настраиваемая видимость)
8. Сохраняем состояние:
   - `last_seen_notif_id`
   - кэш `status_id` (чтобы не отвечать повторно после рестарта)

---

### 2) Синтаксис запроса (теги)

- Пробелы = несколько тегов:  
  `cute fluffy tail` → `cute, fluffy, tail`
- Запятые тоже можно:  
  `cute, fluffy, tail`
- Кавычки сохраняют фразу как один тег:  
  `"rainbow dash"` → `rainbow dash`
- Минус-теги работают:  
  `-gore` → `-gore`
- `random` / `rnd` игнорируются (рандомный результат).

NSFW-режим:
- Если в тексте есть слово `nsfw`, включается NSFW и это слово убирается из тегов.

---

### 3) Про Furbooru API

Используем:
- `GET /api/v1/json/search/images?q=...&per_page=50&page=1`

Фильтруем результаты:
- `format == "gif"`
- есть рабочие ссылки `representations`
- выбираем случайно

---

### 4) ALT-текст

ALT строится из тегов Furbooru:
- выкидываются системные/рейтинг-теги `safe`, `nsfw`, `animated`, `gif`
- берём до 20 тегов
- префикс:
  - `Animated GIF: ...`
  - `NSFW animated GIF: ...`

---

### 5) Антиспам / Rate-limit

1) Кулдаун на пользователя (`USER_COOLDOWN_SEC`)  
2) Глобальный token-bucket (`GLOBAL_RATE_PER_SEC`, `GLOBAL_BURST`)

---

### 6) Защита от повторных ответов (state)

Файл `STATE_FILE` (по умолчанию `giffer_state.json`) хранит:
- `last_seen_notif_id`
- `processed_status_ids`

Если удалить state-файл — бот может снова отвечать на старые упоминания.

---

### 7) Особенности Windows

Усиленная защита от “вечных зависаний”:
- `socket.setdefaulttimeout(...)`
- `requests.Session` с retry
- явные таймауты connect/read
- watchdog-таймаут вокруг вызовов Mastodon API

---

### 8) Типовые проблемы

**422 “обработка файлов не окончена”**
- увеличь `MEDIA_PROCESS_MAX_WAIT` (например до 90)
- инстанс может быть медленным

**“1440x1440 GIF files are not supported”**
- ожидаемо для некоторых инстансов
- бот уйдёт на меньшие версии GIF, потом на MP4

**Не конвертится в MP4**
- поставь `imageio-ffmpeg`:
  - `py -m pip install imageio-ffmpeg`
- или установи ffmpeg в систему и добавь в PATH

**После рестарта отвечает на старые упоминания**
- проверь, что `giffer_state.json` не удаляется и доступен на запись

---

### 9) Рекомендуемая структура репо

- `giffer_bot.py`
- `README.md`
- `docs.md`
- `.gitignore` (исключить `config.env`, `giffer_state.json`, `*.log`)
- `LICENSE`