SUPLA-PLEX-WEBHOOK

Znasz ten moment: siadasz na kanapie, odpalasz film w Pleksie… i jeszcze wstajesz, żeby zgasić światło. Potem pauza na herbatę i szukanie włącznika po ciemku. Na koniec seansu znowu to samo.

Supla-Plex Webhook łączy Plex Media Server z automatyką SUPLA. Gdy na wybranym odtwarzaczu wciśniesz play, pauzę, wznów albo stop, aplikacja od razu uruchamia przypisaną scenę lub kanał w SUPLI. Światło gaśnie, przygasa albo się zapala, rolety zjeżdżają, a Ty siedzisz dalej na kanapie.

W tym wpisie pokazuję, jak to działa w środku i jak w kilka minut uruchomić to u siebie.

Jak to działa

Cała zabawa opiera się na dwóch gotowych mechanizmach:

• Webhooki Pleksa. Przy każdej zmianie stanu odtwarzania Plex Media Server wysyła żądanie HTTP pod wskazany adres. W treści jest JSON z typem zdarzenia (media.play, media.pause, media.resume, media.stop) i identyfikatorem (UUID) odtwarzacza.
• Linki bezpośrednie SUPLA (direct links). SUPLA Cloud pozwala wygenerować dla kanału lub sceny adres, którego wywołanie wykonuje konkretną akcję bez logowania i bez aplikacji.

Supla-Plex Webhook siedzi pomiędzy nimi. Odbiera zdarzenie z Pleksa, sprawdza, czy dotyczy odtwarzacza, który Cię interesuje, i jeśli tak, wysyła żądanie PATCH do API SUPLA z kodem i akcją wyciągniętymi z Twojego linku.

Mapowanie zdarzeń na akcje

Każdy odtwarzacz ma cztery pola, po jednym na każde zdarzenie. W każde wklejasz link bezpośredni do kanału albo sceny. Przykładowa konfiguracja „kinowa”:

PLAY i RESUME mogą wskazywać tę samą scenę. Możesz też zostawić któreś pole puste: wtedy dane zdarzenie jest po prostu pomijane.

Co dzieje się z każdym webhookiem

Zanim cokolwiek zostanie wysłane do SUPLI, zdarzenie przechodzi przez kilka filtrów. Każda decyzja ląduje w logach, więc zawsze widać, dlaczego coś się wykonało albo nie.

Czego potrzebujesz

Wymaganie	Uwagi
Docker + Docker Compose	Na serwerze domowym, NAS-ie albo Raspberry Pi.
Plex Media Server z Plex Pass	Webhooki w Pleksie są dostępne tylko z aktywnym Plex Pass.
Konto SUPLA Cloud	Przynajmniej jeden kanał lub scena z wygenerowanym linkiem bezpośrednim.
Sieć	Plex Media Server musi widzieć aplikację (np. w tej samej sieci LAN), a aplikacja musi mieć dostęp do internetu, żeby dotrzeć do serwera SUPLA.

Instalacja w Dockerze

Wystarczą trzy polecenia:

git clone https://github.com/KlimasTech/supla-plex-webhook.git
cd supla-plex-webhook
docker compose up -d --build

Aplikacja wystartuje na porcie 3000. Plik docker-compose.yml wygląda tak:

services:
  supla-plex-webhook:
    build:
      context: .
      dockerfile: supla-plex-webhook
    container_name: supla-plex-webhook
    environment:
      - TZ=Europe/Warsaw
    ports:
      - "3000:3000"
    volumes:
      - ./data:/data
    restart: unless-stopped

• TZ=Europe/Warsaw ustawia strefę czasową. Wpływa ona na godziny w logach i na działanie ograniczenia godzinowego.
• ./data:/data to miejsce na konfigurację (config.json) i logi. Dzięki wolumenowi ustawienia przetrwają restart i aktualizację kontenera.

Pierwsze logowanie

Otwórz w przeglądarce http://<adres-serwera>:3000/login.

Domyślne dane to login admin i hasło supla. Zmień je od razu po pierwszym zalogowaniu przyciskiem Zmień hasło w nagłówku. Okienko zmiany hasła jest dostępne z każdej podstrony panelu.

Podłączenie Pleksa

Po zalogowaniu na samej górze panelu zobaczysz gotowy adres webhooka do skopiowania. Poniżej są ustawienia odtwarzaczy, linki SUPLA i godziny działania.

W Pleksie przejdź do Ustawienia → Konto → Webhooks → Add Webhook i wklej:

http://<adres-serwera>:3000/webhook

Pamiętaj o końcówce /webhook. Sam adres serwera bez tej ścieżki nie zadziała. To najczęstszy błąd przy konfiguracji.

Wystarczy jeden webhook w Pleksie, niezależnie od tego, ile odtwarzaczy skonfigurujesz. Aplikacja sama przypisuje każde zdarzenie do właściwego odtwarzacza po jego UUID.

Znalezienie UUID odtwarzacza

Plex wysyła zdarzenia ze wszystkich odtwarzaczy na koncie: telewizora, telefonu, laptopa. Żeby światło nie gasło, gdy ktoś puści serial na komórce w pokoju obok, aplikacja reaguje tylko na odtwarzacze, których UUID wpiszesz w konfiguracji.

UUID nie trzeba szukać w ustawieniach Pleksa:

1. Na docelowym urządzeniu (np. telewizorze) włącz cokolwiek w Pleksie. Zwykły play wystarczy.
2. W panelu wejdź w Logi. Urządzenie pojawi się w tabeli Ostatnio wykryci playerzy.
3. Kliknij Kopiuj i wklej UUID w pole UUID playera do nasłuchiwania na zakładce odtwarzacza.
4. Opcjonalnie nadaj mu przyjazną nazwę, np. „NVIDIA Shield”. Będzie widoczna w logach obok identyfikatora.

Wpisy, których nie potrzebujesz (np. Twój telefon), usuniesz przyciskiem ✕. Jeśli z tego urządzenia przyjdzie kolejne zdarzenie, wpis wróci.

Linki bezpośrednie SUPLA

W SUPLA Cloud przy wybranym kanale lub scenie utwórz link bezpośredni z akcją, którą chcesz wykonać (np. execute dla sceny). Link wygląda mniej więcej tak:

https://svr11.supla.org/direct/1571/UuojuqMJD9S8RuGw/execute
        └─ serwer ──┘        └id─┘ └──── kod ─────┘ └akcja┘

Wklej cały link w pole odpowiadające zdarzeniu (PLAY, RESUME, PAUSE albo STOP). Aplikacja sama rozłoży go na części i wyśle do API SUPLA takie żądanie:

PATCH https://svr11.supla.org/direct/1571
Content-Type: application/json

{"code": "XuojuqMMD9S8RuPw", "action": "execute"}

Wskazówka. Najwygodniej przygotować w SUPLI sceny, np. „Kino”, „Przerwa” i „Koniec seansu”, i podpiąć pod webhook właśnie je. Jedna scena może sterować wieloma urządzeniami naraz: światłem, ściemniaczem, roletą.

Po wpisaniu wszystkiego kliknij Zapisz konfigurację na dole strony.

Godziny działania

Nie każdy seans wymaga gaszenia światła. W południe, przy słońcu za oknem, nie ma to sensu. Dlatego każdy odtwarzacz ma sekcję Godziny działania webhooka:

• zaznacz Ogranicz działanie do wybranych godzin,
• ustaw zakres Od i Do, np. 20:00–07:00. Zakres może przechodzić przez północ.

Poza tym przedziałem zdarzenia nadal są odbierane i widoczne w logach, ale akcje SUPLA nie są wysyłane.

Kilka odtwarzaczy naraz

Masz telewizor w salonie i drugi w sypialni? Aplikacja obsługuje do czterech odtwarzaczy, każdy z niezależną konfiguracją: własnym UUID, czterema linkami i godzinami działania.

1. W sekcji Liczba odtwarzaczy wybierz liczbę i kliknij Zastosuj liczbę odtwarzaczy.
2. Każdy odtwarzacz dostaje swoją zakładkę. Przełączasz się między nimi bez przeładowania strony.

Odtwarzacz można też tymczasowo wyłączyć, odznaczając Włączony. Cała konfiguracja zostaje, a webhook po prostu go ignoruje. Wyłączona zakładka jest wyszarzona i podpisana „(wyłączony)”.

Zmniejszenie liczby odtwarzaczy usuwa konfigurację z zakładek na końcu listy. Aplikacja poprosi o potwierdzenie.

Logi i diagnostyka

Zakładka Logi to pierwsze miejsce, do którego warto zajrzeć, gdy coś nie działa. Strona odświeża się sama co 5 sekund, a najnowsze wpisy są na górze. Typowa sesja wygląda tak:

[2026-10-15 21:15:41] INFO Zdarzenie Plex: NVIDIA Shield uuid=a1b2c3d4…-com-plexapp-android event=media.play
[2026-10-15 21:15:41] INFO Wysłano PATCH (PLAY) na https://svr11.supla.org/direct/1571 (action=execute) -> status 202
[2026-10-15 21:15:44] INFO Zdarzenie Plex: Samsung TV Salon uuid=f0e1d2c3… event=media.play
[2026-10-15 21:15:44] INFO Odtwarzacz Samsung TV Salon jest wyłączony — pomijam akcję

Co znaczą najczęstsze komunikaty:

Wpis w logu	Znaczenie
Wysłano PATCH (…) -> status 2xx	Wszystko OK, SUPLA przyjęła akcję.
Zdarzenie Plex: uuid=… bez dalszych wpisów	Zdarzenie z odtwarzacza, którego nie ma w konfiguracji.
… jest wyłączony	Odtwarzacz ma odznaczone pole Włączony.
Poza godzinami aktywności	Zadziałało ograniczenie godzinowe.
nie skonfigurowano linku	Puste pole linku dla tego zdarzenia.
Nieprawidłowy format linku	Link nie pasuje do wzoru https://<serwer>/direct/<id>/<kod>/<akcja>.
Brak pola 'payload'	Pod /webhook przyszło coś, co nie jest webhookiem Pleksa.

Przyciskiem Zapisz logi pobierzesz cały log do pliku, co przydaje się przy zgłaszaniu problemu. Usuń logi czyści go po potwierdzeniu.

Na telefonie

Panel jest w pełni responsywny, więc zmianę godzin albo wyłączenie odtwarzacza zrobisz z kanapy, bez komputera.

Bezpieczeństwo

• Plik data/config.json zawiera hash hasła do panelu i kody linków bezpośrednich SUPLA. Kto ma kod linku, może wywołać akcję, więc nie publikuj tego katalogu. W repozytorium jest wykluczony przez .gitignore.
• Adres /webhook jest celowo dostępny bez logowania, bo Plex nie umie się uwierzytelnić. Nie wystawiaj aplikacji do internetu. Plex Media Server zwykle stoi w tej samej sieci lokalnej, więc nie ma takiej potrzeby.
• Zmień domyślne hasło supla od razu po instalacji.

FAQ

Webhook nic nie robi, w logach pusto.

Sprawdź, czy adres w Pleksie kończy się na /webhook, czy masz aktywny Plex Pass i czy serwer Plex ma dostęp do portu 3000 na maszynie z aplikacją.

W logach widzę zdarzenia, ale światło się nie zmienia.

Spójrz na wpis tuż pod zdarzeniem. Znajdziesz tam powód: inny UUID, wyłączony odtwarzacz, poza godzinami, brak linku albo kod odpowiedzi SUPLI.

Mogę sterować czymś innym niż światło?

Tak, wszystkim, co obsługuje link bezpośredni SUPLA: roletami, gniazdkami, ściemniaczami, a przede wszystkim scenami.

Godziny w logach się nie zgadzają.

Ustaw właściwą strefę w zmiennej TZ w docker-compose.yml i zrestartuj kontener.

Czy po aktualizacji stracę ustawienia?

Nie. Konfiguracja leży na wolumenie ./data. Starszy format z jednym odtwarzaczem jest automatycznie migrowany przy pierwszym uruchomieniu.

Podsumowanie

Supla-Plex Webhook to kilkaset linijek Pythona w kontenerze, a robi sporą różnicę w codziennym oglądaniu. Raz konfigurujesz sceny w SUPLI, wklejasz linki, wskazujesz odtwarzacz i ustawiasz godziny. Potem po prostu naciskasz play.

Miłego seansu! 🍿