NaviWatcher/README.md

NaviWatcher

Language: 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. Notifies you about missing albums/singles/EPs through daily Telegram digests and a web dashboard.

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).
• Configurable filters — ignore bootlegs, singles, compilations, live albums, remixes, soundtracks per artist or globally.
• 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.
• Web dashboard — browse missing albums, ignore releases, manage artist-specific settings.
• 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:

   cp config.yaml.example config.yaml
   # Edit config.yaml with your settings
   

3. Build and run:

   go build -o naviwatcher
   ./naviwatcher
   

4. Or use Docker:

   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) and performs a compute-only scan of all monitored artists, logging the count of missing releases. musicbrainz.user_agent is required and validated at startup. The notifier and Web UI are not yet wired into the running service — scan results are logged only.

Configuration

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

See 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 (compute-only). 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.
• Notifier and Web UI — not yet implemented (out of scope for the scanner plan). main.run() currently performs a compute-only scan and logs missing-release counts; it does not persist results or send notifications.

License

WTFPL — 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. Уведомляет об отсутствующих альбомах/синглах/EP через ежедневные дайджесты в Telegram и веб-панель.

Возможности

• Совместим с Subsonic API — работает с Navidrome, Airsonic, Ampache и другими Subsonic-совместимыми серверами.
• Нечёткое сравнение — умная нормализация строк (игнорирует ремастеры, deluxe/anniversary-издания, год в скобках, спецсимволы).
• Гибкие фильтры — игнорирование бутлегов, синглов, компиляций, лайвов, ремиксаундов — глобально или для конкретного артиста.
• Кэширование MusicBrainz — TTL 24 часа для минимизации запросов и соблюдения лимитов (1 запрос/сек).
• Уведомления в Telegram — ежедневные сводки со ссылками на веб-интерфейс.
• Веб-панель — просмотр отсутствующих альбомов, игнорирование релизов, управление настройками артистов.
• Один бинарный файл — все 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:

   cp config.yaml.example config.yaml
   # Отредактируйте config.yaml
   

3. Соберите и запустите:

   go build -o naviwatcher
   ./naviwatcher
   

4. Или используйте Docker:

   docker compose up -d
   

5. Откройте веб-интерфейс по адресу http://localhost:8080

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

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

Полную справку по конфигурации и архитектуру см. в 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)/год/спецсимволы, пропускаются отмеченные как игнорируемые.
• Notifier и Web UI — пока не реализованы (вне рамок плана сканера). main.run() выполняет только вычислительное сканирование и логирует количество отсутствующих релизов; результаты не сохраняются и уведомления не отправляются.

Лицензия

WTFPL — Do What The Fuck You Want To Public License