253 lines
15 KiB
Markdown
253 lines
15 KiB
Markdown
# NaviWatcher
|
||
|
||
> **Language:** [English](#english) | [Русский](#русский)
|
||
|
||
---
|
||
|
||
## English
|
||
|
||
NaviWatcher is an autonomous service daemon that monitors your Navidrome music collection, compares it against artist discographies from MusicBrainz, and notifies you about missing releases via Telegram and a built-in web interface.
|
||
|
||
### How It Works
|
||
|
||
1. **Scans** your Navidrome library via Subsonic API to get the list of artists and albums.
|
||
2. **Fetches** full artist discographies from MusicBrainz (using Release Groups to avoid duplicate editions).
|
||
3. **Compares** local collection with external data using fuzzy matching (configurable threshold, default 0.85).
|
||
4. **Syncs automatically** on a periodic loop (`sync.interval`, default 6h): Navidrome artist/album pull → lazy MusicBrainz ID resolution → discography cache → re-scan, so the dashboard and digests always reflect current state.
|
||
5. **Notifies** you about missing albums/singles/EPs through daily Telegram digests and a web dashboard.
|
||
|
||
### How It Works Now
|
||
|
||
On startup NaviWatcher opens (or auto-migrates) a local SQLite database at `naviwatcher.db` in the working directory, performs one immediate sync+scan, then runs a ticker-driven periodic sync+scan goroutine until SIGTERM. The Web UI serves a basic-auth-protected dashboard; the Notifier runs a cron scheduler emitting a daily digest of newly-found missing releases (tracked via `notifications_sent`). The MusicBrainz ID for each artist is resolved lazily on first sync and cached on the `artist_settings` row.
|
||
|
||
### Features
|
||
|
||
- **Subsonic API compatible** — works with Navidrome, Airsonic, Ampache, and other Subsonic-compatible servers.
|
||
- **Fuzzy matching** — smart string normalization (ignores remastered/deluxe/anniversary editions, year suffixes, special characters).
|
||
- **Per-artist filters** — opt out of Singles and Compilations per artist (via `artist_settings`); type filtering includes only Album/Single/EP primary types (plus release groups whose secondary types include Single/EP/Compilation).
|
||
- **MusicBrainz caching** — 24-hour TTL cache to minimize API calls and respect rate limits (1 req/sec).
|
||
- **Telegram notifications** — daily summary messages with links to the web UI, sent on the configured `telegram.cron_schedule`.
|
||
- **Web dashboard** — browse missing albums, ignore releases, manage artist-specific settings, with an archive of ignored releases.
|
||
- **Single binary deployment** — all HTML templates embedded via `//go:embed`.
|
||
- **Docker support** — ready for `docker compose` deployment.
|
||
|
||
### Technology Stack
|
||
|
||
- **Language:** Go 1.25+
|
||
- **Database:** SQLite 3
|
||
- **HTTP Server:** Go standard library (`net/http` + `html/template`)
|
||
- **Key dependencies:**
|
||
- `github.com/mattn/go-sqlite3` — SQLite driver
|
||
- `github.com/lithammer/fuzzysearch` — fuzzy string matching
|
||
- `gopkg.in/yaml.v3` — configuration parsing
|
||
|
||
### Quick Start
|
||
|
||
1. **Create a service user in Navidrome:**
|
||
- Go to Settings → Users → Add User
|
||
- Set a username and password
|
||
- Ensure the user has access to your music libraries
|
||
|
||
2. **Configure NaviWatcher:**
|
||
```bash
|
||
cp config.yaml.example config.yaml
|
||
# Edit config.yaml with your settings
|
||
```
|
||
|
||
3. **Build and run:**
|
||
```bash
|
||
go build -o naviwatcher
|
||
./naviwatcher
|
||
```
|
||
|
||
4. **Or use Docker:**
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
5. **Access the web UI** at `http://localhost:8080`
|
||
|
||
> **Note (current status):** On startup the service opens a local SQLite database at
|
||
> `naviwatcher.db` in the working directory (existing databases are auto-migrated), performs
|
||
> one immediate sync+scan, then runs a periodic sync+scan loop (`sync.interval`, default 6h)
|
||
> until shutdown. `musicbrainz.user_agent` is required and validated at startup. The Web UI
|
||
> (basic-auth protected) and Telegram notifier (cron-scheduled) are wired in; set
|
||
> `telegram.enabled` to activate digests.
|
||
|
||
### Configuration
|
||
|
||
```yaml
|
||
server:
|
||
host: "0.0.0.0"
|
||
port: 8080
|
||
username: "admin"
|
||
password: "CHANGE_ME"
|
||
|
||
navidrome:
|
||
url: "http://localhost:4533"
|
||
user: "watcher_service"
|
||
password: "CHANGE_ME"
|
||
|
||
musicbrainz:
|
||
user_agent: "NaviWatcher/1.0 ( mail@example.com )"
|
||
cache_ttl: 24h
|
||
|
||
telegram:
|
||
enabled: true
|
||
token: "bot_token"
|
||
chat_id: "your_chat_id"
|
||
cron_schedule: "0 10 * * *"
|
||
|
||
scanner:
|
||
fuzzy_threshold: 0.85
|
||
|
||
# Periodic sync+scan loop frequency (Go duration, e.g. "6h", "30m"); defaults to 6h.
|
||
sync:
|
||
interval: 6h
|
||
```
|
||
|
||
See [docs/Specification.md](docs/Specification.md) for the full configuration reference and architecture details.
|
||
|
||
### Architecture
|
||
|
||
| Module | Purpose |
|
||
|--------|---------|
|
||
| **Navidrome Client** | Subsonic API v1.16.1 communication (token-based auth) |
|
||
| **MusicBrainz Provider** | Discography fetching with rate limiting and caching |
|
||
| **Scanner Engine** | String normalization and fuzzy comparison |
|
||
| **Database Layer** | SQLite persistence: `artist_settings`, `local_albums` (Navidrome sync), `external_releases` (MusicBrainz cache), `notifications_sent` |
|
||
| **Notifier** | Scheduled Telegram notifications |
|
||
| **Web UI** | Dashboard for browsing and managing missing releases |
|
||
|
||
### Implementation Status
|
||
|
||
- **Scanner Engine** — implemented. The missing-release detection core is complete: string normalization lives in `internal/normalize`, similarity scoring and the diff engine (`FindMissingReleases`, `ScanArtist`, `ScanAll`) in `internal/scanner`. It uses the configurable `scanner.fuzzy_threshold` (default 0.85), normalizes titles (ignoring `(Remastered)`/year/special-char variants), and skips releases marked ignored.
|
||
- **Sync pipeline** — implemented. `SyncAll` pulls artists/albums from Navidrome into the DB, resolves each artist's MusicBrainz ID lazily (cached on `artist_settings.mbid`), syncs the MusicBrainz discography, then re-runs the scanner. Wired into `main.run()` as an immediate + periodic (`sync.interval`) loop.
|
||
- **Notifier** — implemented. A `Sender` interface with a Telegram implementation, `FormatDigest` for daily summaries, and a cron scheduler honoring `telegram.cron_schedule` (no-op when `enabled=false`); sent-tracking via `notifications_sent`.
|
||
- **Web UI** — implemented. Basic-auth-protected `net/http` server with `//go:embed` templates: dashboard with missing-release counts, artist detail with ignore actions, and an archive of ignored releases with restore.
|
||
|
||
### License
|
||
|
||
[WTFPL](License.md) — Do What The Fuck You Want To Public License
|
||
|
||
---
|
||
|
||
## Русский
|
||
|
||
NaviWatcher — это автономный сервис-демон для мониторинга музыкальной коллекции в Navidrome. Он сравнивает вашу медиатеку с полными дискографиями артистов из MusicBrainz и уведомляет об отсутствующих релизах через Telegram и веб-интерфейс.
|
||
|
||
### Как это работает
|
||
|
||
1. **Сканирует** библиотеку Navidrome через Subsonic API — получает список артистов и альбомов.
|
||
2. **Загружает** полные дискографии артистов из MusicBrainz (использует Release Groups, чтобы избежать дубликатов изданий).
|
||
3. **Сравнивает** локальную коллекцию с внешними данными через нечёткое сравнение строк (настраиваемый порог, по умолчанию 0.85).
|
||
4. **Синхронизируется автоматически** по периодическому циклу (`sync.interval`, по умолчанию 6h): выгрузка артистов/альбомов из Navidrome → ленивое разрешение MusicBrainz ID → кэш дискографии → повторное сканирование, чтобы панель и дайджесты всегда отражали текущее состояние.
|
||
5. **Уведомляет** об отсутствующих альбомах/синглах/EP через ежедневные дайджесты в Telegram и веб-панель.
|
||
|
||
### Как это работает сейчас
|
||
|
||
При запуске NaviWatcher открывает (или автомигрирует) локальную SQLite-БД `naviwatcher.db` в рабочей директории, выполняет одну немедленную синхронизацию+сканирование, затем запускает управляемый тикером периодический цикл до получения SIGTERM. Веб-интерфейс — это панель под basic-auth; нотификатор запускает cron-планировщик, отправляющий ежедневный дайджест новых отсутствующих релизов (отслеживается через `notifications_sent`). MusicBrainz ID каждого артиста разрешается лениво при первой синхронизации и кэшируется в строке `artist_settings`.
|
||
|
||
### Возможности
|
||
|
||
- **Совместим с Subsonic API** — работает с Navidrome, Airsonic, Ampache и другими Subsonic-совместимыми серверами.
|
||
- **Нечёткое сравнение** — умная нормализация строк (игнорирует ремастеры, deluxe/anniversary-издания, год в скобках, спецсимволы).
|
||
- **Фильтры по артистам** — отключение синглов и компиляций для конкретного артиста (через `artist_settings`); фильтрация по типам включает только основные типы Album/Single/EP (а также группы релизов, чьи вторичные типы содержат Single/EP/Compilation).
|
||
- **Кэширование MusicBrainz** — TTL 24 часа для минимизации запросов и соблюдения лимитов (1 запрос/сек).
|
||
- **Уведомления в Telegram** — ежедневные сводки со ссылками на веб-интерфейс, отправляемые по расписанию `telegram.cron_schedule`.
|
||
- **Веб-панель** — просмотр отсутствующих альбомов, игнорирование релизов, управление настройками артистов, архив проигнорированных релизов.
|
||
- **Один бинарный файл** — все HTML-шаблоны встроены через `//go:embed`.
|
||
- **Поддержка Docker** — готов к развёртыванию через `docker compose`.
|
||
|
||
### Технологический стек
|
||
|
||
- **Язык:** Go 1.21+
|
||
- **База данных:** SQLite 3
|
||
- **HTTP-сервер:** стандартная библиотека Go (`net/http` + `html/template`)
|
||
- **Ключевые зависимости:**
|
||
- `github.com/mattn/go-sqlite3` — драйвер SQLite
|
||
- `github.com/lithammer/fuzzysearch` — нечёткое сравнение строк
|
||
- `gopkg.in/yaml.v3` — парсинг конфигурации
|
||
|
||
### Быстрый старт
|
||
|
||
1. **Создайте сервисного пользователя в Navidrome:**
|
||
- Перейдите в Settings → Users → Add User
|
||
- Задайте имя пользователя и пароль
|
||
- Убедитесь, что у пользователя есть доступ к медиатекам
|
||
|
||
2. **Настройте NaviWatcher:**
|
||
```bash
|
||
cp config.yaml.example config.yaml
|
||
# Отредактируйте config.yaml
|
||
```
|
||
|
||
3. **Соберите и запустите:**
|
||
```bash
|
||
go build -o naviwatcher
|
||
./naviwatcher
|
||
```
|
||
|
||
4. **Или используйте Docker:**
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
5. **Откройте веб-интерфейс** по адресу `http://localhost:8080`
|
||
|
||
### Конфигурация
|
||
|
||
```yaml
|
||
server:
|
||
host: "0.0.0.0"
|
||
port: 8080
|
||
username: "admin"
|
||
password: "CHANGE_ME"
|
||
|
||
navidrome:
|
||
url: "http://localhost:4533"
|
||
user: "watcher_service"
|
||
password: "CHANGE_ME"
|
||
|
||
musicbrainz:
|
||
user_agent: "NaviWatcher/1.0 ( mail@example.com )"
|
||
cache_ttl: 24h
|
||
|
||
telegram:
|
||
enabled: true
|
||
token: "bot_token"
|
||
chat_id: "your_chat_id"
|
||
cron_schedule: "0 10 * * *"
|
||
|
||
scanner:
|
||
fuzzy_threshold: 0.85
|
||
|
||
# Частота периодического цикла синхронизации+сканирования (длительность Go, напр. "6h", "30m"); по умолчанию 6h.
|
||
sync:
|
||
interval: 6h
|
||
```
|
||
|
||
Полную справку по конфигурации и архитектуру см. в [docs/Specification.md](docs/Specification.md).
|
||
|
||
### Архитектура
|
||
|
||
| Модуль | Назначение |
|
||
|--------|------------|
|
||
| **Navidrome Client** | Взаимодействие с Subsonic API v1.16.1 (токенная аутентификация) |
|
||
| **MusicBrainz Provider** | Загрузка дискографий с кэшированием и rate limiting |
|
||
| **Scanner Engine** | Нормализация строк и нечёткое сравнение |
|
||
| **Database Layer** | SQLite: `artist_settings`, `local_albums` (синхронизация из Navidrome), `external_releases` (кэш MusicBrainz), `notifications_sent` |
|
||
| **Notifier** | Планировщик уведомлений в Telegram |
|
||
| **Web UI** | Панель управления отсутствющими релизами |
|
||
|
||
### Статус реализации
|
||
|
||
- **Scanner Engine** — реализован. Ядро поиска отсутствующих релизов готово: нормализация строк в `internal/normalize`, оценка схожести и движок сравнения (`FindMissingReleases`, `ScanArtist`, `ScanAll`) в `internal/scanner`. Используется настраиваемый `scanner.fuzzy_threshold` (по умолчанию 0.85), игнорируются варианты `(Remastered)`/год/спецсимволы, пропускаются отмеченные как игнорируемые.
|
||
- **Sync pipeline** — реализован. `SyncAll` выгружает артистов/альбомы из Navidrome в БД, лениво разрешает MusicBrainz ID каждого артиста (кэшируется в `artist_settings.mbid`), синхронизирует дискографию MusicBrainz, затем повторно запускает сканер. Подключён в `main.run()` как немедленный + периодический (`sync.interval`) цикл.
|
||
- **Notifier** — реализован. Интерфейс `Sender` с Telegram-реализацией, `FormatDigest` для ежедневных сводок и cron-планировщик по `telegram.cron_schedule` (no-op при `enabled=false`); отслеживание отправок через `notifications_sent`.
|
||
- **Web UI** — реализован. Защищённый basic-auth `net/http` сервер с `//go:embed` шаблонами: панель со счётчиками отсутствующих релизов, страница артиста с действиями игнорирования и архив проигнорированных релизов с восстановлением.
|
||
|
||
### Лицензия
|
||
|
||
[WTFPL](License.md) — Do What The Fuck You Want To Public License
|