Reprodução de vídeo

Faça streaming de vídeo para uma scene

Existem três maneiras diferentes de mostrar um video em uma scene:

Fazer upload de um arquivo de video como parte do conteúdo da scene
Fazer stream do video a partir de uma fonte externa
Fazer stream ao vivo via Decentraland cast

💡 Dica: No Scene Editor no Creator Hub, você pode usar um Video Player Smart Item para uma forma sem código de fazer isso.

Em todos os casos, você vai precisar de:

Uma entity com uma forma primitiva como um plane, cube ou até mesmo um cone.
Um material com um VideoTexture atribuído à sua texture
Um VideoPlayer component para controlar o estado do video.

Considerações de desempenho

Tenha em mente que fazer streaming de video exige um esforço significativo da máquina do jogador. É recomendável evitar reproduzir mais de um video por vez.

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

Baixa: 1
Média: 5
Alta: 10

Também recomendamos iniciar a reprodução do video quando o jogador estiver próximo ou executar uma action para fazê-lo. Iniciar a reprodução de um video quando sua scene for carregada muito ao longe no horizonte afetará desnecessariamente o desempenho enquanto os jogadores visitam scenes vizinhas.

Evite também fazer streaming de videos em resolução muito alta. Não use nada acima de HD.

Também é ideal reproduzir videos em materiais Basic (unlit), para reduzir a carga de desempenho, como é o caso em todos os trechos de exemplo abaixo.

Mostrar um video

As instruções a seguir se aplicam a todas as três opções de exibição de video:

Crie uma entity para servir como a screen do video. Dê a essa entity um MeshRenderer component para que ela tenha uma forma visível.
Crie um VideoPlayer component, fazendo referência a uma URL de stream ou a um path para um arquivo de video. Aqui você também pode definir o playing estado e o volume do video. Esse component pode ser atribuído à entity da screen do video ou a qualquer outra entity na scene.
Crie um VideoTexture object, e em sua videoPlayerEntity property atribua a entity que possui o VideoPlayer component.
Crie um Material, atribua-o à entity da screen e defina sua texture para a VideoTexture que você criou.

Este exemplo usa um video armazenado localmente em uma /videos pasta no projeto da scene:

// #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 video de uma URL de streaming externa, altere o passo 2 para que a src property no VideoPlayer component referencie a URL de streaming.

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

Veja Streaming using Decentraland cast para detalhes sobre como usar esse terceiro método alternativo.

Sobre Streaming Externo

A fonte do streaming deve ser uma https URL (http URLs não são suportadas).

Você deve conseguir colar uma URL apontando para um video da maioria dos sites populares de streaming de video. Tenha atenção aos termos de serviço dessas plataformas.

Para fazer stream de um arquivo de video que você tem na sua máquina local, o caminho mais fácil é fazer upload desse video para um Google Drive público e colar o link.

Outra opção é usar um provedor de hospedagem gerenciada como Vimeo , Livepeer Studio ou Serraform onde você paga uma taxa ao provedor para gerenciar toda a infraestrutura de streaming.

A abordagem mais poderosa é configurar seu próprio server, 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 maior parte 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 um streaming bem-sucedido

OBS é uma ferramenta popular e gratuita para gerenciar seus streams.

Seja você usando a stream key de um local ou o seu próprio server RTMP, suas configurações no OBS são importantes para o sucesso do seu stream. Você deve buscar uma conexão sólida e consistente.

Configuração simples do OBS

A seguinte configuração simples é recomendada:

Bitrate 2500kbps (que funcionará com todos os locais Decentraland)
Audio bitrate 160kbps
Predefinição do video encoder: Hardware NVENC
Audio Encoder AAC
Resolução máxima: 720 (qualquer valor maior causa problemas no DCL)
Frame rate 30fps

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

Conselhos para novos streamers

As verificações de som iniciais são essenciais para testar sua configuração com o local.
Pequenos erros, como um dígito errado na stream key, são os mais prováveis de comprometer o stream.
Não ultrapasse a resolução 720 nem um bitrate de 2500 kbps.

Live streaming

Você pode fazer livestream pela sua câmera ou compartilhar sua tela usando o Live streaming feature do Admin tools smart item.

Este método de streaming usa a mesma arquitetura de comms usada para comunicações ao vivo entre jogadores. É fácil de configurar e tem muito menos delay do que fazer streaming de fontes externas.

Adicione um Admin tools smart item à sua scene, bem como um Video player smart item.
Publique sua scene, seja em um World ou em Genesis City.
Entre na scene como um jogador com permissão para usar o Admin tools.
Abra o Admin console, selecione a aba Video , depois selecione a funcionalidade Live e clique no botão Get Stream Key .
Copie o Server URL e Streaming key* para o seu software de streaming (por exemplo, OBS).
Pressione o botão Activate para iniciar o streaming.

Em vez de adicionar um smart item Video player à sua scene, você também pode usar a URL livekit-video://current-stream como fonte de video, para reproduzir o stream na sua scene. Você ainda precisará do Admin tools para obter a stream key.

// #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,
})

Video Materials

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

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

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

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

💡 Dica: Como o video é uma texture 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 Video

Os seguintes formatos de arquivo são suportados:

.mp4
.ogg
.webm

Tenha em mente que um arquivo de video aumenta o tamanho total da scene, o que faz a scene demorar mais para ser baixada pelos jogadores que entram na sua scene. O tamanho do video também pode fazer você ultrapassar as scene limitations, já que você tem no máximo 15 MB por parcel para usar. Recomendamos comprimir o video o máximo possível, para que isso seja menos problemático.

Também recomendamos iniciar a reprodução do video quando o jogador estiver por perto ou executar uma action para acioná-lo. Iniciar a reprodução de um video quando sua scene for carregada muito ao longe no horizonte afetará desnecessariamente o desempenho enquanto os jogadores visitam scenes vizinhas.

Iniciar, pausar e parar um video

Para iniciar a reprodução do video ou pausá-lo, defina a playing property para true ou false. Se playing for definido como false, o video fica pausado no último frame exibido.

Você pode tornar uma screen alternável adicionando um evento de pointer a ela, como 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 video e enviá-lo de volta ao primeiro frame, defina a position property para 0. No exemplo a seguir, clicar no video o interrompe.

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 properties opcionais estão disponíveis para definir no VideoPlayer component:

playing: Determina se o video está sendo reproduzido no momento. Se false, o video fica pausado.

📔 Nota: Só pode haver um VideoPlayer component ativo por vez em cada scene.

playbackRate: Altera a velocidade com que o video é reproduzido. 1 por padrão.
volume: Permite alterar o volume do audio. 1 por padrão.
position: Permite definir uma posição inicial diferente no video. Ela é expressa em segundos após o início original do video. -1 por padrão, o que faz com que ele comece no início real do video.
loop: Boolean que determina se o video é reproduzido continuamente em loop ou se para após ser reproduzido uma vez. false por padrão.

Reproduzir vários videos

Para evitar problemas de desempenho, cada scene só pode reproduzir uma texture de video por vez. No entanto, uma scene pode reproduzir várias cópias da mesma texture de video em várias screens diferentes. Isso não é restrito, pois impacta o desempenho de forma muito menor do que reproduzir videos separados. Para reproduzir o mesmo video em múltiplas entities, basta atribuir a mesma instância do objeto de texture de video aos Material components de cada entity de screen.

// #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, só é necessário criar um VideoPlayer component, que controla o estado de ambas as video screens. Nesse caso, o component é atribuído à screen1 entity, mas também poderia ser atribuído a qualquer outra entity na scene, não necessariamente a uma das screens.

Video events

Lide facilmente com mudanças de state em um video, para responder quando um video começa a reproduzir, é pausado etc. Isso pode ser usado, por exemplo, para reproduzir animations em sincronia perfeita com um video, garantindo que comecem ao mesmo tempo que o video.

Use videoEventsSystem.registerVideoEventsEntity para definir uma function que é executada toda vez que o estado do video atribuído a uma entity muda. Sempre que o estado muda, sua function pode verificar o novo estado e responder de acordo.

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

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

videoEventsSystem.registerVideoEventsEntity(
	videoPlayerEntity,
	function (videoEvent) {
		console.log(
			'video event - state: ' +
				videoEvent.state +
				'\ncurrent offset:' +
				videoEvent.currentOffset +
				'\nvideo length:' +
				videoEvent.videoLength
		)

		switch (videoEvent.state) {
			case VideoState.VS_READY:
				console.log('video event - video is READY')
				break
			case VideoState.VS_NONE:
				console.log('video event - video is in NO STATE')
				break
			case VideoState.VS_ERROR:
				console.log('video event - video ERROR')
				break
			case VideoState.VS_SEEKING:
				console.log('video event - video is SEEKING')
				break
			case VideoState.VS_LOADING:
				console.log('video event - video is LOADING')
				break
			case VideoState.VS_BUFFERING:
				console.log('video event - video is BUFFERING')
				break
			case VideoState.VS_PLAYING:
				console.log('video event - video started PLAYING')
				break
			case VideoState.VS_PAUSED:
				console.log('video event - video is PAUSED')
				break
		}
	}
)

O objeto videoEvent passado como input para a function contém as seguintes properties:

currentOffset (number): O valor atual da position property no video. Esse valor mostra os segundos após o início original do video. -1 por padrão, se o video ainda não tiver começado a reproduzir.
state: O novo status do video, expresso como um valor do VideoState enum. Esse 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 (number ): O comprimento em segundos de todo o video. -1 se o comprimento for desconhecido.
timeStamp ( number): Um lamport timestamp que é incrementado toda vez que o video muda de state.
tickNumber (number): O momento em que o evento ocorreu, expresso como contagem de ticks desde que a scene começou a rodar.

Último evento de video

Consulte um video para obter sua última mudança de state usando videoEventsSystem.getVideoState(). Essa function sempre retorna o valor mais recente de VideoEvent para o video.

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 videos

Um truque interessante para ter screens de video não retangulares é aplicar uma alpha texture sobre um plane. Você pode recortar parte do plane para qualquer forma que desejar.

Use a seguinte imagem para recortar seu video 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 property só existia em materiais PBR. Atualmente, ela só funciona em materiais basic.

Reproduzir um video em um modelo glTF

Você pode reproduzir um video em um glTF modelo usando o GltfNodeModifiers component. Veja Modify glTF materials para mais detalhes.

Isso permite reproduzir seus videos em qualquer forma, não apenas em planes. Por exemplo, você pode reproduzir videos em uma screen curva, ou até mesmo em todo o corpo 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 video seguirá o mapeamento UV original que o modelo usa. Isso significa que, se o modelo tiver uma texture mapeada para uma parte específica do modelo, o video será mapeado para essa mesma parte.

Você também pode usar o GltfNodeModifiers component para reproduzir um video apenas em uma mesh específica dentro do modelo. Por exemplo, você pode reproduzi-lo em uma wall específica de um building, mesmo que o modelo abranja todo o building. Veja Modify glTF materials para mais detalhes.

Áudio espacial

Por padrão, o video de um VideoPlayer component é global, o que significa que ele será ouvido com volume consistente em toda a sua scene. Se um jogador sair da scene, ele não ouvirá o streaming de forma alguma.

Para tornar o audio espacial, defina a spatial property 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 video agora será ouvido a partir da posição da entity que possui o VideoPlayer component, e ficará mais alto conforme o jogador se aproximar.

Controle o audio espacial com as seguintes properties:

spatialMinDistance: A distância mínima em que o audio se torna espacial. Se o jogador estiver mais perto, o audio será ouvido em volume total. 0 por padrão.
spatialMaxDistance: A distância máxima em que o audio é ouvido. Se o jogador estiver mais longe, o audio 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 video não suportam audio espacial. Certifique-se de que o stream esteja codificado em mp4, m4a, ou mov.

Análise de áudio

Você pode ler dados de amplitude e frequência em tempo real da faixa de áudio de uma VideoPlayer entity para acionar visuais reativos que sincronizam com a trilha sonora do video. Veja Análise de áudio.

AnteriorExibir um NFT Certificado PróximoDebugging

Atualizado há 13 dias