🔧 Audio Preview & Spatial Placement
Visão Geral#
O sistema de Audio Preview & Spatial Placement permite a gestão e configuração de som diretamente no editor. Esta ferramenta é dividida em duas partes: a pré-visualização de assets de áudio no Asset Browser e a configuração espacial de fontes sonoras (AudioSource) dentro da cena. Os utilizadores podem visualizar a forma de onda (waveform), testar efeitos de som e música antes de os integrar no jogo.
No viewport, o editor fornece gizmos visuais para representar o alcance e o falloff do som espacializado. Isto permite que os designers ajustem com precisão onde um som deve ser ouvido e como o seu volume diminui com a distância, facilitando a criação de ambientes sonoros imersivos. Além disso, uma mesa de mistura simplificada permite o controlo de barramentos (buses) para categorias como SFX, Música e Voz.
Implementação#
A implementação utiliza a biblioteca de áudio do motor para carregar e reproduzir sons em modo de editor, com suporte para 3D attenuation.
Estrutura do Painel de Áudio#
namespace Caffeine::Editor {
class AudioPreviewPanel : public EditorPanel {
public:
AudioPreviewPanel();
void OnImGuiRender() override;
void PlayPreview(Ref<AudioAsset> asset);
void StopPreview();
private:
void RenderWaveform(Ref<AudioAsset> asset);
void RenderPlaybackControls();
void RenderMixer();
Ref<AudioAsset> m_currentAsset;
float m_volume = 1.0f;
float m_pitch = 1.0f;
bool m_isLooping = false;
// Mixagem
float m_busVolumes[4] = { 1.0f, 1.0f, 1.0f, 1.0f }; // Master, SFX, Music, Voice
};
class AudioSourceGizmo : public EditorGizmo {
public:
void OnRender(const Entity& entity, const SceneView& view) override {
if (!entity.HasComponent<AudioSourceComponent>()) return;
auto& source = entity.GetComponent<AudioSourceComponent>();
auto& transform = entity.GetComponent<TransformComponent>();
// Desenhar esfera de alcance mínimo (volume máximo)
RenderUtils::DrawWireSphere(transform.position, source.minDistance, Color::Cyan);
// Desenhar esfera de alcance máximo (silêncio)
RenderUtils::DrawWireSphere(transform.position, source.maxDistance, Color::Blue);
}
};
} // namespace Caffeine::Editor
Lógica de Visualização da Waveform (ASCII)#
A waveform é gerada processando os samples do áudio e criando um grafo de picos.
┌─────────────────────────────────────────────────────────────┐
│ Audio Asset: "explosion_01.wav" [▶] [■] [⟳] │
├─────────────────────────────────────────────────────────────┤
│ Waveform: │
│ | ||| | │
│ ||||| ||||||| ||||| || │
│ ||||||||||||||||||||||||| ||||||| │
│ ────────────────────────────────────────────────────────── │
│ 0.0s 1.5s 3.0s │
├─────────────────────────────────────────────────────────────┤
│ Settings: │
│ Volume: [----------o---] 0.8 │
│ Pitch: [------o-------] 1.0 │
│ Falloff: Linear [v] Max Dist: [ 50.0 ] │
└─────────────────────────────────────────────────────────────┘
Exemplo de Configuração de AudioSource#
void AudioEditor::ApplySettingsToSource(const Entity& entity) {
auto& source = entity.GetComponent<AudioSourceComponent>();
// Configurar parâmetros no motor de áudio
AudioEngine::SetSourcePosition(source.handle, entity.GetTransform().position);
AudioEngine::SetSourceGain(source.handle, source.volume);
AudioEngine::SetSourcePitch(source.handle, source.pitch);
AudioEngine::SetSourceAttenuation(source.handle, source.minDist, source.maxDist);
}
Decisões de Design#
| Decisão | Justificativa |
|---|---|
| Pré-visualização no Asset Browser | Permite iteração rápida sem necessidade de colocar o som na cena para o ouvir. |
| Gizmos de Distância | Essencial para visualizar o espaço 3D que o som ocupa, algo impossível de avaliar apenas com números. |
| Categorização por Buses | Facilita o balanceamento de áudio global do jogo (ex: baixar toda a música para ouvir melhor os diálogos). |
| Representação por Waveform | Ajuda a identificar visualmente o início e o fim de samples, além de detetar clipping. |
Critério de Aceitação#
- [ ] Reprodução de ficheiros de áudio (WAV, OGG, MP3) no editor.
- [ ] Visualização correta da waveform com cursor de progresso.
- [ ] Gizmos no viewport que refletem os valores de
minDistanceemaxDistance. - [ ] Controlo de volume e pitch em tempo real com efeito imediato no áudio.
- [ ] Mesa de mistura funcional para ajuste de volumes por categoria.
Dependências#
- Upstream:
docs/audio/audio-system.md(o backend de áudio propriamente dito) - Downstream:
docs/editor/scene-editor.md(para integração de gizmos)
🔗 Tópicos Relacionados#
| Tópico | Descrição |
|---|---|
| Audio Engine | O motor de som de baixo nível (ex: OpenAL, SoLoud ou FMOD). |
| Spatial Audio | Teoria de som 3D e funções de atenuação. |
| Asset Browser | Onde os assets de áudio são selecionados para preview. |
Referências#
- Documentação da API de áudio espacial (Attenuation models).
- Algoritmos para extração de RMS e picos para desenho de waveforms.
- Padrões de mistura de áudio para videojogos.