myshows-scrobbler

KO | EN

gitlite — search

#react #ai #typescript #llm #android #machine-learning #rust #nodejs #windows #kubernetes #pytorch #security #ios #mcp

myshows-scrobbler

(★ 13)

Universal media scrobbler for MyShows — Plex, Emby, Jellyfin, Kodi & local players.

myshows-scrobbler Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# MyShows Scrobbler

**Универсальный скробблер для [MyShows.me](https://myshows.me) — Plex, Jellyfin, Emby, Kodi и десктопные плееры.**

[English](README.en.md)

[![Release](https://img.shields.io/github/v/release/myshowsme/myshows-scrobbler)](https://github.com/myshowsme/myshows-scrobbler/releases)
[![Platforms](https://img.shields.io/badge/platforms-Windows%20%7C%20macOS%20%7C%20Linux-2b2b2b)](https://github.com/myshowsme/myshows-scrobbler/releases/latest)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://raw.githubusercontent.com/myshowsme/myshows-scrobbler/main/LICENSE)

[Установка](#установка) · [Быстрый старт](#быстрый-старт) · [Источники](#источники) · [Lampa](#lampa) · [Без приложения](#без-десктоп-приложения) · [Разработка](#разработка)

</div>

---

Смотрите привычным вам способом — в Plex, Jellyfin, Emby, Kodi или просто в десктопном плеере. Не переживайте об отметке: прогресс просмотра и дата отправляются в ваш профиль [MyShows.me](https://myshows.me).

Скробблер работает локально: следит за воспроизведением, и когда вы досмотрели серию до порога (по умолчанию 80%), отправляет отметку в MyShows. Недосмотренное не засчитывается. Никакой телеметрии — данные уходят только в MyShows и на ваши медиасерверы.

## Скриншоты

![MyShows Scrobbler](https://raw.githubusercontent.com/myshowsme/myshows-scrobbler/main/assets/screenshots/app-ru.png)

</div>

## Установка

Готовые сборки — на странице [Releases](https://github.com/myshowsme/myshows-scrobbler/releases/latest):

| Платформа             | Файл                                      |
| --------------------- | ----------------------------------------- |
| Windows               | `MyShows Scrobbler Setup <версия>.exe`    |
| macOS (Apple Silicon) | `*-arm64.dmg`                             |
| Linux                 | `*.AppImage` (portable, экспериментально) |

Ставить что-либо дополнительно не нужно — сборки самодостаточны: ffprobe и нативные модули уже внутри.

> - **macOS** — сборка подписана сертификатом Apple Developer ID и нотаризована: ставится и запускается без предупреждений.
> - **Windows** — сборка не подписана, SmartScreen покажет предупреждение: **Подробнее → Выполнить в любом случае**.
> - **Linux** — AppImage не подписывается; при необходимости сделайте файл исполняемым (`chmod +x`).

Приложение живёт в трее и продолжает скробблить с закрытым окном. Обновления подтягиваются с GitHub Releases — приложение спросит, прежде чем ставить.

## Быстрый старт

1. **Токен MyShows.** Возьмите токен в вашем [профиле](https://myshows.me/profile/watch-history/) и вставьте в поле наверху — приложение сразу проверит его.
2. **Включите источник.** Если Plex или Kodi установлены на этой же машине, токен и адрес подставятся автоматически. Для Jellyfin есть Quick Connect (код на экране — подтверждение на сервере), для Emby — вход по логину и паролю. Если смотрите без медиасервера, включите «Локальный плеер».
3. **Запустите что-нибудь.** Карточка «Сейчас смотрю» появится в приложении — это значит, что прогресс просмотра начал отправляться на MyShows.

## Источники

| Источник                      | Подключение                                                                                                                                                                                                                            |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Plex**                      | Токен находится автоматически в локальном Plex Media Server. Для удалённого сервера — вручную (`X-Plex-Token`)                                                                                                                         |
| **Jellyfin**                  | Quick Connect или API-ключ                                                                                                                                                                                                             |
| **Emby**                      | Вход по логину и паролю или API-ключ                                                                                                                                                                                                   |
| **Kodi**                      | Логин, пароль и порт веб-интерфейса находятся автоматически или задаются вручную                                                                                                                                                       |
| **VLC, mpv, MPC-HC/BE, IINA** | Включаются одной кнопкой в панели Setup: приложение само может править конфиг плеера (HTTP-интерфейс у VLC и MPC, IPC у mpv и IINA) и начнёт получать точные позицию и состояние                                                       |
| **Stremio**                   | Облачный источник: вставьте authKey аккаунта Stremio (из консоли web.stremio.com: `JSON.parse(localStorage.profile).auth.key`). Читает библиотеку `api.strem.io` и ловит просмотры со всех клиентов Stremio — web, desktop, мобайл, TV |
| **Локальный плеер**           | Нулевая настройка: сканирование процессов + системные медиа-API (SMTC на Windows, AppleScript на macOS). Ловит и плееры, для которых нет отдельного адаптера                                                                           |

### Что умеет

- Отслеживаем прогресс просмотра и автоматически сохраняем его для вас.
- Сериалы и фильмы распознаются и сопоставляются автоматически на стороне MyShows.
- Повторные просмотры тоже фиксируются.

### Ограничения локального плеера

- Скробблер должен работать на той же машине, что и плеер. Из Docker процессы хоста не видны.
- Для плееров, подключённых через панель Setup, позиция точная — берётся из API плеера. Для остальных прогресс оценивается по времени жизни процесса: паузы и перемотки в этом режиме не видны.
- Название, сезон и серия автоматически извлекаются из имени файла — [guessit-js](https://github.com/wuestholz/guessit-js).

## Lampa

Смотрите в [Lampa](https://lampa.mx)? Для неё есть отдельный плагин — [myshows-scrobbler-lampa](https://github.com/myshowsme/myshows-scrobbler-lampa). Он отправляет отметки в MyShows сам, прямо из Lampa: десктопное приложение из этого репозитория ставить не нужно, и работает он в том числе на ТВ, где его негде запустить (Tizen, webOS — плагин собран под ES5).

Установка: **Настройки → Расширения → Добавить плагин по URL**

```
https://myshowsme.github.io/myshows-scrobbler-lampa/myshows.js
```

Дальше — тот же [токен MyShows](https://myshows.me/profile/watch-history/) в настройках плагина (проверяется сразу при вводе) и настраиваемый порог отметки (50–95%). Токен хранится отдельно для каждого профиля Lampa.

## Без десктоп-приложения

Скробблеру не обязательно жить на вашем компьютере. Если дома есть NAS или домашний сервер, поставьте его туда — и отметки будут уходить в MyShows, даже когда компьютер выключен. Это то, что нужно, если вы смотрите с телевизора или телефона.

Единственное ограничение: изнутри контейнера не видно программ, запущенных на вашем компьютере, поэтому «Локальный плеер», VLC и mpv так работать не будут. Plex, Jellyfin, Emby и Kodi — будут: к ним скробблер подключается по сети.

### Docker

Собирать ничего не нужно, готовый образ уже опубликован. Он подходит и обычным процессорам Intel/AMD, и процессорам ARM — на них работает большинство NAS, а также Raspberry Pi.

**1. Создайте папку для настроек.** В ней скробблер будет хранить свой конфиг, чтобы тот не пропадал при обновлении:

```bash
mkdir -p /volume1/docker/myshows-scrobbler/data
sudo chown -R 1001:1001 /volume1/docker/myshows-scrobbler/data
```

Путь замените на свой — на NAS папки обычно лежат в `/volume1`, `/Volume1` или `/share`, посмотреть можно командой `ls /`.

Вторая команда отдаёт папку тому пользователю, под которым работает контейнер. Без неё скробблер не сможет сохранить настройки и будет забывать токен при каждом перезапуске. На Windows и macOS этот шаг не нужен.

**2. Запустите контейнер:**

```bash
docker run -d \
  --name myshows-scrobbler \
  --restart unless-stopped \
  -p 3000:3000 \
  -v /volume1/docker/myshows-scrobbler/data:/data \
  ghcr.io/myshowsme/myshows-scrobbler:latest
```

`--restart unless-stopped` означает, что скробблер сам поднимется после перезагрузки NAS.

**3. Откройте веб-интерфейс** по адресу сервера и порту 3000 — например, `http://192.168.1.50:3000`. Дальше всё как в десктопном приложении: вставьте [токен MyShows](https://myshows.me/profile/watch-history/) и включите нужный источник.

Одна тонкость при подключении медиасервера, который стоит на той же машине: указывайте его адрес в сети (`http://192.168.1.50:8096`), а не `localhost`. Для контейнера `localhost` — это он сам, а не ваш Jellyfin.

Проверить, что всё запустилось, можно командой `docker logs myshows-scrobbler` — там должна быть строка `Server listening`.

#### Через docker compose

В репозитории лежит готовый [docker-compose.yml](docker-compose.yml):

```bash
docker compose up -d
```

Права на папку `data` нужны те же, что и выше.

#### Собрать образ самому

Нужно, только если правите код: раскомментируйте `build: .` в [docker-compose.yml](docker-compose.yml), и `docker compose up -d` соберёт образ из локальных исходников.

### Node.js

Нужны Node.js 24+ и [pnpm](https://pnpm.io/) 11+ (`corepack enable`).

```bash
pnpm install
pnpm build:all
pnpm start:ui        # сервер + веб-интерфейс на :5172
```

Или одной командой: [start.sh](start.sh) (Linux/macOS) и [start.bat](start.bat) (Windows) — проверят Node, поставят зависимости и запустят сервер.

Флаг `--ui` раздаёт веб-интерфейс. Переменная `CONFIG_PATH` задаёт путь к конфигу (по умолчанию `./data/config.json`, в Docker — `/data/config.json`).

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

Всё настраивается через интерфейс, но можно и руками — `data/config.json`:

```json
{
  "myshows_token": "ваш_bearer_token_с_myshows.me",
  "scrobble_percent": 80,
  "log_level": "info",
  "sources": [
    {
      "type": "plex",
      "enabled": true,
      "url": "http://localhost:32400",
      "token": "plex_x_token",
      "poll_interval": 5000
    }
  ]
}
```

- `scrobble_percent` — порог отметки «просмотрено», в процентах.
- `poll_interval` — период опроса источника, мс.

### Фильтр пользователей

На общем сервере Plex, Emby или Jellyfin скробблятся сеансы всех пользователей. Чтобы засчитывать только свои просмотры, добавьте к источнику поле `user_filter` — список имён или ID пользователей. В интерфейсе этого поля нет, оно задаётся только вручную в `data/config.json`:

```json
{
  "type": "plex",
  "url": "http://localhost:32400",
  "token": "plex_x_token",
  "user_filter": ["username"]
}
```

То же самое для Emby или Jellyfin:

```json
{
  "type": "emby",
  "url": "http://localhost:8096",
  "token": "emby_api_key",
  "user_filter": ["username"]
}
```

Засчитываются только сеансы, у которых имя пользователя или его ID совпадает с записью из списка: для Plex это `User.title` и `User.id`, для Emby и Jellyfin — `UserName` и `UserId`. Регистр и пробелы по краям не важны.
Без `user_filter` засчитываются все зрители.
Отброшенные фильтром сеансы видны в логах на уровне `debug`.

## API скробблинга

Скробблер общается с MyShows по простому HTTP API (`POST /start`, `/pause`, `/stop`, `GET /check`) с авторизацией `Authorization: Bearer <токен>`. Формат payload — надмножество scrobble-API Trakt и Simkl. Полное описание DTO — в [src/scrobblers/scrobble-dto.ts](src/scrobblers/scrobble-dto.ts).

## Разработка

Тулчейн — [Vite+](https://viteplus.dev/): сборка, линт, форматирование и тесты одной командой.

```bash
pnpm dev             # headless-сервер с auto-reload
pnpm dev:all         # сервер + Vue UI dev-сервер (:5173)
pnpm check           # формат + линт + typecheck
pnpm test            # unit-тесты
pnpm test:e2e        # playwright (сам соберёт проект)
```

### Новый источник

1. Класс-наследник [`BaseAdapter`](src/adapters/base.ts): `name`, `checkConnection`, `poll()`. Таймер опроса поднимает базовый класс; адаптер зовёт `emitScrobble(event)`.
2. Тип в union `SourceType` в [src/types.ts](src/types.ts). Источникам без URL/токена место в `LOCAL_SOURCE_TYPES`.
3. `registerAdapter(...)` в [src/server.ts](src/server.ts) и тип в `VALID_SOURCE_TYPES` в [src/routes/api.ts](src/routes/api.ts).
4. `pnpm generate:ui-types`.

Анти-спам, порог и ретраи живут в общем pipeline (`handleScrobble`) — адаптеру о них думать не нужно.

Как присылать PR и сообщать о багах — в [CONTRIBUTING.md](CONTRIBUTING.md).

## Лицензия

MIT

myshows-scrobbler

myshows-scrobbler Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

myshows-scrobbler

myshows-scrobbler Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README