TapHome

Denon HEOS

Packet Parser → TCP
Pridal
Posledná aktualizácia: 04. 2026
Denon HEOS

Denon HEOS je bezdrôtová multiroom audio platforma postavená na HEOS Command Line Interface (CLI) — textovom protokole, ktorý sprístupňuje každý reproduktor, soundbar, zosilňovač a HEOS-enabled komponent v lokálnej sieti cez TCP port 1255. TapHome využíva tento protokol na ovládanie prehrávania, hlasitosti, stlmenia a režimu prehrávania HEOS reproduktorov bez závislosti na cloude.

Šablóna pokrýva celú bezdrôtovú HEOS ponuku (HEOS 1, 3, 5, 7), soundbary HEOS Bar a HomeCinema, komponenty HEOS Amp / Link / Drive, HEOS Sub a novšie reproduktory Denon Home 150 / 250 / 350 a Sound Bar 550. Stačí jedno HEOS zariadenie v LAN — CLI sprístupní všetkých ostatných HEOS hráčov v sieti cez endpoint player/get_players.

Táto šablóna je určená len pre HEOS reproduktory, soundbary a HEOS-enabled zosilňovače. Denon a Marantz AVR receivery (rady AVR-X, SR atď.) používajú samostatný Denon/Marantz Telnet control protokol na porte 23 a s touto šablónou nie sú kompatibilné, ani na modeloch, ktoré zároveň obsahujú HEOS Built-in.

Sieťové pripojenie

HEOS komunikuje cez TCP na porte 1255 pomocou textových ASCII príkazov ukončených \r\n a vracia odpovede v JSON formáte. Autentifikácia nie je potrebná — akékoľvek zariadenie v rovnakej LAN sa môže pripojiť na CLI port.

Pred tým, než HEOS reproduktor dokáže TapHome ovládať, musí byť zariadenie nastavené cez HEOS mobilnú aplikáciu:

  1. Nainštalujte aplikáciu HEOS App (Android / iOS) na telefón alebo tablet v rovnakej Wi-Fi sieti.
  2. Pripojte HEOS zariadenie na Wi-Fi alebo Ethernet cez úvodného sprievodcu nastavením v aplikácii.
  3. Uistite sa, že firmware je aktuálny (šablóna je postavená na HEOS CLI v1.17, čo zodpovedá firmware 2.41.140 alebo novšiemu).
  4. Poznačte si IP adresu reproduktora — nájdete ju v aplikácii HEOS v Settings → My Devices → About alebo v zozname DHCP klientov routera.

Pre HEOS zariadenie, ku ktorému sa TapHome pripája, použite statickú IP alebo DHCP rezerváciu. Reproduktor funguje ako brána k všetkým ostatným HEOS hráčom, takže stabilná adresa udrží dostupnosť celého ekosystému.

HEOS CLI nemá žiadnu autentifikáciu. Reproduktor držte v dôveryhodnom LAN segmente — každé zariadenie so sieťovým prístupom k portu 1255 môže ovládať prehrávanie.

Konfigurácia

Parametre pripojenia v TapHome

Pri importe šablóny v aplikácii TapHome zadajte IP adresu HEOS reproduktora do parametra IP Address. TCP port 1255 a framing protokolu sú v šablóne už nastavené. TapHome otvorí jedno perzistentné TCP spojenie a cez neho pipeliuje HEOS CLI príkazy.

Inicializácia PlayerId

Každý príkaz heos://player/* vyžaduje player id (pid) — veľké signed integer číslo, ktoré HEOS priraďuje každému reproduktoru v sieti. Šablóna ho ukladá do vlastnej premennej PlayerId. Pretože HEOS generuje pid dynamicky pre každú sieť, šablóna prichádza s placeholder hodnotou (-1857880384), ktorú treba pri prvom nastavení nahradiť.

Modul ponúka dve servisné akcie na objavenie a priradenie pid. Po importe šablóny ich spustite raz:

  1. Get Players — odošle heos://player/get_players a JSON odpoveď uloží do premennej modulu PlayersResponse. Servisný atribút modulu Players následne zobrazí zoznam HEOS hráčov viditeľných v sieti vrátane ich mena, pid, modelu a IP adresy.
  2. Set Player Id — prijíma parameter Index (0-based pozícia v poli Players) a zapíše zodpovedajúci pid do vlastnej premennej PlayerId. Vyberte index reproduktora, ktorý chce TapHome ovládať — jeden TapHome modul je viazaný na jedného HEOS hráča.

Po týchto dvoch krokoch fungujú všetky podriadené zariadenia (Volume, Mute, Play, Pause atď.) voči vybranému reproduktoru. Na ovládanie druhého HEOS hráča importujte druhú inštanciu šablóny proti rovnakej (alebo inej) HEOS IP a opakujte krok Set Player Id s iným indexom.

Ak je atribút Players pri prvom spustení prázdny, HEOS CLI modul môže byť v spiacom režime. Spustite Get Players po pár sekundách znova — HEOS naštartuje CLI jadro pri prvom pripojení a môže trvať chvíľu, kým enumeruje všetkých hráčov.

Premenné zariadenia

Dve podriadené zariadenia majú po importe šablóny konfigurovateľné premenné:

ZariadeniePremennáDefaultPoznámky
Play URLURLPixabay zvonček MP3Ľubovoľná priama HTTP(S) URL na audio stream alebo súbor
Volume Up / Volume DownStep5Zmena hlasitosti na stlačenie; HEOS špecifikácia obmedzuje rozsah na 1–10

V aplikácii TapHome otvorte detail každého zariadenia a nastavte tieto premenné na potrebné hodnoty. URL-encoded špeciálne znaky v stream URL (&, =, %) rieši skript šablóny.

Funkcie zariadenia

Šablóna poskytuje 12 podriadených zariadení pokrývajúcich prehrávanie, hlasitosť, stlmenie a URL streaming pre jedného HEOS hráča.

Ovládanie hlasitosti

Zariadenie Volume je dimmer, ktorý číta heos://player/get_volume (úroveň 0–100) a škáluje ju do dimmer rozsahu 0.0–1.0 (Le := level / 100). Zápis posiela heos://player/set_volume s ROUND(Le * 100). Hlasitosť sa pollne každé 2,5 sekundy, takže externé zmeny hlasitosti z aplikácie HEOS alebo iného ovládača sa v TapHome prejavia v ďalšom cykle.

Volume Up a Volume Down sú tlačidlové zariadenia, ktoré posielajú heos://player/volume_up a heos://player/volume_down s konfigurovateľným krokom Step. Užitočné pri naviazaní na fyzické nástenné spínače alebo smart pravidlá.

Mute

Mute je spínač, ktorý číta heos://player/get_mute a zapisuje heos://player/set_mute s state=on|off. Pri stlmení je reproduktor utíšený bez zmeny podkladovej úrovne hlasitosti.

Transport

Štyri tlačidlové zariadenia 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

Sú to write-only tlačidlá — šablóna aktuálny stav prehrávania nepollne, takže transportné tlačidlá neodzrkadlujú, či reproduktor reálne prehráva.

Režim prehrávania

Play Mode je multi-value spínač, ktorý kombinuje HEOS flagy repeat a shuffle do jedného 6-stavového enumu. Číta a zapisuje cez heos://player/get_play_mode a heos://player/set_play_mode:

HodnotaRežim
0Bez opakovania, bez premiešania
1Opakovať všetko
2Opakovať jednu skladbu
3Premiešať, bez opakovania
4Premiešať, opakovať všetko
5Premiešať, opakovať jednu

XML šablóna rezervuje v multi-value konfigurácii sloty 6–9, ale tie sú nepoužité — hodnoty 0–5 sú jediné dostupné stavy.

QuickSelect predvoľby

Quick Select je write-only multi-value spínač (1–9), ktorý spúšťa HEOS QuickSelect predvoľbu cez heos://player/play_quickselect?id={1-9}. Quick selecty sú uložené priamo v hráčovi (typicky cez spárovaný Denon AVR alebo HEOS Bar) a môžu obsahovať prednastavený vstup, zdroj alebo stanicu.

Quick Select je v HEOS špecifikácii §4.2.24 definovaný ako AVR-only príkaz. Funguje na HEOS Amp, HEOS Link, HEOS Bar a HEOS-enabled AVR/receiver produktoch, ale na samostatných bezdrôtových HEOS reproduktoroch ako HEOS 1, 3, 5 a 7 vráti chybu.

Play URL (vlastný stream)

Play URL je tlačidlo, ktoré streamuje ľubovoľnú HTTP(S) audio URL do zvoleného HEOS hráča cez heos://browse/play_stream?pid={PlayerId}&url={URL}. Premenná URL zariadenia drží cieľový stream — v defaulte obsahuje ukážkové MP3 zvončeka z Pixabay a typicky sa prepíše na internetové rádio, notifikačný zvuk alebo ľubovoľnú priamu audio URL.

Dobré využitie: zvončekové notifikácie, hlasové oznámenia z lokálneho HTTP servera, prehranie fixnej URL internetového rádia bez HEOS Favorites.

Ďalšie schopnosti

HEOS CLI protokol ponúka oveľa viac funkcií, než šablóna aktuálne implementuje. Tieto je možné pridať v budúcej aktualizácii šablóny:

  • Metadáta Now Playing (player/get_now_playing_media) — aktuálny názov skladby, interpret, album a URL obalu ako string atribúty.
  • Spätná väzba stavu prehrávania (player/get_play_state) — načítanie play / pause / stop, aby transportné tlačidlá odzrkadlovali skutočný stav.
  • Toggle Mute (player/toggle_mute) — jediný príkaz na prepnutie stlmenia bez predchádzajúceho čítania stavu.
  • Správa fronty (player/get_queue, play_queue, clear_queue) — prechádzanie a manipulácia aktuálnej fronty prehrávania.
  • Obľúbené a predvoľby (browse/play_preset) — spustenie uložených HEOS Favorites podľa čísla predvoľby, jednoduchšie ako holý Play URL pre uložené stanice.
  • Výber fyzického vstupu (browse/play_input) — prepnutie na AUX / Line-In na HEOS Amp, Link a AVR modeloch.
  • Multiroom zoskupenie (group/*) — vytváranie, rušenie a hromadné ovládanie hlasitosti HEOS skupín pre synchronizované prehrávanie v celom dome.
  • Správa firmware (system/check_update, system/reboot) — spustenie kontroly firmware aktualizácií a vzdialený reštart.
  • Change events (system/register_for_change_events) — voliteľné push notifikácie pre zmeny hlasitosti, stavu a metadát namiesto pollovania.
  • Prihlásenie do HEOS účtu (system/sign_in) — potrebné pre prístup k plateným streamovacím službám (Tidal, Amazon Music, Deezer, vlastné TuneIn stanice) z TapHome.

Riešenie problémov

Atribút Players je po Get Players prázdny

HEOS beží v CLI module v spiacom režime a jadro naštartuje pri prvom socket pripojení, čo môže trvať pár sekúnd. Počkajte 5–10 sekúnd a spustite Get Players znova. Ak je stále prázdny, overte:

  1. TapHome CCU vie dosiahnuť IP reproduktora na TCP porte 1255 (rovnaká LAN / subnet, žiadny firewall medzi nimi).
  2. HEOS zariadenie je v aplikácii HEOS plne online — CLI je nedostupné, kým nie je dokončené prvotné Wi-Fi nastavenie.
  3. IP adresa v module stále zodpovedá reproduktoru — obnova DHCP ju môže zmeniť. Použite DHCP rezerváciu alebo statickú IP.
Všetky príkazy zariadení vracajú “ID Not Valid”

Vlastná premenná PlayerId buď stále drží default šablóny (-1857880384), alebo ukazuje na pid, ktorý už neexistuje (napr. reproduktor bol factory-reset). Spustite Get Players a následne Set Player Id so správnym indexom.

Akcia Play URL nereaguje alebo vracia chybu

Skript Play URL v aktuálnej šablóne má známu chybu: odkazuje na playerId (malé písmená) namiesto vlastnej premennej PlayerId. Ak akcia nemá efekt, otvorte v aplikácii TapHome skript zariadenia Play URL a opravte názov premennej tak, aby zodpovedal PlayerId. Po oprave posiela akcia heos://browse/play_stream správne. Uistite sa tiež, že stream URL je z HEOS reproduktora dosiahnuteľná a používa podporovaný audio formát (MP3, AAC, WAV — HLS streamy nie sú spoľahlivo akceptované).

Quick Select vracia chybu

Quick Select funguje len na HEOS-enabled AVR, zosilňovačoch a soundbar produktoch. Na bezdrôtových HEOS reproduktoroch (HEOS 1, 3, 5, 7 a Denon Home reproduktory bez soundbar funkcií) použite radšej Play URL alebo obľúbené streamy.

Zmeny v aplikácii HEOS nie sú v TapHome viditeľné

Šablóna pollne stav každé 2,5 sekundy pre Volume, Mute a Play Mode. Transportný stav (Play / Pause / Stop) sa nepolluje — to sú len push tlačidlá. Ak externý ovládač zmenil režim prehrávania alebo spároval nový streamovací účet, odpojenie a znovupripojenie TapHome modulu k reproduktoru si vynúti novú CLI reláciu.

Viac HEOS hráčov — ako ovládať viac než jedného

Jeden TapHome modul ovláda presne jedného HEOS hráča (jeden pid). Na ovládanie druhého reproduktora importujte druhú inštanciu šablóny Denon HEOS. IP adresa môže ukazovať na rovnaké HEOS zariadenie — CLI jedného reproduktora dosiahne každého iného HEOS hráča v sieti — a akcia Set Player Id s iným indexom viaže druhý modul na iný reproduktor.

Dostupné zariadenia

Reproduktor Denon HEOS Modul
Servisné atribúty
HráčiJSON pole HEOS hráčov dosiahnuteľných v sieti (meno, pid, model, IP, verzia). Naplní ho akcia Získať hráčov; slúži na výber indexu pre Nastaviť Player Id.
Servisné akcie
Získať hráčovObjaví všetkých HEOS hráčov v sieti odoslaním heos://player/get_players. Odpoveď sa uloží do atribútu Hráči a akcia musí byť spustená pred Nastaviť Player Id.
Nastaviť Player IdZviazuje tento TapHome modul s jedným HEOS hráčom. Berie 0-based index zo zoznamu Hráči a zapíše príslušný pid do vlastnej premennej PlayerId. Vyžadované po Získať hráčov, aby fungovali podriadené zariadenia.
Vlastné premenné

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é atribúty
Players
PARSEJSON(PlayersResponse, "payload");
Servisné akcie
Get Players
SENDDATA("heos://player/get_players");
Set Player Id
Parametre: Index (0–20 Index)
PlayerId := PARSEJSON(PlayersResponse,"payload[" + Index + "].pid");
Stlmiť reproduktor Prepínač

Stlmuje alebo ruší stlmenie audio výstupu na vybranom HEOS hráčovi bez zmeny podkladovej úrovne hlasitosti.

boolean switch
Hodnoty / Stavy: Muted · Unmuted

Stlmiť reproduktor

Čítanie stavu prepínača
SENDDATA("heos://player/get_mute?pid=" + PlayerId);
Zápis stavu prepínača
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
Ďalšia skladba Tlačidlo
button push

Ďalšia skladba

Zápis stavu tlačidla
SENDDATA("heos://player/play_next?pid=" + PlayerId);
Pozastaviť Tlačidlo
button push

Pozastaviť

Zápis stavu tlačidla
SENDDATA("heos://player/set_play_state?pid=" + PlayerId + "&state=pause")
Prehrať Tlačidlo
button push

Prehrať

Zápis stavu tlačidla
SENDDATA("heos://player/set_play_state?pid=" + PlayerId + "&state=play");
Režim prehrávania Viacstavový prepínač

Kombinovaný stav opakovania a premiešania ako 6-hodnotový enum — 0 bez opakovania, 1 opakovať všetko, 2 opakovať jednu, 3 premiešať, 4 premiešať + opakovať všetko, 5 premiešať + opakovať jednu.

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

Režim prehrávania

Čítanie stavu prepínača
SENDDATA("heos://player/get_play_mode?pid=" + PlayerId);
Zápis stavu prepínača
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
Prehrať URL Tlačidlo

Streamuje ľubovoľnú HTTP(S) audio URL do HEOS hráča (zvuky zvončeka, internetové rádio, hlasové oznámenia). URL sa konfiguruje na úrovni zariadenia cez vlastnú premennú URL.

button push
Premenná: URL

Prehrať URL

Zápis stavu tlačidla
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
Predchádzajúca skladba Tlačidlo
button push

Predchádzajúca skladba

Zápis stavu tlačidla
SENDDATA("heos://player/play_previous?pid=" + PlayerId);
Rýchla voľba Viacstavový prepínač

Spúšťa jednu z HEOS QuickSelect predvolieb 1–9 uloženú v hráčovi. Len AVR / HEOS Bar / HEOS Amp — na samostatných bezdrôtových HEOS reproduktoroch nie je podporované.

enum multi-value

Rýchla voľba

Zápis stavu prepínača
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
Zastaviť Tlačidlo
button push

Zastaviť

Zápis stavu tlačidla
SENDDATA("heos://player/set_play_state?pid=" + PlayerId + "&state=stop")
Hlasitosť Stmievač

Dimmerové ovládanie hlasitosti HEOS hráča. HEOS úroveň 0–100 je mapovaná na dimmer rozsah 0.0–1.0 a pollne sa každé 2,5 sekundy.

numeric Jednotka: % dimmer

Hlasitosť

Čítanie úrovne
SENDDATA("heos://player/get_volume?pid=" + PlayerId)
Zápis úrovne
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
Zníženie hlasitosti Tlačidlo

Znižuje hlasitosť o nakonfigurovaný krok Step (default 5, HEOS povoľuje 1–10) cez príkaz heos://player/volume_down.

button push
Premenná: Step

Zníženie hlasitosti

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

Zvyšuje hlasitosť o nakonfigurovaný krok Step (default 5, HEOS povoľuje 1–10) cez príkaz heos://player/volume_up.

button push
Premenná: Step

Zvýšenie hlasitosti

Zápis stavu tlačidla
SENDDATA("heos://player/volume_up?pid=" + PlayerId + "&step=" + Step);
Pripojenie: Packet Parser → TCP
Možné vylepšenia (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