Socket de controle e comandos

O veil daemon escuta em um socket Unix. Todo outro comando veil que fala com o daemon (veil set, veil status, ...) é um cliente desse socket, e qualquer outro programa também pode ser: uma barra de status, um script, um atalho de teclado, um programa em outra linguagem. Esta página é a referência do protocolo (o socket, o formato de transmissão, cada comando, cada campo, cada resposta e cada código de erro) e do lado da linha de comando (qual comando envia o quê, o que imprime, seu código de saída).

O socket#

O socket é $XDG_RUNTIME_DIR/veil-$WAYLAND_DISPLAY.sock:

• XDG_RUNTIME_DIR deve estar definido como um caminho absoluto. Não há alternativa em um diretório compartilhado como /tmp, onde outro usuário poderia criar o socket primeiro; sem ele, todo comando veil falha (código de saída 1).
• Se WAYLAND_DISPLAY é um caminho (alguns compositores definem o caminho completo do seu socket), só o seu último componente é usado. Se não está definido, o nome é wayland-0.

Assim, um daemon executa por compositor, e um cliente alcança o daemon do compositor em que executa. Em um shell:

sock="$XDG_RUNTIME_DIR/veil-${WAYLAND_DISPLAY##*/}.sock"

Acesso:

• O arquivo do socket tem o modo 0600, e o daemon também verifica o id de usuário de cada cliente (SO_PEERCRED): um processo de outro usuário recebe a resposta forbidden e sua requisição não é lida. O veil faz o mesmo no sentido contrário e não envia requisições a um socket em que um processo de outro usuário escuta.
• Ao lado do socket fica o seu arquivo de lock, veil-$WAYLAND_DISPLAY.sock.lock. Um daemon mantém um lock sobre ele enquanto executa, e é assim que um segundo daemon sabe que já há um em execução (ele termina com código de saída 4). O arquivo de lock permanece quando o daemon termina; não o remova enquanto um daemon executa.
• O daemon remove o socket quando termina. Um daemon que foi morto o deixa para trás: a conexão é então recusada (ECONNREFUSED), o que o veil informa como "no daemon is running" (código de saída 3), e o próximo daemon remove o resto.

Conexões#

Uma conexão carrega uma requisição e uma resposta:

1. O cliente conecta e envia a requisição: um objeto JSON, em UTF-8, terminado por uma nova linha ou pelo fim do fluxo (o cliente encerra o seu lado de escrita). Espaços em branco ao redor do objeto são ignorados, então uma quebra de linha CRLF funciona.
2. O daemon lê até a primeira nova linha. Tudo depois dela é ignorado: uma segunda requisição na mesma conexão nunca é lida.
3. O daemon envia a resposta, um objeto JSON em uma linha terminada por uma nova linha, e fecha a conexão.

O socat faz tudo isso. (Os exemplos desta página foram enviados a um daemon em execução; só os caminhos, os nomes das saídas e números como o pid foram alterados.)

echo '{"cmd":"ping"}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"ok"}

A maioria das requisições é respondida de imediato. set e clear são respondidos quando o papel de parede está na tela, o que leva o tempo de carregar o arquivo (para um vídeo, até o primeiro quadro ser exibido); enquanto isso, o daemon continua atendendo outros clientes. Um cliente deve esperar pela resposta; o veil espera até 30 segundos. Se o cliente vai embora antes da resposta, a requisição ainda é executada.

Limites#

As respostas timeout, too_large, busy e forbidden vêm do transporte do daemon, antes de a requisição ser lida ou analisada; a conexão é fechada logo depois delas. Um cliente que ainda está enviando quando sua requisição é recusada pode ver a conexão ser reiniciada depois da resposta (o socat imprime Connection reset by peer depois de um too_large).

Requisições#

Uma requisição é um objeto JSON cujo cmd nomeia o comando, com os campos do comando ao lado:

{"cmd":"set","output":"DP-3","input":"~/walls/sea.png","mode":"fit"}

• cmd é um dos comandos abaixo, em minúsculas.
• Um campo que o comando não aceita é recusado (invalid_request), inclusive para comandos que não aceitam campo algum: uma opção escrita errada nunca é ignorada em silêncio. Os campos podem vir em qualquer ordem.
• Um campo opcional pode ser omitido ou ser null; ambos significam o padrão.
• output nomeia uma saída (monitor) como o compositor a nomeia, como DP-3 ou HDMI-A-1 (veil outputs as lista). Não pode ser vazio. Sem ele, um comando vale para todas as saídas em que o daemon desenha, inclusive saídas desconectadas no momento (o daemon mantém o papel de parede delas para quando voltarem). Uma saída é uma em que o daemon desenha se ele a viu desde que iniciou ou, quando o daemon foi iniciado com --output (ou outputs no arquivo de configuração), se ela é uma das saídas nomeadas ali, conectada ou não. Qualquer outro nome recebe a resposta unknown_output, com os nomes em que o daemon desenha na mensagem.
• Uma cor (bg_color) é uma string #rrggbb de seis dígitos hexadecimais; o # pode ser omitido e os dígitos podem ser maiúsculos ou minúsculos. As respostas sempre escrevem #rrggbb em minúsculas.
• Um caminho (input) é absoluto. O daemon executa em um diretório de trabalho próprio, então recusa um caminho relativo, e ~ não é expandido. veil set transforma um caminho relativo em absoluto antes de enviá-lo.

ping#

Sem campos. Respondido com ok de imediato: há um daemon em execução e seu loop de eventos não está travado.

set#

Exibe uma imagem ou um vídeo como o papel de parede de uma saída ou de todas as saídas.

O que acontece:

• O arquivo é verificado e decodificado fora do loop de eventos do daemon, uma única vez para todas as saídas da requisição. Uma requisição é carregada por vez; as outras esperam em ordem.
• A última requisição vence em cada saída. Uma requisição toma suas saídas de todo set ou clear anterior que ainda não foi exibido. Uma requisição anterior que não tem mais saída alguma recebe a resposta superseded de imediato e nunca é exibida; uma que mantém algumas saídas (um set para todas as saídas seguido de um para uma única saída) é exibida nas saídas que manteve.
• A resposta é ok quando o papel de parede está em todas as saídas a que se destina: uma imagem quando é desenhada, um vídeo quando seu primeiro quadro está na tela, e em ambos os casos não antes de o vídeo que ele substitui ter saído. Uma saída desconectada, ou cujo vídeo é interrompido porque o compositor não o exibe (released), guarda o papel de parede para depois, e essa parte é concluída de imediato.
• Sem output, um papel de parede que foi exibido passa a ser o padrão: as saídas conectadas depois também o exibem, a menos que tenham um próprio.
• A menos que persist seja false, o papel de parede de cada saída é salvo em $XDG_STATE_HOME/veil/state.json, e um daemon iniciado sem --input o exibe de novo.

Erros:

• O próprio arquivo (não existe, não é um arquivo regular, está vazio, não pode ser lido, não é uma imagem nem um vídeo que o veil conheça, ou não pode ser decodificado): nada muda em nenhuma saída, e o código diz por quê: not_found, unsupported_media ou failed para os demais.
• Uma saída em que o papel de parede não pode ser exibido (um vídeo que falha ao iniciar ali): essa saída mantém o que exibia, as outras exibem o novo papel de parede, e a resposta é failed. Quando a requisição era para várias saídas, a mensagem nomeia as saídas que falharam (DP-3: <reason>; HDMI-A-1: <reason>), a menos que todas tenham falhado pelo mesmo motivo.
• Nenhuma saída onde exibi-lo (um daemon sem saídas, um set sem output): failed.

echo '{"cmd":"set","input":"~/walls/sea.png"}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"ok"}
echo '{"cmd":"set","output":"HDMI-A-1","input":"~/walls/sea.png","mode":"fit","bg_color":"#202020"}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"ok"}
echo '{"cmd":"set","output":"DP-3","input":"~/walls/waves.webm","persist":false}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"ok"}
echo '{"cmd":"set","input":"~/walls/missing.png"}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"error","code":"not_found","message":"Failed to resolve path '~/walls/missing.png': No such file or directory (os error 2)"}
echo '{"cmd":"set","input":"~/notes.txt"}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"error","code":"unsupported_media","message":"'~/notes.txt' is neither an image nor a video that veil recognises, by its content or by its extension"}
echo '{"cmd":"set","output":"DP-9","input":"~/walls/sea.png"}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"error","code":"unknown_output","message":"output 'DP-9' is not driven by this daemon; it draws on DP-3, HDMI-A-1"}
echo '{"cmd":"set","input":"walls/sea.png"}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"error","code":"invalid_request","message":"input must be an absolute path, got 'walls/sea.png'"}
echo '{"cmd":"set","input":"~/walls/sea.png","mode":"zoom"}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"error","code":"invalid_request","message":"invalid request: unknown variant `zoom`, expected one of `fill`, `fit`, `stretch`, `center`, `tile`"}

Um set que um mais novo substituiu, enviado enquanto um vídeo ainda carregava:

echo '{"cmd":"set","input":"~/walls/waves.webm"}' | socat - UNIX-CONNECT:"$sock" &
echo '{"cmd":"set","input":"~/walls/sea.png"}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"error","code":"superseded","message":"replaced by a newer `veil set` before it was shown"}
# {"version":1,"status":"ok"}

clear#

Exibe apenas uma cor e solta o arquivo do papel de parede (veil clear). É um set sem arquivo: passa pela mesma fila (o último set ou clear vence em cada saída), é respondido quando a cor está na tela, passa a ser o padrão sem output e é salvo a menos que persist seja false, de modo que um daemon reiniciado exibe a cor também.

echo '{"cmd":"clear","output":"HDMI-A-1","bg_color":"#102030","persist":false}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"ok"}

pause#

Pausa o papel de parede em vídeo de uma saída ou de todas as saídas até o resume, seja o que for que esteja na tela (veil pause). Respondido com ok de imediato.

Um vídeo pausado mantém o quadro na tela e não decodifica nada. O daemon também pausa um vídeo por conta própria quando o compositor o oculta (--pause-on); os dois se somam, e um vídeo só é reproduzido quando nenhum dos dois o segura. Um papel de parede definido em uma saída pausada começa pausado. As imagens não têm o que pausar, mas são seguradas do mesmo modo (paused_by_user em status). Uma pausa não é salva, e uma saída conectada depois não é pausada.

echo '{"cmd":"pause","output":"DP-3"}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"ok"}

resume#

Encerra um pause (veil resume). Respondido com ok de imediato. Um vídeo que o compositor oculta continua pausado até voltar a ser exibido.

echo '{"cmd":"resume"}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"ok"}

toggle#

resume se todas as saídas a que se destina estão pausadas por pause; caso contrário, pause (em todas elas, de modo que um atalho de teclado transforma um estado misto em pausado). Respondido de imediato, com um resultado Toggled que diz qual dos dois fez.

echo '{"cmd":"toggle"}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"ok","result":{"paused":true}}
echo '{"cmd":"toggle"}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"ok","result":{"paused":false}}

status#

Sem campos. Respondido de imediato, com um resultado Status: o daemon, seu papel de parede padrão e todas as saídas em que ele desenha, inclusive as que não estão conectadas. veil status --json imprime esse resultado.

echo '{"cmd":"status"}' | socat - UNIX-CONNECT:"$sock"

A resposta, em uma linha (espalhada aqui):

{
  "version": 1,
  "status": "ok",
  "result": {
    "default": {"bg_color": "#000000", "input": "~/walls/sea.png", "mode": "fill"},
    "outputs": [
      {
        "connected": true,
        "hidden": false,
        "kind": "video",
        "name": "DP-3",
        "next": null,
        "paused_by_user": false,
        "scale": 1.0,
        "size": {"height": 1080, "width": 1920},
        "state": "playing",
        "video": {"dropped": 0, "fps": 30.0, "rendered": 41, "size": {"height": 720, "width": 1280}},
        "wallpaper": {"bg_color": "#000000", "input": "~/walls/waves.webm", "mode": "fill"}
      },
      {
        "connected": true,
        "hidden": false,
        "kind": "image",
        "name": "HDMI-A-1",
        "next": null,
        "paused_by_user": false,
        "scale": 1.0,
        "size": {"height": 1080, "width": 1920},
        "state": "shown",
        "video": null,
        "wallpaper": {"bg_color": "#202020", "input": "~/walls/sea.png", "mode": "fit"}
      }
    ],
    "pause_on": "fullscreen",
    "pid": 4242,
    "uptime_secs": 7385,
    "version": "1.0.0-beta.1"
  }
}

outputs#

Sem campos. Respondido de imediato, com um resultado OutputList: as saídas que o compositor anunciou, se o daemon desenha nelas e, depois, as saídas que o daemon aguarda. veil outputs --json imprime esse resultado.

echo '{"cmd":"outputs"}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"ok","result":{"outputs":[{"connected":true,"description":"Dell Inc. DELL U2720Q 1A2B3C4D","name":"DP-3","wallpaper":true},{"connected":true,"description":"Samsung Electric Company C24F390 HTQH600000","name":"HDMI-A-1","wallpaper":true}]}}

quit#

Sem campos. Encerra o daemon como o SIGTERM: ele responde ok primeiro; depois o daemon desmonta seus papéis de parede e termina com código de saída 0. O socket desaparece quando o daemon termina; veil quit espera por isso, então veil quit && veil daemon funciona. Sob a unidade do systemd, pare o serviço em vez disso (systemctl --user stop veil).

echo '{"cmd":"quit"}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"ok"}

Requisições recusadas#

echo '{"cmd":"explode"}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"error","code":"invalid_request","message":"invalid request: unknown variant `explode`, expected one of `set`, `clear`, `pause`, `resume`, `toggle`, `status`, `outputs`, `quit`, `ping` at line 1 column 16"}
echo '{"cmd":"status","output":"DP-3"}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"error","code":"invalid_request","message":"invalid request: unknown field `output`, there are no fields"}
echo '{"cmd":"set","input":"~/walls/sea.png","colour":"red"}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"error","code":"invalid_request","message":"invalid request: unknown field `colour`, expected one of `output`, `input`, `mode`, `bg_color`, `persist`"}
echo '{"cmd":"clear","bg_color":"red"}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"error","code":"invalid_request","message":"invalid request: invalid colour 'red': expected #rrggbb"}
echo '{"cmd":"pause","output":""}' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"error","code":"invalid_request","message":"output must not be empty"}
echo 'not json' | socat - UNIX-CONNECT:"$sock"
# {"version":1,"status":"error","code":"invalid_request","message":"invalid request: expected ident at line 1 column 2"}

Respostas#

Uma resposta é ok, com um result para os comandos que informam alguma coisa:

{"version":1,"status":"ok","result":{"paused":true}}

ou um erro, com um código para programas e uma mensagem para pessoas:

{"version":1,"status":"error","code":"unknown_output","message":"output 'DP-9' is not driven by this daemon; it draws on DP-3, HDMI-A-1"}

Campos#

A ordem das chaves não significa nada (hoje, as chaves de um result vêm em ordem alfabética).

Códigos de erro#

Resultados#

Todo campo de um resultado está sempre presente, null quando não há nada a dizer, de modo que um programa não precisa distinguir uma chave ausente de uma vazia.

Status#

O resultado de status.

OutputStatus#

Uma saída em um Status.

WallpaperInfo#

Um papel de parede: um arquivo ou apenas uma cor.

VideoInfo#

O fluxo de um vídeo e o que o compositor fez com seus quadros.

Size#

OutputList#

O resultado de outputs.

OutputInfo#

Toggled#

O resultado de toggle.

Valores#

state#

Em que ponto está o papel de parede de uma saída (OutputStatus.state).

kind#

O que uma saída exibe (OutputStatus.kind).

mode#

Como um papel de parede é ajustado à sua saída (set, WallpaperInfo.mode).

pause_on#

Quando o daemon pausa um vídeo porque o compositor o oculta (Status.pause_on, o --pause-on do daemon). Exige um compositor cujo IPC o veil acompanhe (Hyprland, sway); nos demais, os vídeos sempre são reproduzidos.

Compatibilidade#

• Novos comandos, campos, campos de resultado, códigos de erro e valores são acrescentados sem mudar version. Os campos nunca são renomeados nem removidos. version só é incrementada para uma mudança que um par da versão anterior leria errado.
• Um cliente deve ignorar os campos de resultado que não conhece, tratar um código de erro que não conhece como failed, e um state ou kind que não conhece como desconhecido. O próprio veil faz assim.
• Um daemon mais antigo que um comando o responde com invalid_request, com unknown variant na mensagem; um mais antigo que um campo, com unknown field. O veil então diz que o daemon é mais antigo que o cliente e deve ser reiniciado.
• Uma resposta sem version vem de um daemon mais antigo que o campo.

Os comandos do veil#

Os comandos do veil são os clientes acima, mais alguns que não precisam de daemon. Cada opção é descrita em veil <command> --help e nas páginas de manual (man veil, man veil-set, ...), que o binário gera a partir das mesmas definições.

Comandos#

veil status sem --json:

veil 1.0.0-beta.1 (pid 4242), running for 2h 03m; videos pause on: fullscreen
default: ~/walls/sea.png (fill, #000000)
DP-3: playing ~/walls/waves.webm (fill, #000000); 1920x1080 at scale 1; video 1280x720, 30 fps, 41 frames shown, 0 dropped
HDMI-A-1: showing ~/walls/sea.png (fit, #202020); 1920x1080 at scale 1

O texto é para pessoas e pode mudar; os scripts usam --json, cujos campos são descritos em Resultados. Por exemplo, com jq:

veil status --json | jq -r '.outputs[] | "\(.name): \(.state)"'

Um comando que falha imprime seu erro no stderr. veil set, clear, pause, resume, toggle e quit também emitem uma notificação de desktop quando falham, já que costumam ser executados a partir de um atalho de teclado, onde ninguém vê o stderr; status, outputs e ping nunca emitem (uma barra de status pode perguntar a cada segundo enquanto nenhum daemon executa), e um set ou clear que foi superseded também não (o mais novo está na tela).

Códigos de saída#

Estes são estáveis: scripts podem confiar neles.