> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-ko/sdk7/media/video-playing.md).

# 비디오 재생

씬에 비디오 스트리밍

씬에서 동영상을 보여주는 방법은 세 가지입니다:

* 씬 콘텐츠의 일부로 동영상 파일 업로드
* 외부 소스에서 동영상 스트리밍
* Decentraland cast를 통해 실시간 스트리밍

{% hint style="info" %}
**💡 팁**에서 [Creator Hub의 씬 편집기](https://docs.decentraland.org/creator/content-creator-ko/scene-editor/get-started/about-editor.md)를 사용하면 **비디오 플레이어** [스마트 아이템](https://docs.decentraland.org/creator/content-creator-ko/scene-editor/interactivity/smart-items.md) 이 작업을 코드 없이 수행하는 방법은 다음과 같습니다.
{% endhint %}

모든 경우에 다음이 필요합니다.

* 다음이 있는 엔티티 [기본 도형](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/shape-components.md) 예: 평면, 큐브 또는 원뿔입니다.
* 다음이 필요합니다. [머티리얼](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/materials.md) 에 다음을 `VideoTexture` 텍스처로 할당합니다.
* A `VideoPlayer` 비디오 상태를 제어하는 컴포넌트입니다.

## 성능 고려 사항

스트리밍 비디오는 플레이어의 컴퓨터에 상당한 부하를 준다는 점에 유의하세요. 한 번에 하나 이상의 비디오를 재생하지 않는 것이 좋습니다.

장면에서 동시에 재생되는 비디오가 너무 많으면 엔진이 일부 비디오를 일시 중지할 수 있습니다. 어떤 화면을 일시 중지할지는 플레이어와의 거리, 화면 크기, 플레이어의 시야에 화면이 들어오는지 여부 등 여러 요소를 바탕으로 결정됩니다. 동시에 재생할 수 있는 비디오의 최대 개수는 플레이어의 품질 설정에 따라 달라집니다.

* 낮음: 1
* 중간: 5
* 높음: 10

또한 플레이어가 가까이 다가오거나 동영상 재생을 시작하는 동작을 할 때 동영상이 재생되도록 하는 것이 좋습니다. 장면이 로드되자마자 저 멀리 있는 동영상의 재생을 시작하면 플레이어가 주변 장면을 방문하는 동안 성능에 불필요한 영향을 줍니다.

또한 해상도가 매우 높은 비디오는 스트리밍하지 않는 것이 좋습니다. 다음을 초과하는 해상도는 사용하지 마세요. *HD*.

아래의 모든 예제 스니펫처럼 성능 부하를 줄이려면 Basic(언릿) 머티리얼에서 비디오를 재생하는 것이 좋습니다.

## 비디오 표시

다음 지침은 세 가지 동영상 표시 옵션 모두에 적용됩니다:

1. 동영상 화면으로 사용할 엔터티를 만듭니다. 이 엔터티에 `MeshRenderer` 컴포넌트를 추가해 보이는 형태를 갖도록 합니다.
2. 다음 컴포넌트를 만듭니다: `VideoPlayer` 스트리밍 URL 또는 동영상 파일 경로를 참조하도록 설정합니다. 여기서 동영상의 `playing` 상태와 볼륨도 설정할 수 있습니다. 이 컴포넌트는 동영상 화면 엔터티나 장면의 다른 엔터티에 할당할 수 있습니다.
3. 다음 항목을 만듭니다: `VideoTexture` 객체의  `videoPlayerEntity`  속성에 다음을 소유한 엔티티를 할당합니다:  `VideoPlayer`  컴포넌트.
4. 다음 항목을 만듭니다:  `Material`을 만들어 화면 엔티티에 할당하고, 해당  `texture` 에 `VideoTexture` 생성한

이 예제에서는 씬 프로젝트의 `/videos` 폴더에 로컬로 저장된 동영상을 사용합니다:

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

외부 스트리밍 URL의 동영상을 사용하려면 2단계에서 `src` 속성이 `VideoPlayer` 컴포넌트에서 스트리밍 URL을 참조하도록 변경합니다.

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

자세한 내용은 [라이브 스트리밍](#live-streaming) 에서 세 번째 대안 방법의 사용법을 확인하세요.

## 외부 스트리밍 정보

스트리밍 소스는 *https* URL이어야 합니다(*http* URL은 지원되지 않습니다).

대부분의 인기 동영상 스트리밍 사이트에서 동영상을 가리키는 URL을 붙여넣을 수 있습니다. 이러한 플랫폼의 서비스 약관을 준수하세요.

로컬 컴퓨터에 있는 동영상 파일을 스트리밍하려면, 가장 간단한 방법은 동영상을 Google Drive에 공개로 업로드한 다음 링크를 붙여넣는 것입니다.

또 다른 방법은 다음과 같은 관리형 호스팅 제공업체를 이용하는 것입니다: [Vimeo](https://vimeo.com/) , [Livepeer Studio](https://livepeer.studio/) 또는 [Serraform](https://serraform.gitbook.io/streaming-docs/guides/decentraland-playback) 이 경우 스트리밍 인프라 관리 비용을 제공업체에 지불합니다.

가장 유연한 방법은 무료 소프트웨어를 사용해 자체 서버를 설정하고, 다음과 같은 플랫폼의 호스팅 비용을 지불하는 것입니다: [Digital Ocean](https://try.digitalocean.com/developerbrand/?_campaign=emea_brand_kw_en_cpc&_adgroup=digitalocean_exact_exact&_keyword=digitalocean&_device=c&_adposition=&_content=conversion&_medium=cpc&_source=bing\&msclkid=160bfc160a2a1bab9bbf9933594bd9c5\&utm_source=bing\&utm_medium=cpc\&utm_campaign=emea_brand_kw_en_cpc\&utm_term=digitalocean\&utm_content=DigitalOcean%20Exact_Exact) 또는 [Cloudflare](https://www.cloudflare.com/products/cloudflare-stream/). 필요한 기능 대부분이 기본 제공되는 [Node Media Server](https://github.com/illuspas/Node-Media-Server)와 같은 솔루션을 배포할 수 있습니다.

각 옵션은 상황에 따라 장단점이 있습니다. 자신의 요구 사항과 기술 수준, 예산을 고려해 가장 적합한 방법을 선택하세요.

## 성공적인 스트리밍을 위한 OBS 설정

[OBS](https://obsproject.com/) 는 스트림을 관리하는 데 널리 사용되는 무료 도구입니다.

행사장의 스트림 키를 사용하든 자체 RTMP 서버를 사용하든, OBS 설정은 스트리밍의 성공에 중요합니다. 안정적이고 일관된 연결을 유지하는 것을 목표로 하세요.

### 간단한 OBS 설정

다음과 같은 간단한 설정을 권장합니다:

* 비트레이트 2500kbps(모든 Decentraland 공간에서 사용 가능)
* 오디오 비트레이트 160kbps
* 비디오 인코더 사전 설정: 하드웨어 NVENC
* 오디오 인코더 AAC
* 최대 해상도: 720(이보다 높으면 DCL에서 문제가 발생합니다)
* 프레임 속도 30fps

{% hint style="warning" %}
**📔 참고**: OBS에서 멀티트랙 스트리밍을 비활성화해야 합니다. 설정 > 방송에서 찾을 수 있습니다.
{% endhint %}

### 신규 스트리머를 위한 조언

* 공연 장소에 맞춰 설정을 테스트하려면 사전에 음향을 점검하는 것이 중요합니다.
* 스트림 키의 숫자 하나가 잘못된 것처럼 사소한 오류가 스트리밍을 망칠 가능성이 가장 큽니다.
* 해상도는 720을, 비트레이트는 2500 kbps를 초과하지 마세요.

## 라이브 스트리밍

카메라 영상을 실시간 스트리밍하거나 화면을 공유할 수 있습니다. 이 기능은 [실시간 스트리밍](https://docs.decentraland.org/creator/content-creator-ko/scene-editor/operate-live/live-streaming.md) 의 기능이며, [관리자 도구](https://docs.decentraland.org/creator/content-creator-ko/scene-editor/operate-live/scene-admin.md) 스마트 항목에서 사용할 수 있습니다.

이 스트리밍 방식은 플레이어 간 실시간 통신에 사용되는 것과 동일한 통신 아키텍처를 사용합니다. 설정이 간편하고 외부 소스에서 스트리밍하는 것보다 지연 시간이 훨씬 짧습니다.

1. 항목을 추가하세요. [관리자 도구](https://docs.decentraland.org/creator/content-creator-ko/scene-editor/operate-live/scene-admin.md) 스마트 아이템을 씬에 추가하고, [비디오 플레이어](https://docs.decentraland.org/creator/content-creator-ko/scene-editor/interactivity/video-screen.md) 스마트 아이템을 추가합니다.
2. 씬을 월드 또는 제네시스 시티에 게시합니다.
3. 관리자 도구를 사용할 권한이 있는 플레이어로 씬에 입장합니다.
4. 관리자 콘솔을 열고 **비디오** 탭을 선택한 다음 **라이브** 기능을 사용하고 **스트림 키 가져오기** 버튼을 클릭합니다.
5. 다음을 복사합니다: **서버 URL** 및 *스트리밍 키*\*를 스트리밍 소프트웨어(예: OBS)에 붙여넣습니다.
6. 다음을 누릅니다: **활성화** 스트리밍을 시작하는 버튼입니다.

장면에 Video player 스마트 항목을 추가하는 대신 URL을 사용할 수도 있습니다. `livekit-video://current-stream` 를 동영상 소스로 사용하면 장면에서 스트림을 재생할 수 있습니다. 스트림 키를 가져오려면 Admin 도구가 여전히 필요합니다.

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

## 동영상 머티리얼

대부분의 경우 동영상은 PBR 머티리얼이 아니라 언릿 [Basic 머티리얼](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/materials.md#unlit-materials)에서 재생하는 것이 좋습니다. 이렇게 하면 이미지가 훨씬 더 밝고 선명해지며 성능에도 유리합니다.

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

일반적으로 성능을 위해 Basic 언릿 머티리얼에서 동영상을 재생하는 것이 좋습니다. 하지만 동영상을 PBR 머티리얼에 투사하려는 경우 기본 속성으로 인해 동영상이 다소 불투명하게 보인다는 점에 유의하세요. 머티리얼의 다른 속성을 변경해 이를 개선할 수 있습니다. 동영상이 더 돋보이도록 설정하는 방법은 다음과 같습니다.

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

{% hint style="info" %}
**💡 팁**: 동영상은 머티리얼에 추가되는 텍스처이므로, 색조를 입히거나 다른 텍스처 레이어를 추가해 화면을 더럽게 보이게 하는 등 머티리얼의 다른 속성도 실험해 볼 수 있습니다.

자세한 내용은  [머티리얼](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/materials.md) 을 참조하세요.
{% endhint %}

## 비디오 파일 정보

다음 파일 형식을 지원합니다:

* *.mp4*
* *.ogg*
* *.webm*

비디오 파일은 장면의 전체 용량에 포함되므로 장면에 들어오는 플레이어가 장면을 다운로드하는 데 시간이 더 오래 걸립니다. 또한 비디오 용량 때문에 [장면 제한](https://docs.decentraland.org/creator/content-creator-ko/sdk7/optimizing/scene-limitations.md)을 초과할 수도 있습니다. 각 구획에 사용할 수 있는 용량은 최대 15MB입니다. 문제가 생기지 않도록 비디오를 최대한 압축하는 것을 권장합니다.

플레이어가 가까이 있을 때나 특정 동작을 수행했을 때 동영상 재생을 시작하도록 설정하는 것을 권장합니다. 장면이 로드될 때 지평선 너머 멀리 있는 동영상까지 재생하면 플레이어가 주변 장면을 방문하는 동안 불필요하게 성능에 영향을 줍니다.

## 동영상 재생, 일시 중지 및 중지

동영상 재생을 시작하거나 일시 중지하려면  `playing`  속성을  *true*  또는  *false*로 설정합니다.  `playing` 가 false로 설정되면 마지막으로 표시된 프레임에서 동영상이 일시 중지됩니다.

아래와 같이 포인터 이벤트를 추가해 화면을 토글할 수 있도록 설정할 수 있습니다.

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

동영상을 중지하고 첫 번째 프레임으로 되돌리려면  `position`  속성을 0으로 설정합니다. 다음 예제에서는 동영상을 클릭하면 동영상이 중지됩니다.

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

## 동영상 플레이어 구성

다음과 같은 선택적 속성을  `VideoPlayer`  컴포넌트에 설정할 수 있습니다.

* `playing`: 동영상이 현재 재생 중인지 여부를 지정합니다. false이면 동영상이 일시 중지됩니다.

{% hint style="warning" %}
**📔 참고**: 동시에 재생할 수 있는 동영상 수는 플레이어의 품질 설정에 따라 제한됩니다. 장면에서 이 수보다 많은 동영상을 재생하면 엔진이 우선순위가 가장 낮은 동영상을 일시 중지합니다. 자세한 내용은  [성능 고려 사항](#performance-considerations).
{% endhint %}

* `playbackRate`: 동영상 재생 속도를 변경합니다. *1* 가 기본값입니다.
* `volume`: 오디오 볼륨을 변경할 수 있습니다. *1* 가 기본값입니다.
* `position`: 동영상의 시작 위치를 다르게 설정할 수 있습니다. 동영상의 원래 시작 지점부터 경과한 초 단위로 지정합니다. *0* 기본값이며, 실제 동영상 시작 지점부터 재생됩니다.
* `loop`: 동영상을 반복 재생할지, 한 번 재생한 후 멈출지 결정하는 불리언 값입니다. *false* 기본값입니다.

## 여러 동영상 재생하기

성능 문제를 방지하려면 동시에 재생되는 서로 다른 동영상의 수를 적게 유지하세요. 엔진에서 동시에 재생할 수 있는 동영상 수는 플레이어의 품질 설정에 따라 제한됩니다(자세한 내용은  [성능 고려 사항](#performance-considerations) 참조). 하지만 하나의 장면에서 동일한 동영상 텍스처를 여러 화면에 복사해 재생할 수 있습니다. 별도의 동영상을 재생하는 경우보다 성능에 미치는 영향이 훨씬 적으므로 이 방식에는 제한이 없습니다. 여러 엔티티에서 같은 동영상을 재생하려면 동영상 텍스처 객체의 동일한 인스턴스를 각 화면 엔티티의  `Material` 컴포넌트에 할당하면 됩니다.

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

위 예제에서는 두 동영상 화면의 상태를 제어하는  `VideoPlayer` 컴포넌트를 하나만 만들면 됩니다. 이 경우 컴포넌트는  `screen1` 엔티티에 할당되지만, 화면 중 하나일 필요 없이 장면의 다른 엔티티에 할당해도 됩니다.

## 동영상 이벤트

동영상 재생 시작, 일시 정지 등의 상태 변화를 쉽게 처리할 수 있습니다. 예를 들어 동영상과 완벽하게 동기화해 애니메이션을 재생하여 동영상과 동시에 시작되도록 할 수 있습니다.

다음을 사용해 `videoEventsSystem.registerVideoEventsEntity` 엔티티에 할당된 동영상의 상태가 바뀔 때마다 실행되는 함수를 정의하세요. 상태가 바뀔 때마다 함수에서 새로운 상태를 확인하고 그에 맞게 대응할 수 있습니다.

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

// ... VideoPlayer 컴포넌트, Transform, MeshRenderer.setPlane() 등을 사용해 videoPlayerEntity 생성 ...

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
		}
	}
)
```

함수의 입력으로 전달되는 videoEvent 객체에는 다음 속성이 포함됩니다:

* `currentOffset` (*숫자*): 동영상의 `position` 속성의 현재 값입니다. 이 값은 동영상이 시작된 시점부터 경과한 시간(초)을 나타냅니다. *-1* 동영상 재생이 아직 시작되지 않은 경우.
* `state`: 새 동영상 상태이며, `VideoState` 열거형의 값으로 표시됩니다. 이 열거형은 다음 값 중 하나를 가질 수 있습니다:
  * `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` (*숫자* ): 동영상 전체 길이(초)입니다. *-1* 길이를 알 수 없는 경우.
* `timestamp` ( *숫자*): *Lamport* 타임스탬프로, 동영상 상태가 변경될 때마다 증가합니다.
* `tickNumber` (*숫자*): 씬이 실행되기 시작한 이후 경과한 틱 수로 표시한 이벤트 발생 시각입니다.

이미 콜백이 등록된 엔티티에 콜백을 다시 등록하면(예: 상태 변경 시 동작을 바꾸려는 경우), 새 콜백이 이전 콜백을 대체하고 마지막으로 보고된 상태는 유지됩니다. 따라서 이전 콜백에 이미 보고된 상태에 대해서는 새 콜백이 다시 호출되지 않습니다.

### 엔티티 등록 여부 확인

사용 `videoEventsSystem.hasVideoEventsEntity()` 를 사용해 엔티티에 동영상 이벤트 콜백이 이미 등록되어 있는지 확인하세요.

```ts
if (videoEventsSystem.hasVideoEventsEntity(videoPlayerEntity)) {
	console.log('This entity already has a video event listener')
}
```

### 최신 동영상 이벤트

다음을 사용해 동영상의 마지막 상태 변경을 조회합니다. `videoEventsSystem.getVideoState()`. 이 메서드는 해당 엔티티의 최신 `VideoEvent` 값을 반환하며, `undefined` 는 아직 이벤트가 보고되지 않은 경우에 반환됩니다. 콜백을 등록하지 않고 시스템에서 이 메서드를 호출해 매 프레임 동영상 상태를 확인할 수 있습니다.

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

	console.log(`state: ${latestVideoEvent.state}
    \ncurrentOffset: ${latestVideoEvent.currentOffset}
    \nvideoLength: ${latestVideoEvent.videoLength}`)
}
```

## 동영상의 알파 마스크

직사각형이 아닌 동영상 화면을 만드는 유용한 방법은 평면 위에 알파 텍스처를 적용하는 것입니다. 평면의 일부를 잘라 원하는 모양으로 만들 수 있습니다.

다음 이미지를 사용해 동영상을 투명한 모서리가 있는 원형으로 잘라 보세요.

![](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-ee3e152f3312f46d04d8640b44f42f1254e26f3b%2Fcircle_mask.webp?alt=media)

```ts
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,
})
```

![](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-901568ee2ece2fed1734c93716d4c7069869c47c%2Fcircular-video-screen.webp?alt=media)

{% hint style="warning" %}
**📔 참고**: 이전 버전에서는 `alphaTexture` 속성이 PBR 재질에만 있었습니다. 현재는 기본 재질에서만 작동합니다.
{% endhint %}

## glTF 모델에서 동영상 재생

다음 컴포넌트를 사용하면 *glTF* 모델에서 동영상을 재생할 수 있습니다: [GltfNodeModifiers](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/materials.md#modify-gltf-materials) 컴포넌트입니다. 자세한 내용은 [glTF 재질 수정](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/materials.md#modify-gltf-materials) 을 참조하세요.

이 기능을 사용하면 평면뿐 아니라 어떤 모양에서든 동영상을 재생할 수 있습니다. 예를 들어 곡면 화면이나 NPC의 몸 전체에서 동영상을 재생할 수 있습니다.

```ts
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,
						}),
					},
				},
			},
		},
	],
})
```

동영상 매핑은 모델이 사용하는 원래 UV 매핑을 따릅니다. 즉, 모델의 텍스처가 특정 부분에 매핑되어 있다면 동영상도 같은 부분에 매핑됩니다.

또한 `GltfNodeModifiers` 컴포넌트를 사용하면 모델 내부의 특정 메시에서만 동영상을 재생할 수 있습니다. 예를 들어 모델이 건물 전체를 차지하더라도 건물의 특정 벽에서만 동영상을 재생할 수 있습니다. 자세한 내용은 [glTF 재질 수정](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/materials.md#modify-gltf-materials) 을 참조하세요.

## 공간 오디오

기본적으로 `VideoPlayer` 컴포넌트의 동영상 오디오는 전역으로 재생되므로 장면 전체에서 일정한 음량으로 들립니다. 플레이어가 장면 밖으로 나가면 스트리밍 소리가 전혀 들리지 않습니다.

오디오를 공간화하려면 `spatial` 속성을 *true*.

```ts
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,
})
```

이제 다음 위치에서 동영상 소리가 들립니다. 이 위치는 다음을 소유한 엔티티의 위치이며, `VideoPlayer` 컴포넌트가 플레이어에 가까워질수록 소리가 커집니다.

다음 속성을 사용해 공간 오디오를 제어할 수 있습니다.

* `spatialMinDistance`: 오디오가 공간 오디오로 전환되는 최소 거리입니다. 플레이어가 이보다 가까우면 오디오가 최대 음량으로 들립니다. *0* 가 기본값입니다.
* `spatialMaxDistance`: 오디오가 들리는 최대 거리입니다. 플레이어가 이보다 멀리 있으면 오디오 음량이 0이 됩니다. *60* 가 기본값입니다

```ts
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 }),
})
```

{% hint style="warning" %}
**📔 참고**: 일부 동영상 형식은 공간 오디오를 지원하지 않습니다. 스트림이 다음 형식 중 하나로 인코딩되었는지 확인하세요. *mp4*, *m4a*또는 *mov*.
{% endhint %}

## 오디오 분석

의 오디오 트랙에서 실시간 진폭 및 주파수 데이터를 읽어 `VideoPlayer` 엔티티의 동영상 사운드트랙과 동기화되는 반응형 시각 효과를 구현할 수 있습니다. 자세한 내용은 [오디오 분석](https://docs.decentraland.org/creator/content-creator-ko/sdk7/media/audio-analysis.md).

{% hint style="info" %}
**💡 팁**: 기본 도형이 아닌 GLTF 모델에서 동영상을 재생하는 방법은 다음을 참조하세요. [`74,-8-gltfnodemodifier`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/74,-8-gltfnodemodifier) 테스트 장면에서는 `GltfNodeModifiers` 를 사용해 특정 GLTF 노드에 HLS 스트림을 적용합니다.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-ko/sdk7/media/video-playing.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
