Reproducción de video

Transmite video a una escena

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

Sube un archivo de video como parte del contenido de la escena
Transmitir el video desde una fuente externa
Transmitir en vivo a través de Decentraland cast

💡 Consejo: En el Scene Editor en Creator Hub, puedes usar un reproductor de video Smart Item para lograr esto sin código.

En todos los casos, necesitarás:

Una Entity con una forma primitiva como un plano, un cubo o incluso un cono.
A material con una VideoTexture asignada a su textura
A VideoPlayer componente para controlar el estado del video.

Consideraciones de rendimiento

Ten en cuenta que transmitir video exige un esfuerzo considerable de la máquina del jugador. Se recomienda evitar reproducir más de un video a la vez.

Si se están reproduciendo demasiados videos 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, incluida 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 los ajustes de calidad del jugador.

Bajo: 1
Medio: 5
Alto: 10

También recomendamos empezar a reproducir el video cuando el jugador esté cerca o realice una acción para hacerlo. Empezar a reproducir un video cuando tu escena se carga lejos en el horizonte afectará innecesariamente al 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 fragmentos de ejemplo a continuación.

Mostrar un video

Las siguientes instrucciones aplican a las tres opciones para mostrar video:

Crea una Entity para que sirva como pantalla de video. Dale a esta Entity un MeshRenderer componente para que tenga una forma visible.
Crea un VideoPlayer componente, ya sea haciendo referencia a una URL de streaming o a una ruta a un archivo de video. Aquí también puedes establecer el reproducción estado y su volumen. Este componente puede asignarse a la Entity de la pantalla de video o a cualquier otra Entity de la escena.
Crea un VideoTexture objeto, y en su videoPlayerEntity propiedad, asigna la Entity que posee el VideoPlayer component.
Crea un Material, asígnalo a la Entity de la pantalla y establece su textura a la VideoTexture que creaste.

Este ejemplo usa un video que está almacenado localmente en una /videos carpeta del 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 de la VideoPlayer propiedad en el componente haga referencia a la URL de streaming.

// #2
VideoPlayer.create(screen, {
	src: 'https://vz-7c61c1b5-d59.b-cdn.net/ccea595a-b910-4de6-b160-092819db021d/playlist.m3u8',
	playing: true,
})

Consulta Streaming usando Decentraland cast para obtener más detalles sobre cómo usar este tercer método alternativo.

Acerca de la transmisión externa

La fuente del streaming debe ser una https URL (http las URL no son compatibles).

Deberías poder pegar una URL que apunte a un video desde la mayoría de los sitios populares de streaming de video. Ten en cuenta los términos de servicio de estas plataformas.

Para transmitir desde un archivo de video que tienes en tu máquina local, la forma más sencilla es subir este video a un Google Drive público y pegar el enlace.

Otra opción es usar un proveedor de hosting administrado como Vimeo , Livepeer Studio Settings Serraform donde pagas una tarifa al proveedor para que gestione toda la infraestructura de streaming.

El enfoque más potente es configurar tu propio server, usando software libre pero pagando el hosting en una plataforma como Digital Ocean Settings Cloudflare. Puedes desplegar algo como un Node Media Server, que proporciona la mayor parte de lo que necesitas listo para usar.

Todas estas opciones tienen ventajas y desventajas para distintos escenarios. Debes evaluar cuál es la mejor para ti teniendo en cuenta tus necesidades, habilidades técnicas y presupuesto.

Configuración de OBS para una transmisión exitosa

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

Ya sea que estés usando la stream key de un venue o tu propio server RTMP, tus ajustes en OBS son importantes para el éxito de tu stream. Debes buscar una conexión sólida y consistente.

Configuración simple de OBS

Se recomienda la siguiente configuración simple:

Bitrate 2500 kbps (que funcionará con todos los espacios de Decentraland)
Bitrate de audio 160 kbps
Preajuste del codificador de video: Hardware NVENC
Codificador de audio AAC
Resolución máxima: 720 (cualquier valor mayor causa problemas en DCL)
Velocidad de fotogramas 30 fps

📔 Nota: Asegúrate de desactivar Multitrack streaming en OBS. Puedes encontrarlo en Settings > Stream.

Consejos para nuevos streamers

Los primeros chequeos de sonido son esenciales para probar tu configuración con el venue.
Errores pequeños como un dígito incorrecto en la stream key son los que más probablemente arruinen el stream.
No superes la resolución 720 ni un bitrate de 2500 kbps.

Transmisión en vivo

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

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

Añade un Admin tools smart item a tu escena, así como un Video player smart item.
Publica tu escena, ya sea en un World o en Genesis City.
Entra en la escena como un player con permiso para usar las Admin tools.
Abre la consola de Admin, selecciona la Video pestaña, luego selecciona la Live funcionalidad y haz clic en el Obtener clave de streaming .
Copia la URL del servidor 2 clave de streaming* a tu software de streaming (por ejemplo, OBS).
Pulsa el Activar botón para iniciar la transmisión.

En lugar de añadir un smart item Video player a tu escena, también puedes usar la URL livekit-video://current-stream como fuente del video para reproducir el stream en tu escena. Todavía necesitarás las Admin tools para obtener la 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,
})

Materiales de video

La mayor parte del tiempo, querrás reproducir videos en un material Basic, en lugar de un material PBR. Esto da como resultado una imagen mucho más brillante y nítida y es mejor para el rendimiento.

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

Normalmente 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 mejorarlo alterando otras propiedades del material. Aquí tienes algunos ajustes recomendados 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(),
})

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

Consulta 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 a tu escena. El tamaño del video también podría hacer que superes el limitaciones de sceneparcel, ya que tienes un máximo de 15 MB por parcel para usar. Recomendamos comprimir el video tanto como sea posible, para que sea menos problemático.

También recomendamos empezar a reproducir el video cuando el player esté cerca o realice una acción para activarlo. Empezar a reproducir un video cuando tu escena se carga lejos en el horizonte afectará innecesariamente al rendimiento mientras los players visitan escenas vecinas.

Iniciar, pausar y detener un video

Para iniciar la reproducción del video o pausarlo, establece la reproducción propiedad en true Settings false. Si reproducción se establece en false, el video se pausa en el último fotograma mostrado.

Puedes hacer que una pantalla sea alternable añadiéndole un pointer event como se muestra a continuación:

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

Para detener el video y devolverlo al primer fotograma, establece la posición 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: 'DETENER' },
	},
	function () {
		const videoPlayer = VideoPlayer.getMutable(screen)
		videoPlayer.playing = false
		videoPlayer.position = 0
	}
)

Configura el reproductor de video

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

reproducción: Determina si el video se está reproduciendo actualmente. Si es false, el video está en pausa.

📔 Nota: Solo puede reproducirse un número limitado de videos al mismo tiempo, según los ajustes de calidad del player. Si la escena reproduce más que eso, el engine pausa los de menor prioridad. Consulta Consideraciones de rendimiento.

playbackRate: Cambia la velocidad a la que se reproduce el video. 1 de forma predeterminada.
volume: Te permite cambiar el volumen del audio. 1 de forma predeterminada.
posición: Te permite establecer una posición de inicio diferente en el video. Se expresa en segundos después del comienzo original del video. 0 de forma predeterminada, lo que hace que comience al inicio real del video.
loop: Boolean que determina si el video se reproduce continuamente en un loop, o si se detiene después de reproducirse una vez. false de forma predeterminada.

Reproducir varios videos

Para evitar problemas de rendimiento, mantén baja la cantidad de videos diferentes que se reproducen al mismo tiempo; el engine solo permite un número limitado de videos simultáneos, según los ajustes de calidad del player (consulta Consideraciones de rendimiento). Sin embargo, una escena puede reproducir múltiples copias de la misma textura de video en varias pantallas distintas. Esto no está restringido, ya que afecta al rendimiento considerablemente menos que reproducir videos separados. Para reproducir el mismo video en múltiples Entities, simplemente asigna la misma instancia del objeto de textura de video a los Material componentes de cada Entity de 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://vz-7c61c1b5-d59.b-cdn.net/ccea595a-b910-4de6-b160-092819db021d/playlist.m3u8',
	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 se asigna a la screen1 Entity, pero también podría asignarse a cualquier otra Entity de la escena, no necesariamente a una de las pantallas.

Eventos de video

Gestiona fácilmente los cambios de estado en un video, para responder cuando un video empieza a reproducirse, se pausa, etc. Esto puede usarse, por ejemplo, para reproducir animaciones perfectamente sincronizadas con un video, asegurando que empiecen al mismo tiempo que el video.

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

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

// ... Crea videoPlayerEntity con el componente VideoPlayer, Transform, MeshRenderer.setPlane(), etc. ...

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

		switch (videoEvent.state) {
			case VideoState.VS_READY:
				console.log('evento de video - el video está LISTO')
				break
			case VideoState.VS_NONE:
				console.log('evento de video - el video está SIN ESTADO')
				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á buscando')
				break
			case VideoState.VS_LOADING:
				console.log('evento de video - el video se está cargando')
				break
			case VideoState.VS_BUFFERING:
				console.log('evento de video - el video está almacenando en búfer')
				break
			case VideoState.VS_PLAYING:
				console.log('evento de video - el video empezó a reproducirse')
				break
			case VideoState.VS_PAUSED:
				console.log('evento de video - el video está en pausa')
				break
		}
	}
)

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

currentOffset (number): El valor actual de la posición propiedad del video. Este valor muestra los segundos transcurridos desde el comienzo original del video. -1 si el video aún no ha comenzado a reproducirse.
state: El nuevo estado del video, expresado como un valor del VideoState enum. 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 (number ): La duración en segundos de todo el video. -1 si la duración es desconocida.
timestamp ( number): Un lamport timestamp que se incrementa cada vez que el video cambia de estado.
tickNumber (number): El momento en que ocurrió el evento, expresado como el conteo de ticks desde que la escena empezó a ejecutarse.

Si vuelves a registrar un callback en una Entity que ya tiene uno (por ejemplo, para cambiar lo que ocurre al cambiar de estado), el nuevo callback reemplaza al anterior y se conserva el último estado reportado. Esto significa que el nuevo callback no se vuelve a llamar para un estado que ya había sido reportado al callback anterior.

Comprueba si una Entity está registrada

Usa videoEventsSystem.hasVideoEventsEntity() para comprobar si una Entity ya tiene un callback de eventos de video registrado.

if (videoEventsSystem.hasVideoEventsEntity(videoPlayerEntity)) {
	console.log('Esta Entity ya tiene un listener de eventos de video')
}

Último evento de video

Consulta el último cambio de estado de un video usando videoEventsSystem.getVideoState(). Esto devuelve el último VideoEvent valor de la Entity, o undefined si aún no se ha reportado ningún evento. Puedes llamar a esto desde un system para consultar el estado del video en cada frame sin registrar un callback.

function mySystem() {
	const latestVideoEvent = videoEventsSystem.getVideoState(videoPlayerEntity)
	if (!latestVideoEvent) return

	console.log(`estado: ${latestVideoEvent.state}
    \noffset actual: ${latestVideoEvent.currentOffset}
    \nduración del video: ${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 quieras.

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 solo estaba presente 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 GltfNodeModifiers component. 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://vz-7c61c1b5-d59.b-cdn.net/ccea595a-b910-4de6-b160-092819db021d/playlist.m3u8',
	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 que está mapeada a una parte específica del modelo, el video se mapeará a esa misma parte.

También puedes usar el GltfNodeModifiers component para reproducir un video solo en una Mesh 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 video de un VideoPlayer component es global, lo que significa que se escuchará a un volumen constante en toda tu escena. Si un jugador sale de la escena, no escuchará el streaming en absoluto.

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

Ahora el video se escuchará desde la posición de la entity que posee el VideoPlayer component, y sonará 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 de forma predeterminada.
spatialMaxDistance: La distancia máxima a la que se escucha el audio. Si el jugador está más lejos, el audio se escuchará a 0 volumen. 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 admiten audio espacial. Asegúrate de que el stream esté codificado en mp4, m4a, o mov.

Análisis de audio

Puedes leer datos de amplitud y frecuencia en tiempo real de la pista de audio de un VideoPlayer entity para impulsar visuales reactivos que se sincronizan con la banda sonora del video. Ver Análisis de audio.

💡 Consejo: Para ver un video reproducido en un modelo GLTF en lugar de un primitivo, consulta el 74,-8-gltfnodemodifier escena de prueba, que envía un stream HLS a nodos GLTF específicos usando GltfNodeModifiers texturas de video.

AnteriorMostrar un NFT certificado

SiguienteDepuración

Última actualización hace 18 días