Reproducción de video

Transmitir video en una escena

Hay tres maneras diferentes de mostrar un video en una escena:

• Subir un archivo de video como parte del contenido de la escena

• Transmitir el video desde una fuente externa

• Transmitir en vivo vía Decentraland cast

💡 Consejo: En el Scene Editor in Creator Hub, puedes usar un Video Player Smart Item para una forma sin código de lograr esto.

En todos los casos, necesitarás:

• Una entidad con una primitive shape como un plano, cubo o incluso un cono.

• A material con un , expresado como un valor del enum asignado a su textura

• A VideoPlayer componente para controlar el estado del video.

Consideraciones de rendimiento

Ten en cuenta que la transmisión de video exige un esfuerzo significativo por parte de la máquina del jugador. Se recomienda evitar reproducir más de un video a la vez.

Si demasiados videos se están reproduciendo al mismo tiempo en tu escena, algunos serán pausados por el engine. La prioridad para pausar una pantalla se determina en función de varios factores, incluyendo la proximidad al jugador, el tamaño y si la pantalla está en el campo de visión del jugador. El número máximo de videos simultáneos depende de la configuración de calidad del jugador.

• Bajo: 1

• Medio: 5

• Alto: 10

También recomendamos iniciar la reproducción del video cuando el jugador esté cerca o realice una acción para hacerlo. Empezar a reproducir un video cuando tu escena está cargada en la distancia afectará innecesariamente el rendimiento mientras los jugadores visitan escenas vecinas.

Además, evita transmitir videos en muy alta resolución. No uses nada por encima de HD.

También es ideal reproducir videos en materiales Basic (unlit), para reducir la carga de rendimiento, como ocurre en todos los fragmentos de ejemplo abajo.

Mostrar un video

Las siguientes instrucciones se aplican a las tres opciones de mostrar video:

1. Crea una entidad que servirá como la pantalla de video. Dale a esta entidad un MeshRenderer componente para que tenga una forma visible.

2. Crea un VideoPlayer componente, ya sea referenciando una URL de streaming o una ruta a un archivo de video. Aquí también puedes configurar el detiene todas las demás animaciones que la entidad está reproduciendo actualmente. Para reproducir múltiples animaciones al mismo tiempo, modifica manualmente la propiedad estado del video y su volumen. Este componente puede asignarse a la entidad pantalla de video o a cualquier otra entidad en la escena.

3. Crea un , expresado como un valor del enum objeto, y en su videoPlayerEntity propiedad asigna la entidad que posee el VideoPlayer componente.

4. Crea un Material, asígnalo a la entidad pantalla y establece su texture al , expresado como un valor del enum que creaste.

Este ejemplo usa un video que está almacenado localmente en una /videos carpeta en el proyecto de la escena:

// #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 un video desde una URL de streaming externa, cambia el paso 2 para que el src propiedad en el VideoPlayer componente haga referencia a la URL de streaming.

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

Vea Streaming usando Decentraland cast para detalles sobre cómo usar este tercer método alternativo.

Acerca del streaming externo

La fuente del streaming debe ser una https URL (http No se admiten URLs), y la fuente debería tener CORS policies (Cross Origin Resource Sharing) que permitan el acceso externo. Si este no es el caso, puede que necesites configurar un servidor para actuar como proxy y exponer el stream de manera válida.

Hay varias opciones para transmitir video. La opción más simple es usar un proveedor de hosting gestionado como Vimeo , Livepeer Studio o Serraform donde pagas una tarifa al proveedor para gestionar toda la infraestructura de streaming.

La otra alternativa recomendada es configurar tu propio servidor, usando software libre pero pagando el hosting en una plataforma como Digital Ocean o Cloudflare. Puedes desplegar algo como un Node Media Server, que proporciona la mayoría de lo que necesitas listo para usar.

Todas estas opciones tienen pros y contras para diferentes escenarios. Debes evaluar qué es mejor para ti teniendo en cuenta tus necesidades, habilidades técnicas y presupuesto.

Configurar OBS para un streaming exitoso

OBS es una herramienta popular y gratuita para gestionar tus streams.

Ya sea que uses la clave de stream de un recinto o tu propio servidor RTMP, tus ajustes en OBS son importantes para el éxito de tu stream. Debes apuntar a una conexión sólida y consistente.

Configuración simple de OBS

Se recomienda la siguiente configuración simple:

• Bitrate 2500kbps (lo cual funcionará con todos los recintos de Decentraland)

• Bitrate de audio 160kbps

• Preset del codificador de video: Hardware NVENC

• Codificador de audio AAC

• Resolución máxima: 720 (cualquier mayor causa problemas en DCL)

• Tasa de fotogramas 30fps

Consejos para nuevos transmisores

• Las pruebas de sonido tempranas son esenciales para probar tu configuración con el recinto.

• Pequeños errores como un dígito incorrecto en la clave de stream son los más propensos a arruinar la transmisión.

• No excedas la resolución 720 ni un bitrate de 2500 kbps.

Transmisión en vivo

Puedes hacer streaming en vivo desde tu cámara o compartir tu pantalla usando la Transmisión en vivo función de los Admin tools smart item.

Este método de streaming usa la misma arquitectura de comunicaciones utilizada para comunicaciones en vivo entre jugadores. Es fácil de configurar y tiene mucha menos latencia que transmitir desde fuentes externas.

1. Agrega un Admin tools smart item a tu escena, así como un Video player smart item.

2. Publica tu escena, ya sea en un World o en Genesis City.

3. Entra en la escena como jugador con el permiso para usar los Admin tools.

4. Abre la consola de Admin, selecciona la pestaña Video luego selecciona la Live funcionalidad y haz clic en el Obtener clave de stream botón.

5. Copia la Server URL y Streaming key* a tu software de streaming (por ejemplo OBS).

6. Presiona la Activa el botón para comenzar a transmitir.

En lugar de agregar un smart item Video player a tu escena, también puedes usar la URL livekit-video://current-stream como la fuente de video, para reproducir el stream en tu escena. Aún necesitarás los Admin tools para obtener la clave de stream.

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

Materiales de video

La mayoría de las veces, querrás reproducir videos en un material Basic material, en lugar de un material PBR. Esto resulta en una imagen mucho más brillante y nítida y es mejor para el rendimiento.

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

Usualmente se recomienda reproducir videos en materiales Basic unlit, ya que esto es mejor para el rendimiento. Sin embargo, si quieres proyectar un video sobre un material PBR, ten en cuenta que las propiedades por defecto hacen que el video se vea bastante opaco. Puedes mejorar esto alterando otras propiedades del material. Aquí hay algunas configuraciones recomendadas para hacer que el video resalte más:

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

💡 Consejo: Dado que el video es una textura que se agrega a un material, también puedes experimentar con otras propiedades de los materiales, como tintarlo con un color o agregar otras capas de textura, por ejemplo para producir un efecto de pantalla sucia.

Vea materials para más detalles.

Acerca de los archivos de video

Se admiten los siguientes formatos de archivo:

• .mp4

• .ogg

• .webm

Ten en cuenta que un archivo de video se suma al tamaño total de la escena, lo que hace que la escena tarde más en descargarse para los jugadores que entren en tu escena. El tamaño del video también podría hacer que superes el limitaciones de la escena, ya que tienes un máximo de 15 MB por parcela para usar. Recomendamos comprimir el video tanto como sea posible, para que sea menos problemático.

También recomendamos iniciar la reproducción del video cuando el jugador esté cerca o realice una acción para activarlo. Empezar a reproducir un video cuando tu escena está cargada en la distancia afectará innecesariamente el rendimiento mientras los jugadores visitan escenas vecinas.

Iniciar, pausar y detener un video

Para empezar a reproducir el video o pausarlo, establece el detiene todas las demás animaciones que la entidad está reproduciendo actualmente. Para reproducir múltiples animaciones al mismo tiempo, modifica manualmente la propiedad a true o false. Si detiene todas las demás animaciones que la entidad está reproduciendo actualmente. Para reproducir múltiples animaciones al mismo tiempo, modifica manualmente la propiedad está establecido en false, el video queda pausado en el último fotograma mostrado.

Puedes hacer que una pantalla sea conmutables añadiéndole un evento de puntero como se muestra abajo:

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

Para detener el video y devolverlo al primer fotograma, establece la position propiedad en 0. En el siguiente ejemplo, al hacer clic en el video se detiene.

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

Configurar el reproductor de video

Las siguientes propiedades opcionales están disponibles para configurar en el VideoPlayer componente:

• detiene todas las demás animaciones que la entidad está reproduciendo actualmente. Para reproducir múltiples animaciones al mismo tiempo, modifica manualmente la propiedad: Determina si el video se está reproduciendo actualmente. Si es false, el video está en pausa.

📔 Nota: Solo puede haber un VideoPlayer componente activo a la vez en cada escena.

• playbackRate: Cambia la velocidad a la que se reproduce el video. 1 totalVideoLength

• volume: Te permite cambiar el volumen del audio. 1 totalVideoLength

• position: Te permite establecer una posición de inicio diferente en el video. Se expresa en segundos desde el comienzo original del video. -1 por defecto, lo que hace que comience en el inicio real del video.

• loop: Booleano que determina si el video se reproduce continuamente en bucle, o si se detiene después de reproducirse una vez. false totalVideoLength

Reproducir múltiples videos

Para evitar problemas de rendimiento, cada escena solo está permitida reproducir una textura de video a la vez. Sin embargo, una escena puede reproducir múltiples copias de la misma textura de video en varias pantallas diferentes. Esto no está restringido, ya que impacta mucho menos en el rendimiento que reproducir videos separados. Para reproducir el mismo video en múltiples entidades, simplemente asigna la misma instancia del objeto de textura de video a los Material componentes de cada entidad pantalla.

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

Nota que en el ejemplo anterior, solo es necesario crear un VideoPlayer componente, que controla el estado de ambas pantallas de video. En este caso, el componente está asignado a la screen1 entidad, pero también podría asignarse a cualquier otra entidad en la escena, no necesariamente a una de las pantallas.

Eventos de video

Maneja fácilmente los cambios de estado en un video, para responder cuando un video comienza a reproducirse, se pausa, etc. Esto puede usarse por ejemplo para reproducir animaciones en perfecta sincronía con un video, asegurando que comiencen al mismo tiempo que el video.

Usa videoEventsSystem.registerVideoEventsEntity para definir una función que se ejecute cada vez que el estado del video asignado a una entidad cambie. Cada vez que el estado cambie, tu función puede comprobar el nuevo estado y responder en consecuencia.

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

// ... Create videoPlayerEntity with VideoPlayer component, Transform, MeshRenderer.setPlane(), etc. ...

videoEventsSystem.registerVideoEventsEntity(
	videoPlayerEntity,
	function (videoEvent) {
		console.log(
			'evento de video - estado: ' +
				videoEvent.state +
				'\noffset actual:' +
				videoEvent.currentOffset +
				'\nlongitud del video:' +
				videoEvent.videoLength
		)

		switch (videoEvent.state) {
			case VideoState.VS_READY:
				console.log('evento de video - el video está READY')
				break
			case VideoState.VS_NONE:
				console.log('evento de video - el video está en NO STATE')
				break
			case VideoState.VS_ERROR:
				console.log('evento de video - ERROR del video')
				break
			case VideoState.VS_SEEKING:
				console.log('evento de video - el video está SEEKING')
				break
			case VideoState.VS_LOADING:
				console.log('evento de video - el video está LOADING')
				break
			case VideoState.VS_BUFFERING:
				console.log('evento de video - el video está BUFFERING')
				break
			case VideoState.VS_PLAYING:
				console.log('evento de video - el video comenzó a PLAYING')
				break
			case VideoState.VS_PAUSED:
				console.log('evento de video - el video está PAUSED')
				break
		}
	}
)

El objeto videoEvent pasado como entrada a la función contiene las siguientes propiedades:

• ): El valor actual de la propiedad (numberseek position por defecto. -1 por defecto, si el video no ha comenzado a reproducirse.

• state: El nuevo estado del video, expresado como un valor del VideoState VideoStatus.NONE

  • 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 si la duración es desconocida. -1 videoStatus

• timeStamp ( number): Un lamport timestamp que se incrementa cada vez que el video cambia de estado.

• tickNumber (number): El momento en el que ocurrió el evento, expresado como ticks contados desde que la escena comenzó a ejecutarse.

Último evento de video

Consulta un video para su último cambio de estado usando videoEventsSystem.getVideoState(). Esta función siempre devuelve el último VideoEvent valor para el video.

function mySystem() {
    const latestVideoEvent = videoEventsSystem.getVideoState(videoPlayerEntity)
    if(!latestVideoEvent) return
    
    console.log(`estado: ${latestVideoEvent.state}
    \noffset actual: ${latestVideoEvent.currentOffset}
    \nlongitud del video: ${latestVideoEvent.videoLength}`)
}

Máscaras alpha en videos

Un truco útil para tener pantallas de video no rectangulares es aplicar una textura alpha encima de un plano. Puedes recortar parte del plano en la forma que desees.

Usa la siguiente imagen para recortar tu video en una forma circular, con esquinas 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: En versiones anteriores, la alphaTexture propiedad estaba presente solo en materiales PBR. Actualmente, solo funciona en materiales basic.

Reproducir un video en un modelo glTF

Puedes reproducir un video en un glTF model by using the GltfNodeModifiers componente. Ver Modificar materiales glTF para más detalles.

Esto te permite reproducir tus videos en cualquier forma, no solo en planos. Por ejemplo, puedes reproducir videos en una pantalla curva, o incluso en todo el cuerpo de un 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,
						}),
					},
				},
			},
		}],
	})

El mapeo del video seguirá el mapeo UV original que usa el modelo. Esto significa que si el modelo tiene una textura mapeada a una parte específica del modelo, el video se mapeará a esa misma parte.

También puedes usar el GltfNodeModifiers componente para reproducir un video solo en una malla específica dentro del modelo. Por ejemplo, puedes reproducirlo en una pared específica de un edificio, aunque el modelo abarque todo el edificio. Ver Modificar materiales glTF para más detalles.

Audio espacial

Por defecto, el audio del video de un VideoPlayer componente es global, lo que significa que se oirá a un volumen consistente en toda tu escena. Si un jugador sale de la escena, no escuchará la transmisión en absoluto.

Para hacer el audio espacial, establece la spatial a 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,
})

El audio del video ahora se escuchará desde la posición de la entidad que posee el VideoPlayer componente, y será más fuerte a medida que el jugador se acerque.

Controla el audio espacial con las siguientes propiedades:

• spatialMinDistance: La distancia mínima a la que el audio se vuelve espacial. Si el jugador está más cerca, el audio se escuchará a volumen completo. 0 totalVideoLength

• spatialMaxDistance: La distancia máxima a la que se escucha el audio. Si el jugador está más lejos, el audio se escuchará a volumen 0. 60 por defecto

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: Algunos formatos de video no soportan audio espacial. Asegúrate de que el stream esté codificado en mp4, m4a, o mov.