O módulo de Pré-Masterização é responsável pela normalização de loudness (LUFS) e preparação de áudio para análise comparativa na pipeline do Produce.it. Ele resolve o problema fundamental de comparar mixagens não finalizadas com masters comerciais, garantindo que as análises posteriores sejam realizadas em níveis de volume equiparados.
A Pré-Masterização ocorre na Etapa 1 da pipeline principal, sendo o primeiro processamento aplicado aos arquivos de áudio:
1. Pré-Masterização (LUFS) → 2. Campo Estéreo → 3. Análise Espectral
# Em src/pipeline.py - Etapa 1
orig_lufs, new_lufs, mastered_path = self.lufs_analyzer.master_to_reference(
user_track_path,
ref_track_path,
tmp_dir=self.output_dir
)O módulo recebe a faixa original do usuário e a referência, calcula a diferença de LUFS, aplica normalização e gera um arquivo temporário masterizado que será usado nas etapas subsequentes.
Contém a classe principal para análise e normalização de loudness.
init(equal_threshold=0.01)
- Inicializa analisador com threshold de igualdade configurável
- Define precisão mínima para considerar dois arquivos equivalentes em LUFS
- Padrão de 0.01 LUFS garante comparações precisas
read_lufs(file_path)
- Lê arquivo de áudio e calcula LUFS integrado
- Converte áudio estéreo para mono automaticamente
- Utiliza pyloudnorm para medição precisa segundo padrão ITU-R BS.1770
- Retorna valor LUFS como float
compare(file_a, file_b)
- Compara LUFS de dois arquivos de áudio
- Calcula diferença e determina qual arquivo é mais alto
- Retorna dicionário completo com métricas e ganhos necessários
- Base para decisões de normalização
master_to_reference(user_file, reference_file, tmp_dir=None)
- Função principal de masterização/normalização
- Aplica ganho digital para igualar LUFS da referência
- Implementa proteção contra clipping (limitação a 0.9999)
- Gera arquivo temporário masterizado para análises posteriores
- Retorna tupla (LUFS_original, LUFS_novo, caminho_temporário)
process(original, reference, tmp_dir=None)
- Pipeline completo de análise e masterização
- Executa comparação antes e depois da normalização
- Fornece relatório detalhado do processo
- Função de alto nível para uso standalone
Classe para anotação e persistência de dados LUFS em formato CSV.
init(lufs_analyzer=None, sr=44100)
- Inicializa anotador com analyzer opcional
- Define sample rate de fallback para casos especiais
- Permite reutilização de instância LUFSAnalyzer existente
_compute_lufs(path)
- Método interno para cálculo de LUFS com fallback
- Tenta usar analyzer principal, recorre a librosa se necessário
- Garante robustez em diferentes formatos de áudio
annotate_lufs(user_path, ref_path, output_dir="annotations")
- Computa LUFS para ambos os arquivos
- Calcula diferença e organiza dados em estrutura CSV
- Cria diretórios de saída automaticamente
- Salva dados em formato tabular para análise posterior
- Retorna dicionário com dados e caminho do arquivo
O módulo implementa o padrão internacional para medição de loudness:
- Medição integrada ao longo de todo o arquivo
- Ponderação por frequência (filtro K-weighting)
- Gating para ignorar passagens muito silenciosas
- Resultado em LUFS (Loudness Units relative to Full Scale)
# Aplicação de ganho linear para igualar LUFS
normalized = pyln.normalize.loudness(audio, original_lufs, target_lufs)
# Proteção contra clipping
if max_abs > 1.0:
normalized = normalized / max_abs * 0.9999# Criação segura de arquivo temporário
suffix = os.path.splitext(user_file)[1] or ".wav"
fd, tmp_path = tempfile.mkstemp(suffix=suffix, dir=tmp_dir)
os.close(fd)- Validação de leitura de arquivos de áudio
- Verificação de cálculos LUFS
- Proteção contra falhas de escrita
- Cleanup automático em caso de erro
{
"lufs_a": float, # LUFS do arquivo usuário
"lufs_b": float, # LUFS do arquivo referência
"difference": float, # Diferença (ref - user)
"result": str, # "a", "b", ou "equal"
"gain_a_to_match_b": float, # Ganho necessário (dB)
"gain_b_to_match_a": float # Ganho inverso (dB)
}{
"csv_path": str, # Caminho do arquivo CSV
"user_song": str, # Caminho da música usuário
"ref_song": str, # Caminho da referência
"user_lufs": float, # LUFS usuário (1 decimal)
"ref_lufs": float, # LUFS referência (1 decimal)
"lufs_diff": float # Diferença (1 decimal)
}# Tupla retornada por master_to_reference
(
original_lufs: float, # LUFS antes da normalização
new_lufs: float, # LUFS após normalização
tmp_path: str # Caminho do arquivo masterizado
)# Em AnalysisPipeline.__init__()
self.lufs_analyzer = LUFSAnalyzer(equal_threshold=0.01)
self.csv_annotator = AudioCSVAnnotator(self.lufs_analyzer)# Leitura de LUFS originais
orig_lufs = self.lufs_analyzer.read_lufs(user_track_path)
target_lufs = self.lufs_analyzer.read_lufs(ref_track_path)
# Comparação antes da masterização
comparison = self.lufs_analyzer.compare(user_track_path, ref_track_path)
# Normalização para referência
orig_lufs, new_lufs, mastered_path = self.lufs_analyzer.master_to_reference(
user_track_path, ref_track_path, tmp_dir=self.output_dir
)# Criação de CSV com dados LUFS
csv_result = self.csv_annotator.annotate_lufs(user_track_path, ref_track_path)Cenário Típico: Comparar mixagem caseira (-18 LUFS) com master comercial (-8 LUFS) Solução: Normalização temporária da mixagem para -8 LUFS antes das análises
- Identifica diferenças de volume entre mixagem e referência
- Calcula ganho exato necessário para equiparação
- Valida se normalização foi aplicada corretamente
- Garante comparação justa em análises posteriores (estéreo, espectral)
- Elimina bias de volume nas métricas de similaridade
- Permite foco em características qualitativas, não quantitativas
- Verifica se arquivo masterizado mantém integridade
- Detecta problemas de clipping ou distorção
- Documenta processo de normalização para auditoria
- Cria registros CSV para análise estatística
- Facilita comparações em lote de múltiplas faixas
- Permite tracking de tendências de loudness
- numpy: Operações matemáticas e processamento de arrays
- soundfile: Leitura e escrita de arquivos de áudio
- pyloudnorm: Implementação do padrão LUFS ITU-R BS.1770
- pandas: Manipulação de dados tabulares para CSV
- librosa: Fallback para processamento de áudio alternativo
- Conversão automática estéreo→mono reduz processamento
- Reutilização de instâncias LUFSAnalyzer evita reinicialização
- Gestão eficiente de arquivos temporários
- Cálculos LUFS otimizados via pyloudnorm
- Arquivos temporários consomem espaço em disco
- Normalização é não-destrutiva (não altera originais)
- Precisão limitada pelo padrão LUFS (não considera aspectos perceptuais)
- Processamento sequencial (não paralelizado)
Padrão internacional para medição de loudness percebido:
- Baseado em pesquisa psicoacústica
- Correlaciona melhor com percepção humana que RMS ou Peak
- Usado em broadcast, streaming e masterização
Filtro de ponderação que simula resposta auditiva:
- Atenua frequências muito graves e muito agudas
- Enfatiza faixa de maior sensibilidade (1-5kHz)
- Parte integral do algoritmo LUFS
Processo de exclusão de passagens silenciosas:
- Absolute Gate: -70 LUFS (remove silêncio absoluto)
- Relative Gate: -10 LU abaixo da média (remove pausas)
- Garante medição apenas de conteúdo musical relevante
- Normalização: Ajuste linear de ganho (preserva dinâmica)
- Masterização: Processamento complexo (compressão, EQ, limitação)
- O módulo aplica normalização para comparação justa, não masterização artística