Reprodução de Vídeo

Transmitir vídeo em uma cena

Existem três maneiras diferentes de mostrar um vídeo em uma cena:

• Enviar um arquivo de vídeo como parte do conteúdo da cena

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

• Transmitir ao vivo via Decentraland cast

💡 Tip: No Scene Editor in Creator Hub, você pode usar um Video Player Smart Item para uma maneira sem código de conseguir isso.

Em todos os casos, você precisará:

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

• A material com um VideoTexture atribuído à sua textura

• A VideoPlayer componente para controlar o estado do vídeo.

Considerações de desempenho

Tenha em mente que transmitir vídeo exige um esforço significativo da máquina do jogador. Recomenda-se evitar reproduzir mais de um vídeo por vez.

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

• Baixa: 1

• Média: 5

• Alta: 10

Também recomendamos começar a reproduzir o vídeo quando o jogador estiver próximo ou executar uma ação para isso. Começar a reproduzir um vídeo quando sua cena é carregada à distância afetará desnecessariamente o desempenho enquanto jogadores visitam cenas vizinhas.

Também evite transmitir vídeos em resolução muito alta. Não use nada acima de HD.

Também é ideal reproduzir vídeos em materiais Basic (sem iluminação), para reduzir a carga de desempenho, como é o caso em todos os trechos de exemplo abaixo.

Mostrar um vídeo

As instruções a seguir se aplicam às três opções de exibição de vídeo:

1. Crie uma entidade para servir como tela de vídeo. Dê a essa entidade um MeshRenderer componente para que ela tenha uma forma visível.

2. Criar um VideoPlayer componente, referenciando uma URL de streaming ou um caminho para um arquivo de vídeo. Aqui você também pode definir o playing estado do vídeo e seu volume. Esse componente pode ser atribuído à entidade da tela de vídeo ou a qualquer outra entidade na cena.

3. Criar um VideoTexture objeto, e em seu videoPlayerEntity propriedade atribua a entidade que possui o VideoPlayer component.

4. Criar um Material, atribua-o à entidade da tela e defina seu textura até VideoTexture que você criou.

Este exemplo usa um vídeo que está armazenado localmente em uma pasta /videos no projeto da cena:

// #1
const screen = engine.addEntity()
MeshRenderer.setPlane(screen)
Transform.create(screen, { position: { x: 4, y: 1, z: 4 } })

// #2
VideoPlayer.create(screen, {
	src: 'videos/myVideo.mp4',
	playing: true,
})

// #3
const videoTexture = Material.Texture.Video({ videoPlayerEntity: screen })

// #4
Material.setBasicMaterial(screen, {
	texture: videoTexture,
})

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

// #2
VideoPlayer.create(screen, {
	src: 'https://player.vimeo.com/external/552481870.m3u8?s=c312c8533f97e808fccc92b0510b085c8122a875',
	playing: true,
})

Veja Streaming usando Decentraland cast para detalhes sobre como usar este terceiro método alternativo.

Sobre Streaming Externo

A fonte da transmissão deve ser uma https URL (http URLs não são suportadas), e a fonte deve ter políticas CORS (Cross Origin Resource Sharing) que permitam acesso externo. Se este não for o caso, pode ser necessário configurar um servidor para agir como proxy e expor a transmissão de forma válida.

Existem várias opções para transmitir vídeo. A opção mais simples é usar um provedor de hospedagem gerenciado como Vimeo , Livepeer Studio ou Serraform onde você paga uma taxa ao provedor para gerenciar toda a infraestrutura de streaming.

A outra alternativa recomendada é configurar seu próprio servidor, usando software gratuito mas pagando pela hospedagem em uma plataforma como Digital Ocean ou Cloudflare. Você pode implantar algo como um Node Media Server, que fornece a maioria do que você precisa pronto para uso.

Todas essas opções têm prós e contras para diferentes cenários. Você deve avaliar o que é melhor para você levando em conta suas necessidades, habilidades técnicas e orçamento.

Configurando o OBS para streaming bem-sucedido

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

Quer você esteja usando a chave de stream de um local ou seu próprio servidor RTMP, suas configurações no OBS são importantes para o sucesso da sua transmissão. Você deve buscar uma conexão sólida e consistente.

Configuração simples do OBS

A seguinte configuração simples é recomendada:

• Taxa de bits 2500kbps (o que funcionará com todos os locais do Decentraland)

• Taxa de bits de áudio 160kbps

• Preset do codificador de vídeo: Hardware NVENC

• Codificador de áudio AAC

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

• Taxa de quadros 30fps

📔 Nota: Certifique-se de desabilitar Multitrack streaming no OBS. Você pode encontrar isso em Settings > Stream.

Conselhos para novos streamers

• Checagens de som antecipadas são essenciais para testar sua configuração com o local.

• Pequenos erros como um dígito errado na chave de transmissão são os mais prováveis de arruinar a transmissão.

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

Transmissão ao vivo

Você pode transmitir ao vivo da sua câmera ou compartilhar sua tela usando o recurso Transmissão ao vivo do Admin tools Reproduza um stream de áudio a partir de uma URL, usando o

Este método de transmissão usa a mesma arquitetura de comunicações usada para comunicações ao vivo entre jogadores. É fácil de configurar e tem muito menos atraso do que transmitir a partir de fontes externas.

1. Adicione um Admin tools smart item à sua cena, assim como um Video player Reproduza um stream de áudio a partir de uma URL, usando o

2. Publique sua cena, seja em um World ou em Genesis City.

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

4. Abra o console Admin, selecione a aba Video , então selecione a funcionalidade Live e clique no Get Stream Key botão.

5. Copie o Server URL e Streaming key* para o seu software de streaming (por exemplo OBS).

6. Pressione a Activate botão para começar a transmitir.

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

// #1
const screen = engine.addEntity()
MeshRenderer.setPlane(screen)
Transform.create(screen, { position: { x: 4, y: 1, z: 4 } })

// #2
VideoPlayer.create(screen, {
	src: `livekit-video://current-stream`,
	playing: true,
})

// #3
const videoTexture = Material.Texture.Video({ videoPlayerEntity: screen })

// #4
Material.setBasicMaterial(screen, {
	texture: videoTexture,
})

Materiais de Vídeo

Na maioria das vezes, você vai querer reproduzir vídeos em um material sem iluminação Basic material, em vez de um material PBR. Isso resulta em uma imagem muito mais brilhante e nítida e é melhor para desempenho.

Material.setBasicMaterial(screen, {
	texture: videoTexture,
})

Geralmente é recomendado reproduzir vídeos em materiais Basic sem iluminação, pois isso é melhor para o desempenho. No entanto, se você quiser projetar um vídeo em um material PBR, tenha em mente que as propriedades padrão fazem o vídeo parecer bastante opaco. Você pode melhorar isso alterando outras propriedades do material. Aqui estão algumas configurações recomendadas para fazer o vídeo se destacar mais:

Material.setPbrMaterial(screen, {
	texture: videoTexture,
	roughness: 1.0,
	specularIntensity: 0,
	metallic: 0,
	emissiveTexture: videoTexture,
	emissiveIntensity: 0.6,
	emissiveColor: Color3.White(),
})

💡 Tip: Como o vídeo é uma textura adicionada a um material, você também pode experimentar outras propriedades dos materiais, como tingi-lo com uma cor ou adicionar outras camadas de textura, por exemplo para produzir um efeito de tela suja.

Veja materials para mais detalhes.

Sobre Arquivos de Vídeo

Os seguintes formatos de arquivo são suportados:

• .mp4

• .ogg

• .webm

Tenha em mente que um arquivo de vídeo aumenta o tamanho total da cena, o que faz a cena demorar mais para ser baixada pelos jogadores que entram na sua cena. O tamanho do vídeo também pode fazer você ultrapassar o limite de limitações da cena, pois você tem um máximo de 15 MB por parcela para usar. Recomendamos comprimir o vídeo o máximo possível, para que seja menos problemático.

Também recomendamos começar a reproduzir o vídeo quando o jogador estiver por perto ou executar uma ação para dispará-lo. Começar a reproduzir um vídeo quando sua cena é carregada à distância afetará desnecessariamente o desempenho enquanto jogadores visitam cenas vizinhas.

Iniciar, pausar e parar um vídeo

Para começar a reproduzir o vídeo ou pausá-lo, defina o playing propriedade para true ou false. Se playing estiver definido como false, o vídeo fica pausado no último quadro exibido.

Você pode tornar uma tela alternável adicionando a ela um evento de ponteiro conforme mostrado abaixo:

pointerEventsSystem.onPointerDown(
	{
		entity: screen,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Play/Pause' },
	},
	function () {
		const videoPlayer = VideoPlayer.getMutable(screen)
		videoPlayer.playing = !videoPlayer.playing
	}
)

Para parar o vídeo e retorná-lo ao primeiro quadro, defina a propriedade position para 0. No exemplo a seguir, clicar no vídeo o para.

pointerEventsSystem.onPointerDown(
	{
		entity: screen,
		opts: { button: InputAction.IA_POINTER, hoverText: 'STOP' },
	},
	function () {
		const videoPlayer = VideoPlayer.getMutable(screen)
		videoPlayer.playing = false
		videoPlayer.position = 0
	}
)

Configurar o video player

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

• playing: Determina se o vídeo está atualmente sendo reproduzido. Se false, o vídeo está pausado.

📔 Nota: Só pode haver um VideoPlayer componente ativo por vez em cada cena.

• playbackRate: Altera a velocidade com que o vídeo é reproduzido. 1 por padrão.

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

• position: Permite definir uma posição inicial diferente no vídeo. É expresso em segundos a partir do início original do vídeo. -1 por padrão, o que faz começar no início real do vídeo.

• loop: Booleano que determina se o vídeo é reproduzido continuamente em loop ou se para após ser reproduzido uma vez. false por padrão.

Reproduzir múltiplos vídeos

Para evitar problemas de desempenho, cada cena só tem permissão para reproduzir uma textura de vídeo por vez. No entanto, uma cena pode reproduzir várias cópias da mesma textura de vídeo em várias telas diferentes. Isso não é restrito, pois impacta o desempenho consideravelmente menos do que reproduzir vídeos distintos. Para reproduzir o mesmo vídeo em múltiplas entidades, simplesmente atribua a mesma instância do objeto de textura de vídeo aos componentes Material de cada entidade tela.

// #1
const screen1 = engine.addEntity()
MeshRenderer.setPlane(screen1)
Transform.create(screen1, { position: { x: 4, y: 1, z: 4 } })

const screen2 = engine.addEntity()
MeshRenderer.setPlane(screen2)
Transform.create(screen2, { position: { x: 6, y: 1, z: 4 } })

// #2
VideoPlayer.create(screen1, {
	src: 'https://player.vimeo.com/external/552481870.m3u8?s=c312c8533f97e808fccc92b0510b085c8122a875',
	playing: true,
})

// #3
const videoTexture = Material.Texture.Video({ videoPlayerEntity: screen1 })

// #4
Material.setBasicMaterial(screen1, {
	texture: videoTexture,
})

Material.setBasicMaterial(screen2, {
	texture: videoTexture,
})

Observe que no exemplo acima, é necessário criar apenas um componente VideoPlayer que controla o estado de ambas as telas de vídeo. Nesse caso, o componente é atribuído à screen1 entidade, mas também poderia ser atribuído a qualquer outra entidade na cena, não necessariamente uma das telas.

Eventos de vídeo

Trate facilmente mudanças de estado em um vídeo, para responder quando um vídeo começa a reproduzir, é pausado, etc. Isso pode ser usado por exemplo para reproduzir animações em perfeita sincronia com um vídeo, garantindo que comecem ao mesmo tempo que o vídeo.

Use videoEventsSystem.registerVideoEventsEntity para definir uma função que é executada toda vez que o estado do vídeo atribuído a uma entidade muda. Toda vez que o estado muda, sua função pode verificar o novo estado e responder de acordo.

import {
	engine,
	Entity,
	VideoPlayer,
	videoEventsSystem,
	VideoState,
} from '@dcl/sdk/ecs'

// ... Crie videoPlayerEntity com o componente VideoPlayer, Transform, MeshRenderer.setPlane(), etc. ...

videoEventsSystem.registerVideoEventsEntity(
	videoPlayerEntity,
	function (videoEvent) {
		console.log(
			'evento de vídeo - estado: ' +
				videoEvent.state +
				'\noffset atual:' +
				videoEvent.currentOffset +
				'\ncomprimento do vídeo:' +
				videoEvent.videoLength
		)

		switch (videoEvent.state) {
			case VideoState.VS_READY:
				console.log('evento de vídeo - vídeo está READY')
				break
			case VideoState.VS_NONE:
				console.log('evento de vídeo - vídeo está em NO STATE')
				break
			case VideoState.VS_ERROR:
				console.log('evento de vídeo - vídeo ERROR')
				break
			case VideoState.VS_SEEKING:
				console.log('evento de vídeo - vídeo está SEEKING')
				break
			case VideoState.VS_LOADING:
				console.log('evento de vídeo - vídeo está LOADING')
				break
			case VideoState.VS_BUFFERING:
				console.log('evento de vídeo - vídeo está BUFFERING')
				break
			case VideoState.VS_PLAYING:
				console.log('evento de vídeo - vídeo começou a PLAYING')
				break
			case VideoState.VS_PAUSED:
				console.log('evento de vídeo - vídeo está PAUSED')
				break
		}
	}
)

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

• currentOffset (maxDistance): O valor atual da propriedade position . Esta propriedade mostra segundos após o começo original do vídeo. -1 por padrão, se o vídeo ainda não começou a reproduzir.

• state: O novo status do vídeo, expresso como um valor do VideoState . Este enum pode conter os seguintes valores possíveis:

  • 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 (maxDistance ): O comprimento em segundos de todo o vídeo. -1 se o comprimento for desconhecido.

• timeStamp ( maxDistance): Um lamport timestamp que é incrementado toda vez que o vídeo muda de estado.

• tickNumber (maxDistance): O tempo em que o evento ocorreu, expresso como contagem de ticks desde que a cena começou a rodar.

Último evento de vídeo

Consulte um vídeo para sua última alteração de estado usando videoEventsSystem.getVideoState(). Esta função sempre retorna o último VideoEvent valor para o vídeo.

function mySystem() {
    const latestVideoEvent = videoEventsSystem.getVideoState(videoPlayerEntity)
    if(!latestVideoEvent) return
    
    console.log(`state: ${latestVideoEvent.state}
    \ncurrentOffset: ${latestVideoEvent.currentOffset}
    \nvideoLength: ${latestVideoEvent.videoLength}`)
}

Máscaras alpha em vídeos

Um truque bacana para ter telas de vídeo não retangulares é aplicar uma textura alpha sobre um plano. Você pode recortar parte do plano na forma que desejar.

Use a imagem a seguir para cortar seu vídeo em uma forma circular, com cantos transparentes.

const videoTexture = Material.Texture.Video({
	videoPlayerEntity: screen,
})
const alphaMask = Material.Texture.Common({
	src: 'assets/scene/circle_mask.png',
	wrapMode: TextureWrapMode.TWM_MIRROR,
})

Material.setBasicMaterial(screen, {
	texture: videoTexture,
	alphaTexture: alphaMask,
})

📔 Nota: Em versões anteriores, a alphaTexture propriedade estava presente apenas em materiais PBR. Atualmente, ela só funciona em materiais basic.

Reproduzir um vídeo em um modelo glTF

Você pode reproduzir um vídeo em um arquivo glTF model por meio do uso do GltfNodeModifiers componente. Veja Modify glTF materials para mais detalhes.

Isto permite que você reproduza seus vídeos em qualquer forma, 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.

const myEntity = engine.addEntity()

GltfContainer.create(myEntity, {
  src: 'models/myModel.glb',
})

Transform.create(myEntity, {
  position: Vector3.create(4, 0, 4),
})

VideoPlayer.create(myEntity, {
	src: 'https://player.vimeo.com/external/552481870.m3u8?s=c312c8533f97e808fccc92b0510b085c8122a875',
	playing: true,
})

GltfNodeModifiers.create(
	myEntity,
	{
		modifiers: [{
			path: '',
			material: {
				material: {
					$case: 'pbr', pbr: {
						texture: Material.Texture.Video({
							videoPlayerEntity: myEntity,
						}),
					},
				},
			},
		}],
	})

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

Você também pode usar o GltfNodeModifiers componente 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. Veja Modify glTF materials para mais detalhes.

Áudio espacial

Por padrão, o áudio do vídeo de um VideoPlayer componente é global, significando que será ouvido com um volume consistente em toda a sua cena. Se um jogador sair da cena, ele não ouvirá a transmissão.

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

VideoPlayer.create(entity, {
	src: 'https://player.vimeo.com/progressive_redirect/playback/1145666916/rendition/540p/file.mp4%20%28540p%29.mp4?loc=external&signature=db1cd6946851313cb8f7be60d1f6c30af0902bcc46fdae0ba2a06e5fdf44c329',
	playing: true,
	spatial: true,
})

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

Controle o áudio espacial com as seguintes propriedades:

• spatialMinDistance: A distância mínima na qual o áudio se torna espacial. Se o jogador estiver mais próximo, o áudio será ouvido em volume total. 0 por padrão.

• spatialMaxDistance: A distância máxima na qual o áudio é ouvido. Se o jogador estiver mais distante, o áudio será ouvido em volume 0. 60 por padrão

const videoPlayerEntity = engine.addEntity();

Transform.create(videoPlayerEntity, {
    position: Vector3.create(8, 2, 8),
});

VideoPlayer.create(videoPlayerEntity, {
	src: 'https://player.vimeo.com/progressive_redirect/playback/1145666916/rendition/540p/file.mp4%20%28540p%29.mp4?loc=external&signature=db1cd6946851313cb8f7be60d1f6c30af0902bcc46fdae0ba2a06e5fdf44c329',
	playing: true,
	spatial: true,
	spatialMinDistance: 5,
	spatialMaxDistance: 10
});

MeshRenderer.setPlane(videoPlayerEntity)

Material.setBasicMaterial(videoPlayerEntity, {
texture: Material.Texture.Video({ videoPlayerEntity: videoPlayerEntity })
})

📔 Nota: Alguns formatos de vídeo não suportam áudio espacial. Certifique-se de que a transmissão esteja codificada em mp4, m4a, ou mov.