diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..e03eacb --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -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. diff --git a/.github/workflows/sync-public-screenshots.yml b/.github/workflows/sync-public-screenshots.yml new file mode 100644 index 0000000..98df317 --- /dev/null +++ b/.github/workflows/sync-public-screenshots.yml @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..525a80e --- /dev/null +++ b/CONTRIBUTING.md @@ -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). \ No newline at end of file diff --git a/README.md b/README.md index b7bdafc..05adaa7 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,74 @@ # 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. + +

+ 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. +

+

Actual Windows JUCE editor screenshot from M7 • Full mode 612 × 580

+ +## 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 @@ -59,14 +76,8 @@ 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). \ No newline at end of file diff --git a/docs/PRODUCT-SHOWCASE.md b/docs/PRODUCT-SHOWCASE.md new file mode 100644 index 0000000..e08b2d1 --- /dev/null +++ b/docs/PRODUCT-SHOWCASE.md @@ -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). \ No newline at end of file diff --git a/docs/RELEASE-STATUS.md b/docs/RELEASE-STATUS.md new file mode 100644 index 0000000..8ea7699 --- /dev/null +++ b/docs/RELEASE-STATUS.md @@ -0,0 +1,26 @@ +# Release status — ArSonComp v0.2.0-rc.1 + +**Public release:** [v0.2.0-rc.1](https://github.com/masarray/arson-comp/releases/tag/v0.2.0-rc.1) +**Release commit:** `0a039ef6d340e26aa01a62df3670f74da1f03a12` +**Installer CI:** [Run #41273600039](https://github.com/masarray/arson-comp/actions/runs/41273600039) +**Most recent GUI screenshots:** [M7 Windows run #41267899861](https://github.com/masarray/arson-comp/actions/runs/41267899861) + +## Automated checks completed + +- Windows x64 VST3 and Standalone compiled, JUCE/editor and DSP tests passed, and the Inno Setup EXE was produced. +- Ubuntu x86_64 compiled, executed tests under a virtual display, and produced DEB and portable archives. +- macOS arm64 + x86_64 universal build and tests completed, ad-hoc signing and signature verification passed, and universal PKG/VST3 archive were produced. +- Public prerelease assets and SHA-256 checksums were published. + +## Evidence still required before a production-stable label + +- Verify with pluginval and two independent real VST3 hosts on target operating systems. +- Measure physical-driver callback timing, xruns and sustained performance at 48 kHz / 128, 64 and 32 samples; validate a 60-minute session. +- Record actual Maono PS22 ASIO behavior with bypass/on A/B/C/D isolation, rather than infer it from CPU utilization. +- Validate project restore, external sidechain routing, automation and editor open/close in installed hosts. +- Conduct loudness-matched audio quality comparisons; no verified FabFilter sonic equivalence. +- Review JUCE/ASIO SDK redistribution terms; Apple Developer ID and notarization remain needed for frictionless macOS installation. + +**Public availability and successful CI are not the same as production-stable audio certification.** This version is intentionally labelled a *Release Candidate* until physical and host-level gates are complete. + +[Installation guide](INSTALL-PUBLIC.md) · [Windows physical test](WINDOWS-QUICKSTART.md) · [Validation archive](VALIDATION.md). \ No newline at end of file diff --git a/docs/VALIDATION.md b/docs/VALIDATION.md index 584552b..4fd91fc 100644 --- a/docs/VALIDATION.md +++ b/docs/VALIDATION.md @@ -1,6 +1,6 @@ # Validation record -> **Latest verified baseline (2026-10-31):** Both Windows build/editor-smoke/benchmark/artifact and Linux engine-safety passed for source commit `7b340eb2ee5740df13b52b5bfcf984a3b66d0dd3`, [Actions #41202549812](https://github.com/masarray/arson-comp/actions/runs/41202549812). The Windows artifact includes full 780×640, minimum 740×585, sidechain 740×585, and MINI 780×330 actual JUCE screenshots. Static layout/asset/value-readout tests passed. Older pending-CI descriptions below are historical milestones, **not** the latest result. Real DAW/device/pluginval tests remain pending.\n +> **Current public verification (2026-11-01):** ArSonComp [v0.2.0-rc.1](https://github.com/masarray/arson-comp/releases/tag/v0.2.0-rc.1) was packaged from commit `0a039ef6d340e26aa01a62df3670f74da1f03a12` with a successful [Windows/Linux/macOS release workflow #41273600039](https://github.com/masarray/arson-comp/actions/runs/41273600039). The latest product screenshots are from [M7 Windows editor CI #41267899861](https://github.com/masarray/arson-comp/actions/runs/41267899861), with Full 612×580, Minimum/Sidechain 580×540 and MINI 612×320. The rest of this document retains historical engineering evidence. Physical audio-device testing, pluginval in real hosts, macOS notarization and licensing review are **not** complete gates; see [current release status](RELEASE-STATUS.md). Initial implementation, 2026-10-31. diff --git a/docs/images/arsoncomp-full.png b/docs/images/arsoncomp-full.png new file mode 100644 index 0000000..600cb9b Binary files /dev/null and b/docs/images/arsoncomp-full.png differ diff --git a/docs/images/arsoncomp-mini.png b/docs/images/arsoncomp-mini.png new file mode 100644 index 0000000..3cf6731 Binary files /dev/null and b/docs/images/arsoncomp-mini.png differ diff --git a/docs/images/arsoncomp-minimum.png b/docs/images/arsoncomp-minimum.png new file mode 100644 index 0000000..76cb968 Binary files /dev/null and b/docs/images/arsoncomp-minimum.png differ diff --git a/docs/images/arsoncomp-presets.png b/docs/images/arsoncomp-presets.png new file mode 100644 index 0000000..3e1403d Binary files /dev/null and b/docs/images/arsoncomp-presets.png differ diff --git a/docs/images/arsoncomp-sidechain.png b/docs/images/arsoncomp-sidechain.png new file mode 100644 index 0000000..44c5500 Binary files /dev/null and b/docs/images/arsoncomp-sidechain.png differ