
Denon HEOS to bezprzewodowa platforma audio multiroom oparta na HEOS Command Line Interface (CLI) — protokole tekstowym, który udostępnia każdy głośnik, soundbar, wzmacniacz i komponent obsługujący HEOS w sieci lokalnej przez port TCP 1255. TapHome wykorzystuje ten protokół do sterowania odtwarzaniem, głośnością, wyciszeniem i trybem odtwarzania głośników HEOS bez żadnych zależności od chmury.
Szablon obejmuje całą bezprzewodową linię HEOS (HEOS 1, 3, 5, 7), soundbary HEOS Bar i HomeCinema, komponenty HEOS Amp / Link / Drive, HEOS Sub oraz nowsze głośniki Denon Home 150 / 250 / 350 i Sound Bar 550. Wystarczy jedno urządzenie HEOS w LAN — CLI udostępnia wszystkich pozostałych odtwarzaczy HEOS w sieci przez punkt końcowy player/get_players.
Ten szablon jest przeznaczony wyłącznie dla głośników HEOS, soundbarów i wzmacniaczy obsługujących HEOS. Amplitunery Denon i Marantz AVR (serie AVR-X, SR itd.) używają osobnego protokołu Denon/Marantz Telnet control na porcie 23 i nie są kompatybilne z tym szablonem, nawet w modelach wyposażonych również w HEOS Built-in.
Połączenie sieciowe
HEOS komunikuje się przez TCP na porcie 1255 za pomocą jawnych poleceń ASCII zakończonych \r\n i zwraca odpowiedzi w formacie JSON. Uwierzytelnianie nie jest wymagane — dowolne urządzenie w tej samej sieci LAN może połączyć się z portem CLI.
Zanim TapHome będzie mogło sterować urządzeniem, głośnik HEOS musi zostać skonfigurowany w aplikacji mobilnej HEOS:
- Zainstaluj aplikację HEOS App (Android / iOS) na telefonie lub tablecie w tej samej sieci Wi-Fi.
- Połącz urządzenie HEOS z Wi-Fi lub Ethernetem za pomocą kreatora konfiguracji w aplikacji.
- Upewnij się, że firmware jest aktualny (szablon opiera się na HEOS CLI v1.17, co odpowiada firmware 2.41.140 lub nowszemu).
- Zanotuj adres IP głośnika — znajdziesz go w aplikacji HEOS w Settings → My Devices → About albo na liście klientów DHCP w routerze.
Dla urządzenia HEOS, z którym łączy się TapHome, użyj statycznego IP lub rezerwacji DHCP. Głośnik działa jako brama do wszystkich pozostałych odtwarzaczy HEOS, więc stabilny adres utrzyma dostępność całego ekosystemu.
HEOS CLI nie ma żadnego uwierzytelniania. Utrzymuj głośnik w zaufanym segmencie LAN — każde urządzenie z dostępem sieciowym do portu 1255 może sterować odtwarzaniem.
Konfiguracja
Parametry połączenia w TapHome
Podczas importu szablonu w aplikacji TapHome podaj adres IP głośnika HEOS w parametrze IP Address. Port TCP 1255 i framing protokołu są już ustawione w szablonie. TapHome otwiera jedno trwałe połączenie TCP i przepuszcza przez nie polecenia HEOS CLI.
Inicjalizacja PlayerId
Każde polecenie heos://player/* wymaga player id (pid) — dużej liczby całkowitej ze znakiem, którą HEOS dynamicznie przypisuje każdemu głośnikowi w sieci. Szablon przechowuje go w zmiennej użytkownika PlayerId. Ponieważ HEOS generuje pid dynamicznie per sieć, szablon dostarczany jest z wartością zastępczą (-1857880384), którą trzeba podmienić przy pierwszej konfiguracji.
Moduł udostępnia dwie akcje serwisowe do wykrycia i przypisania pid. Uruchom je jednorazowo po imporcie szablonu:
- Get Players — wysyła
heos://player/get_playersi zapisuje odpowiedź JSON w zmiennej modułuPlayersResponse. Atrybut serwisowy modułu Players pokazuje następnie listę odtwarzaczy HEOS widocznych w sieci wraz z nazwą, pid, modelem i adresem IP. - Set Player Id — przyjmuje parametr
Index(pozycja 0-based w tablicy Players) i zapisuje odpowiedni pid do zmiennej użytkownikaPlayerId. Wybierz indeks głośnika, który TapHome ma kontrolować — jeden moduł TapHome powiązany jest z jednym odtwarzaczem HEOS na raz.
Po tych dwóch krokach wszystkie urządzenia podrzędne (Volume, Mute, Play, Pause itd.) działają na wybranym głośniku. Aby sterować drugim odtwarzaczem HEOS, zaimportuj drugą instancję szablonu na ten sam (lub inny) adres IP HEOS i powtórz krok Set Player Id z innym indeksem.
Jeśli atrybut Players jest pusty przy pierwszym uruchomieniu, moduł HEOS CLI może być w trybie uśpienia. Uruchom Get Players ponownie po kilku sekundach — HEOS startuje rdzeń CLI przy pierwszym połączeniu i może chwilę potrwać, zanim wyliczy wszystkich odtwarzaczy.
Zmienne urządzenia
Dwa urządzenia podrzędne mają konfigurowalne zmienne po imporcie szablonu:
| Urządzenie | Zmienna | Domyślna | Uwagi |
|---|---|---|---|
| Play URL | URL | MP3 dzwonka z Pixabay | Dowolny bezpośredni URL HTTP(S) do strumienia lub pliku audio |
| Volume Up / Volume Down | Step | 5 | Zmiana głośności na naciśnięcie; specyfikacja HEOS ogranicza zakres do 1–10 |
W aplikacji TapHome otwórz szczegóły każdego urządzenia i ustaw te zmienne na potrzebne wartości. Znaki specjalne URL-encoded w URL-u strumienia (&, =, %) obsługuje skrypt szablonu.
Funkcje urządzenia
Szablon udostępnia 12 urządzeń podrzędnych obejmujących odtwarzanie, głośność, wyciszenie i strumieniowanie URL dla jednego odtwarzacza HEOS.
Sterowanie głośnością
Urządzenie Volume to ściemniacz, który odczytuje heos://player/get_volume (poziom 0–100) i skaluje go do zakresu ściemniacza 0.0–1.0 (Le := level / 100). Zapis wysyła heos://player/set_volume z ROUND(Le * 100). Głośność jest odpytywana co 2,5 sekundy, więc zewnętrzne zmiany głośności z aplikacji HEOS lub innego kontrolera odzwierciedlają się w TapHome w kolejnym cyklu.
Volume Up i Volume Down to urządzenia przyciskowe, które wysyłają heos://player/volume_up oraz heos://player/volume_down z konfigurowalnym krokiem Step. Przydatne do powiązania z fizycznymi przełącznikami ściennymi lub inteligentnymi regułami.
Wyciszenie
Mute to przełącznik, który odczytuje heos://player/get_mute i zapisuje heos://player/set_mute z state=on|off. Po wyciszeniu głośnik jest wyciszony bez zmiany podstawowego poziomu głośności.
Transport
Cztery urządzenia przyciskowe obejmują podstawowy transport:
- Play — zapisuje
heos://player/set_play_state?state=play - Pause — zapisuje
heos://player/set_play_state?state=pause - Stop — zapisuje
heos://player/set_play_state?state=stop - Next Track — zapisuje
heos://player/play_next - Previous Track — zapisuje
heos://player/play_previous
Są to przyciski tylko do zapisu — szablon nie odpytuje bieżącego stanu odtwarzania, więc przyciski transportu nie odzwierciedlają tego, czy głośnik faktycznie odtwarza.
Tryb odtwarzania
Play Mode to przełącznik wielowartościowy, który łączy flagi HEOS repeat i shuffle w jeden 6-stanowy enum. Odczyt i zapis przez heos://player/get_play_mode i heos://player/set_play_mode:
| Wartość | Tryb |
|---|---|
| 0 | Bez powtarzania, bez losowania |
| 1 | Powtarzaj wszystkie |
| 2 | Powtarzaj jeden utwór |
| 3 | Losowo, bez powtarzania |
| 4 | Losowo, powtarzaj wszystkie |
| 5 | Losowo, powtarzaj jeden |
Szablon XML rezerwuje w konfiguracji wielowartościowej sloty 6–9, ale są one nieużywane — tylko wartości 0–5 są osiągalnymi stanami.
Presety QuickSelect
Quick Select to wielowartościowy przełącznik tylko do zapisu (1–9), który uruchamia preset HEOS QuickSelect przez heos://player/play_quickselect?id={1-9}. Quick selecty są zapisane bezpośrednio na odtwarzaczu (zwykle przez sparowany Denon AVR lub HEOS Bar) i mogą przechowywać prekonfigurowane wejście, źródło lub stację.
Quick Select jest w specyfikacji HEOS §4.2.24 zdefiniowany jako polecenie AVR-only. Działa na HEOS Amp, HEOS Link, HEOS Bar i produktach AVR/receiver z obsługą HEOS, ale na samodzielnych bezprzewodowych głośnikach HEOS, takich jak HEOS 1, 3, 5 i 7, zwraca błąd.
Play URL (własny strumień)
Play URL to przycisk, który strumieniuje dowolny URL audio HTTP(S) do wybranego odtwarzacza HEOS przez heos://browse/play_stream?pid={PlayerId}&url={URL}. Zmienna URL urządzenia przechowuje cel strumienia — domyślnie jest to przykładowy MP3 dzwonka z Pixabay, typowo nadpisywany strumieniem radia internetowego, dźwiękiem powiadomienia lub dowolnym bezpośrednim URL audio.
Dobre zastosowania: powiadomienia dzwonka do drzwi, komunikaty głosowe z lokalnego serwera HTTP, odtwarzanie stałego URL radia internetowego bez użycia HEOS Favorites.
Dodatkowe możliwości
Protokół HEOS CLI udostępnia wiele więcej funkcji niż obecnie implementuje szablon. Można je dodać w przyszłej aktualizacji szablonu:
- Metadane Now Playing (
player/get_now_playing_media) — bieżący tytuł, wykonawca, album i URL okładki jako atrybuty tekstowe. - Informacja zwrotna o stanie odtwarzania (
player/get_play_state) — odczyt play / pause / stop, aby przyciski transportu odzwierciedlały rzeczywisty stan. - Toggle Mute (
player/toggle_mute) — jedno polecenie do przełączania wyciszenia bez wcześniejszego odczytu stanu. - Zarządzanie kolejką (
player/get_queue,play_queue,clear_queue) — przeglądanie i modyfikacja bieżącej kolejki odtwarzania. - Ulubione i presety (
browse/play_preset) — uruchamianie zapisanych HEOS Favorites po numerze presetu, prościej niż surowy Play URL dla zapisanych stacji. - Wybór wejścia fizycznego (
browse/play_input) — przełączanie na AUX / Line-In w modelach HEOS Amp, Link i AVR. - Grupowanie multiroom (
group/*) — tworzenie, rozwiązywanie i zbiorcze sterowanie głośnością grup HEOS dla synchronicznego odtwarzania w całym domu. - Konserwacja firmware (
system/check_update,system/reboot) — uruchamianie sprawdzania aktualizacji firmware i zdalny restart. - Change events (
system/register_for_change_events) — opcjonalne powiadomienia push o zmianach głośności, stanu i now-playing zamiast odpytywania. - Logowanie do konta HEOS (
system/sign_in) — wymagane do dostępu do płatnych usług streamingowych (Tidal, Amazon Music, Deezer, własne stacje TuneIn) z TapHome.
Rozwiązywanie problemów
Atrybut Players po Get Players pozostaje pusty
HEOS uruchamia moduł CLI w trybie uśpienia i startuje rdzeń przy pierwszym połączeniu przez gniazdo, co może potrwać kilka sekund. Odczekaj 5–10 sekund i uruchom Get Players ponownie. Jeśli nadal jest pusty, sprawdź:
- TapHome CCU może osiągnąć adres IP głośnika na porcie TCP 1255 (ta sama LAN / podsieć, brak firewalla pomiędzy).
- Urządzenie HEOS jest w pełni online w aplikacji mobilnej HEOS — CLI jest niedostępne, dopóki wstępna konfiguracja Wi-Fi nie zostanie zakończona.
- Adres IP w module nadal odpowiada głośnikowi — odnowienia DHCP mogą go zmienić. Użyj rezerwacji DHCP lub statycznego IP.
Wszystkie polecenia urządzeń zwracają “ID Not Valid”
Zmienna użytkownika PlayerId albo wciąż utrzymuje domyślną wartość szablonu (-1857880384), albo wskazuje na pid, które już nie istnieje (np. głośnik został zresetowany fabrycznie). Uruchom ponownie Get Players, a następnie Set Player Id z poprawnym indeksem.
Akcja Play URL nic nie robi lub zwraca błąd
Skrypt Play URL w obecnym szablonie ma znaną osobliwość: odwołuje się do playerId (małe litery) zamiast do zmiennej użytkownika PlayerId. Jeśli akcja nie ma efektu, otwórz w aplikacji TapHome skrypt urządzenia Play URL i popraw nazwę zmiennej na PlayerId. Po tej poprawce akcja poprawnie wysyła heos://browse/play_stream. Upewnij się też, że URL strumienia jest osiągalny z głośnika HEOS i używa obsługiwanego formatu audio (MP3, AAC, WAV — strumienie HLS nie są niezawodnie akceptowane).
Quick Select zwraca błąd
Quick Select działa tylko na produktach AVR, wzmacniaczach i soundbarach obsługujących HEOS. Na bezprzewodowych głośnikach HEOS (HEOS 1, 3, 5, 7 oraz głośniki Denon Home bez funkcji soundbara) używaj zamiast tego Play URL lub ulubionych strumieni.
Zmiany dokonane w aplikacji HEOS nie są widoczne w TapHome
Szablon odpytuje stan co 2,5 sekundy dla Volume, Mute i Play Mode. Stan transportu (Play / Pause / Stop) nie jest odpytywany — to wyłącznie przyciski. Jeśli zewnętrzny kontroler zmienił tryb odtwarzania lub sparował nowe konto streamingowe, odłączenie i ponowne podłączenie modułu TapHome do głośnika wymusi nową sesję CLI.
Wielu odtwarzaczy HEOS — jak sterować więcej niż jednym
Jeden moduł TapHome steruje dokładnie jednym odtwarzaczem HEOS (jednym pid). Aby sterować drugim głośnikiem, zaimportuj drugą instancję szablonu Denon HEOS. Adres IP może wskazywać na to samo urządzenie HEOS — CLI jednego głośnika sięga każdego innego odtwarzacza HEOS w sieci — a akcja Set Player Id z innym indeksem powiąże drugi moduł z innym głośnikiem.
