docs: add smart spectrum sync documentation

README.md

@@ -31,7 +31,7 @@
 - 🔬 **Myopic Scan** — Deep Scan restricted to selected tracks.
 - 🔊 **Silence Scan** — Analyze and identify extended periods of silence within audio tracks.
 - 🎛️ **Track Selection** — Choose which video, audio, and subtitle streams to keep in the final file.
-- 🎶 **Smart Spectrum Sync** — Automatically aligns audio tracks from different sources, using advanced waveform cross-correlation.
+- 🎶 **[Smart Spectrum Sync](docs/features/SMART_SPECTRUM_SYNC.md)** — Automatically aligns audio tracks from different sources, using advanced waveform cross-correlation.
 - ⏱️ **Sync Adjustment / End Cut** — Defines time offset and end cut to avoid lip-sync issues.
 - 🔀 **File Merging** — Merges tracks from two files into a single MKV, with automatic/manual sync and Strict Mode.
 - 🏷️ **Tag Editing** — Edits language (e.g., `por`, `eng`, `jpn`) and title for each track.
@@ -42,7 +42,7 @@
 
 - **[FFmpeg & FFprobe](https://www.ffmpeg.org/download.html)** (Installed globally on the system)
 
-## 📦 Installation (Linux)
+## 📦 Installation
 
 > [!IMPORTANT]
 > The installation script currently downloads native binaries for **Linux** (x86_64 / ARM64). macOS native binaries are coming soon! For **Windows**, use **Docker** below.
@@ -110,6 +110,8 @@ jellycc merge
 > [!NOTE]
 > By default, JellyCC merges files using **Optimized Full Repair** (extracting and aligning streams individually to prevent sync issues and trailing silence). 
 > You can choose **Legacy** mode from the menu to do a direct remux without temp files if the source streams have fully healthy structures and timestamps.
+> 
+> For automatic audio alignment between different files, see [Smart Spectrum Sync](docs/features/SMART_SPECTRUM_SYNC.md).
 
 ### Configuration
 

README.pt.md

@@ -31,7 +31,7 @@
 - 🔬 **Myopic Scan** — Deep Scan restrito apenas às faixas selecionadas.
 - 🔊 **Silence Scan** — Analisar e identificar longos períodos de silêncio nas faixas de áudio.
 - 🎛️ **Seleção de Faixas** — Escolha quais streams de vídeo, áudio e legenda manter no arquivo final.
-- 🎶 **Smart Spectrum Sync** — Alinha automaticamente faixas de áudio de origens diferentes, usando correlação matemática de ondas sonoras.
+- 🎶 **[Smart Spectrum Sync](docs/features/SMART_SPECTRUM_SYNC.pt.md)** — Alinha automaticamente faixas de áudio de origens diferentes, usando correlação matemática de ondas sonoras.
 - ⏱️ **Ajuste de Sincronia / Corte Final** — Define offset temporal e corte final para evitar problemas de lip-sync.
 - 🔀 **Mesclagem de Arquivos** — Une faixas de dois arquivos em um único MKV, com sync automático/manual e Modo Estrito.
 - 🏷️ **Edição de Tags** — Edita idioma (ex: `por`, `eng`, `jpn`) e título de cada faixa.
@@ -111,6 +111,8 @@ jellycc merge
 > [!NOTE]
 > Por padrão, o JellyCC mescla os arquivos usando o **Optimized Full Repair** (extraindo e alinhando as streams individualmente para evitar problemas de sincronização e silêncio no final).
 > Você pode escolher o modo **Legacy** no menu para fazer um remux direto sem arquivos temporários, caso as streams de origem tenham estruturas e timestamps totalmente íntegros.
+> 
+> Para alinhamento automático de áudio entre arquivos, veja o [Smart Spectrum Sync](docs/features/SMART_SPECTRUM_SYNC.pt.md).
 
 ### Configuração
 

docs/features/SMART_SPECTRUM_SYNC.md

@@ -0,0 +1,43 @@
+# 🎶 Smart Spectrum Sync
+
+Smart Spectrum Sync is a feature that automatically synchronizes audio tracks from different files, aligning audio streams when merging media with different starting points.
+
+## ✏️ Practical Example
+
+Imagine you want to merge tracks from the following files:
+
+* **File A (Main Video):** 4K WEB-DL release with excellent image quality and original English audio.
+* **File B (Dubbing Source):** Lower-quality DVD-Rip release containing Portuguese dubbing.
+
+### The Problem
+
+File B has an extra 3.5 seconds of intro/silence at the beginning compared to File A. If the dubbed track from File B is extracted and combined directly with Video A, the audio will be completely out of sync.
+
+### The Solution with Spectrum Sync
+
+1. You specify a reference point near the start of a distinctive sound effect (e.g., `00:01:15` where a door slams).
+2. Smart Spectrum Sync extracts and compares the audio signatures of both media files in that interval.
+3. The algorithm calculates that the dubbed track requires an offset of **+3500 ms** (3.5 seconds).
+4. JellyCC applies the time compensation during the final merge. The result is a dubbed track that aligns perfectly with the video, without any lag or lead.
+
+## ⚙️ How It Works
+
+The alignment process consists of three steps:
+
+1. **Audio Extraction**
+   FFmpeg extracts a snippet from each file: from File A, 10 seconds starting from the user-specified point; from File B, a 30-second window starting 10 seconds prior to that point.
+   The snippets are extracted as mono, 1000 Hz, 32-bit float (`f32le`), yielding one sample per millisecond.
+
+2. **Correlation Calculation**
+   The analyzer compares the two snippets using the [Pearson Correlation Coefficient (PCC)](https://en.wikipedia.org/wiki/Pearson_correlation_coefficient), sliding File A's sample across File B's window to find the point of highest absolute correlation.
+
+3. **Time Compensation**
+   The difference between this point and File B's initial margin provides the exact delay. The system rounds the value in milliseconds and applies it during the final merge.
+
+## 💡 Recommendations
+
+> [!TIP]
+> **Choose scenes with distinct sound effects or music:** Gunshots, explosions, stings, door slams, or isolated instrument chords offer unique waveform signatures and high correlation accuracy.
+
+> [!WARNING]
+> **Avoid snippets based solely on speech/dialogue:** Dubbing in different languages alters the audio waveform of the voice and articulation timing, which can reduce correlation accuracy.

docs/features/SMART_SPECTRUM_SYNC.pt.md

@@ -0,0 +1,43 @@
+# 🎶 Smart Spectrum Sync
+
+O Smart Spectrum Sync é um recurso que sincroniza automaticamente faixas de áudio de arquivos diferentes, alinhando trilhas de áudio quando você junta mídias com pontos de início diferentes.
+
+## ✏️ Exemplo Prático
+
+Imagine que você quer unir faixas dos seguintes arquivos:
+
+* **Arquivo A (Vídeo Principal):** Release 4K WEB-DL com excelente imagem e áudio original em inglês.
+* **Arquivo B (Fonte da Dublagem):** Release DVD-Rip de menor qualidade, porém contendo a dublagem em português.
+
+### O Problema
+
+O Arquivo B tem 3,5 segundos a mais de introdução/silêncio no início em comparação ao Arquivo A. Se a faixa dublada do Arquivo B for extraída e combinada diretamente com o vídeo A, o áudio ficará totalmente dessincronizado.
+
+### A Solução com Spectrum Sync
+
+1. Você indica um ponto de referência próximo ao início de um efeito sonoro marcante (ex: `00:01:15` onde uma porta bate).
+2. O Smart Spectrum Sync extrai e compara a assinatura sonora das duas mídias nesse intervalo.
+3. O algoritmo calcula que a faixa dublada precisa de uma compensação de **+3500 ms** (3,5 segundos).
+4. O JellyCC aplica a compensação de tempo na junção final. O resultado é uma faixa dublada que começa exatamente onde o vídeo começa, sem nenhum atraso ou adiantamento.
+
+## ⚙️ Como funciona
+
+O alinhamento acontece em três etapas:
+
+1. **Extração de áudio**
+   O FFmpeg extrai um trecho de cada arquivo: do Arquivo A, 10 segundos a partir do ponto informado pelo usuário; do Arquivo B, uma janela de 30 segundos que começa 10 segundos antes desse ponto.
+   Os trechos saem em mono, 1000 Hz, float de 32 bits (f32le), o que dá uma amostra por milissegundo.
+
+2. **Cálculo da correlação**
+   O analisador compara os dois trechos pelo [Coeficiente de Correlação de Pearson (PCC)](https://en.wikipedia.org/wiki/Pearson_correlation_coefficient), deslizando a amostra do Arquivo A sobre a janela do Arquivo B até achar o ponto de maior correlação absoluta.
+
+3. **Compensação de tempo**
+   A diferença entre esse ponto e a margem inicial do Arquivo B dá o atraso exato. O sistema arredonda o valor em milissegundos e aplica na junção final.
+
+## 💡 Recomendações de Uso
+
+> [!TIP]
+> **Escolha cenas com efeitos sonoros nítidos ou música:** Tiros, explosões, vinhetas, batidas de porta ou acordes de instrumentos isolados oferecem assinaturas de onda únicas e alta precisão de correlação.
+
+> [!WARNING]
+> **Evite trechos exclusivamente baseados em fala/diálogos:** Dublagens em idiomas diferentes alteram a forma de onda sonora da voz e os tempos de articulação, o que pode reduzir a precisão do cálculo de correlação.