Caffeine

🔧 Audio Preview & Spatial Placement

Planned Milestone: M4 — Advanced Tools & Polish Namespace: `Caffeine::Editor` Arquivos: `src/editor/AudioEditor.hpp`, `src/editor/AudioEditor.cpp` RF: RF6.4 Last updated:

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#

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

text
┌─────────────────────────────────────────────────────────────┐
│ 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#

cpp
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 minDistance e maxDistance.
  • [ ] 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.