From 4865e68a0d809f417656ca704d393f37e5fce49b Mon Sep 17 00:00:00 2001 From: Patrick Luan Date: Fri, 14 Aug 2026 21:57:05 -0300 Subject: [PATCH] docs: add smart spectrum sync documentation --- README.md | 6 ++-- README.pt.md | 4 ++- docs/features/SMART_SPECTRUM_SYNC.md | 43 +++++++++++++++++++++++++ docs/features/SMART_SPECTRUM_SYNC.pt.md | 43 +++++++++++++++++++++++++ 4 files changed, 93 insertions(+), 3 deletions(-) create mode 100644 docs/features/SMART_SPECTRUM_SYNC.md create mode 100644 docs/features/SMART_SPECTRUM_SYNC.pt.md diff --git a/README.md b/README.md index 2a73044..f26a831 100644 --- a/README.md +++ b/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 diff --git a/README.pt.md b/README.pt.md index 40e737f..f7e02c6 100644 --- a/README.pt.md +++ b/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 diff --git a/docs/features/SMART_SPECTRUM_SYNC.md b/docs/features/SMART_SPECTRUM_SYNC.md new file mode 100644 index 0000000..be702cf --- /dev/null +++ b/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. diff --git a/docs/features/SMART_SPECTRUM_SYNC.pt.md b/docs/features/SMART_SPECTRUM_SYNC.pt.md new file mode 100644 index 0000000..d56fda9 --- /dev/null +++ b/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. \ No newline at end of file