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
162 changes: 162 additions & 0 deletions .github/workflows/release-installers.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
name: Build public installers
on:
pull_request:
paths: ['CMakeLists.txt', 'packaging/**', 'docs/INSTALL-PUBLIC.md', '.github/workflows/release-installers.yml']
push:
branches: [main]
paths: ['CMakeLists.txt', 'packaging/**', 'docs/INSTALL-PUBLIC.md', '.github/workflows/release-installers.yml']
workflow_dispatch:
inputs:
publish:
type: boolean
description: Publish checked installers to GitHub Releases
default: false
stable:
type: boolean
description: Stable requires ARSON_STABLE_APPROVED=yes repository variable
default: false
permissions:
contents: read
concurrency:
group: arsoncomp-packages-${{ github.ref }}
cancel-in-progress: true
env:
RELEASE_VERSION: 0.2.0
jobs:
windows:
runs-on: windows-latest
steps:
- uses: actions/checkout@v4
- uses: actions/cache@v4
with:
path: build/_deps/juce-src
key: arson-juce-8.0.12-windows
- name: Build and run all Windows tests
shell: pwsh
run: |
cmake -S . -B build -A x64 -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel 4
ctest --test-dir build -C Release --output-on-failure
- name: Compile Inno installer
shell: pwsh
run: |
$ErrorActionPreference = 'Stop'
$stage = Join-Path $pwd 'dist\stage'
$out = Join-Path $pwd 'dist\out'
New-Item -ItemType Directory -Force "$stage\VST3", "$stage\Standalone", $out | Out-Null
Copy-Item -Recurse 'build\ArSonComp_artefacts\Release\VST3\ArSonComp.vst3' "$stage\VST3\"
Copy-Item 'build\ArSonComp_artefacts\Release\Standalone\ArSonComp.exe' "$stage\Standalone\"
Copy-Item docs\INSTALL-PUBLIC.md "$stage\START-HERE.md"
Copy-Item LICENSE "$stage\LICENSE"
$iscc = Join-Path ([Environment]::GetFolderPath('ProgramFilesX86')) 'Inno Setup 6\ISCC.exe'
if (-not (Test-Path $iscc)) { choco install innosetup -y --no-progress }
if (-not (Test-Path $iscc)) { throw 'Inno Setup 6 was not found' }
& $iscc "/DStageDir=$stage" "/DAppVersion=$env:RELEASE_VERSION" "/O$out" "packaging\windows\ArSonComp.iss"
if ($LASTEXITCODE -ne 0) { throw "ISCC exit $LASTEXITCODE" }
if (@(Get-ChildItem "$out\*.exe").Count -ne 1) { throw 'Missing installer EXE' }
- uses: actions/upload-artifact@v4
with:
name: ArSonComp-Windows-Installer
path: dist/out/*.exe
if-no-files-found: error
linux:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v4
- name: Install JUCE prerequisites
run: |
sudo apt-get update -qq
sudo apt-get install -y --no-install-recommends \
libasound2-dev libjack-jackd2-dev ladspa-sdk libfreetype-dev \
libfontconfig1-dev libx11-dev libxcomposite-dev libxcursor-dev \
libxext-dev libxinerama-dev libxrandr-dev libxrender-dev \
libxi-dev libglu1-mesa-dev libgtk-3-dev xvfb
- uses: actions/cache@v4
with:
path: build/_deps/juce-src
key: arson-juce-8.0.12-ubuntu24
- name: Build, smoke-test and package Linux
run: |
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel 2
xvfb-run -a ctest --test-dir build --output-on-failure
bash packaging/linux/package.sh build dist/out "$RELEASE_VERSION"
dpkg-deb --info "dist/out/ArSonComp-$RELEASE_VERSION-Ubuntu-Debian-amd64.deb"
tar -tzf "dist/out/ArSonComp-$RELEASE_VERSION-Linux-x86_64-Portable.tar.gz" | grep -F install.sh
- uses: actions/upload-artifact@v4
with:
name: ArSonComp-Linux-Installers
path: dist/out/*
if-no-files-found: error
macos:
runs-on: macos-15
steps:
- uses: actions/checkout@v4
- uses: actions/cache@v4
with:
path: build/_deps/juce-src
key: arson-juce-8.0.12-macos
- name: Universal build, test and ad-hoc package
run: |
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
-DCMAKE_OSX_DEPLOYMENT_TARGET=11.0 \
'-DCMAKE_OSX_ARCHITECTURES=arm64;x86_64'
cmake --build build --parallel 3
ctest --test-dir build --output-on-failure
bash packaging/macos/package.sh build dist/out "$RELEASE_VERSION"
test -s "dist/out/ArSonComp-$RELEASE_VERSION-macOS-Universal-AdHoc.pkg"
- uses: actions/upload-artifact@v4
with:
name: ArSonComp-macOS-Installers
path: dist/out/*
if-no-files-found: error
publish:
needs: [windows, linux, macos]
if: >-
github.event_name == 'push' ||
(github.event_name == 'workflow_dispatch' && inputs.publish)
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/download-artifact@v4
with:
pattern: ArSonComp-*-Installer*
path: dist
merge-multiple: true
- name: Publish only after all OS gates pass
shell: bash
env:
GH_TOKEN: ${{ github.token }}
GH_REPO: ${{ github.repository }}
STABLE_APPROVAL: ${{ vars.ARSON_STABLE_APPROVED }}
STABLE_REQUEST: ${{ inputs.stable }}
run: |
set -euo pipefail
shopt -s nullglob
files=(dist/*.exe dist/*.deb dist/*.tar.gz dist/*.pkg dist/*.zip)
if (( ${#files[@]} < 5 )); then
echo "Missing one or more platform installers"; exit 7
fi
( cd dist && sha256sum ./* > SHA256SUMS.txt )
tag="v${RELEASE_VERSION}-rc.1"
flag="--prerelease"
if [[ "$STABLE_REQUEST" == "true" ]]; then
if [[ "$STABLE_APPROVAL" != "yes" ]]; then
echo "Stable requires repository variable ARSON_STABLE_APPROVED=yes"; exit 8
fi
tag="v${RELEASE_VERSION}"
flag=""
fi
if gh release view "$tag" >/dev/null 2>&1; then
echo "Release already exists: $tag. Refusing to overwrite artifacts."; exit 9
fi
cat > notes.md <<EOF
ArSonComp $tag — Windows Inno Setup, Linux DEB + portable and macOS universal ad-hoc PKG/VST3.
Installation: https://github.com/masarray/arson-comp/blob/$GITHUB_SHA/docs/INSTALL-PUBLIC.md
Source (AGPL): https://github.com/masarray/arson-comp/tree/$GITHUB_SHA
macOS PKG is NOT Apple notarized; Gatekeeper may warn.
CI is not hardware/DAW/ASIO stability certification. Check the included SHA256SUMS.txt.
EOF
gh release create "$tag" dist/* \
--target "$GITHUB_SHA" --title "ArSonComp $tag" $flag --notes-file notes.md
7 changes: 7 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,3 +30,10 @@
- Keep the user-approved separate transparent horizontal silver ruler and round thumb; avoid fake light waves or diagonal specular backgrounds. Cache matte brushed grain only on resize.
- Retain visual/native slider hit separation, caption clearances, host automation and LCD meter isolation.
- A shipped Windows test artifact needs the actual screenshot set, QA inventory helper and an explicit physical-test checklist; no CI result proves PS22 xruns or commercial sonic parity.

## Public installer release gate (v0.2)
- Rebuild VST3/Standalone and run actual plugin smoke on all three supported OS runners. Publish only if Windows Inno, Linux DEB+portable and macOS universal ad-hoc packages all pass.
- Inno defaults to user install and supports optional all-users UAC; install to Steinberg-standard VST3 locations, with uninstall and duplicate-scope detection.
- Linux package must provide a user-mode no-sudo option. macOS ad-hoc is **not** Apple Developer ID signing or notarization. Do not instruct users to disable Gatekeeper globally.
- Do not describe a CI-only artifact as hardware-certified stable. Promote the public RC to stable only after license and DAW/interface tests are documented and ARSON_STABLE_APPROVED is explicitly enabled by repository owner.
- Do not remove bundled ASIO support without stating the user impact; check redistribution terms before public stable.
2 changes: 1 addition & 1 deletion CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
cmake_minimum_required(VERSION 3.22)
project(ArSonComp VERSION 0.1.0 LANGUAGES CXX)
project(ArSonComp VERSION 0.2.0 LANGUAGES C CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
option(ARSON_BUILD_PLUGIN "Build VST3 and standalone" ON)
Expand Down
126 changes: 64 additions & 62 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,70 +1,72 @@
# ArSonComp

A lightweight **real-time compressor** with a framework-independent C++17 DSP core, JUCE VST3 and Windows Standalone application. Designed for live vocal, karaoke, podcast, music and mix-bus use. This is an **engineering test baseline**, not a certified production release or a claimed FabFilter Pro-C clone.

## Current verified milestone — 31 October 2026

| Area | Implemented and checked |
| --- | --- |
| DSP | Clean feed-forward, causal Feedback and Smooth dual-envelope models; Peak and 10 ms RMS detection; Attack, Release, Hold, Threshold, Ratio, Knee, Range and Auto Release |
| Signal path | Input/Makeup gain, wet/dry Mix, stereo Link, mono/stereo main buses, optional external sidechain, detector HP/LP, SC Listen, smoothed Bypass |
| Latency | **0 additional algorithmic samples** reported by the plugin; host buffer, driver and audio interface latency are separate |
| Host interoperability | Stable APVTS parameter IDs, project state restore, six factory starting presets, user `.arsoncomp` save/open through **FILE**, A/B snapshots, automation attachments |
| GUI | Grey brushed-metal chassis, recessed black LCD graph and IN/GR/OUT meters, photographic black rotary knobs, matched metal toggle PNGs, fixed gunmetal slider rails with moving PNG thumbs and red value fill |
| Value workflow | **No floating value popup/tooltip.** Hover/drag the knobs and sliders to read their value in the LCD's bottom-center footer; MINI uses a small right-side footer |
| Dimensions | Full **780×640** default, **740×585** minimum; MINI **330 px** tall. Resizable full layout and responsive SIDECHAIN row |
| Automated verification | Windows Release VST3 + Standalone, `engine_contract`, `plugin_state_editor`, Linux engine safety/sanitizers, renderer/asset/layout checks, benchmark and install-ready Windows artifact |

**Latest code-tested revision:** `7b340eb2ee5740df13b52b5bfcf984a3b66d0dd3`. Both jobs passed in [GitHub Actions #41202549812](https://github.com/masarray/arson-comp/actions/runs/41202549812). The [Windows x64 artifact](https://github.com/masarray/arson-comp/actions/runs/41202549812/artifacts/13043510391) contains VST3, Standalone, four actual Windows screenshot captures, a benchmark, and SHA-256 manifests. Subsequent documentation-only reconciliation does not modify the compiled source.

### What is *not* verified yet

Real-device ASIO/WASAPI audio latency and stability; two independent DAW/VST3 hosts, external hardware/host sidechain, pluginval, multi-instance long sessions, 125–150% DPI scaling, and loudness-matched listening comparisons. No full Pro-C sonic, feature or production-readiness claim. The initial standalone uses standard JUCE audio device backends; **ASIO support is not claimed**.

## Quick start — Windows

1. Download the Windows artifact linked above and extract its contents.
2. Run `Standalone/ArSonComp.exe`, then choose audio input/output devices in its settings; **or** copy the entire `Plugin/ArSonComp.vst3` folder to `C:\Program Files\Common Files\VST3\`, then rescan your VST3 host.
3. Start with Clean and a moderate preset. Lower Threshold until the GR meter indicates the desired compression. Use Makeup to match audible loudness before A/B or model comparisons.
4. Open **SIDECHAIN** to configure Peak/RMS, HP/LP and optional EXT SC and LISTEN; use **DYNAMICS** for Range, Hold, Mix, Link, Auto Release. FILE provides Save/Open user presets.
5. Hover or move any knob/slider to see name, numerical value and unit in the graph LCD footer. Double-click to restore the parameter's default. Use MINI/FULL to switch form factor.

A disconnected external sidechain may produce silence at the detector. Use LISTEN only to audit the detector and turn it off for normal use. This is a compressor—not a limiter; with no lookahead, transients may pass.

## Build from source

CMake 3.22+, C++17, JUCE 8.0.12 pinned to commit `29396c22c93392d6738e021b83196283d6e4d850`. On Windows, install Visual Studio 2022 or newer with C++ desktop tools.

```sh
cmake -S . -B build -A x64 -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel 4
ctest --test-dir build -C Release --output-on-failure
```

For engine-only verification on Linux/macOS, omit the Windows `-A x64` argument and use:
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).

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

Linux plugin build dependencies depend on the desktop stack, commonly `pkg-config libasound2-dev libx11-dev libxext-dev libxinerama-dev libxrandr-dev libxcursor-dev libfreetype6-dev libfontconfig1-dev libgl1-mesa-dev`. Use `-DJUCE_SOURCE_DIR=/path/to/JUCE` to reuse a local checkout. ASan/UBSan engine testing: `-DARSON_SANITIZE=ON -DCMAKE_BUILD_TYPE=Debug` under GCC/Clang. **Do not enable fast-math**, because non-finite handling relies on IEEE floating-point semantics.

## Engineering boundaries

The independent DSP core is free of JUCE. The audio callback does not require a worker, mutex, heap allocation or file/network I/O; it has bounded telemetry. GUI paint is message-thread-only, with cached materials, gradient/grid geometry and 30 Hz display updates. The plugin adds no intentional lookahead, oversampling, linear-phase stage or audio delay line. A reported zero algorithmic samples does **not** mean the full monitoring system has zero latency.

Presets and parameter updates are smoothed where appropriate, but are not promised sample-accurate atomic transactions. Host automation behavior, sidechain audibility, distortion and CPU load must be verified with actual devices.

## Documentation and release gates
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.

- [PRD: scope and acceptance](docs/PRD.md)
- [ARD: DSP, scheduling and GUI ownership](docs/ARD.md)
- [VALIDATION: evidence and outstanding tests](docs/VALIDATION.md)
- [HANDOFF: current next steps and historical milestones](docs/HANDOFF.md)
- [WINDOWS-QUICKSTART: physical test checklist](docs/WINDOWS-QUICKSTART.md)
- [AGENTS: engineering guardrails](AGENTS.md)
### License and compliance

Repository license remains AGPL-3.0; JUCE has its own AGPL/commercial terms. FabFilter Pro-C is a third-party workflow and sound-quality reference; no FabFilter asset, code or proprietary algorithm is included.
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.
Loading
Loading