> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unicontrol.me/llms.txt
> Use this file to discover all available pages before exploring further.

# DLNA / UPnP

> Controle renderers DLNA (TVs, soundbars, receivers) e navegue conteúdo de servidores DLNA/UPnP

# DLNA / UPnP

Unifica as duas pontas do padrão **DLNA** (Digital Living Network Alliance),
que roda sobre UPnP:

* **Digital Media Renderer (DMR)** — TVs, soundbars, receivers e dongles que
  tocam mídia. Vira uma entidade `media_player` com play/pause/stop, volume,
  mute, next/previous, seek e `play_media` por URL.
* **Digital Media Server (DMS)** — NAS, Jellyfin, MiniDLNA, Plex (modo DLNA),
  qualquer PC rodando um servidor UPnP. Vira uma **fonte navegável** no painel
  de mídia, com browse hierárquico e busca por título.

Um mesmo aparelho que anuncia os dois services (comum em TVs modernas e
soundbars) aparece como **uma única entrada** no Portal e carrega as duas
capacidades.

## Pré-requisitos

* Os dispositivos precisam estar **na mesma LAN** do edge — DLNA/UPnP depende
  de SSDP multicast (`239.255.255.250:1900`) para descoberta e dos próprios
  endpoints HTTP do aparelho para controle. Não funciona por VPN sem bridge
  multicast.
* A integração roda em um **edge local**. Crie um em
  **Configurações → Edges** antes de adicionar.
* Em redes com múltiplas VLANs/subnets, os dispositivos precisam estar no
  mesmo segmento L2 do edge (ou use IGMP snooping + multicast routing).

## Configurar

**1. Adicione a integração**

Vá em **Configurações → Integrações → Adicionar → DLNA / UPnP**.

**2. Escolha o dispositivo**

O Portal faz um M-SEARCH SSDP e lista os dispositivos encontrados (com
fabricante, modelo e capacidades Renderer / Server). A descoberta demora
\~3 segundos. Se o aparelho não aparecer, selecione **"Informar URL
manualmente"**.

**3. Modo manual (quando SSDP falha)**

Informe a URL do *device description* (ex.:
`http://192.168.1.50:49152/description.xml`). Essa URL costuma aparecer na
página de administração do dispositivo, ou pode ser descoberta rodando
`gssdp-discover -n 3` numa máquina Linux da mesma rede.

**4. Pronto**

* Se o dispositivo tem **AVTransport** → é criada uma entidade
  `media_player.dlna_<udn>_media_player`.
* Se tem **ContentDirectory** → o device aparece no painel **Mídia** como
  uma fonte navegável.
* Se tem os dois → ambas as coisas, numa única entry.

## Funcionalidades

### Renderer (DMR)

* Play / Pause / Stop / Next / Previous track
* Volume (ajuste absoluto 0–100 e mute/unmute) — quando o dispositivo
  anuncia `RenderingControl`
* Seek (`media_seek`) quando o stream expõe duração
* `play_media` com URL direta (HTTP/HTTPS, MP3/FLAC/AAC/vídeo)
* Metadados em tempo real: título, artista, álbum, posição, duração, arte da
  capa (via `GetPositionInfo`)

### Server (DMS)

* Browse hierárquico do catálogo, começando pela raiz (`ObjectID=0`)
* Busca por título (`dc:title contains "..."`) — quando o servidor suporta a
  ação `Search` (opcional no spec UPnP)
* Resolução para URL direta tocável em qualquer `media_player`

## Como funciona por baixo

* **SSDP** (`239.255.255.250:1900` UDP multicast) para descobrir os
  dispositivos.
* **HTTP GET** no `LOCATION` recebido do SSDP para ler o *device description
  XML*. Isso dá os `controlURL` dos services suportados.
* **SOAP** (POST XML com header `SOAPAction`) para cada comando: play/pause
  vão em `AVTransport:1`, volume em `RenderingControl:1`, browse em
  `ContentDirectory:1`.
* O polling do estado do DMR é de **10 segundos** — o Portal reage
  otimisticamente aos comandos iniciados por você (o card muda imediatamente),
  e re-sincroniza no próximo ciclo com o estado real do dispositivo.

## Reproduzir mídia (`media_player.play_media`)

```json theme={null}
{
  "media_content_type": "music",
  "media_content_id": "http://192.168.1.100:8080/track.mp3"
}
```

Prefira URLs **HTTP** (não HTTPS) e com **IP** (não hostname) quando possível.
Vários renderers DLNA, especialmente TVs antigas e certos receivers, recusam
HTTPS com certificado válido mas aceitam HTTP em claro.

Para tocar conteúdo de um DMS da mesma casa, o fluxo natural é navegar no
painel **Mídia** → clicar no servidor DLNA → escolher a faixa → selecionar o
renderer DLNA como destino. O Portal resolve o `<res>` do item e passa a URL
pronta para o renderer.

## Limitações desta versão

* **Sem GENA event subscription** — usamos polling de 10s em vez de assinar
  eventos push do UPnP. Isso significa que mudanças iniciadas pelo controle
  remoto físico ou por outro app (não pelo Portal) demoram até 10 segundos
  para refletir no dashboard.
* **Sem agrupamento multiroom** — DLNA não padroniza grouping; cada
  fabricante faz do seu jeito (SongCast, Play-Fi, etc.).
* **Sem "modo exclusivo"** — se outro app estiver controlando o renderer, os
  comandos do Portal competem com ele.

## Solução de problemas

* **Nenhum dispositivo encontrado no SSDP** — a rede do edge pode estar
  bloqueando multicast. Teste com `gssdp-discover -n 3` numa máquina Linux da
  mesma subnet. Soluções comuns:
  * Confirmar que o edge e o dispositivo estão na **mesma VLAN** (routing
    L3 bloqueia multicast por padrão).
  * Em switches gerenciados, verificar se **IGMP snooping** não está
    descartando o tráfego multicast.
  * Como último recurso, use o modo **"Informar URL manualmente"**.
* **"Dispositivo não suporta AVTransport nem ContentDirectory"** — a URL
  aponta para um UPnP que não é DLNA (ex.: um Internet Gateway Device).
* **Comando funciona mas o estado demora para atualizar** — polling de 10s;
  comandos acionados pelo Portal atualizam otimisticamente.
* **"Comando DLNA desconhecido"** — o device recusou uma ação opcional do
  spec (comum em TVs com stack UPnP incompleto). Previous/next em alguns
  renderers só funcionam durante playback de playlist/queue.
* **Arte da capa (`entity_picture`) não aparece** — depende do DMR expor
  `upnp:albumArtURI` no `TrackMetaData`. Nem todos expõem.
* **DMS retorna "0 resultados" na busca** — o servidor pode não implementar a
  ação `Search` (opcional no UPnP ContentDirectory). O browse manual
  continua funcionando.

## Referência

* Spec UPnP Device Architecture 1.1 — [https://openconnectivity.org/upnp-specs/](https://openconnectivity.org/upnp-specs/)
* Spec UPnP AVTransport / ContentDirectory / RenderingControl — mesmos links
  no OpenConnectivity.
* DLNA Guidelines — perfis de mídia (audio, video, image) e matriz de
  compatibilidade entre DMR e DMS.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.