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...

Reproduzindo videos

O Godot oferece suporte à reprodução de vídeo por meio do nó VideoStreamPlayer.

Formatos de reprodução suportados

O único formato suportado nativamente é Ogg Theora (não deve ser confundido com o áudio Ogg Vorbis), com faixas opcionais de áudio Ogg Vorbis. Extensões podem adicionar suporte a formatos adicionais.

H.264 e H.265 não podem ser suportados no núcleo do Godot, pois ambos estão protegidos por patentes de software. O AV1 é isento de royalties, mas permanece lento para decodificar na CPU e o suporte de decodificação de hardware ainda não está disponível em todas as GPUs em uso.

O WebM era suportado nativamente no Godot 3.x, mas o suporte foi removido na versão 4.0 por ser muito instável e difícil de manter.

Nota

Você pode encontrar vídeos com as extensões .ogg ou .ogx, que são extensões genéricas para dados armazenados em um contêiner Ogg.

Renomear essas extensões de arquivo para .ogv talvez possa permitir que os vídeos sejam importados no Godot. No entanto, nem todos os arquivos com extensões .ogg ou .ogx são vídeos - alguns deles podem conter apenas áudio.

Configurando o VideoStreamPlayer

  1. Crie um nó VideoStreamPlayer utilizando a janela Create New Node.

  2. Selecione o nó VideoStreamPlayer na árvore da cena, vá até o Inspetor e carregue um arquivo .ogv na propriedade Stream.

  3. Se desejar que o vídeo seja reproduzido assim que a cena for carregada, marque Autoplay no Inspetor. Caso contrário, deixe Autoplay desabilitado e chame play() no nó VideoStreamPlayer por meio de um script para iniciar a reprodução quando desejado.

Lidando com redimensionamento e diferentes proporções

Por padrão, o VideoStreamPlayer será redimensionado automaticamente para corresponder à resolução do vídeo. Você pode fazê-lo seguir o comportamento normal de dimensionamento de um Control habilitando Expand no nó VideoStreamPlayer.

Para ajustar como o nó VideoStreamPlayer será redimensionado de acordo com o tamanho da janela, ajuste as âncoras usando o menu Layout no topo da viewport do editor 2D. Entretanto, essa configuração pode não ser suficiente para todos os casos de uso, como reproduzir vídeos em tela cheia sem distorção (mas mantendo espaços vazios nas bordas). Para obter mais controle, você pode usar um nó AspectRatioContainer, projetado especificamente para esse tipo de situação:

Adicione um nó AspectRatioContainer. Certifique-se de que não seja filho de nenhum outro nó de contêiner. Selecione o nó AspectRatioContainer e defina seu Layout na parte superior do editor 2D como Full Rect. Defina Ratio no nó AspectRatioContainer para corresponder à proporção do seu vídeo. Você pode usar fórmulas matemáticas no inspetor para se ajudar. Lembre-se de transformar um dos operandos em float. Caso contrário, o resultado da divisão será sempre um número inteiro.

A propriedade Ratio de AspectRatioContainer sendo modificada no inspetor do editor

Isso avaliará para (aproximadamente) 1,777778

Após configurar o AspectRatioContainer, torne o nó VideoStreamPlayer um filho dele. Certifique-se de que Expand esteja habilitado no VideoStreamPlayer. Agora o vídeo deverá se ajustar automaticamente à tela inteira sem sofrer distorções.

Ver também

Consulte Resoluções múltiplas para mais dicas sobre suporte a múltiplas proporções de tela em seu projeto.

Exibindo um vídeo em uma superfície 3D

Utilizando um nó VideoStreamPlayer como filho de um nó SubViewport, é possível exibir qualquer nó 2D em uma superfície 3D. Por exemplo, isso pode ser usado para exibir painéis animados quando uma animação quadro a quadro consumiria memória demais.

Isto pode ser feito com as seguintes etapas:

  1. Crie um nó SubViewport. Defina seu tamanho para corresponder ao tamanho do vídeo em pixels.

  2. Crie um nó VideoStreamPlayer como filho do nó SubViewport e especifique o caminho para um vídeo. Certifique-se de que Expand esteja desabilitado e habilite Autoplay, se necessário.

  3. Crie um nó MeshInstance3D com um recurso PlaneMesh ou QuadMesh atribuído à propriedade Mesh. Redimensione a malha para corresponder à proporção do vídeo (caso contrário, ele aparecerá distorcido).

  4. Crie um novo recurso StandardMaterial3D na propriedade Material Override da seção GeometryInstance3D.

  5. Habilite Local To Scene na seção Resource do StandardMaterial3D (na parte inferior). Isso é obrigatório antes de poder utilizar uma ViewportTexture na propriedade Albedo Texture.

  6. No StandardMaterial3D, defina a propriedade Albedo > Texture como New ViewportTexture. Edite o novo recurso clicando nele e então especifique o caminho para o nó SubViewport na propriedade Viewport Path.

  7. Habilite Albedo Texture Force sRGB no StandardMaterial3D para evitar que as cores fiquem desbotadas.

  8. Se o painel deve emitir sua própria luz, defina Shading Mode como Unshaded para melhorar o desempenho da renderização.

Veja Usando Viewports e o GUI em demonstração 3D para mais informações sobre a configuração desta instalação.

Reproduzindo um vídeo em loop

Para colocar um vídeo em loop, a propriedade Loop pode ser ativada. Isso reiniciará o vídeo perfeitamente quando ele chegar ao fim.

Note que definir a configuração de projeto Video Delay Compensation para um valor diferente de zero pode fazer com que o seu loop não seja contínuo, porque a sincronização de áudio e vídeo ocorre no início de cada loop, causando perda ocasional de quadros. Defina Video Delay Compensation em suas configurações de projeto como 0 para evitar problemas de queda de quadros.

Limitações de reprodução

Existem algumas limitações na implementação atual de reprodução de vídeo no Godot:

  • A transmissão de um vídeo de um URL não é suportada.

  • Apenas a saída de áudio mono e estéreo é suportada. Vídeos com 4, 5.1 e 7.1 canais de áudio são suportados, mas são misturados (down-mixed) para estéreo.

Vídeos com Chroma Key

O Chroma key, comumente conhecido como efeito "tela verde" ou "tela azul", permite remover uma cor específica de uma imagem ou vídeo e substituí-la por outro plano de fundo. Esse efeito é amplamente utilizado na produção de vídeo para compor diferentes elementos de forma integrada.

../../_images/chroma_key_video.webp

We will achieve the chroma key effect by writing a custom shader in GDScript and using a VideoStreamPlayer node to display the video content.

Configuração da cena

Ensure that the scene contains a VideoStreamPlayer node to play the video and a Control node to hold the UI elements for controlling the chroma key effect.

../../_images/chroma_key_scene.webp

Escrevendo o shader personalizado

Para implementar o efeito chroma key, siga estas etapas:

  1. Select the VideoStreamPlayer node in the scene and go to its properties. Under CanvasItem > Material, create a new shader named "ChromaKeyShader.gdshader."

  2. No arquivo "ChromaKeyShader.gdshader", escreva o código do shader personalizado conforme mostrado abaixo:

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

O shader usa o cálculo de distância para identificar os pixels próximos à cor do chroma key e os descarta, removendo efetivamente a cor selecionada. Os pixels que estão ligeiramente mais distantes da cor do chroma key são esmaecidos com base no fade_factor, misturando-os suavemente com as cores ao redor. Esse processo cria o efeito chroma key desejado, fazendo parecer que o plano de fundo foi substituído por outra imagem ou vídeo.

O código acima representa uma demonstração simples do shader Chroma Key, e os usuários podem personalizá-lo de acordo com suas necessidades específicas.

Controles de interface

To allow users to manipulate the chroma key effect in real-time, we created sliders in the Control node. The Control node's script contains the following functions:

 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()

certifique-se também de que o intervalo dos controles deslizantes seja apropriado, nossas configurações são:

../../_images/slider_range.webp

Manipulação de sinais

Connect the appropriate signal from the UI elements to the Control node's script. you created in the Control node's script to control the chroma key effect. These signal handlers will update the shader's uniform variables in response to user input.

Salve e execute a cena para ver o efeito chroma key em ação! Com os controles de UI fornecidos, agora você pode ajustar a cor do chroma key, o intervalo de seleção (pickup range) e a quantidade de desfoque (fade amount) em tempo real, alcançando a funcionalidade de chroma key desejada para o seu conteúdo de vídeo.