Reproducción de video

Transmitir video en una escena

Hay tres formas 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

💡 Tip: 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 un forma primitiva como un plano, cubo o incluso un cono.

• A material con un VideoTexture 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 de la máquina del jugador. Se recomienda evitar reproducir más de un video a la vez.

Si demasiados videos se reproducen al mismo tiempo en tu escena, algunos serán pausados por el motor. La prioridad para pausar una pantalla se determina con base en 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 comenzar a reproducir el video cuando el jugador esté cerca o realice una acción para hacerlo. Comenzar a reproducir un video cuando tu escena se carga lejos en el horizonte afectará innecesariamente el rendimiento mientras los jugadores visitan escenas vecinas.

También evita transmitir videos en resoluciones muy altas. No uses nada por encima de HD.

También es ideal reproducir videos en materiales Basic (sin iluminación), para reducir la carga de rendimiento, como ocurre en todos los ejemplos a continuación.

Mostrar un video

Las siguientes instrucciones se aplican a las tres opciones para mostrar videos:

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

2. Crear un VideoPlayer componente, ya sea haciendo referencia a una URL de streaming o a la ruta de un archivo de video. Aquí también puedes establecer el playing 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. Crear un VideoTexture objeto, y en su videoPlayerEntity propiedad asigna la entidad que posee el VideoPlayer component.

4. Crear un Material, asígnalo a la entidad pantalla y establece su textura hasta la VideoTexture 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,
})

Ver Transmisión usando Decentraland cast para detalles sobre cómo usar este tercer método alternativo.

Acerca de la transmisión externa

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

Hay varias opciones para transmitir video. La opción más simple es usar un proveedor de alojamiento 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 gratuito pero pagando por el alojamiento 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 lo mejor para ti teniendo en cuenta tus necesidades, habilidades técnicas y presupuesto.

Configurar OBS para una transmisión exitosa

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

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

Configuración simple de OBS

Se recomienda la siguiente configuración simple:

• Tasa de bits 2500 kbps (que funcionará con todos los recintos de Decentraland)

• Tasa de bits de audio 160 kbps

• Preajuste del codificador de video: Hardware NVENC

• Codificador de audio AAC

• Mayor resolución: 720 (cualquier mayor causa problemas en DCL)

• Frecuencia de imagen 30 fps

📔 Nota: Asegúrate de desactivar la transmisión Multitrack en OBS. Puedes encontrar esto en Settings > Stream.

Consejos para nuevos streamers

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

• Pequeños errores como un dígito equivocado en la clave de transmisión son los que con más probabilidad arruinarán la transmisión.

• No superes la resolución 720 ni una tasa de bits de 2500 kbps.

Transmisión en vivo

Puedes transmitir en vivo desde tu cámara o compartir tu pantalla usando la Transmisión en vivo función del Admin tools smart item.

Este método de transmisión usa la misma arquitectura de comunicaciones usada para comunicaciones en vivo entre jugadores. Es fácil de configurar y tiene mucha menos demora 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 Video pestaña, luego selecciona la Live funcionalidad y haz clic en el Obtener clave de transmisión .

5. Copia el URL del servidor y Clave de transmisión* a tu software de transmisión (por ejemplo OBS).

6. Presiona la Activate 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 la transmisión en tu escena. Aún necesitarás los Admin tools para obtener la clave de transmisión.

// #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 sin iluminación 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,
})

Generalmente se recomienda reproducir videos en materiales Basic sin iluminación, 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 predeterminadas 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 destaque más:

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

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

Ver materials para más detalles.

Acerca de los archivos de video

Los siguientes formatos de archivo son compatibles:

• .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 ella. El tamaño del video también podría hacer que excedas 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 comenzar a reproducir el video cuando el jugador esté cerca o realice una acción para activarlo. Comenzar a reproducir un video cuando tu escena se carga lejos en el horizonte afectará innecesariamente el rendimiento mientras los jugadores visitan escenas vecinas.

Iniciar, pausar y detener un video

Para comenzar a reproducir el video o pausarlo, establece el playing propiedad a true o false. Si playing está establecido en false, el video queda pausado en el último fotograma mostrado.

Puedes hacer que una pantalla sea conmut able añadiendo un evento de puntero como se muestra a continuación:

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 establecer en el VideoPlayer componente:

• playing: 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 por defecto.

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

• 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 por defecto.

Reproducir múltiples videos

Para evitar problemas de rendimiento, cada escena solo puede 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 afecta mucho menos al 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,
})

Ten en cuenta 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 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 cambia, 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 +
				'\ndesplazamiento 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 de 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 empezó 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:

• currentOffset (número): El valor actual de la propiedad position en el video. Este valor muestra los segundos desde el inicio original del video. -1 por defecto, si el video no ha comenzado a reproducirse.

• state: El nuevo estado del video, expresado como un valor del VideoState . Este enum puede contener los siguientes valores posibles:

  • 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 ): La duración en segundos de todo el video. -1 si la duración es desconocida.

• timeStamp ( número): Un lamport sello de tiempo que se incrementa cada vez que el video cambia de estado.

• tickNumber (número): El momento en que ocurrió el evento, expresado como conteo de ticks desde que la escena comenzó a ejecutarse.

Último evento de video

Consulta un video por 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(`state: ${latestVideoEvent.state}
    \ncurrentOffset: ${latestVideoEvent.currentOffset}
    \nvideoLength: ${latestVideoEvent.videoLength}`)
}

Máscaras alfa en videos

Un truco ingenioso para tener pantallas de video no rectangulares es aplicar una textura alfa 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 modelo usando el componente 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 use 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 VideoPlayer componente es global, lo que significa que se escuchará 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 el spatial propiedad 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 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 por defecto.

• 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 la transmisión esté codificada en mp4, m4a, o mov.