Spectro

!Build Status
!License
!Version

Introdução

Spectro é uma biblioteca TypeScript para gerar espectrogramas a partir de dados de áudio (Float32Array).
Ela usa FFT com várias funções janela, possui escala Linear e Mel, colormaps inspirados no Matplotlib, filtros FIR (passa-baixa, passa-alta, passa-banda, rejeita-banda), eixo de frequência e eixo de tempo opcionais, hop size configurável, exportação PNG em alta resolução, além de detecção de pitch e extração de harmônicos.

Recursos

- Geração de espectrograma a partir de single channel Float32Array
- Parâmetros flexíveis:
- Taxa de amostragem, faixa de frequência (fMin, fMax)
- Tamanho de FFT, hop size configurável e funções janela (None, Cosine, Hanning, BH7)
- Escala Linear ou Mel (remapeamento real na exibição)
- Colormaps customizáveis
- Eixo de frequência e eixo de tempo opcionais (com ticks dinâmicos)
- Altura/largura finais do canvas (com margens dinâmicas quando eixos estão habilitados)
- Ganho (gainDb) e normalização por faixa (rangeDb) ancorada no pico global
- Exportação PNG em alta resolução (upscale configurável)
- Filtros FIR de pré-processamento: lowpass, highpass, bandpass, notch
- Pitch Tracking (autocorrelação) e extração de harmônicos
- Colormaps exportados e tipados (ex.: hot, jet, viridis, …)

Pré-requisitos

Antes de começar, certifique-se de ter as seguintes ferramentas instaladas:

- Node.js (recomendado versão LTS)
- npm (geralmente vem com o Node.js)

Instalação

Siga as etapas abaixo para configurar o projeto em sua máquina local:

1. Clone o repositório:
``bash
git clone https://github.com/IMNascimento/Spectro.git
`
2. Navegue até o diretório do projeto:
`bash
cd Spectro
`
3. Instale as dependências:
`bash
npm install
`

Configuração do TypeScript:

O arquivo tsconfig.json já está configurado para gerar módulos ES6 e arquivos de declaração (d.ts):
`json
{
"compilerOptions": {
"target": "ES5",
"module": "ES6",
"declaration": true,
"outDir": "./dist",
"strict": true,
"esModuleInterop": true,
"lib": ["dom", "es2015"]
},
"include": ["src/*/"]
}
`

Compilação

Para compilar o código TypeScript e gerar os arquivos JavaScript na pasta dist, execute:
`bash
npm run build
`

API (Visão Geral)

$3

| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---:|---|
| sampleRate | number | 44100 | Taxa de amostragem (Hz). |
| scaleType | 'Linear' \| 'Mel' | 'Linear' | Escala vertical. Em Mel, a exibição remapeia a altura do espectrograma para a escala perceptual. |
| fMin | number | 1 | Frequência mínima (Hz). |
| fMax | number | 30000 | Frequência máxima (Hz). |
| fftSize | number | 2048 | Tamanho da FFT (potência de 2). |
| hopSize | number | fftSize/2 | Passo entre frames em amostras. |
| windowType | 'None' \| 'Cosine' \| 'Hanning' \| 'BH7' | 'BH7' | Função janela. |
| colormapName | string | 'hot' | Nome do colormap (precisa existir no window). |
| canvasHeight | number | 500 | Altura do espectrograma (área útil). |
| targetWidth | number | 0 | Largura final desejada; 0 usa window.innerWidth. |
| nTicks | number | 0 | Nº de ticks de frequência (0 = cálculo dinâmico). |
| gainDb | number | 0 | Ganho em dB aplicado ao espectro. |
| rangeDb | number | 80 | Faixa em dB p/ normalização ancorada no pico global. Se 0, usa fallback seguro 80. |
| showFrequencyAxis | boolean | false | Exibe eixo de frequência (adiciona margens laterais). |
| showTimeAxis | boolean | false | Exibe eixo de tempo (adiciona margem inferior). |
| timeTickMinPx | number | 60 | Espaçamento mínimo entre ticks do eixo de tempo (px). |
| filterType | 'none' \| 'lowpass' \| 'highpass' \| 'bandpass' \| 'notch' | 'none' | Tipo de filtro FIR aplicado antes da FFT. |
| filterCutoffs | number[] | [] | Para lowpass/highpass: [cutoff]. Para bandpass/notch: [lowCut, highCut]. |
| enablePitchDetection | boolean | false | Habilita detecção de frequência fundamental (autocorrelação). |
| enableHarmonicsExtraction | boolean | false | Habilita extração de harmônicos (múltiplos inteiros da fundamental). |

$3

- generateSpectrogram(audioData: Float32Array): HTMLCanvasElement
Gera e retorna um com o espectrograma.
Obs.:
- Se showFrequencyAxis for true, são aplicadas margens laterais (60px esquerda, 10px direita).
- Se showTimeAxis for true, é aplicada margem inferior (~22px) para os rótulos.

- exportHighResPNG(audioData: Float32Array, upscale = 2): string
Renderiza o espectrograma e retorna um DataURL PNG em alta resolução (upscale = fator de ampliação).

- detectPitch(audioData: Float32Array): number
Retorna a frequência fundamental (Hz) usando autocorrelação simples (útil para pitch tracking básico).

- extractHarmonics(audioData: Float32Array): { fundamental: number; harmonics: number[] }
Calcula a fundamental e retorna os harmônicos (múltiplos inteiros), respeitando fMax.

---

Colormaps (como disponibilizar)

A lib espera funções de colormap no escopo global (window). Use o helper partial para expor:

`ts
import { partial } from '@sophialabs/spectro';

(window as any).partial = partial;
(window as any).hot = partial('hot');
(window as any).jet = partial('jet');
(window as any).viridis = partial('viridis');
(window as any).Greens = partial('Greens');
(window as any).turbo = partial('turbo');
(window as any).terrain = partial('terrain');
(window as any).RdPu = partial('RdPu');
(window as any).binary = partial('binary');
`

---

Exemplos de Uso

$3

1. Instale sua lib via npm.
`bash
npm i @sophialabs/spectro
`
2. Importe a classe em um componente Angular:
`ts
// app.component.ts
import { Component } from '@angular/core';
import { SpectrogramGenerator, SpectrogramParams, partial } from '@sophialabs/spectro';

@Component({
selector: 'app-root',
template:

,
styles: [
#container canvas {
border: 1px solid #000;
display: block;
margin: 10px auto;
}
]
})
export class AppComponent {
onFileChange(event: Event) {
const input = event.target as HTMLInputElement;
if (input.files && input.files.length) {
const file = input.files[0];
const reader = new FileReader();
reader.onload = async (e: any) => {
const arrayBuffer = e.target.result;
const audioCtx = new AudioContext();
const audioBuffer = await audioCtx.decodeAudioData(arrayBuffer);
const audioData = audioBuffer.getChannelData(0);

// Exponha os colormaps globalmente para que a lib os encontre:
(window as any).partial = partial;
(window as any).hot = partial('hot');
(window as any).jet = partial('jet');
(window as any).viridis = partial('viridis');
(window as any).Greens = partial('Greens');
(window as any).turbo = partial('turbo');
(window as any).terrain = partial('terrain');
(window as any).RdPu = partial('RdPu');
(window as any).binary = partial('binary');

// Defina os parâmetros completos com valores e comentários explicativos:
const params: SpectrogramParams = {
sampleRate: 44100, // Taxa de amostragem em Hz.
scaleType: 'Mel', // Escala de frequência ('Mel' ou 'Linear').
fMin: 1, // Frequência mínima (Hz).
fMax: 20000, // Frequência máxima (Hz).
fftSize: 2048, // Tamanho do buffer FFT (deve ser potência de 2).
windowType: 'BH7', // Função janela: 'None', 'Cosine', 'Hanning' ou 'BH7'.
colormapName: 'hot', // Nome do colormap para renderização.
canvasHeight: 500, // Altura do canvas final (px).
nTicks: 20, // Número de ticks para o eixo de frequência (0 para cálculo automático).
gainDb: 20, // Ganho em dB (0 para sem alteração).
rangeDb: 80, // Intervalo em dB para normalização (0 para manter escala original).
targetWidth: 0, // Largura final desejada (0 utiliza window.innerWidth).
showFrequencyAxis: false, // Define se o eixo de frequência será exibido.
filterType: 'none', // Tipo de filtro: 'none', 'lowpass', 'highpass', 'bandpass' ou 'notch'.
filterCutoffs: [], // Frequências de corte para o filtro (ex: [cutoff] para lowpass).
enablePitchDetection: true, // Se true, habilita a detecção de pitch (calcula a frequência fundamental).
enableHarmonicsExtraction: true // Se true, habilita a extração de harmônicos (baseada na fundamental).
};

// Cria a instância do gerador com os parâmetros definidos:
const generator = new SpectrogramGenerator(params);

// Gera o espectrograma e insere o canvas no DOM:
const canvas = generator.generateSpectrogram(audioData);
document.querySelector('#container')?.appendChild(canvas);

// Se a flag de detecção de pitch estiver habilitada, chama o método detectPitch():
if (params.enablePitchDetection) {
const fundamentalFreq = generator.detectPitch(audioData);
console.log('Frequência Fundamental detectada:', fundamentalFreq, 'Hz');
} else {
console.log('Detecção de Pitch desabilitada.');
}

// Se a flag de extração de harmônicos estiver habilitada, chama o método extractHarmonics():
if (params.enableHarmonicsExtraction) {
const { fundamental, harmonics } = generator.extractHarmonics(audioData);
console.log('Frequência Fundamental:', fundamental, 'Hz');
console.log('Harmônicos extraídos:', harmonics);
} else {
console.log('Extração de Harmônicos desabilitada.');
}
};
reader.readAsArrayBuffer(file);
}
}
}
`

3. Adicione os assets necessários:
Certifique-se de que os arquivos compilados (por exemplo, os arquivos de sua lib e os colormaps) estejam disponíveis no build final do Angular. Você pode incluí-los via assets ou importar diretamente em seus módulos.

$3

Basta importar a lib normalmente, seja via npm ou via um caminho relativo. Por exemplo, em um projeto Node.js ou um script ES:
`ts
import { SpectrogramGenerator, SpectrogramParams, partial } from '@sophialabs/spectro';

// Exponha os colormaps globalmente, se necessário:
window.hot = partial('hot');
window.jet = partial('jet');
window.viridis = partial('viridis');
window.Greens = partial('Greens');
window.turbo = partial('turbo');
window.terrain = partial('terrain');
window.RdPu = partial('RdPu');
window.binary = partial('binary');

// Criação do objeto de parâmetros, com comentários sobre cada um:
const params: SpectrogramParams = {
sampleRate: 44100, // Taxa de amostragem em Hz
scaleType: 'Mel', // Tipo de escala ('Mel' ou 'Linear')
fMin: 1, // Frequência mínima (Hz)
fMax: 30000, // Frequência máxima (Hz)
fftSize: 2048, // Tamanho do buffer FFT (deve ser potência de 2)
windowType: 'BH7', // Função janela: 'None', 'Cosine', 'Hanning' ou 'BH7'
colormapName: 'hot', // Nome do colormap usado para renderizar o espectrograma
canvasHeight: 500, // Altura do canvas final em pixels
nTicks: 30, // Número de ticks para o eixo de frequência (0 para cálculo automático)
gainDb: 10, // Ganho em dB aplicado aos dados (use 0 para manter sem alteração)
rangeDb: 20, // Intervalo em dB para normalização dos dados (0 para manter sem alteração)
targetWidth: 0, // Largura do canvas final (0 usa window.innerWidth)
showFrequencyAxis: false, // Se true, exibe o eixo de frequência no canvas
filterType: 'none', // Tipo de filtro: 'none', 'lowpass', 'highpass', 'bandpass' ou 'notch'
filterCutoffs: [], // Frequências de corte para o filtro (ex: [cutoff] para lowpass)
enablePitchDetection: true, // Habilita a detecção de pitch (retorna a frequência fundamental)
enableHarmonicsExtraction: true // Habilita a extração de harmônicos (calculados com base na fundamental)
};

// Suponha que audioData seja um Float32Array contendo os dados de áudio:
declare const audioData: Float32Array;

// Instancia a classe do gerador com os parâmetros definidos:
const generator = new SpectrogramGenerator(params);

// Gera o espectrograma e obtém o canvas resultante:
const canvas = generator.generateSpectrogram(audioData);
// Exemplo de uso: adicionar o canvas ao DOM:
document.body.appendChild(canvas);

// Se a detecção de pitch estiver habilitada, calcula a frequência fundamental:
if (params.enablePitchDetection) {
const fundamentalFreq = generator.detectPitch(audioData);
console.log('Frequência Fundamental detectada:', fundamentalFreq, 'Hz');
}

// Se a extração de harmônicos estiver habilitada, extrai os harmônicos:
if (params.enableHarmonicsExtraction) {
const { fundamental, harmonics } = generator.extractHarmonics(audioData);
console.log('Frequência Fundamental:', fundamental, 'Hz');
console.log('Harmônicos extraídos:', harmonics);
}

// Opcional: Exporta uma imagem PNG de alta resolução do espectrograma (fator de ampliação = 3)
const pngDataUrl = generator.exportHighResPNG(audioData, 3);
console.log('PNG de alta resolução:', pngDataUrl);
`

$3

Para testar a lib em uma página web:

1. Crie um arquivo index.html na raiz do projeto (ou utilize o exemplo fornecido abaixo).

2. Utilize um servidor local para servir os arquivos (por exemplo, com http-server). Se ainda não tiver o http-server instalado globalmente, instale-o via npm:
`bash
npm install -g http-server
`
3. Na raiz do projeto, execute:
`bash
http-server .
`
4. Acesse a URL fornecida (por exemplo, http://127.0.0.1:8080/) no navegador.

> Importante: não abra via file://. Sirva com um servidor local (ex.: http-server .).

Exemplo de index.html

`html

Teste da Lib Spectro - Completo

Carregar arquivo de áudio:

Escala:

Linear
Mel

fMin / fMax (Hz):

FFT / Hop:

2048
4096
8192


(hop em amostras; deixe ~fft/2 para começo)

Janela / Colormap:

None
Cosine
Hanning
BH7


hot
jet
viridis
Greens
turbo
terrain
RdPu
binary

Dimensões:


(0 usa window.innerWidth)

Ticks / Eixos:

Eixo de Frequência
Eixo de Tempo

Ganho / Faixa (dB):

Filtro:

none
lowpass
highpass
bandpass
notch


Para low/high: [cutoff]. Para band/notch: [low,high].

Pitch Tracking
Harmônicos

Gerar Espectrograma

`

Dicas / Solução de problemas

- CORS em file://: Sempre sirva via http:// (ex.: http-server .).
- Cache do navegador: se estiver testando alterações locais, anexe um query param ao import:
./dist/index.es.js?v=\${Date.now()}.
- Função não encontrada após build: confirme que está importando do dist gerado e que o servidor está servindo o arquivo atualizado (sem cache).

---

Changelog (resumo)

1.6.9
- Eixo de tempo opcional com espaçamento de ticks automático (showTimeAxis, timeTickMinPx).
- Hop size configurável (hopSize).
- Escala Mel real na exibição (remapeamento vertical correto).
- Normalização em dB ancorada no pico global com rangeDb (fallback seguro para 80).
- Export PNG em alta resolução (exportHighResPNG).
- Filtros FIR: lowpass, highpass, bandpass, notch`.
- Pitch tracking e extração de harmônicos.

---

Contribuindo

Contribuições são bem-vindas! Por favor, siga as diretrizes em CONTRIBUTING.md para fazer um pull request.

Licença

Distribuído sob a licença MIT. Veja LICENSE para mais informações.

Autores

Igor Nascimento - Desenvolvedor Principal - IMNascimento

Agradecimentos

Gostaríamos de expressar nossa sincera gratidão à empresa SophiaLabs pelo apoio inestimável no desenvolvimento de códigos open source. Sua dedicação incansável em fortalecer nossa comunidade e impulsionar o universo open source é uma fonte de constante inspiração.

Agradecemos, também, a Deus, cuja graça e orientação têm sido fundamentais em cada passo desta jornada, possibilitando conquistas e o contínuo aprimoramento de nossos projetos.

Muito obrigado a todos que, de alguma forma, colaboram para tornar esse trabalho possível.