Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

비디오 재생

Godot는 VideoStreamPlayer 노드로 비디오 재생을 지원합니다.

지원되는 플랫폼

코어에서 지원되는 유일한 형식은 선택적 Ogg Vorbis 오디오 트랙이 있는 **Ogg Theora**(Ogg Vorbis 오디오와 혼동하지 마세요)입니다. 확장이 추가 형식을 지원하는 것이 가능합니다.

H.264와 H.265는 둘 다 소프트웨어 특허에 의해 보호되기 때문에 핵심 Godot에서 지원될 수 없습니다. AV1은 로열티가 없지만 CPU에서 디코딩하는 속도가 느리고 아직 사용 중인 모든 GPU에서 하드웨어 디코딩 지원을 쉽게 사용할 수는 없습니다.

WebM은 Godot 3.x에서 핵심적으로 지원되었지만 버그가 너무 많고 유지 관리가 어려웠기 때문에 4.0에서 지원이 제거되었습니다.

참고

Ogg 컨테이너 내 데이터에 대한 일반 확장인 .ogg 또는 .ogx 확장자가 있는 비디오를 찾을 수 있습니다.

이 파일 확장자의 이름을 .ogv``로 바꾸면 비디오를 Godot로 가져올 수 *될 수도 있습니다*. 그러나 ``.ogg 또는 .ogx 확장자를 가진 모든 파일이 비디오는 아닙니다. 일부 파일에는 오디오만 포함될 수 있습니다.

VideoStreamPlayer 설정하기

  1. 만들기 만들기 새 노드 대화 상자를 사용하여 VideoStreamPlayer 노드입니다.

  2. Timer 노드를 선택한 상태에서 인스펙터로 이동하여 자동 시작 속성을 활성화합니다.

    • 아직 Ogg Theora 형식의 비디오가 없다면 :ref:`doc_playing_videos_recommended_theora_encoding_settings`로 이동하세요.

  3. 씬이 로드되자마자 비디오를 재생하려면 인스펙터에서 **Autoplay**를 선택하세요. 그렇지 않은 경우 **자동 재생**을 비활성화한 상태로 두고 스크립트에서 VideoStreamPlayer 노드의 ``play()``를 호출하여 원할 때 재생을 시작합니다.

시그널 다루기

기본적으로 VideoStreamPlayer는 비디오 해상도에 맞게 크기가 자동으로 조정됩니다. VideoStreamPlayer 노드에서 **확장**을 활성화하여 일반적인 Control 크기 조정을 따르도록 할 수 있습니다.

창 크기에 따라 VideoStreamPlayer 노드의 크기가 조정되는 방식을 조정하려면 2D 편집기 뷰포트 상단에 있는 레이아웃 메뉴를 사용하여 앵커를 조정하세요. 그러나 이 설정은 비디오를 왜곡하지 않고 전체 화면 비디오를 재생하는 등의 모든 사용 사례를 처리할 만큼 강력하지 않을 수 있습니다(대신 가장자리에 빈 공간이 있음). 더 많은 제어를 위해 이러한 종류의 사용 사례를 처리하도록 설계된 AspectRatioContainer 노드를 사용할 수 있습니다.

AspectRatioContainer 노드를 추가합니다. 다른 컨테이너 노드의 하위가 아닌지 확인하세요. AspectRatioContainer 노드를 선택한 다음 2D 편집기 상단의 **Layout**을 **Full Rect**로 설정합니다. AspectRatioContainer 노드에서 **비율**을 설정하여 동영상의 가로 세로 비율과 일치시킵니다. 검사기에서 수학 공식을 사용하여 도움을 받을 수 있습니다. 피연산자 중 하나를 부동 소수점으로 만드는 것을 잊지 마세요. 그렇지 않으면 나누기 결과는 항상 정수가 됩니다.

편집기 검사기에서 수정되는 AspectRatioContainer의 Ratio 속성

이는 (대략) 1.777778로 평가됩니다.

AspectRatioContainer를 구성한 후에는 VideoStreamPlayer 노드를 AspectRatioContainer 노드의 하위 항목으로 다시 지정하세요. VideoStreamPlayer에서 **확장**이 활성화되어 있는지 확인하세요. 이제 왜곡을 피하면서 전체 화면에 맞게 비디오 크기가 자동으로 조정됩니다.

더 보기

프로젝트에서 다양한 종횡비를 지원하는 방법에 대한 추가 팁은 :ref:`doc_multiple_resolutions`를 참조하세요.

3D 표면에 비디오 표시

VideoStreamPlayer 노드를 SubViewport 노드의 하위로 사용하면 3D 표면에 2D 노드를 표시할 수 있습니다. 예를 들어, 프레임별 애니메이션에 너무 많은 메모리가 필요할 때 애니메이션 광고판을 표시하는 데 사용할 수 있습니다.

적 씬은 다음 노드들을 사용할 것입니다:

  1. 만들기 및 SubViewport 노드. 동영상 크기(픽셀)와 일치하도록 크기를 설정하세요.

  2. 만들기 VideoStreamPlayer 노드 *SubViewport 노드*의 하위 항목으로 여기에 비디오 경로를 지정합니다. **확장**이 비활성화되어 있는지 확인하고 필요한 경우 **자동재생**을 활성화하세요.

  3. Mesh 속성에 PlaneMesh 또는 QuadMesh 리소스가 있는 만들기 MeshInstance3D 노드. 비디오의 종횡비에 맞게 메시 크기를 조정합니다(그렇지 않으면 왜곡되어 나타납니다).

  4. 만들기 GeometryInstance3D 섹션의 Material Override 속성에 새로운 StandardMaterial3D 리소스가 있습니다.

  5. StandardMaterial3D의 리소스 섹션(하단)에서 **Local To 씬**를 활성화합니다. 이는 Albedo Texture 속성에서 ViewportTexture를 사용하기 전에 *필수*입니다.

  6. StandardMaterial3D에서 Albedo > Texture 속성을 New ViewportTexture**로 설정합니다. 새 리소스를 클릭하여 편집한 다음 **뷰포트 Path 속성에서 SubViewport 노드에 대한 경로를 지정합니다.

  7. 색상이 바래지는 것을 방지하려면 StandardMaterial3D에서 **Albedo Texture Force sRGB**를 활성화하세요.

  8. 빌보드가 자체적으로 빛을 발산해야 하는 경우 **Shading Mode**를 **Unshaded**로 설정하여 렌더링 성능을 향상시킵니다.

이를 설정하는 것에 대한 자세한 정보는 뷰포트 사용하기와 3D 데모에서의 GUI를 참조하세요.

비디오 루프하기

비디오를 반복하려면 Loop 속성을 활성화할 수 있습니다. 이렇게 하면 비디오가 끝나면 원활하게 다시 시작됩니다.

프로젝트 설정 **비디오 지연 보상**을 0이 아닌 값으로 설정하면 루프가 원활하지 않게 될 수 있습니다. 오디오와 비디오의 동기화가 각 루프의 시작 부분에서 발생하여 가끔 프레임 누락이 발생하기 때문입니다. 프레임 드롭 문제를 방지하려면 프로젝트 설정에서 **비디오 지연 보상**을 **0**으로 설정하세요.

재생 제한 사항

glTF 내보내기에는 몇 가지 제약이 있습니다.

  • URL에서 비디오 스트리밍은 지원되지 않습니다.

  • 모노 및 스테레오 오디오 출력만 지원됩니다. 4, 5.1, 7.1 오디오 채널의 비디오는 지원되지만 스테레오로 다운믹스됩니다.

크로마키 비디오

일반적으로 "그린 스크린" 또는 "블루 스크린" 효과로 알려진 크로마 키를 사용하면 이미지나 비디오에서 특정 색상을 제거하고 다른 배경으로 바꿀 수 있습니다. 이 효과는 다양한 요소를 원활하게 결합하기 위해 비디오 제작에 널리 사용됩니다.

../../_images/chroma_key_video.webp

GDScript에서 사용자 정의 셰이더를 작성하고 VideoStreamPlayer 노드를 사용하여 비디오 콘텐츠를 표시함으로써 크로마 키 효과를 얻을 것입니다.

씬 설정

씬에는 비디오를 재생하는 VideoStreamPlayer 노드가 포함되어 있고 크로마 키 효과를 제어하기 위한 UI 요소를 보유하는 Control 노드가 포함되어 있는지 확인하세요.

../../_images/chroma_key_scene.webp

셰이더 개선하기

크로마키 효과를 구현하려면 다음 단계를 따르세요.

  1. 씬에서 VideoStreamPlayer 노드를 선택하고 해당 속성으로 이동합니다. CanvasItem > Material 아래에 "ChromaKeyShader.gdshader"라는 이름의 새 셰이더를 만듭니다.

  2. "ChromaKeyShader.gdshader" 파일에서 아래와 같이 사용자 정의 셰이더 코드를 작성합니다.

shader_type canvas_item;

// Uniform variables for chroma key effect
uniform vec3 chroma_key_color : source_color = vec3(0.0, 1.0, 0.0);
uniform float pickup_range : hint_range(0.0, 1.0) = 0.1;
uniform float fade_amount : hint_range(0.0, 1.0) = 0.1;

void fragment() {
    // Get the color from the texture at the given UV coordinates
    vec4 color = texture(TEXTURE, UV);

    // Calculate the distance between the current color and the chroma key color
    float distance = length(color.rgb - chroma_key_color);

    // If the distance is within the pickup range, discard the pixel
    // the lesser the distance more likely the colors are
    if (distance <= pickup_range) {
        discard;
    }

    // Calculate the fade factor based on the pickup range and fade amount
    float fade_factor = smoothstep(pickup_range, pickup_range + fade_amount, distance);

    // Set the output color with the original RGB values and the calculated fade factor
    COLOR = vec4(color.rgb, fade_factor);
}

셰이더는 거리 계산을 사용하여 크로마 키 색상에 가까운 픽셀을 식별하고 이를 삭제하여 선택한 색상을 효과적으로 제거합니다. 크로마키 색상에서 약간 떨어진 픽셀은 fade_factor에 따라 페이드되어 주변 색상과 부드럽게 혼합됩니다. 이 과정을 통해 원하는 크로마키 효과가 생성되어 마치 배경이 다른 이미지나 비디오로 대체된 것처럼 보입니다.

위의 코드는 크로마 키 셰이더의 간단한 데모를 나타내며 사용자는 특정 요구 사항에 따라 이를 사용자 정의할 수 있습니다.

Control

사용자가 크로마 키 효과를 실시간으로 조작할 수 있도록 Control 노드에 슬라이더를 만들었습니다. Control 노드의 스크립트에는 다음 기능이 포함되어 있습니다.

 extends Control

 func _on_color_picker_button_color_changed(color):
     # Update the "chroma_key_color" shader parameter of the VideoStreamPlayer's material.
     $VideoStreamPlayer.material.set("shader_parameter/chroma_key_color", color)

 func _on_h_slider_value_changed(value):
     # Update the "pickup_range" shader parameter of the VideoStreamPlayer's material.
     $VideoStreamPlayer.material.set("shader_parameter/pickup_range", value)

 func _on_h_slider_2_value_changed(value):
     # Update the "fade_amount" shader parameter of the VideoStreamPlayer's material.
     $VideoStreamPlayer.material.set("shader_parameter/fade_amount", value)

func _on_video_stream_player_finished():
     # Restart the video playback when it's finished.
     $VideoStreamPlayer.play()

또한 슬라이더 범위가 적절한지 확인하십시오. 설정은 다음과 같습니다.

../../_images/slider_range.webp

입력

연결 UI 요소의 적절한 시그널에서 Control 노드의 스크립트까지. 크로마키 효과를 제어하기 위해 Control 노드의 스크립트에서 생성했습니다. 이러한 시그널 핸들러는 사용자 입력에 응답하여 셰이더의 균일 변수를 업데이트합니다.

씬을 저장하고 실행하여 크로마키 효과가 실제로 나타나는지 확인하세요! 제공된 UI 컨트롤을 사용하면 이제 크로마 키 색상, 픽업 범위 및 페이드 양을 실시간으로 조정하여 비디오 콘텐츠에 대해 원하는 크로마 키 기능을 얻을 수 있습니다.