Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
140 lines (99 loc) · 5.04 KB

ARCHITECTURE.md

File metadata and controls

140 lines (99 loc) · 5.04 KB
Raw

Arquitetura do Pipeline de ML — backend/src

Este documento descreve a organização interna de backend/src, responsável por toda a cadeia de pré-processamento de áudio e inferência de modelos de vibração háptica.

Visão geral

Stems separados (WAV)
        │
        ▼
 audio_processing.py   ← carrega, reamostra, janela, gera Mel spectrograms
        │
        ▼
 [Num_Windows, 4, N_MELS, Time_Steps]
        │
        ▼
  models/               ← redes neurais recebem o tensor acima
        │
        ▼
 [Batch_Size, 4]        ← intensidades hápticas por zona

O pipeline assume que a separação de stems já foi realizada por outra etapa (ex.: Demucs). Cada módulo deste pacote tem responsabilidade única e não acessa a API web diretamente.

Módulos

config.py

Centraliza todos os hiperparâmetros de pré-processamento. Nenhuma constante de áudio ou modelo deve ser definida fora deste arquivo.

Parâmetros principais:

Constante Valor padrão Descrição
SAMPLE_RATE 22050 Taxa de reamostragem alvo (Hz)
N_MELS 64 Bins do Mel spectrogram
WINDOW_SECONDS 1.0 Duração de cada janela de contexto (s)
WINDOW_HOP_SECONDS 0.1 Passo entre janelas consecutivas (s)
N_FFT 1024 Tamanho da FFT
HOP_LENGTH 441 Hop do Mel spectrogram (samples)
STEM_ORDER [drums, bass, vocals, other] Ordem fixa dos canais
DEVICE cuda Dispositivo preferido (fallback: CPU)
SPECTROGRAM_TIME_STEPS WINDOW_SIZE_SAMPLES // HOP_LENGTH Passos temporais por janela

audio_processing.py

Pré-processamento de stems separados. Entrada: dicionário {stem_name: path}. Saída: tensor [Num_Windows, 4, N_MELS, Time_Steps].

Funções públicas:

Função Descrição
process_stems(stem_paths) Ponto de entrada principal; encadeia todas as etapas abaixo
load_stem(path) Carrega um stem, converte para mono e reamostra
load_stems(stem_paths) Carrega os 4 stems em paralelo e empilha em tensor padded
align_stem_lengths(stems) Apareia todos os stems ao mais curto (evita silêncio artificial)
split_stems_into_windows(stems) Divide o tensor alinhado em janelas sobrepostas
create_mel_spectrogram_windows(windows) Gera Mel spectrograms com nnAudio (log1p)
normalize_spectrograms(spectrograms) Z-score por janela e canal de stem

Exceção personalizada: AudioProcessingError (subclasse de ValueError).

dataset_loader.py

Carrega o dataset para treino a partir de um manifest.csv. Implementa torch.utils.data.Dataset com crop aleatório (data augmentation) e normalização z-score baseada em estatísticas pré-calculadas.

Classes e funções:

Nome Tipo Descrição
StemDataset Dataset Carrega chunks de 1 s de 4 stems + ground truth de vibração
compute_mel_stats() função Calcula média/std das Mels no split de treino (Welford online)
build_dataloaders() função Cria DataLoaders para train/val/test

Formato de saída de StemDataset.__getitem__:

{
    "mel":       Tensor[4, N_MELS, N_TIME_FRAMES],  # log-Mel spectrograms
    "vibration": Tensor[GT_FRAMES, N_REGIONS],       # ground truth de vibração
    "song_id":   str,
}

synthetic_stem_example.py

Script de validação de integração: gera stems sintéticos (senos de frequências determinísticas) e executa process_stems para verificar o shape do tensor de saída sem depender de áudio real.

Útil para verificar a instalação do ambiente e confirmar que as dependências de processamento de áudio estão funcionando.

python -m backend.src.synthetic_stem_example
# Synthetic stem validation passed: shape=(11, 4, 64, 50)

Subpacotes

  • models/ — arquiteturas de redes neurais
  • engine/ — avaliação e inferência

engine/

Arquivo Descrição
evaluation.py Loop de avaliação com dados sintéticos; mede MSE e latência média
inference.py Prepara tensores para inferência e carrega checkpoint do modelo

O módulo inference.py expõe:

  • prepare_inference_input(drums, bass, vocals, other) — wrapper sobre process_stems
  • prepare_inference_input_from_directory(dir) — assume nomes canônicos drums.wav etc.
  • load_inference_model(path) — carrega CNN2DMultichannel de um .pt e retorna em modo eval()

Status: a etapa de predição em batch e geração da matriz final de vibração [Total_Frames, 4] ainda está em desenvolvimento (ver TODOs em inference.py).

Dependências externas

Biblioteca Uso
torch / torchaudio Tensores, carregamento de áudio, reamostragem
nnAudio Mel spectrogram diferenciável (GPU-friendly)
librosa Fallback e utilitários de análise de áudio
pandas Leitura do manifest CSV
numpy Operações numéricas no dataset loader