ytdlp-navidrome — сервис поиска и загрузки музыки

Назначение

Сервис-компаньон к Navidrome. Интерфейс — Matrix-бот. Позволяет:

1. Искать музыку по названию трека или имени исполнителя.
2. Отправлять превью (файл аудио) в чат для прослушивания.
3. По подтверждению пользователя скачивать трек в коллекцию Navidrome.

Весь трафик наружу (yt-dlp и Matrix) проходит через локальный ByeByeDPI-прокси (обход DPI).

Инфраструктура: k3s на Raspberry Pi. Музыка хранится на SSD:

• Рабочая директория (превью): /mnt/ssd/k3s/services/ytdlp_navidrome/tmp
• Коллекция Navidrome (финальный файл): /mnt/ssd/k3s/services/navidrome/music/ytdlp

---

1. Архитектура

┌────────────┐                    ┌────────────────────────────────┐
│ Matrix     │   Matrix CS API    │      ytdlp-navidrome pod       │
│ homeserver │◄──────────────────►│                                │
│            │                    │  ┌────────────┐ ┌───────────┐  │
└────────────┘                    │  │ Go-сервис  │ │ ByeByeDPI │  │
                                  │  │ (Matrix    │ │ (sidecar  │  │
                                  │  │  бот +     │ │  SOCKS5   │  │
                                  │  │  yt-dlp)   │ │  прокси)  │  │
                                  │  └─────┬──────┘ └─────▲─────┘  │
                                  │        │              │ :1080   │
                                  │        │  --proxy     │         │
                                  │        └──────────────┘         │
                                  └───────────────┬────────────────┘
                                                  │
                       ┌──────────────────────────┼──────────────┐
                       │ /mnt/ssd (hostPath)      │              │
                       │                          ▼              │
                       │  ytdlp_navidrome/tmp/    navidrome/music/ytdlp/
                       │  (превью, очищается)     (финальные файлы)
                       └─────────────────────────────────────────┘

Стек

Компонент	Технология	Обоснование
Язык	Go	Статический бинарник, минимум зависимостей для ARM.
Фреймворк	Echo GO	Простой, быстрый
Matrix SDK	mautrix-go	Де-факто стандартный Go SDK для Matrix.
Поиск	yt-dlp --flat-playlist --print	Только метаданные, без скачивания.
Скачивание	yt-dlp + ffmpeg	Поддержка всех музыкальных источников.
Прокси	ByeByeDPI (sidecar)	Обход DPI без внешнего VPN. Локальный SOCKS5.
Хранение	hostPath	Общие директории с Navidrome и для превью.

Контейнеры в поде

Контейнер	Образ	Порты	Назначение
ytdlp-bot	Собственный (Go + yt-dlp + ffmpeg)	—	Основной сервис
byedpi	ghcr.io/hufrea/byedpi:latest (или собственный)	1080 (SOCKS5)	Обход DPI, локальный прокси

---

2. Функциональные требования

2.1 Диалог с пользователем (Matrix-бот)

Пользователь общается с ботом в личном или групповом чате Matrix.

Пользователь:  /search Radiohead Creep
Бот:           Найдено 5 результатов:
               1. Radiohead - Creep (3:58)
               2. Radiohead - Creep [Live] (4:21)
               3. Radiohead - Creep [Acoustic] (3:45)
               ...
               Ответьте номером для превью.

Пользователь:  1
Бот:           [прикреплённый аудиофайл]
               Добавить в коллекцию Navidrome? (да/нет)

Пользователь:  да
Бот:           ✅ Добавлено: Radiohead - Creep.opus

Команды бота

Команда	Описание
/search <запрос>	Искать музыку. Возвращает список результатов с номерами.
<номер>	Отправить аудиопревью трека из результатов поиска.
да / yes / добавить	Сохранить трек в коллекцию Navidrome.
нет / no / отмена	Отменить. Удалить превью.
/status	Показать статус: место на диске, время работы, версия.
/proxy	Показать текущие настройки прокси и статус ByeByeDPI.
/help	Справка.

Состояние диалога

Бот хранит состояние per-user (в памяти, не персистентное в v1):

Состояние	Данные
idle	—
search_results	Запрос, список результатов, timestamp
preview_sent	video_id, путь к превью-файлу, timestamp

Таймаут состояния: 10 минут. После таймаута превью удаляется из tmp/.

2.2 Поиск (внутренний)

1. Бот формирует запрос к yt-dlp:

   yt-dlp "ytsearch{limit}:{query}" \
     --flat-playlist --print "%(id)s\t%(title)s\t%(duration_string)s\t%(channel)s" \
     --proxy socks5://byedpi:1080
   

2. Парсит вывод, возвращает пронумерованный список.
3. Таймаут: SEARCH_TIMEOUT (по умолчанию 10s).

2.3 Превью аудио (внутренний)

1. Указанный трек скачивается во временную директорию:

   yt-dlp "https://www.youtube.com/watch?v={id}" \
     -x --audio-format opus --audio-quality 5 \
     --output "{tmp_dir}/{id}.%(ext)s" \
     --proxy socks5://byedpi:1080
   

   Качество 5 (среднее) — превью, сэкономить трафик и место.
2. Бот отправляет файл в Matrix-чат как m.audio.
3. Файл сохраняется в tmp_dir до решения пользователя (добавить / отменить).

2.4 Добавление в коллекцию (внутренний)

1. Окончательное скачивание (или конвертация превью) в коллекцию:

   yt-dlp "https://www.youtube.com/watch?v={id}" \
     -x --audio-format opus --audio-quality 0 \
     --embed-thumbnail --add-metadata \
     --output "{music_dir}/{artist} - {title}.%(ext)s" \
     --proxy socks5://byedpi:1080
   

   Качество 0 (лучшее) — финальный файл для Navidrome.
2. Файл переименовывается в формат <artist> - <title>.<ext>.
3. Превью из tmp/ удаляется.
4. Navidrome обнаружит файл при следующем сканировании (раз в 6ч).

2.5 Health check

Эндпоинт: GET /healthz (для Kubernetes liveness/readiness probes)

Ответ: 200 OK {"status": "ok"} — если:

• Go-сервис запущен
• yt-dlp доступен
• ByeByeDPI sidecar отвечает (проверка через socks5://byedpi:1080)

---

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

3.1 Переменные окружения

Matrix

Переменная	Обязательная	По умолчанию	Описание
MATRIX_HOMESERVER	да	—	URL homeserver (например https://matrix.example.com)
MATRIX_USER_ID	да	—	@bot:example.com — ID бота
MATRIX_ACCESS_TOKEN	да	—	Access token бота
MATRIX_DEVICE_ID	нет	YTDLBOT	Device ID
MATRIX_ENCRYPTION	нет	false	Использовать E2EE (требует libolm/curve25519-dalek)

Поиск и скачивание

Переменная	По умолчанию	Описание
SEARCH_LIMIT	10	Максимум результатов поиска
SEARCH_TIMEOUT	10s	Таймаут на yt-dlp search
DOWNLOAD_TIMEOUT	120s	Таймаут на скачивание
AUDIO_FORMAT	opus	Целевой формат аудио
AUDIO_QUALITY_PREVIEW	5	Качество превью (0=лучшее, 10=худшее)
AUDIO_QUALITY_FINAL	0	Качество финального файла
PREVIEW_TTL	10m	Время жизни превью-файла до автоудаления
ALLOWED_USERS	—	Список Matrix ID через запятую (пустой = все)

Прокси (пробрасывается в yt-dlp через --proxy)

Переменная	По умолчанию	Описание
PROXY_ENABLED	true	Включить прокси для yt-dlp. false = без прокси.
PROXY_URL	socks5://localhost:1080	URL прокси (SOCKS5 / HTTP). Если запущен sidecar — socks5://byedpi:1080

ByeByeDPI (sidecar-контейнер)

Параметры ByeByeDPI передаются через COMMAND в Deployment (см. §4.2).

Флаг	По умолчанию (рекомендация)	Описание
--ip	0.0.0.0	Адрес для прослушивания
--port	1080	Порт SOCKS5
--disorder	1-1	Fake packet для браузеров/доменов
--auto	(включён)	Автоматический обход DPI
--ttl	3	TTL для fake-пакетов

Все флаги настраиваются в Deployment-манифесте. Если нужен другой обходчик DPI (naiveproxy, xray, sing-box), поменяйте image и PROXY_URL.

Пути

Переменная	По умолчанию	Описание
MUSIC_DIR	/music	mountPath к коллекции Navidrome
MUSIC_SUBDIR	ytdlp	Поддиректория для финальных файлов
TMP_DIR	/tmp/ytdlp-previews	Рабочая директория для превью
YTDLP_PATH	yt-dlp	Путь к бинарнику

3.2 Kubernetes-манифесты

Каталог: rasp/k3s/services/ytdlp_navidrome/

├── README.md           # ← этот документ
├── main.go             # исходный код сервиса
├── Dockerfile          # мультистейдж: Go build + yt-dlp + ffmpeg
├── service.yaml        # Namespace + Deployment + PersistentVolumes
└── go.mod

Deployment — ключевые моменты

spec:
  containers:
    - name: ytdlp-bot
      image: ytdlp-navidrome:latest        # Собственный образ
      env:
        - name: MATRIX_HOMESERVER
          valueFrom:
            secretKeyRef:
              name: ytdlp-matrix-secret
              key: homeserver
        - name: MATRIX_USER_ID
          valueFrom:
            secretKeyRef:
              name: ytdlp-matrix-secret
              key: user-id
        - name: MATRIX_ACCESS_TOKEN         # секрет
          valueFrom:
            secretKeyRef:
              name: ytdlp-matrix-secret
              key: access-token
        - name: PROXY_URL
          value: "socks5://localhost:1080"   # sidecar
        - name: MUSIC_DIR
          value: "/music"
      volumeMounts:
        - name: music
          mountPath: /music/ytdlp           # коллекция (Read-Write)
        - name: tmp
          mountPath: /tmp/ytdlp-previews
      resources:
        requests: { memory: "64Mi", cpu: "50m" }
        limits:   { memory: "128Mi", cpu: "500m" }

    - name: byedpi                          # ◀ sidecar
      image: ghcr.io/hufrea/byedpi:latest
      command: ["ciadpi"]
      args:
        - "--ip=0.0.0.0"
        - "--port=1080"
        - "--auto"
        - "--disorder=1-1"
        - "--ttl=3"
      ports:
        - containerPort: 1080
          name: sock5
      resources:
        requests: { memory: "16Mi", cpu: "10m" }
        limits:   { memory: "32Mi", cpu: "100m" }
      # network=host не нужен — sidecar общается с основным
      # контейнером через localhost (shared network namespace в поде)

  volumes:
    - name: music
      hostPath:
        path: /mnt/ssd/k3s/services/navidrome/music
        type: DirectoryOrCreate
    - name: tmp
      emptyDir: { medium: Memory, sizeLimit: 512Mi }
      # Превью хранятся в tmpfs — не нагружают SSD,
      # ограничены 512 MiB для безопасности

Service: не нужен для бота (исходящие подключения к Matrix homeserver). Если нужен health endpoint для мониторинга — ClusterIP на порт 8080.

Secret:

apiVersion: v1
kind: Secret
metadata:
  name: ytdlp-matrix-secret
  namespace: ytdlp-navidrome
type: Opaque
stringData:
  homeserver: "https://matrix.example.com"
  user-id: "@bot:example.com"
  access-token: "syt_..."                  # ← ваш токен бота

---

4. Нефункциональные требования

4.1 Формат аудио

Параметр	Превью	Финальный файл
Кодек	Opus	Opus
Качество	5 (среднее)	0 (лучшее)
Обложка	нет	--embed-thumbnail
Теги	минимальные	--add-metadata (title, artist, album)
Пример размера	~1–2 МБ на трек	~3–5 МБ на трек

Альтернатива: MP3 V0, если клиенты не поддерживают Opus.

4.2 Именование файлов

Директория на хосте: /mnt/ssd/k3s/services/navidrome/music/ytdlp/

Формат имени: <artist> - <title>.<ext>

Примеры:

• Radiohead - Creep.opus
• Massive Attack - Teardrop.opus
• unknown - dQw4w9WgXcQ.opus (метаданные неизвестны)

Запрещённые символы в имени файла (/ \ : * ? " < > |) заменяются на _.

4.3 Производительность

Метрика	Целевое значение
Поиск (10 результатов)	≤ 5 секунд
Превью (1 трек)	≤ 30 секунд
Финальное скачивание (1 трек)	≤ 60 секунд
Потребление RAM (простой)	≤ 64 MiB
Потребление RAM ( ByeByeDPI )	≤ 16 MiB
Потребление CPU (простой)	≤ 50m + 10m (bot + proxy)

4.4 Доступ из Matrix

• Бот запускается как зарегистрированный пользователь homeserver.
• Бот слушает события m.room.message и /search, реагирует на m.text.
• Бот может быть ограничен ALLOWED_USERS — список Matrix ID через запятую (если пусто — отвечает всем).
• В v1 без E2EE. E2EE поддерживается mautrix-go (опциональное включение через MATRIX_ENCRYPTION=true).

4.5 Безопасность

Вопрос	Решение
Токен бота в секрете	ytdlp-matrix-secret — не в env-файле кластера
Доступ к боту	Опционально ALLOWED_USERS
Прокси — только для yt-dlp	ByeByeDPI слушает на localhost, не проброшен наружу
Запись в коллекцию	runAsUser совпадает с Navidrome (совместимость прав)

4.6 Ограничения (scope v1)

Feature	Статус в v1	Примечание
Matrix-бот	✅ входит	Основной интерфейс
E2EE	⚠️ опционально	По флагу MATRIX_ENCRYPTION
REST API	❌ не входит	Только Matrix. REST — при необходимости позже.
Web UI	❌ не входит	—
Групповые чаты	⚠️ basic	Бот отвечает на mention в группах
Очередь загрузок	❌ не входит	Синхронная загрузка
SoundCloud/Bandcamp	⚠️ best-effort	yt-dlp поддерживает, поиск может не работать
Изменение прокси на лету	❌ не входит	Требуется перезапуск пода

---

5. Логирование

Формат: текстовый, в stdout.

2026-07-02T14:30:00Z INFO  search user=@alice:example.com query="Radiohead Creep" results=10 dur=2.1s
2026-07-02T14:30:05Z INFO  preview user=@alice:example.com video_id=XF2YMYBLnSw size=1.2MB dur=18s
2026-07-02T14:30:20Z INFO  download user=@alice:example.com file="Radiohead - Creep.opus" size=3.7MB dur=12s
2026-07-02T14:30:20Z INFO  cleanup preview=XF2YMYBLnSw removed=true
2026-07-02T14:31:00Z WARN  preview_ttl_expired video_id=dQw4w9WgXcQ
2026-07-02T14:32:00Z INFO  byedpi_check status=ok latency=3ms

Уровень логирования: настраивается через LOG_LEVEL.

---

6. Тестирование

Уровень	Что проверять
Unit	Парсинг вывода yt-dlp, формирование имён файлов, санитизация, FSM состояний
Integration	Запуск yt-dlp в subprocess с /dev/null прокси, проверка формата вывода
Matrix	Взаимодействие с тестовым homeserver (Dendrite/Conduit)
Manual	Полный сценарий: /search → номер → превью → да → файл в navidrome

---

7. Стадии реализации

Stage 1 — MVP

• Matrix-бот: подключение через mautrix-go
• Команда /search — парсинг вывода yt-dlp, отправка результатов
• Превью: скачивание трека в tmp/, отправка аудио в чат
• Добавление: финальное скачивание в коллекцию, очистка tmp
• ByeByeDPI sidecar в Deployment
• --proxy везде где yt-dlp обращается наружу
• Dockerfile (Go + yt-dlp + ffmpeg)
• service.yaml (Deployment + Secret)
• Smoke-тест: /search → preview → да → файл появился в файловой системе

Stage 2 — Улучшения

• Авторизация через ALLOWED_USERS
• E2EE (опционально)
• Автоочистка tmp/ по расписанию (cronJob или timer в Go)
• /status и /proxy команды
• Обработка ошибок: не найдено, таймаут превью, нет места
• Батч-загрузка (серия треков по команде)

Stage 3 — Интеграция

• Принудительное сканирование Navidrome после загрузки (Navidrome API)
• Метрики Prometheus
• Адаптация прокси под разные обходчики (naiveproxy, xray, sing-box)
• REST-эндпоинты для альтернативного доступа (опционально)