For the complete documentation index, see llms.txt. This page is also available as Markdown.

Reprodução de Vídeo

Transmita vídeo para uma scene

Existem três formas diferentes de apresentar um vídeo numa cena:

  • Carregar um ficheiro de vídeo como parte do conteúdo da cena

  • Transmitir o vídeo a partir de uma fonte externa

  • Transmitir em direto através do Decentraland Cast

💡 Dica: no Scene Editor no Creator Hub, pode usar um Video Player Smart Item para o fazer sem escrever código.

Em todos os casos, vai precisar de:

  • Uma entidade com uma forma primitiva como um plano, um cubo ou até mesmo um cone.

  • Um Material com uma VideoTexture atribuída à respetiva textura

  • Um VideoPlayer Component para controlar o estado do vídeo.

Considerações de desempenho

Tenha em conta que a transmissão de vídeo exige um esforço significativo da máquina do jogador. Recomenda-se evitar a reprodução de mais de um vídeo de cada vez.

Se estiverem a ser reproduzidos demasiados vídeos ao mesmo tempo na sua cena, alguns serão pausados pelo Engine. A prioridade de pausa de um ecrã é determinada com base em vários fatores, incluindo a proximidade do jogador, o tamanho e se o ecrã está no campo de visão do jogador. O número máximo de vídeos simultâneos depende das definições de qualidade do jogador.

  • Baixa: 1

  • Média: 5

  • Alta: 10

Também recomendamos que o vídeo comece a ser reproduzido quando o jogador estiver por perto ou realizar uma ação para o iniciar. Começar a reproduzir um vídeo quando a sua cena é carregada muito longe, no horizonte, afetará desnecessariamente o desempenho enquanto os jogadores visitam cenas vizinhas.

Evite também transmitir vídeos com uma resolução muito alta. Não utilize nada acima de HD.

Também é ideal reproduzir vídeos em Materials Basic (sem iluminação) para reduzir o impacto no desempenho, como acontece em todos os exemplos de código abaixo.

Apresentar um vídeo

As instruções seguintes aplicam-se às três opções para apresentar vídeos:

  1. Crie uma entidade que servirá de ecrã de vídeo. Adicione a esta entidade um Component MeshRenderer para que tenha uma forma visível.

  2. Crie um Component VideoPlayer que faça referência a um URL de transmissão ou ao caminho para um ficheiro de vídeo. Aqui também pode definir o estado playing do vídeo e o respetivo volume. Este Component pode ser atribuído à entidade do ecrã de vídeo ou a qualquer outra entidade da cena.

  3. Crie um objeto VideoTexture e, na respetiva propriedade videoPlayerEntity atribua a entidade que contém o Component VideoPlayer .

  4. Crie um Material, atribua-o à entidade do ecrã e defina a respetiva propriedade texture para o VideoTexture que criou.

Este exemplo usa um vídeo armazenado localmente numa /videos pasta do projeto da cena:

Para usar um vídeo de um URL de streaming externo, altere o passo 2 para que a src propriedade no componente VideoPlayer aponte para o URL de streaming.

Consulte Transmissão em direto para saber como utilizar este terceiro método alternativo.

Sobre o streaming externo

A origem do streaming tem de ser um URL https (http não são suportados).

Deverá ser possível colar um URL que aponte para um vídeo na maioria dos sites populares de streaming de vídeo. Tenha em atenção os termos de serviço destas plataformas.

Para transmitir um ficheiro de vídeo que tem no seu computador, a forma mais fácil é carregá-lo para uma conta pública do Google Drive e colar o link.

Outra opção é utilizar um fornecedor de alojamento gerido, como Vimeo , Livepeer Studio ou Serraform onde paga uma taxa ao fornecedor para gerir toda a infraestrutura de streaming.

A opção mais avançada é configurar o seu próprio servidor, utilizando software gratuito e pagando pelo alojamento numa plataforma como Digital Ocean ou Cloudflare. Pode implementar algo como o Node Media Server, que oferece, logo à partida, a maior parte do que precisa.

Todas estas opções têm vantagens e desvantagens, consoante o cenário. Deve avaliar qual é a melhor para si, tendo em conta as suas necessidades, competências técnicas e orçamento.

Configurar o OBS para transmitir com sucesso

OBS é uma ferramenta popular e gratuita para gerir as suas transmissões.

Quer esteja a utilizar uma chave de transmissão de um espaço ou o seu próprio servidor RTMP, as definições do OBS são importantes para o sucesso da sua transmissão. Procure garantir uma ligação estável e consistente.

Configuração simples do OBS

Recomenda-se a seguinte configuração simples:

  • Taxa de bits: 2500 kbps (compatível com todos os espaços do Decentraland)

  • Taxa de bits do áudio: 160 kbps

  • Predefinição do codificador de vídeo: Hardware NVENC

  • Codificador de áudio: AAC

  • Resolução máxima: 720 (qualquer valor superior causa problemas no DCL)

  • Taxa de fotogramas: 30 fps

Conselhos para quem está a começar a fazer transmissões

  • É essencial fazer testes de áudio com antecedência para testar a configuração no espaço.

  • Pequenos erros, como um algarismo errado na chave de transmissão, são os que mais provavelmente vão comprometer a transmissão.

  • Não ultrapasse a resolução de 720 nem uma taxa de bits de 2500 kbps.

Transmissão em direto

Pode fazer uma transmissão em direto a partir da sua câmara ou partilhar o ecrã através da funcionalidade Live streaming do smart item Admin tools .

Este método de transmissão usa a mesma arquitetura de comunicações que permite as comunicações em direto entre jogadores. É fácil de configurar e tem muito menos atraso do que a transmissão a partir de fontes externas.

  1. Adicione um smart item Admin tools à sua cena, bem como um smart item Video player .

  2. Publique a sua cena, num World ou em Genesis City.

  3. Entre na cena como jogador com permissão para usar o Admin tools.

  4. Abra a consola Admin, selecione o separador Video , depois selecione a funcionalidade Live e clique no botão Get Stream Key .

  5. Copie o Server URL e a Streaming key* para o seu software de transmissão (por exemplo, OBS).

  6. Prima o botão Activate para iniciar a transmissão.

Em vez de adicionar um smart item Video player à sua cena, também pode usar o URL livekit-video://current-stream como fonte de vídeo para reproduzir a transmissão na sua cena. Continua a precisar do Admin tools para obter a chave de transmissão.

Materiais de vídeo

Na maioria dos casos, vai querer reproduzir vídeos num material Basicsem iluminação, em vez de um material PBR. Isto resulta numa imagem muito mais brilhante e nítida e melhora o desempenho.

Geralmente, recomenda-se reproduzir vídeos em materiais Basic sem iluminação, pois isso melhora o desempenho. No entanto, se quiser projetar um vídeo num material PBR, tenha em conta que as propriedades predefinidas fazem com que o vídeo pareça bastante opaco. Pode melhorar este aspeto alterando outras propriedades do material. Eis algumas definições recomendadas para dar mais destaque ao vídeo:

💡 Dica: Como o vídeo é uma textura adicionada a um Material, também pode experimentar outras propriedades dos Materials, como aplicar-lhe uma tonalidade ou adicionar outras camadas de textura, por exemplo, para produzir um efeito de ecrã sujo.

Consulte materials para obter mais detalhes.

Sobre ficheiros de vídeo

São suportados os seguintes formatos de ficheiro:

  • .mp4

  • .ogg

  • .webm

Tenha em atenção que um ficheiro de vídeo aumenta o tamanho total da Scene, o que faz com que esta demore mais tempo a ser transferida para os jogadores que entram na sua Scene. O tamanho do vídeo também pode fazer com que ultrapasse as limitações da Scene, uma vez que tem um máximo de 15 MB por parcela. Recomendamos comprimir o vídeo tanto quanto possível, para minimizar este problema.

Também recomendamos que comece a reproduzir o vídeo quando o jogador estiver por perto ou realizar uma ação que o acione. Começar a reproduzir um vídeo quando a sua cena é carregada longe, no horizonte, afetará desnecessariamente o desempenho enquanto os jogadores visitam cenas vizinhas.

Iniciar, pausar e parar um vídeo

Para começar a reproduzir o vídeo ou pausá-lo, defina a propriedade playing como true ou false. Se playing estiver definida como false, o vídeo é pausado no último fotograma apresentado.

Pode tornar um ecrã alternável adicionando-lhe um evento de ponteiro, como mostrado abaixo:

Para parar o vídeo e voltar ao primeiro fotograma, defina a propriedade position como 0. No exemplo seguinte, clicar no vídeo para-o.

Configurar o leitor de vídeo

As seguintes propriedades opcionais estão disponíveis para definir no componente VideoPlayer :

  • playing: Determina se o vídeo está a ser reproduzido. Se for false, o vídeo fica pausado.

  • playbackRate: Altera a velocidade de reprodução do vídeo. 1 por predefinição.

  • volume: Permite alterar o volume do áudio. 1 por predefinição.

  • position: Permite definir uma posição inicial diferente no vídeo. É expressa em segundos desde o início original do vídeo. 0 por predefinição, o que faz com que comece no início efetivo do vídeo.

  • loop: Booleano que determina se o vídeo é reproduzido continuamente em loop ou se para depois de ser reproduzido uma vez. false por predefinição.

Reproduzir vários vídeos

Para evitar problemas de desempenho, mantenha reduzido o número de vídeos diferentes reproduzidos em simultâneo; o motor só permite um número limitado de vídeos simultâneos, dependendo das definições de qualidade do jogador (consulte Considerações sobre o desempenho). No entanto, uma cena pode reproduzir várias cópias da mesma textura de vídeo em vários ecrãs diferentes. Isto não é restringido, pois tem um impacto consideravelmente menor no desempenho do que reproduzir vídeos separados. Para reproduzir o mesmo vídeo em várias entidades, basta atribuir a mesma instância do objeto de textura de vídeo aos componentes Material de cada entidade de ecrã.

Note que, no exemplo acima, só é necessário criar um componente VideoPlayer , que controla o estado de ambos os ecrãs de vídeo. Neste caso, o componente é atribuído à entidade screen1 , mas também poderia ser atribuído a qualquer outra entidade da cena, não necessariamente a um dos ecrãs.

Eventos de vídeo

Trate facilmente as alterações de estado de um vídeo, respondendo, por exemplo, ao início da reprodução ou à pausa. Isto pode ser utilizado, por exemplo, para reproduzir animações em perfeita sincronização com um vídeo, garantindo que começam ao mesmo tempo que o vídeo.

Utilize videoEventsSystem.registerVideoEventsEntity para definir uma função que é executada sempre que o estado do vídeo atribuído a uma entidade muda. Sempre que o estado muda, a função pode verificar o novo estado e responder em conformidade.

O objeto videoEvent passado como entrada para a função contém as seguintes propriedades:

  • currentOffset (número): O valor atual da position propriedade no vídeo. Este valor indica os segundos decorridos desde o início original do vídeo. -1 se o vídeo ainda não tiver começado a ser reproduzido.

  • state: O novo estado do vídeo, expresso como um valor do VideoState enum. Este enum pode ter os seguintes valores:

    • VideoState.VS_READY

    • VideoState.VS_NONE

    • VideoState.VS_ERROR

    • VideoState.VS_SEEKING

    • VideoState.VS_LOADING

    • VideoState.VS_BUFFERING

    • VideoState.VS_PLAYING

    • VideoState.VS_PAUSED

  • videoLength (número ): A duração total do vídeo em segundos. -1 se a duração for desconhecida.

  • timestamp ( número): Um lamport timestamp que é incrementado sempre que o estado do vídeo muda.

  • tickNumber (número): O momento em que o evento ocorreu, expresso como a contagem de ticks desde que a cena começou a ser executada.

Se voltar a registar um callback numa Entity que já tenha um (por exemplo, para alterar o que acontece quando o estado muda), o novo callback substitui o anterior e o último estado comunicado é preservado. Isto significa que o novo callback não é chamado novamente para um estado que já tenha sido comunicado ao callback anterior.

Verificar se uma Entity está registada

Use videoEventsSystem.hasVideoEventsEntity() para verificar se uma Entity já tem um callback de eventos de vídeo registado.

Evento de vídeo mais recente

Consulte a última alteração de estado de um vídeo usando videoEventsSystem.getVideoState(). Isso retorna o valor mais recente de VideoEvent para a entidade, ou undefined se nenhum evento tiver sido reportado ainda. Você pode chamar isso em um sistema para verificar o estado do vídeo a cada frame sem registrar um callback.

Máscaras alfa em vídeos

Um truque interessante para criar telas de vídeo não retangulares é aplicar uma textura alfa sobre um plano. Você pode recortar parte do plano no formato que quiser.

Use a imagem a seguir para recortar o vídeo em formato circular, com cantos transparentes.




Reproduzir um vídeo em um modelo glTF

Você pode reproduzir um vídeo em um modelo glTF usando o componente GltfNodeModifiers . Consulte Modificar materiais glTF para saber mais.

Isso permite reproduzir vídeos em qualquer formato, não apenas em planos. Por exemplo, você pode reproduzir vídeos em uma tela curva ou até mesmo no corpo inteiro de um NPC.

O mapeamento do vídeo seguirá o mapeamento UV original usado pelo modelo. Isso significa que, se o modelo tiver uma textura mapeada para uma parte específica, o vídeo será mapeado para essa mesma parte.

Você também pode usar o componente GltfNodeModifiers para reproduzir um vídeo apenas em uma malha específica dentro do modelo. Por exemplo, você pode reproduzi-lo em uma parede específica de um edifício, mesmo que o modelo abranja o edifício inteiro. Consulte Modificar materiais glTF para saber mais.

Áudio espacial

Por padrão, o vídeo de um componente VideoPlayer tem áudio global, o que significa que será ouvido com volume constante em toda a cena. Se um jogador sair da cena, não ouvirá o streaming.

Para tornar o áudio espacial, defina a propriedade spatial como true.

Agora, o vídeo será ouvido a partir da posição da entidade que possui o VideoPlayer componente, e ficará mais alto à medida que o jogador se aproximar dele.

Controle o áudio espacial com as seguintes propriedades:

  • spatialMinDistance: a distância mínima a partir da qual o áudio se torna espacial. Se o jogador estiver mais perto, o áudio será ouvido no volume máximo. 0 por predefinição.

  • spatialMaxDistance: a distância máxima a partir da qual o áudio é ouvido. Se o jogador estiver mais longe, o áudio será ouvido com volume 0. 60 por predefinição

Análise de áudio

Pode ler dados de amplitude e frequência em tempo real da faixa de áudio de uma entidade VideoPlayer para controlar elementos visuais reativos que se sincronizam com a banda sonora do vídeo. Consulte Análise de áudio.

💡 Sugestão: Para ver um vídeo reproduzido num modelo GLTF em vez de num elemento primitivo, consulte a cena de teste 74,-8-gltfnodemodifier , que reproduz uma stream HLS em nós GLTF específicos utilizando GltfNodeModifiers texturas de vídeo.

Atualizado