MODELS.md

Modelos de Redes Neurais — backend/src/models

Este documento descreve as arquiteturas de modelos disponíveis para predição de intensidade háptica a partir de Mel spectrograms de stems separados.

---

Contrato de entrada e saída

Todos os modelos herdam de BaseHapticModel e devem respeitar:

Parâmetro	Shape	Descrição
Entrada	[Batch_Size, 4, N_MELS, Time_Steps]	Mel spectrograms dos 4 stems
Saída	[Batch_Size, 4]	Intensidades hápticas normalizadas [0.0, 1.0]

Os 4 canais de entrada correspondem, em ordem, a: drums, bass, vocals, other. Os 4 valores de saída correspondem às zonas: Vib_Seat, Vib_Lumbar, Vib_Neck, Vib_Arms.

---

BaseHapticModel (base_model.py)

Classe abstrata que impõe o contrato de shape e força a implementação de forward.

class BaseHapticModel(nn.Module, ABC):
    def _validate_input_shape(self, x: torch.Tensor): ...  # verifica (B, 4, mels, time)
    @abstractmethod
    def forward(self, x: torch.Tensor) -> torch.Tensor: ...

Parâmetros de validação configuráveis via config dict:

Parâmetro	Padrão
expected_channels	4
expected_mel_bins	64
expected_time_steps	50

---

CNN2DMultichannel (cnn_2d_multichannel.py)

CNN 2D que trata os stems como canais de imagem (analogia com RGB). É o modelo principal atualmente em uso.

Arquitetura

Input [B, 4, N_MELS, Time]
        │
   ConvBlock(4 → 16)     Conv2d(3×3) + BN + ReLU + MaxPool2d(2) + Dropout2d
        │
   ConvBlock(16 → 32)
        │
   ConvBlock(32 → 64)
        │
   AdaptiveAvgPool2d(1, 1)
        │
   Flatten → Linear(64→32) → ReLU → Dropout → Linear(32→4) → Sigmoid
        │
Output [B, 4]  ∈ [0.0, 1.0]

Parâmetros do construtor

Parâmetro	Padrão	Descrição
input_channels	4	Stems de entrada
output_size	4	Zonas hápticas de saída
dropout	0.3	Probabilidade de dropout (conv e classificador)

Características

• AdaptiveAvgPool2d permite qualquer combinação de N_MELS × Time_Steps — o modelo não está preso às dimensões de config.py.
• Validação de shape sobrescreve a da classe base para checar apenas rank e canais, ignorando Mel bins e time steps.
• Saída constrainada a [0.0, 1.0] pelo Sigmoid final.

Uso mínimo

from backend.src.models.cnn_2d_multichannel import CNN2DMultichannel

model = CNN2DMultichannel(input_channels=4, output_size=4, dropout=0.3)
model.eval()

x = torch.randn(8, 4, 64, 50)   # batch de 8 janelas
y = model(x)                     # shape: [8, 4]

---

Modelos planejados

Modelo	Arquivo	Status
CNN2DMultichannel	cnn_2d_multichannel.py	✅ Implementado
MultiBranchCNN	—	🔜 Planejado
TCN1D	—	🔜 Planejado

MultiBranchCNN processará cada stem em ramos independentes antes de fundir as representações. TCN1D operará diretamente sobre sequências temporais de features de áudio usando convoluções causais dilatadas.

---

Adicionando um novo modelo

1. Crie backend/src/models/meu_modelo.py.
2. Herde de BaseHapticModel.
3. Implemente forward(self, x) respeitando o contrato de shape.
4. Exporte no __init__.py do pacote models.
5. Documente aqui neste arquivo.