# yuki-jp/wavesync architecture

> Architecture diagram of the GitHub repository yuki-jp/wavesync, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yuki-jp/wavesync
- Repository: https://github.com/yuki-jp/wavesync

## Overview

WaveSync is a desktop multicamera audio/video synchronizer that exports an FCP XML timeline for Premiere. The main workflow is selecting reference audio and camera videos, synchronizing them, saving the XML, and importing it into Premiere. The graph also shows configuration, DSP and evidence validation, audit/layout reporting, diagnostics, and the documented update check. Some internal links are based on the SOURCE INDEX and README; unsampled implementation details are not inferred beyond those relationships.

Main entry points: [`main.py`](https://github.com/yuki-jp/wavesync/blob/main/main.py) (Sync Engine), [`WaveSync.py`](https://github.com/yuki-jp/wavesync/blob/main/WaveSync.py) (WaveSync UI), [`backend/audio_processor.py`](https://github.com/yuki-jp/wavesync/blob/main/backend/audio_processor.py) (Audio DSP), [`backend/sync_evidence.py`](https://github.com/yuki-jp/wavesync/blob/main/backend/sync_evidence.py) (Sync Evidence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Desktop Interface"]
  node_gui["WaveSync UI<br/>[WaveSync.py]"]
  node_config["Config Builder<br/>[make_config.py]"]
end

subgraph group_sync["Synchronization"]
  node_engine["Sync Engine<br/>[main.py]"]
  node_dsp["Audio DSP<br/>[audio_processor.py]"]
  node_evidence["Sync Evidence<br/>[sync_evidence.py]"]
end

subgraph group_outputs["Timeline and Reports"]
  node_xml["Premiere XML<br/>[xml_generator.py]"]
  node_audit["Sync Audit<br/>[audit_report.py]"]
  node_layout["Audio Layout Report"]
end

subgraph group_support["Support and Updates"]
  node_diagnostics["Diagnostic Package and Upload<br/>[diagnostics.py]"]
end

node_user(("User"))
node_local[("Local Outputs and Cache")]
node_premiere["Adobe Premiere"]
node_relay["Support Relay"]
node_github["GitHub Version Check"]

node_user -->|"selects media"| node_gui
node_gui -->|"builds selection config"| node_config
node_gui -->|"starts sync"| node_engine
node_engine -->|"extracts and correlates audio"| node_dsp
node_engine -->|"validates placements"| node_evidence
node_evidence -->|"decodes samples"| node_dsp
node_engine -->|"generates timeline"| node_xml
node_engine -->|"creates audit reports"| node_audit
node_engine -->|"creates layout report"| node_layout
node_dsp -->|"caches WAV and features"| node_local
node_xml -->|"writes XML"| node_local
node_audit -->|"writes audit files"| node_local
node_layout -.->|"writes layout reports"| node_local
node_user -->|"imports XML"| node_premiere
node_gui -->|"creates and sends package"| node_diagnostics
node_diagnostics -->|"uploads package"| node_relay
node_gui -->|"checks for updates"| node_github

click node_gui "https://github.com/yuki-jp/wavesync/blob/main/WaveSync.py"
click node_config "https://github.com/yuki-jp/wavesync/blob/main/tools/make_config.py"
click node_engine "https://github.com/yuki-jp/wavesync/blob/main/main.py"
click node_dsp "https://github.com/yuki-jp/wavesync/blob/main/backend/audio_processor.py"
click node_evidence "https://github.com/yuki-jp/wavesync/blob/main/backend/sync_evidence.py"
click node_xml "https://github.com/yuki-jp/wavesync/blob/main/backend/xml_generator.py"
click node_audit "https://github.com/yuki-jp/wavesync/blob/main/backend/audit_report.py"
click node_layout "https://github.com/yuki-jp/wavesync/blob/main/backend/audio_layout_report.py"
click node_diagnostics "https://github.com/yuki-jp/wavesync/blob/main/backend/diagnostics.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gui,node_config,node_user toneBlue
class node_engine,node_dsp,node_evidence,node_local toneAmber
class node_xml,node_audit,node_layout toneMint
class node_diagnostics toneRose
class node_premiere,node_relay,node_github toneIndigo
```

## Components

### Desktop Interface

- [WaveSync UI](https://github.com/yuki-jp/wavesync/blob/main/WaveSync.py): `WaveSync.py`
- [Config Builder](https://github.com/yuki-jp/wavesync/blob/main/tools/make_config.py): `tools/make_config.py`

### Synchronization

- [Sync Engine](https://github.com/yuki-jp/wavesync/blob/main/main.py): `main.py`
- [Audio DSP](https://github.com/yuki-jp/wavesync/blob/main/backend/audio_processor.py): `backend/audio_processor.py`
- [Sync Evidence](https://github.com/yuki-jp/wavesync/blob/main/backend/sync_evidence.py): `backend/sync_evidence.py`

### Timeline and Reports

- [Premiere XML](https://github.com/yuki-jp/wavesync/blob/main/backend/xml_generator.py): `backend/xml_generator.py`
- [Sync Audit](https://github.com/yuki-jp/wavesync/blob/main/backend/audit_report.py): `backend/audit_report.py`
- [Audio Layout Report](https://github.com/yuki-jp/wavesync/blob/main/backend/audio_layout_report.py): `backend/audio_layout_report.py`

### Support and Updates

- [Diagnostic Package and Upload](https://github.com/yuki-jp/wavesync/blob/main/backend/diagnostics.py): `backend/diagnostics.py`

### Other components

- **User**
- **Local Outputs and Cache**
- **Adobe Premiere**
- **Support Relay**
- **GitHub Version Check**

## Connections

- User → WaveSync UI: selects media (evidence: `README.md`)
- WaveSync UI → Config Builder: builds selection config (evidence: `WaveSync.py`)
- WaveSync UI → Sync Engine: starts sync (evidence: `WaveSync.py`)
- Sync Engine → Audio DSP: extracts and correlates audio (evidence: `main.py`)
- Sync Engine → Sync Evidence: validates placements (evidence: `main.py`)
- Sync Evidence → Audio DSP: decodes samples (evidence: `backend/sync_evidence.py`)
- Sync Engine → Premiere XML: generates timeline (evidence: `main.py`)
- Sync Engine → Sync Audit: creates audit reports (evidence: `main.py`)
- Sync Engine → Audio Layout Report: creates layout report (evidence: `main.py`)
- Audio DSP → Local Outputs and Cache: caches WAV and features (evidence: `backend/audio_processor.py`)
- Premiere XML → Local Outputs and Cache: writes XML (evidence: `README.md`)
- Sync Audit → Local Outputs and Cache: writes audit files (evidence: `README.md`)
- Audio Layout Report → Local Outputs and Cache: writes layout reports
- User → Adobe Premiere: imports XML (evidence: `README.md`)
- WaveSync UI → Diagnostic Package and Upload: creates and sends package (evidence: `WaveSync.py`)
- Diagnostic Package and Upload → Support Relay: uploads package (evidence: `README.md`)
- WaveSync UI → GitHub Version Check: checks for updates (evidence: `README.md`)