Plugin de legendas e legendas ocultas

O que é?

Um plugin do Unreal Engine projetado para oferecer suporte a legendas, legendas ocultas e descrições de cenas dissociadas do áudio. Por exemplo, essas novas legendas podem ser acessadas de qualquer outro sistema, independentemente da duração de qualquer ativo de áudio relacionado ou do estado de reprodução. Este novo sistema de legendas substituirá e tornará obsoleto o sistema existente, que não suporta o uso independente de legendas a partir de sons. É possível personalizar o tempo de exibição das legendas, fontes, cores, etc.

Onde ele fica?

\Engine\Plugins\Experimental\SubtitlesAndClosedCaptions

Incluir: #include SubtitlesSubsystem.h

Para carregar o plugin no Editor, vá em Editar > Plugins, na aba que abrir digite o nome ou role até Legendas e Legendas Ocultas, marque a caixa de seleção e clique em Reiniciar o Editor.

Como usar?

Cada legenda é armazenado como uma UCLASS USubtitleAssetUserData derivada de UAssetUserData e pode ser subclassificada para armazenar dados personalizados adicionais em qualquer objeto de ativo do Unreal.

Membros do USubtitleAssetUserData

Texto: o FText localizável que aparece na legenda.

• Várias linhas de texto são suportadas usando Shift + Enter ou incluindo \n no texto para especificar novas linhas.

• Os FTexts são localizados para o idioma atual no cliente usando a implementação de hashkey do sistema de localização – a localização ocorre antes e independentemente do sistema de legendas.

Duração: tempo para exibir a legenda em segundos.     

• Padrão: 3 segundos.

• Deve ser >= 0,05 segundos.

• Somente habilitado quando o Tipo de Duração estiver definido como UseDurationProperty.

Tipo de duração: pode ser definido como UseDurationProperty, que habilita a propriedade Duração, ou como UseSoundDuration para parar automaticamente quando um som anexado termina.  

• UseSoundDuration só funciona quando a legenda é adicionada como um AssetUserData a um ativo SoundBase.

StartOffset: deslocamento de tempo em segundos para iniciar a exibição da linha de legenda.  

• Isso pode ser usado para simplificar a exibição de várias legendas por ativo de áudio, por exemplo um SoundWave longo com várias frases pode usar várias legendas, cada uma com StartOffset definido como o deslocamento de tempo do início de cada frase.

• Padrão: 0 segundos.

Prioridade: se várias legendas forem reproduzidas simultaneamente, somente aquelas com prioridade mais alta (maior valor) serão reproduzidas em vez daquelas com valores menores.

• Isso se aplica mesmo que as legendas se sobreponham apenas parcialmente. A sobreposição é determinada a partir de StartOffset e duração.

• Se uma nova legenda for definida para ser exibida imediatamente ou via StartOffset enquanto uma legenda de prioridade mais alta estiver sendo exibida, a legenda de prioridade mais baixa não será exibida.

• Somente uma de cada categoria (legenda, descrição de áudio, etc.) será exibida por vez.

• Se duas legendas concorrentes tiverem a mesma prioridade, a mais antiga na fila continuará sendo exibida. Sempre que uma legenda na fila não é exibida devido a um conflito de prioridade, um aviso é enviado ao log de depuração.

• Padrão: 1.

ESRB: classificação ESRB da categoria de legenda. Este é um conjunto de campos descritivos usado por desenvolvedores de jogos.  

• Permite que o chamador determine se uma linha de legenda deve ser exibida verificando esse valor. 

• Padrão: ESRB::Everyone.

SubtitleType: especifica se o ativo é uma Legenda, ClosedCaption, ou AudioDescription.  Este é um campo descritivo definido pelos desenvolvedores de jogos.

• Permite que o chamador determine se uma linha de legenda deve ser exibida verificando esse valor.

• Cada SubtitleType tem parâmetros de exibição independentes definidos por meio de um widget TextBlock documentado abaixo.

• Quando exibidos, diferentes tipos de legendas são posicionados de forma que não se sobreponham.

Parâmetros de exibição

As legendas são exibidas usando um widget TextBlock:

1. No Unreal Editor, vá em Editar > Configurações de Projeto, role até Jogo, clique em Legendas e Legendas Ocultas.

2. No menu, use o menu suspenso para selecionar DefaultSubtitleWidget.

3. Clique no ícone Navegar até o Ativo para visualizar o widget.

   

4. Clique duas vezes no widget para abri-lo.

5. O widget de legenda padrão permite parâmetros de exibição independentes (por exemplo, posicionamento, fonte, cor, opacidade, etc.) para legendas, legendas ocultas e descrições de áudio. Clique duas vezes na caixa de texto das legendas para abrir a aba Detalhes.

   

Acesso ao Blueprint

Além dos parâmetros do widget USubtitleAssetUserData e TextBlock, a seguinte API é exposta para uso por C++ e Blueprints:

QueueSubtitle(const FQueueSubtitleParameters&, const ESubtitleTiming Timing = ESubtitleTiming::InternallyTimed)

Onde FQueueSubtitleParameters contém:

1. A legenda, um USubtitleAssetUserData, documentado acima.

2. Um parâmetro opcional para substituir a duração do ativo.

   Se a legenda já estiver sendo exibida ativamente, a duração da legenda ativa será atualizada para a duração especificada.

Sincronia

Defina como ESubtitleTiming::ExternallyTimed para controlar o enfileiramento e a expiração de uma legenda manualmente, em vez de usar a duração da legenda.  As legendas temporizadas externamente permanecerão ativas indefinidamente, até serem removidas manualmente com StopSubtitle().  Para cenários de Sequencer envolvendo dilatação ou distorção de tempo, é melhor usar ESubtitleTiming::ExternallyTimed e enfileirar e parar as legendas manualmente. Ao enfileirar várias legendas, a mais recente da prioridade mais alta é exibida.

Exibindo legendas geradas dinamicamente

FText de fontes arbitrárias (e.g. replicado dinamicamente de um servidor multijogador) pode ser exibido como legendas. Exemplo:

USubtitlesSubsystem* Subsystem = NewObject<USubtitlesSubsystem>(pWorld, NAME_None, RF_Transient);

check(Subsystem != nullptr);

USubtitleAssetUserData* Subtitle = NewObject<USubtitleAssetUserData>(GetTransientPackage(), NAME_None, RF_Transient);

check(Subtitle != nullptr);
Subtitle->Text = <arbitrary FText input>;

const UAssetUserData& AssetUserData = *CastChecked<const UAssetUserData>(Subtitle);

Sequencer

Arraste seu ativo de legenda para uma faixa de legenda no Sequencer. As propriedades da legenda podem ser editadas clicando com o botão direito do mouse na legenda e selecionando Propriedades. No Sequencer, a duração da legenda é controlada pelo intervalo de seleção inicial e final, e não pela propriedade de duração.

Localização

O sistema de legendas oferece suporte à localização por meio de sua propriedade localizável FText.  Os FTexts são localizados para o idioma atual no cliente usando a implementação de hashkey do sistema de localização – a localização ocorre antes e independentemente do sistema de legendas.  Consulte Localização de conteúdo no Unreal Engine | Documentação do Unreal Engine 5.5 | Comunidade de desenvolvedores da Epic.

Guia de Migração

A Ferramenta de Migração copia os dados de legenda em um determinado DialogueWave e/ou SoundWave para o novo tipo de ativo Legenda. Ele coloca o novo ativo no DialogueWave e/ou AssetUserData do SoundWave fornecido. As legendas já migradas serão atualizadas se o DialogueWave e/ou SoundWave fornecido for migrado novamente.  Entretanto, se a nova migração não resultar em nenhuma alteração, o ativo de destino não será marcado como sujo e não precisará ser salvo novamente no disco.

A migração não é destrutiva; legendas antigas e novas serão exibidas automaticamente por padrão, permitindo que o usuário controle qual conteúdo será usado.

Exibir configurações de parâmetros (por exemplo, fonte, cor, etc.) não faze parte atualmente da ferramenta de migração.  Eles são definidos por categoria por meio das configurações do widget TextBlock documentadas acima.

Como migrar SoundWaves

Para usar a ferramenta, selecione um ou mais ativos SoundWave no Navegador de Conteúdo. Em seguida, clique com o botão direito, localize o submenu Ações do Editor de Script e selecione Criar Legenda.  Isso criará novos USubtitleAssetUserData para os SoundWave que contêm os dados de legenda migrados.

Quando desejado, é possível remover dados do antigo sistema de legendas da seguinte maneira:

1. No Navegador de Conteúdo, selecione um ou mais ativos SoundWave.

2. Clique com o botão direito do mouse e encontre o submenu Ações do Editor de Script.

3. Selecione Remover legendas legadas, o que esvazia a matriz de legendas antiga...

   

Como migrar DialogueWaves

Após migrar o SoundWave associado a um DialogueWave, use o comando do console au.UseNewSubtitles 1 para vê-lo com este plugin de legendas. Você pode voltar a usar o conteúdo original e o sistema de legendas configurando a variável de console de volta ao seu padrão de 0.

Observações de desempenho

O uso do disco varia ligeiramente entre o sistema antigo e o novo, com as legendas migradas para o novo sistema exigindo aproximadamente 16 bytes a mais por legenda (80 bytes no sistema antigo, para 96 bytes no novo) quando estiverem na fila para exibição.

Antes (80 bytes por legenda na fila):

• FQueueSubtitleParams: 56 bytes

• FSubtitleCue: múltiplos de 24 bytes. Considerando apenas um destes para esta comparação.

Depois (96 bytes por legenda na fila):

• FQueueSubtitleParameters: 16 bytes

• USubtitleAssetUserData: 80 bytes

Legendas que não estiverem na fila na memória não usam as estruturas FQueueSubtitleParameters, então legendas "em massa" mostram uma diferença maior de 24 bytes (antigo) a 80 bytes (novo), com uma diferença de 56 bytes devido às propriedades e recursos adicionais.

Fonte da ferramenta de migração

Caso sejam necessárias modificações na ferramenta de migração, ela pode ser encontrada na pasta do plugin de legendas: SubtitlesAndClosedCaptions/Content/EditorUtilities/CreateSubtitlesFromSoundWaves.uasset

Assim como o restante do novo plugin de legendas, a ferramenta de migração está atualmente marcada como experimental.