Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 79 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
name: Audio or GUI bug
description: Report a reproducible ArSonComp issue with technical context.
title: "[Bug] "
labels: [bug]
body:
- type: markdown
attributes:
value: |
Please describe the problem without sharing private account data, tokens, or passwords. Check if it also occurs with host bypass.
- type: dropdown
id: os
attributes:
label: Operating system
options:
- Windows 10/11
- Ubuntu / Debian
- Other Linux
- macOS Apple Silicon
- macOS Intel
validations:
required: true
- type: dropdown
id: format
attributes:
label: Plugin format
options:
- VST3 in a host
- Standalone
validations:
required: true
- type: input
id: version
attributes:
label: ArSonComp version/build
placeholder: v0.2.0-rc.1
validations:
required: true
- type: input
id: host
attributes:
label: DAW/host and version
placeholder: Reaper, Studio One, ArSonMiX, or Standalone
- type: input
id: driver
attributes:
label: Audio device / driver / rate / buffer
placeholder: Maono PS22 / ASIO / 48 kHz / 128 samples
- type: textarea
id: reproduce
attributes:
label: Steps to reproduce
description: Include current preset, routing, bypass, sidechain, and automation when relevant.
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected result
validations:
required: true
- type: textarea
id: actual
attributes:
label: Actual result
description: Include any audible glitch, host xrun count, visual collision, error dialog, or crash.
validations:
required: true
- type: textarea
id: evidence
attributes:
label: Audio, screenshots, logs
description: Attach only non-sensitive evidence when available.
- type: checkboxes
id: checks
attributes:
label: Isolation (when relevant)
options:
- label: Tried host bypass with the same routing.
- label: Tried the same host path without ArSonComp.
61 changes: 61 additions & 0 deletions .github/workflows/sync-public-screenshots.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
name: Import verified GUI screenshots

on:
pull_request:
types: [opened, synchronize, reopened]
paths:
- README.md
- docs/PRODUCT-SHOWCASE.md
- .github/workflows/sync-public-screenshots.yml

permissions:
contents: write
actions: read

jobs:
screenshots:
if: >-
github.event.pull_request.head.repo.full_name == github.repository &&
github.event.pull_request.head.ref == 'docs/m8-public-showcase'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
ref: docs/m8-public-showcase
persist-credentials: true
- name: Retrieve screenshot images from successful JUCE Windows CI
env:
GH_TOKEN: ${{ github.token }}
SOURCE_RUN: "41267899861"
shell: bash
run: |
set -euo pipefail
source_dir="$RUNNER_TEMP/arsoncomp-screenshot-source"
mkdir -p "$source_dir" docs/images
gh run download "$SOURCE_RUN" --repo "$GITHUB_REPOSITORY" \
--name ArSonComp-Windows-x64-ReadyToTest --dir "$source_dir"
grep -F "actions/runs/$SOURCE_RUN" "$source_dir/BUILD-INFO.txt"
test -s "$source_dir/Plugin/ArSonComp.vst3/Contents/x86_64-win/ArSonComp.vst3"
cp "$source_dir/Screenshots/ArSonComp-preview.png" docs/images/arsoncomp-full.png
cp "$source_dir/Screenshots/ArSonComp-preview-minimum.png" docs/images/arsoncomp-minimum.png
cp "$source_dir/Screenshots/ArSonComp-preview-sidechain.png" docs/images/arsoncomp-sidechain.png
cp "$source_dir/Screenshots/ArSonComp-preview-compact.png" docs/images/arsoncomp-mini.png
cp "$source_dir/Screenshots/ArSonComp-preview-browser.png" docs/images/arsoncomp-presets.png
for png in docs/images/arsoncomp-*.png; do
test -s "$png"
file "$png" | grep -q "PNG image data"
echo "Verified screenshot: $(basename "$png") ($(wc -c < "$png") bytes)"
done
- name: Save real screenshots in public PR branch
shell: bash
run: |
set -euo pipefail
git add docs/images/arsoncomp-*.png
if git diff --cached --quiet; then
echo "All screenshots already match the source CI run"
exit 0
fi
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git commit -m "docs: embed actual M7 Windows JUCE screenshots"
git push origin HEAD:docs/m8-public-showcase
30 changes: 30 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# Contributing to ArSonComp

We welcome focused fixes, reproducible issues, compatibility improvements and evidence-based audio engineering contributions.

## Before opening an issue

Check existing [issues](https://github.com/masarray/arson-comp/issues) and [pull requests](https://github.com/masarray/arson-comp/pulls). Audio bug reports should include host and version, OS, VST3/Standalone, driver, interface, sample rate, buffer length, routing, settings, reproducible steps and actual xrun/audio results. Attach non-sensitive audio recordings or host logs when possible. Visual reports should include actual application screenshots at default/minimum DPI.

## Engineering expectations

- Keep the C++17 DSP in `engine/` independent of JUCE; `plugin/` adapts host IO, parameters and GUI.
- Do not allocate, lock, wait, open files or touch GUI from the real-time processing callback.
- Preserve existing APVTS parameter IDs, host recall and zero additional algorithmic sample latency in the default path.
- Changes to compression quality require deterministic numerical tests, loudness-matched listening, and reproducible benchmarks rather than undocumented similarity claims.
- UI work must verify actual JUCE render screenshots; favor compact, legible, responsive, professional interfaces, not design mockups in place of real software.
- Do not assert glitch-free hardware/ASIO behavior from synthetic CI engine tests.

## Validation

For an initial engine-only build:

```sh
cmake -S . -B build -DARSON_BUILD_PLUGIN=OFF -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel 2
ctest --test-dir build --output-on-failure
```

GUI changes require VST3/Standalone smoke and screenshot review. Keep pull requests cohesive, explain user-facing benefits and identify remaining manual checks.

[Architecture](docs/ARD.md) · [Release gates](docs/RELEASE-STATUS.md) · [Engineering contract](AGENTS.md) · [AGPL-3.0](LICENSE).
133 changes: 72 additions & 61 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,72 +1,83 @@
# ArSonComp

ArSonComp is a lightweight real-time dynamics compressor for vocals,
karaoke, streaming and music, written in C++17 with a reusable JUCE-free
audio engine and a JUCE 8 VST3/Standalone interface.

## Download for Windows, Linux and macOS

**[GitHub Releases](https://github.com/masarray/arson-comp/releases)**

- **Windows 10/11 x64:** Inno Setup EXE. Choose *Just me* (no admin) or
*All users*. Installs VST3 and Standalone by default, Start Menu/uninstaller.
- **Ubuntu/Debian x86_64:** DEB installer with VST3 and Standalone.
- **Other desktop Linux x86_64:** portable archive with no-sudo
per-user install/uninstall scripts.
- **macOS Apple Silicon + Intel:** universal VST3 and Standalone in a PKG.
Ad-hoc code signed; unsigned/not-notarized PKG may trigger Gatekeeper.

See [installer guide](docs/INSTALL-PUBLIC.md) for exact steps, install
locations, limitations and Mac security instructions.

### Features

Original Clean/Feedback/Smooth causal compressor styles; Peak/RMS detection;
external mono/stereo sidechain, adjustable detector HP/LP, wet/dry Mix,
Auto Release, adjustable Range, stereo Link and sidechain listen.
46 original factory presets, user preset Save/Open, A/B, APVTS automation
and project restore. The compact 612×580 full GUI has a tall black-glass
transfer/history/meter LCD, brushed graphite chassis and approved silver
hardware-style sliders. MINI and separate Dynamics/Sidechain panels are
available. The host reports **zero additional algorithmic samples**;
actual audio device/driver round-trip latency is separate.

### Platform verification and releases

The cross-platform release workflow builds VST3 and Standalone on Windows,
Linux and macOS, performs automated engine/editor smoke tests, creates
Inno Setup / DEB / portable archive / ad-hoc PKG, and publishes SHA-256
manifests. The initial public tag is a **release candidate** until physical
DAW and audio-interface results, ASIO/JUCE licensing review and (for
frictionless Mac distribution) Developer ID notarization are complete.
A public CI artifact alone is not certified production-stable.

See [Windows physical test quickstart](docs/WINDOWS-QUICKSTART.md),
[hardware readiness](docs/M7-PHYSICAL-READINESS.md), and
[validation](docs/VALIDATION.md). Real-device Maono PS22 crackles/underruns,
32/64/128 buffers, multiple hosts, pluginval, long-session memory and
loudness-matched quality are separate release gates.

### Build locally

CMake 3.22+, C++17, JUCE 8.0.12 pinned to a verified commit.
Visual Studio 2022 C++ Desktop on Windows; Xcode on macOS; JUCE Linux
dependencies from [JUCE official documentation](https://github.com/juce-framework/JUCE/blob/master/docs/Linux%20Dependencies.md).
**Real-time dynamics for vocals, music, podcasts, streaming, and live mixing.**

[![Cross-platform packages](https://github.com/masarray/arson-comp/actions/workflows/release-installers.yml/badge.svg)](https://github.com/masarray/arson-comp/actions/workflows/release-installers.yml)
[![Tests](https://github.com/masarray/arson-comp/actions/workflows/build.yml/badge.svg)](https://github.com/masarray/arson-comp/actions/workflows/build.yml)
[![Release Candidate](https://img.shields.io/badge/release-v0.2.0--rc.1-orange)](https://github.com/masarray/arson-comp/releases/tag/v0.2.0-rc.1)
[![AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)

ArSonComp is an open-source compressor built with a reusable C++17 DSP engine and JUCE 8 interface. Use it as a **VST3 plug-in** in your DAW/mixer or run it **Standalone**. The default signal path introduces **zero algorithmic samples of latency**; audio-interface, driver, and host-buffer latency still exist.

<p align="center">
<a href="docs/images/arsoncomp-full.png"><img src="docs/images/arsoncomp-full.png" width="612" alt="Real ArSonComp Windows JUCE screenshot showing a large dark transfer and live history graph, stereo level meters, compact silver hardware-style knobs, and a brushed-metal chassis."></a>
</p>
<p align="center"><sub>Actual Windows JUCE editor screenshot from M7 • Full mode 612 × 580</sub></p>

## Get ArSonComp

**[Download v0.2.0-rc.1 — official GitHub Release](https://github.com/masarray/arson-comp/releases/tag/v0.2.0-rc.1)**

| Operating system | One-click / recommended package | Installer behavior |
| --- | --- | --- |
| **Windows 10/11 x64** | [Inno Setup EXE](https://github.com/masarray/arson-comp/releases/download/v0.2.0-rc.1/ArSonComp-0.2.0-Windows-x64-Setup.exe) | VST3 + Standalone; per-user or all-users; uninstall support |
| **Ubuntu / Debian x86_64** | [DEB package](https://github.com/masarray/arson-comp/releases/download/v0.2.0-rc.1/ArSonComp-0.2.0-Ubuntu-Debian-amd64.deb) | Install through system Software Center |
| **Other desktop Linux x86_64** | [Portable tar.gz](https://github.com/masarray/arson-comp/releases/download/v0.2.0-rc.1/ArSonComp-0.2.0-Linux-x86_64-Portable.tar.gz) | Per-user install/uninstall scripts, no sudo |
| **macOS 11+ · Intel and Apple Silicon** | [Universal PKG](https://github.com/masarray/arson-comp/releases/download/v0.2.0-rc.1/ArSonComp-0.2.0-macOS-Universal-AdHoc.pkg) | VST3 + Standalone; ad-hoc signed, **not notarized** |

[macOS VST3-only ZIP](https://github.com/masarray/arson-comp/releases/download/v0.2.0-rc.1/ArSonComp-0.2.0-macOS-VST3-Universal.zip) · [SHA-256 checksums](https://github.com/masarray/arson-comp/releases/download/v0.2.0-rc.1/SHA256SUMS.txt) · [Installation guide](docs/INSTALL-PUBLIC.md)

After installing, restart/rescan your VST3 host and look for **ArSonComp**. The Mac installer may show Gatekeeper warnings because it is not Apple notarized. Do not disable Gatekeeper globally.

## Why ArSonComp

- **Three original causal compressor models:** Clean, Feedback and Smooth.
- **Useful dynamics:** Threshold, Ratio, Knee, Attack, Hold, Release, Range, Input, Makeup, stereo Link and parallel Mix.
- **Flexible detector:** Peak/RMS, mono/stereo external sidechain, HP/LP detector filtering, and Listen SC.
- **See what's happening:** live compression transfer/history LCD with independent input, gain reduction and output meters.
- **Fast preset workflow:** 46 original factory presets, categorized search, favorites, A/B, user Save/Open, host automation and state recall.
- **Live-friendly UI:** Full/MINI modes and separate Dynamics/Sidechain pages; matte graphite brushed-metal body, silver control artwork.
- **Real-time DSP:** framework-independent core, bounded telemetry queue, no GUI work or filesystem operations in the audio callback.

## Screenshots — real software, not concept art

| Dynamics at minimum size | Sidechain controls |
| :---: | :---: |
| [![Minimum GUI](docs/images/arsoncomp-minimum.png)](docs/images/arsoncomp-minimum.png) | [![Sidechain GUI](docs/images/arsoncomp-sidechain.png)](docs/images/arsoncomp-sidechain.png) |

| MINI workflow | Factory preset browser |
| :---: | :---: |
| [![MINI layout](docs/images/arsoncomp-mini.png)](docs/images/arsoncomp-mini.png) | [![Preset browser](docs/images/arsoncomp-presets.png)](docs/images/arsoncomp-presets.png) |

[Open the full GUI gallery and screenshot provenance](docs/PRODUCT-SHOWCASE.md).

## First sound

1. Insert the VST3 on a vocal/music channel, or open Standalone and configure the real input/output device.
2. Choose **Clean**, start around **2:1**, and lower Threshold until the GR meter shows roughly **3–6 dB**.
3. Adjust Makeup for safe output headroom. Compare Active and Bypass at similar perceived loudness.
4. Enable Sidechain only when detector filtering or an external signal is needed.

Start physical audio testing at **48 kHz / 128 samples** and move to 64/32 only when stable. See the [hardware test guide](docs/WINDOWS-QUICKSTART.md).

## Release quality and transparency

**v0.2.0-rc.1 is a public Release Candidate — not a certified production-stable audio release.** The [cross-platform CI run](https://github.com/masarray/arson-comp/actions/runs/41273600039) passed Windows, Linux and macOS builds/tests/packaging. CI does not prove glitch-free audio on physical interfaces or all DAWs, independent pluginval certification, commercially matched sound quality, or notarized macOS installation.

[Current release status](docs/RELEASE-STATUS.md) · [Validation record](docs/VALIDATION.md) · [Architecture](docs/ARD.md) · [Report a problem](https://github.com/masarray/arson-comp/issues/new/choose) · [Contributing](CONTRIBUTING.md)

## Build and licensing

Requires CMake 3.22+, C++17 and JUCE 8.0.12 pinned to a verified commit. Visual Studio 2022 (Windows), Xcode (macOS), or [JUCE Linux dependencies](https://github.com/juce-framework/JUCE/blob/master/docs/Linux%20Dependencies.md).

```sh
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel 2
ctest --test-dir build --output-on-failure
```

Windows Visual Studio uses `cmake -S . -B build -A x64` and
`cmake --build build --config Release`. The Windows Standalone enables
native ASIO by default; review the Steinberg SDK terms when redistributing.
For Visual Studio use `cmake -S . -B build -A x64` and build/test with `--config Release`.

### License and compliance
License: [AGPL-3.0](LICENSE). Respect JUCE and Steinberg ASIO licensing/redistribution requirements. ArSonComp's source, DSP and GUI are original; references to other commercial compressors indicate design goals, **not** sonic equivalence or affiliation.

ArSonComp is AGPL-3.0 licensed; JUCE has its own AGPL/commercial licensing
terms. The Windows Standalone includes Steinberg ASIO SDK-related code
when ARSON_WINDOWS_ASIO=ON. Review its SDK redistribution terms for any
public binary release. No FabFilter code/graphics/algorithms are copied,
and equal sound quality with commercial software is not claimed.
Built by [ArSon Audio](https://github.com/masarray).
39 changes: 39 additions & 0 deletions docs/PRODUCT-SHOWCASE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# ArSonComp — interface gallery

All images below are **actual screenshots captured by the Windows JUCE editor smoke test**, not AI illustrations or visual mockups. The latest interface-changing source is M7; the subsequent v0.2.0-rc.1 installer work did not change the GUI.

**Provenance:** [Windows run #41267899861](https://github.com/masarray/arson-comp/actions/runs/41267899861), which includes the test executable and screenshot bundle.

## Full editor — 612 × 580 px

![ArSonComp full-size editor with transfer graph, meters, and hardware controls](images/arsoncomp-full.png)

The black-glass area displays the transfer curve and real input/output/gain-reduction telemetry, with primary compression controls immediately beneath the screen.

## Minimum — 580 × 540 px

![Responsive ArSonComp minimum editor](images/arsoncomp-minimum.png)

Responsive layout retains essential controls and a readable full graph without enlarging the window unnecessarily.

## Sidechain

![ArSonComp sidechain page](images/arsoncomp-sidechain.png)

The tab exposes detector HP/LP filters, Peak/RMS selection, external sidechain and Listen controls. Switching tabs does not change active audio parameters.

## MINI

![ArSonComp MINI mode](images/arsoncomp-mini.png)

A shorter control-oriented view, with the same native control bindings.

## Preset browser

![ArSonComp factory preset browser](images/arsoncomp-presets.png)

46 original factory starting points with categorization, search, descriptions, and favorites. These are not imported proprietary presets.

---

**Screenshot update rule:** when the GUI changes, refresh these files from the matching successful JUCE Windows editor run, rather than inserting a concept image. [Go back to README](../README.md).
Loading