TapHome

Denon HEOS

Packet Parser → TCP
Přidal
Poslední aktualizace: 04. 2026
Denon HEOS

Denon HEOS je bezdrátová multiroom audio platforma postavená na HEOS Command Line Interface (CLI) — textovém protokolu, který zpřístupňuje každý reproduktor, soundbar, zesilovač a HEOS-enabled komponent v lokální síti přes TCP port 1255. TapHome tento protokol používá k ovládání přehrávání, hlasitosti, ztlumení a režimu přehrávání HEOS reproduktorů bez jakékoliv cloudové závislosti.

Šablona pokrývá celou bezdrátovou HEOS řadu (HEOS 1, 3, 5, 7), soundbary HEOS Bar a HomeCinema, komponenty HEOS Amp / Link / Drive, HEOS Sub a novější reproduktory Denon Home 150 / 250 / 350 a Sound Bar 550. Stačí jedno HEOS zařízení v LAN — CLI zpřístupní všechny ostatní HEOS hráče v síti přes endpoint player/get_players.

Tato šablona je určena pouze pro HEOS reproduktory, soundbary a HEOS-enabled zesilovače. Denon a Marantz AVR receivery (řady AVR-X, SR atd.) používají samostatný Denon/Marantz Telnet control protokol na portu 23 a s touto šablonou nejsou kompatibilní, ani na modelech, které zároveň obsahují HEOS Built-in.

Síťové připojení

HEOS komunikuje přes TCP na portu 1255 pomocí textových ASCII příkazů ukončených \r\n a vrací odpovědi ve formátu JSON. Autentizace není vyžadována — jakékoliv zařízení ve stejné LAN se může k CLI portu připojit.

Než může TapHome HEOS reproduktor ovládat, musí být zařízení nastaveno přes HEOS mobilní aplikaci:

  1. Nainstalujte aplikaci HEOS App (Android / iOS) na telefon nebo tablet ve stejné Wi-Fi síti.
  2. Připojte HEOS zařízení k Wi-Fi nebo Ethernetu přes úvodního průvodce nastavením v aplikaci.
  3. Ujistěte se, že firmware je aktuální (šablona je postavena na HEOS CLI v1.17, což odpovídá firmware 2.41.140 nebo novější).
  4. Poznamenejte si IP adresu reproduktoru — najdete ji v aplikaci HEOS v Settings → My Devices → About nebo v seznamu DHCP klientů routeru.

Pro HEOS zařízení, ke kterému se TapHome připojuje, použijte statickou IP nebo DHCP rezervaci. Reproduktor funguje jako brána ke všem ostatním HEOS hráčům, takže stabilní adresa udrží dostupnost celého ekosystému.

HEOS CLI nemá žádnou autentizaci. Reproduktor držte v důvěryhodném LAN segmentu — jakékoliv zařízení se síťovým přístupem na port 1255 může ovládat přehrávání.

Konfigurace

Parametry připojení v TapHome

Při importu šablony v aplikaci TapHome zadejte IP adresu HEOS reproduktoru do parametru IP Address. TCP port 1255 a framing protokolu jsou v šabloně již nastaveny. TapHome otevře jedno perzistentní TCP spojení a přes něj pipeline HEOS CLI příkazy.

Inicializace PlayerId

Každý příkaz heos://player/* vyžaduje player id (pid) — velké signed integer číslo, které HEOS přiřazuje každému reproduktoru v síti. Šablona ho ukládá do vlastní proměnné PlayerId. Protože HEOS generuje pid dynamicky pro každou síť, šablona přichází s placeholder hodnotou (-1857880384), kterou je třeba při prvním nastavení nahradit.

Modul nabízí dvě servisní akce pro objevení a přiřazení pid. Po importu šablony je spusťte jednou:

  1. Get Players — odešle heos://player/get_players a JSON odpověď uloží do proměnné modulu PlayersResponse. Servisní atribut modulu Players následně zobrazí seznam HEOS hráčů viditelných v síti včetně jejich jména, pid, modelu a IP adresy.
  2. Set Player Id — přijímá parametr Index (0-based pozice v poli Players) a zapíše odpovídající pid do vlastní proměnné PlayerId. Vyberte index reproduktoru, který chce TapHome ovládat — jeden TapHome modul je svázán s jedním HEOS hráčem.

Po těchto dvou krocích fungují všechna podřízená zařízení (Volume, Mute, Play, Pause atd.) vůči zvolenému reproduktoru. Pro ovládání druhého HEOS hráče importujte druhou instanci šablony proti stejné (nebo jiné) HEOS IP a zopakujte krok Set Player Id s jiným indexem.

Pokud je atribut Players při prvním spuštění prázdný, HEOS CLI modul může být ve spícím režimu. Spusťte Get Players po pár sekundách znovu — HEOS nastartuje CLI jádro při prvním připojení a může trvat chvíli, než enumeruje všechny hráče.

Proměnné zařízení

Dvě podřízená zařízení mají po importu šablony konfigurovatelné proměnné:

ZařízeníProměnnáDefaultPoznámky
Play URLURLPixabay zvonek MP3Libovolná přímá HTTP(S) URL na audio stream nebo soubor
Volume Up / Volume DownStep5Změna hlasitosti na stisk; HEOS specifikace omezuje rozsah na 1–10

V aplikaci TapHome otevřete detail každého zařízení a nastavte tyto proměnné na potřebné hodnoty. URL-encoded speciální znaky ve stream URL (&, =, %) řeší skript šablony.

Funkce zařízení

Šablona poskytuje 12 podřízených zařízení pokrývajících přehrávání, hlasitost, ztlumení a URL streaming pro jednoho HEOS hráče.

Ovládání hlasitosti

Zařízení Volume je dimmer, který čte heos://player/get_volume (úroveň 0–100) a škáluje ji do dimmer rozsahu 0.0–1.0 (Le := level / 100). Zápis posílá heos://player/set_volume s ROUND(Le * 100). Hlasitost se pollne každé 2,5 sekundy, takže externí změny hlasitosti z aplikace HEOS nebo jiného ovladače se v TapHome projeví v následujícím cyklu.

Volume Up a Volume Down jsou tlačítková zařízení, která posílají heos://player/volume_up a heos://player/volume_down s konfigurovatelným krokem Step. Užitečné pro navázání na fyzické nástěnné spínače nebo smart pravidla.

Mute

Mute je spínač, který čte heos://player/get_mute a zapisuje heos://player/set_mute s state=on|off. Při ztlumení je reproduktor utišen bez změny podkladové úrovně hlasitosti.

Transport

Čtyři tlačítková zařízení pokrývají základní 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

Jsou to write-only tlačítka — šablona aktuální stav přehrávání nepollne, takže transportní tlačítka neodráží, zda reproduktor reálně přehrává.

Režim přehrávání

Play Mode je multi-value spínač, který kombinuje HEOS flagy repeat a shuffle do jednoho 6-stavového enumu. Čte a zapisuje přes heos://player/get_play_mode a heos://player/set_play_mode:

HodnotaRežim
0Bez opakování, bez promíchání
1Opakovat vše
2Opakovat jednu skladbu
3Promíchat, bez opakování
4Promíchat, opakovat vše
5Promíchat, opakovat jednu

XML šablona rezervuje v multi-value konfiguraci sloty 6–9, ale ty jsou nevyužité — hodnoty 0–5 jsou jediné dostupné stavy.

QuickSelect předvolby

Quick Select je write-only multi-value spínač (1–9), který spouští HEOS QuickSelect předvolbu přes heos://player/play_quickselect?id={1-9}. Quick selecty jsou uloženy přímo v hráči (typicky přes spárovaný Denon AVR nebo HEOS Bar) a mohou obsahovat přednastavený vstup, zdroj nebo stanici.

Quick Select je v HEOS specifikaci §4.2.24 definován jako AVR-only příkaz. Funguje na HEOS Amp, HEOS Link, HEOS Bar a HEOS-enabled AVR/receiver produktech, ale na samostatných bezdrátových HEOS reproduktorech jako HEOS 1, 3, 5 a 7 vrátí chybu.

Play URL (vlastní stream)

Play URL je tlačítko, které streamuje libovolnou HTTP(S) audio URL do zvoleného HEOS hráče přes heos://browse/play_stream?pid={PlayerId}&url={URL}. Proměnná URL zařízení drží cílový stream — ve výchozím stavu obsahuje ukázkové MP3 zvonku z Pixabay a typicky se přepisuje na internetové rádio, notifikační zvuk nebo libovolnou přímou audio URL.

Dobré využití: zvonková oznámení, hlasové zprávy z lokálního HTTP serveru, přehrání fixní URL internetového rádia bez HEOS Favorites.

Další schopnosti

HEOS CLI protokol nabízí mnohem více funkcí, než šablona aktuálně implementuje. Tyto lze přidat v budoucí aktualizaci šablony:

  • Metadata Now Playing (player/get_now_playing_media) — aktuální název skladby, interpret, album a URL obalu jako string atributy.
  • Zpětná vazba stavu přehrávání (player/get_play_state) — načtení play / pause / stop, aby transportní tlačítka odrážela skutečný stav.
  • Toggle Mute (player/toggle_mute) — jediný příkaz pro přepnutí ztlumení bez předchozího čtení stavu.
  • Správa fronty (player/get_queue, play_queue, clear_queue) — procházení a manipulace aktuální fronty přehrávání.
  • Oblíbené a předvolby (browse/play_preset) — spuštění uložených HEOS Favorites podle čísla předvolby, jednodušší než holý Play URL pro uložené stanice.
  • Výběr fyzického vstupu (browse/play_input) — přepnutí na AUX / Line-In na HEOS Amp, Link a AVR modelech.
  • Multiroom seskupení (group/*) — vytváření, rušení a hromadné ovládání hlasitosti HEOS skupin pro synchronizované přehrávání v celém domě.
  • Správa firmware (system/check_update, system/reboot) — spuštění kontroly firmware aktualizací a vzdálený restart.
  • Change events (system/register_for_change_events) — volitelné push notifikace pro změny hlasitosti, stavu a metadat místo pollování.
  • Přihlášení do HEOS účtu (system/sign_in) — nutné pro přístup k placeným streamovacím službám (Tidal, Amazon Music, Deezer, vlastní TuneIn stanice) z TapHome.

Řešení problémů

Atribut Players je po Get Players prázdný

HEOS běží v CLI modulu ve spícím režimu a jádro nastartuje při prvním socket připojení, což může trvat pár sekund. Počkejte 5–10 sekund a spusťte Get Players znovu. Pokud je stále prázdný, ověřte:

  1. TapHome CCU dokáže dosáhnout IP reproduktoru na TCP portu 1255 (stejná LAN / subnet, žádný firewall mezi nimi).
  2. HEOS zařízení je v aplikaci HEOS plně online — CLI je nedostupné, dokud není dokončeno prvotní Wi-Fi nastavení.
  3. IP adresa v modulu stále odpovídá reproduktoru — obnova DHCP ji může změnit. Použijte DHCP rezervaci nebo statickou IP.
Všechny příkazy zařízení vrací “ID Not Valid”

Vlastní proměnná PlayerId buď stále drží default šablony (-1857880384), nebo ukazuje na pid, který už neexistuje (např. reproduktor byl factory-reset). Spusťte Get Players a následně Set Player Id se správným indexem.

Akce Play URL nereaguje nebo vrací chybu

Skript Play URL v aktuální šabloně má známou chybu: odkazuje na playerId (malá písmena) místo vlastní proměnné PlayerId. Pokud akce nemá efekt, otevřete v aplikaci TapHome skript zařízení Play URL a opravte název proměnné tak, aby odpovídal PlayerId. Po opravě posílá akce heos://browse/play_stream správně. Ujistěte se také, že stream URL je z HEOS reproduktoru dosažitelná a používá podporovaný audio formát (MP3, AAC, WAV — HLS streamy nejsou spolehlivě akceptovány).

Quick Select vrací chybu

Quick Select funguje pouze na HEOS-enabled AVR, zesilovačích a soundbar produktech. Na bezdrátových HEOS reproduktorech (HEOS 1, 3, 5, 7 a Denon Home reproduktory bez soundbar funkcí) použijte raději Play URL nebo oblíbené streamy.

Změny v aplikaci HEOS nejsou v TapHome viditelné

Šablona pollne stav každé 2,5 sekundy pro Volume, Mute a Play Mode. Transportní stav (Play / Pause / Stop) se nepolluje — to jsou pouze push tlačítka. Pokud externí ovladač změnil režim přehrávání nebo spároval nový streamovací účet, odpojení a znovupřipojení TapHome modulu k reproduktoru si vynutí novou CLI relaci.

Více HEOS hráčů — jak ovládat více než jednoho

Jeden TapHome modul ovládá právě jednoho HEOS hráče (jeden pid). Pro ovládání druhého reproduktoru importujte druhou instanci šablony Denon HEOS. IP adresa může ukazovat na stejné HEOS zařízení — CLI jednoho reproduktoru dosáhne každého jiného HEOS hráče v síti — a akce Set Player Id s jiným indexem sváže druhý modul s jiným reproduktorem.

Dostupná zařízení

Reproduktor Denon HEOS Modul
Servisní atributy
HráčiJSON pole HEOS hráčů dosažitelných v síti (jméno, pid, model, IP, verze). Naplní ho akce Získat hráče; slouží k výběru indexu pro Nastavit Player Id.
Servisní akce
Získat hráčeObjeví všechny HEOS hráče v síti odesláním heos://player/get_players. Odpověď se uloží do atributu Hráči a akce musí být spuštěna před Nastavit Player Id.
Nastavit Player IdSváže tento TapHome modul s jedním HEOS hráčem. Bere 0-based index ze seznamu Hráči a zapíše příslušný pid do vlastní proměnné PlayerId. Vyžadováno po Získat hráče, aby fungovala podřízená zařízení.
Vlastní proměnné

Denon HEOS speaker

Zápis (modul)
# 1. Run Get Players action
					# 2. Save and go back
					# 3. Review the Players attribute in the top of page
					# 4. Run Set Player Id with index of your choice
Listener
VAR response := TOSTRING(RECEIVEDBYTES);
					VAR command := PARSEJSON(response, "heos.command", 1);
					VAR result := PARSEJSON(response, "heos.result", 1);
					VAR message := PARSEJSON(response, "heos.message", 1);

					IF (result = "fail" AND INDEXOF(message, "ID Not Valid") >= 0)
					ADDERROR("PlayerId is not set properly.");
					END

					IF (command = "player/get_players")
					IF (result = "fail")
					ADDERROR("Error: " + message);
					ELSE
					PlayersResponse := response;
					END
					END
Servisní atributy
Players
PARSEJSON(PlayersResponse, "payload");
Servisní akce
Get Players
SENDDATA("heos://player/get_players");
Set Player Id
Parametry: Index (0–20 Index)
PlayerId := PARSEJSON(PlayersResponse,"payload[" + Index + "].pid");
Ztlumit reproduktor Přepínač

Ztlumuje nebo ruší ztlumení audio výstupu na vybraném HEOS hráči bez změny podkladové úrovně hlasitosti.

boolean switch
Hodnoty / Stavy: Muted · Unmuted

Ztlumit reproduktor

Čtení stavu přepínače
SENDDATA("heos://player/get_mute?pid=" + PlayerId);
Zápis stavu přepínače
VAR mute := SWITCH(St, 0, "off", 1, "on", "off");
							SENDDATA("heos://player/set_mute?pid=" + PlayerId + "&state=" + mute);
Listener
VAR responseJson := TOSTRING(RECEIVEDBYTES);

							IF(PARSEJSON(responseJson, "heos.command", 1) = "player/get_mute")
							VAR mute := PARSETEXT(responseJson, "state=");
							St := SWITCH(mute, "off", 0, "on", 1, 0);
							END
Další skladba Tlačítko
button push

Další skladba

Zápis stavu tlačítka
SENDDATA("heos://player/play_next?pid=" + PlayerId);
Pozastavit Tlačítko
button push

Pozastavit

Zápis stavu tlačítka
SENDDATA("heos://player/set_play_state?pid=" + PlayerId + "&state=pause")
Přehrát Tlačítko
button push

Přehrát

Zápis stavu tlačítka
SENDDATA("heos://player/set_play_state?pid=" + PlayerId + "&state=play");
Režim přehrávání Vícestavový přepínač

Kombinovaný stav opakování a promíchání jako 6-hodnotový enum — 0 bez opakování, 1 opakovat vše, 2 opakovat jednu, 3 promíchat, 4 promíchat + opakovat vše, 5 promíchat + opakovat jednu.

enum multi-value
Hodnoty / Stavy: No repeat · Repeat all · Repeat 1 · Shuffle, no repeat · Shuffle, repeat all · Shuffle, repeat one

Režim přehrávání

Čtení stavu přepínače
SENDDATA("heos://player/get_play_mode?pid=" + PlayerId);
Zápis stavu přepínače
VAR repeat := SWITCH( IF(Mu > 2, Mu - 3, Mu), 0, "off", 1, "on_all", 2, "on_one", "off");
							VAR shuffle := IF(Mu > 2, "on", "off");
							SENDDATA("heos://player/set_play_mode?pid=" + PlayerId + "&repeat=" + repeat + "&shuffle=" + shuffle);
Listener
VAR responseJson := TOSTRING(RECEIVEDBYTES);
							VAR command := PARSEJSON(responseJson, "heos.command", 1);
							VAR result := PARSEJSON(responseJson, "heos.result", 1);

							IF (command = "player/get_play_mode")
							IF (result = "fail")
							VAR errorMessage := PARSEJSON(responseJson, "heos.message", 1);
							ADDERROR("Error: " + errorMessage);
							ELSE
							VAR repeat := PARSETEXT(responseJson, "repeat=", "&");
							VAR shuffle := PARSETEXT(responseJson, "shuffle=");
							Mu := SWITCH(repeat, "off", 0, "on_all", 1, "on_one", 2, 0) + SWITCH(shuffle, "off", 0, "on", 3, 0);
							END
							END
Přehrát URL Tlačítko

Streamuje libovolnou HTTP(S) audio URL do HEOS hráče (zvuky zvonku, internetové rádio, hlasová oznámení). URL se konfiguruje na úrovni zařízení přes vlastní proměnnou URL.

button push
Proměnná: URL

Přehrát URL

Zápis stavu tlačítka
SENDDATA("heos://browse/play_stream?pid=" + playerId + "&url=" + URL);
Listener
VAR response := TOSTRING(RECEIVEDBYTES);
							VAR command := PARSEJSON(response, "heos.command", 1);
							VAR result := PARSEJSON(response, "heos.result", 1);
							VAR message := PARSEJSON(response, "heos.message", 1);

							IF (command = "browse/play_stream")
							IF (result = "fail")
							ADDERROR("Error: " + message);
							ELSE
							VAR success := response;
							END
							END
Předchozí skladba Tlačítko
button push

Předchozí skladba

Zápis stavu tlačítka
SENDDATA("heos://player/play_previous?pid=" + PlayerId);
Rychlá volba Vícestavový přepínač

Spouští jednu z HEOS QuickSelect předvoleb 1–9 uloženou v hráči. Pouze AVR / HEOS Bar / HEOS Amp — na samostatných bezdrátových HEOS reproduktorech není podporováno.

enum multi-value

Rychlá volba

Zápis stavu přepínače
IF(Mu != 0)
							SENDDATA("heos://player/play_quickselect?pid=" + PlayerId + "&id=" + Mu);
							END

							# To make this work like a switch, create a following script.
							#
							# IF(Mu != 0)
							#   SLEEP(100);
							#   Mu := 0;
							# END
Zastavit Tlačítko
button push

Zastavit

Zápis stavu tlačítka
SENDDATA("heos://player/set_play_state?pid=" + PlayerId + "&state=stop")
Hlasitost Stmívač

Dimmerové ovládání hlasitosti HEOS hráče. HEOS úroveň 0–100 je mapována na dimmer rozsah 0.0–1.0 a pollne se každé 2,5 sekundy.

numeric Jednotka: % dimmer

Hlasitost

Čtení úrovně
SENDDATA("heos://player/get_volume?pid=" + PlayerId)
Zápis úrovně
SENDDATA("heos://player/set_volume?pid=" + PlayerId + "&level=" + ROUND(Le*100))
Listener
VAR responseJson := TOSTRING(RECEIVEDBYTES);
							VAR command := PARSEJSON(responseJson, "heos.command", 1);
							VAR result := PARSEJSON(responseJson, "heos.result", 1);

							IF (command = "player/get_volume")
							IF (result = "fail")
							VAR errorMessage := PARSEJSON(responseJson, "heos.message", 1);
							ADDERROR("Error: " + errorMessage);
							ELSE
							Le := PARSETEXT(responseJson, "level=") / 100.0;
							END
							END
Snížení hlasitosti Tlačítko

Snižuje hlasitost o nakonfigurovaný krok Step (default 5, HEOS povoluje 1–10) přes příkaz heos://player/volume_down.

button push
Proměnná: Step

Snížení hlasitosti

Zápis stavu tlačítka
SENDDATA("heos://player/volume_down?pid=" + PlayerId + "&step=" + Step);
Zvýšení hlasitosti Tlačítko

Zvyšuje hlasitost o nakonfigurovaný krok Step (default 5, HEOS povoluje 1–10) přes příkaz heos://player/volume_up.

button push
Proměnná: Step

Zvýšení hlasitosti

Zápis stavu tlačítka
SENDDATA("heos://player/volume_up?pid=" + PlayerId + "&step=" + Step);
Připojení: Packet Parser → TCP
Možná vylepšení (14)
  • Now Playing Metadata — Current track artist, album, title, artwork URL, media_id — would require string attributes and a listener to cache the response
  • Play State (read) — Reads play|pause|stop back from the player. Template only writes play state (Play/Pause/Stop buttons) without feedback
  • Toggle Mute — Single-command mute toggle without reading current state; could be a second push-button
  • Check Firmware Update — Trigger firmware update check — useful as maintenance action
  • Heart Beat / Connection Health — Periodic heart_beat command for connection liveness; could map to a module-level online/offline sensor
  • Reboot Speaker — Remote reboot of the HEOS device — natural service action
  • Play Queue — Full queue management (get, play item, remove, save as playlist, clear, move). Template has no queue exposure
  • Music Sources / Browse — Browse and search streaming services (TuneIn, local library, favorites, playlists). Not exposed in template
  • Favorites / Preset Stations — Play a favorite station by preset number 1–N; simpler than Play URL for saved stations
  • Input Source (AUX / Line-In) — Switch to a physical input (inputs/aux_in_1, inputs/line_in_1, etc.) — only applicable to AVR/Amp/Link models
  • Group / Multi-Room Control — Create/destroy groups, group volume, group mute — enables multi-room synchronized playback across HEOS speakers. Not exposed in template
  • Player Info (name, model, version, IP) — Static metadata about the player; useful for diagnostics
  • Change Events (unsolicited push) — Register for change events via system/register_for_change_events and receive push updates (volume, state, now playing, queue). Template relies on polling only
  • HEOS Account Sign In / Out — Required for access to paid streaming services and cloud favorites; no hooks in template

Zdroje