feat: Vamp plugin exposing features as audio analysis plugins

.clang-format

@@ -15,6 +15,7 @@ AlwaysBreakTemplateDeclarations: Yes
 BinPackArguments: false
 BinPackParameters: false
 BreakAfterAttributes: Leave
+BreakStringLiterals: false
 ColumnLimit: 100
 FixNamespaceComments: true
 IndentWidth: 4

.github/workflows/ci.yml

@@ -59,6 +59,7 @@ jobs:
           -DOPENAE_BUILD_BENCHMARKS=ON
           -DOPENAE_BUILD_TESTS=ON
           -DOPENAE_BUILD_EXAMPLES=ON
+          -DOPENAE_BUILD_VAMP=ON
           -DOPENAE_WARNINGS_AS_ERRORS=ON
           ${{ matrix.config.flags }}
 

.github/workflows/vamp.yml

@@ -0,0 +1,125 @@
+name: Vamp plugin
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build ${{ matrix.config.name }}
+    runs-on: ${{ matrix.config.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        config:
+          - name: linux-x86_64
+            os: ubuntu-24.04
+
+          - name: linux-arm64
+            os: ubuntu-24.04-arm
+
+          - name: macos # universal binary
+            os: macos-15
+            osx_architectures: "x86_64;arm64"
+
+          - name: windows-x64
+            os: windows-2022
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # tags + history for git describe
+
+      - name: Configure CMake
+        env:
+          # <memory_resource> requires 14.0: https://developer.apple.com/xcode/cpp/
+          MACOSX_DEPLOYMENT_TARGET: "14.0"
+          CMAKE_OSX_ARCHITECTURES: ${{ matrix.config.osx_architectures }}
+        run: >
+          cmake -S . -B build
+          -DCMAKE_BUILD_TYPE=Release
+          -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded
+          -DBUILD_SHARED_LIBS=OFF
+          -DOPENAE_BUILD_TESTS=ON
+          -DOPENAE_BUILD_VAMP=ON
+
+      - name: Build
+        run: cmake --build build --config Release --parallel
+
+      - name: Run tests
+        run: ctest --test-dir build --build-config Release --output-on-failure
+
+      - name: Package
+        shell: bash
+        run: |
+          cmake --install build --config Release --component vamp --prefix stage
+          mkdir package
+          cp stage/lib*/vamp/* package/
+          cp bindings/vamp/dist/README.md package/
+          cp LICENSE package/
+
+      - name: Verify universal binary
+        if: runner.os == 'macOS'
+        run: lipo package/openae.dylib -verify_arch x86_64 arm64
+
+      - name: Create archive
+        # cmake -E tar for a portable zip (no zip command on Windows runners)
+        shell: bash
+        working-directory: package
+        run: |
+          version=$(git describe --tags --always)
+          version="${version#v}"
+          cmake -E tar cf "../openae-vamp-${version}-${{ matrix.config.name }}.zip" --format=zip -- .
+
+      - uses: actions/upload-artifact@v6
+        with:
+          name: vamp-${{ matrix.config.name }}
+          path: openae-vamp-*.zip
+          if-no-files-found: error
+
+  summary:
+    name: Package summary
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v6
+        with:
+          pattern: vamp-*
+          path: artifacts/
+          merge-multiple: true
+
+      - name: Write summary table
+        working-directory: artifacts
+        run: |
+          {
+            echo "### Vamp plugin packages"
+            echo ""
+            echo "| File | Size | SHA256 |"
+            echo "| ---- | ---- | ------ |"
+            for f in openae-vamp-*.zip; do
+              echo "| \`$f\` | $(du -h "$f" | cut -f1) | \`$(sha256sum "$f" | cut -d' ' -f1)\` |"
+            done
+          } >> "$GITHUB_STEP_SUMMARY"
+
+  release-assets:
+    name: Attach release assets
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v6
+        with:
+          pattern: vamp-*
+          path: artifacts/
+          merge-multiple: true
+
+      - name: Upload archives to release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release upload "$GITHUB_REF_NAME" artifacts/openae-vamp-*.zip --clobber --repo "$GITHUB_REPOSITORY"

CMakeLists.txt

@@ -58,6 +58,20 @@ else()
     target_compile_options(openae_project_options INTERFACE ${warnings})
 endif()
 
+# dependencies
+include(FetchContent)
+option(XXHASH_BUILD_XXHSUM "Build the xxhsum binary" OFF)
+FetchContent_Declare(
+    xxHash
+    GIT_REPOSITORY    https://github.com/Cyan4973/xxHash.git
+    GIT_TAG           v0.8.3
+    SOURCE_SUBDIR     cmake_unofficial
+    EXCLUDE_FROM_ALL
+    SYSTEM
+    FIND_PACKAGE_ARGS 0.8.3
+)
+FetchContent_MakeAvailable(xxHash)
+
 # library
 add_subdirectory(src)
 
@@ -66,6 +80,19 @@ option(OPENAE_BUILD_TESTS "Build unit tests" OFF)
 if(OPENAE_BUILD_TESTS)
     message(STATUS "Unit tests enabled")
     enable_testing()
+    option(CATCH_INSTALL_DOCS "Install documentation alongside library" OFF)
+    FetchContent_Declare(
+        Catch2
+        GIT_REPOSITORY    https://github.com/catchorg/Catch2.git
+        GIT_TAG           v3.8.0
+        EXCLUDE_FROM_ALL
+        SYSTEM
+        FIND_PACKAGE_ARGS 3.8.0
+    )
+    FetchContent_MakeAvailable(Catch2)
+    if(TARGET Catch2)
+        set_target_properties(Catch2 Catch2WithMain PROPERTIES CXX_CLANG_TIDY "")
+    endif()
     add_subdirectory(tests)
 endif()
 
@@ -83,3 +110,8 @@ cmake_dependent_option(OPENAE_BUILD_PYTHON_STUBS "Build Python stubs" ON "OPENAE
 if(OPENAE_BUILD_PYTHON)
     add_subdirectory(bindings/python)
 endif()
+
+option(OPENAE_BUILD_VAMP "Build Vamp plugin" OFF)
+if(OPENAE_BUILD_VAMP)
+    add_subdirectory(bindings/vamp)
+endif()

CMakePresets.json

@@ -36,7 +36,18 @@
                 "OPENAE_WARNINGS_AS_ERRORS": "ON",
                 "OPENAE_BUILD_TESTS": "ON",
                 "OPENAE_BUILD_BENCHMARKS": "ON",
-                "OPENAE_BUILD_PYTHON": "ON"
+                "OPENAE_BUILD_PYTHON": "ON",
+                "OPENAE_BUILD_VAMP": "ON"
+            }
+        },
+        {
+            "name": "vamp",
+            "inherits": ["release"],
+            "installDir": "${sourceDir}/install/${presetName}",
+            "cacheVariables": {
+                "BUILD_SHARED_LIBS": "OFF",
+                "CMAKE_MSVC_RUNTIME_LIBRARY": "MultiThreaded",
+                "OPENAE_BUILD_VAMP": "ON"
             }
         },
         {

bindings/vamp/.clang-tidy

@@ -0,0 +1,13 @@
+---
+# Extends the project config. The checks disabled here flag constructs the Vamp C plugin ABI forces on us:
+# - raw new/delete across the interface boundary
+# - reinterpret_cast for the interleaved spectrum buffer
+# - C-style buffer/array indexing behind explicit bounds checks
+# - fixed callback signatures
+InheritParentConfig: true
+Checks: >
+  -bugprone-easily-swappable-parameters,
+  -cppcoreguidelines-owning-memory,
+  -cppcoreguidelines-pro-bounds-constant-array-index,
+  -cppcoreguidelines-pro-bounds-pointer-arithmetic,
+  -cppcoreguidelines-pro-type-reinterpret-cast,

bindings/vamp/CMakeLists.txt

@@ -0,0 +1,43 @@
+# Vamp plugin module exposing OpenAE features.
+#
+# Produces a single shared module that exports vampGetPluginDescriptor.
+# The file name defines the plugin library id, so it must be exactly:
+#   Linux   : openae.so
+#   macOS   : openae.dylib
+#   Windows : openae.dll
+# To avoid clashes with the core openae library, the module gets its own output directory in the build tree and its own install destination.
+
+if(BUILD_SHARED_LIBS)
+    message(WARNING "Vamp plugin depends on shared openae library and will not be loadable by hosts; use BUILD_SHARED_LIBS=OFF")
+endif()
+
+add_library(openae_vamp MODULE src/plugin.cpp src/vamp.h)
+target_link_libraries(openae_vamp PRIVATE openae::openae openae_project_options)
+target_include_directories(openae_vamp PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
+
+set_target_properties(
+    openae_vamp
+    PROPERTIES
+        PREFIX ""
+        OUTPUT_NAME "openae"
+        CXX_VISIBILITY_PRESET hidden
+        CXX_VISIBILITY_INLINES_HIDDEN ON
+        POSITION_INDEPENDENT_CODE ON
+        LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}/vamp"
+        ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}/vamp"
+        RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}/vamp"
+)
+if(APPLE)
+    # MODULE targets default to .so on macOS, but Vamp hosts scan for .dylib.
+    set_target_properties(openae_vamp PROPERTIES SUFFIX ".dylib")
+endif()
+
+include(GNUInstallDirs)
+install(
+    TARGETS openae_vamp
+    LIBRARY DESTINATION "${CMAKE_INSTALL_LIBDIR}/vamp" COMPONENT vamp
+)
+
+if(OPENAE_BUILD_TESTS)
+    add_subdirectory(tests)
+endif()

bindings/vamp/dist/README.md

@@ -0,0 +1,37 @@
+# OpenAE Vamp plugin
+
+[Vamp](https://vamp-plugins.org) audio analysis plugin exposing the [OpenAE](https://openae.io) acoustic emission features.
+The plugin can be used in Vamp hosts such as [Sonic Visualiser](https://sonicvisualiser.org), [Audacity](https://www.audacityteam.org) and [Sonic Annotator](https://vamp-plugins.org/sonic-annotator/).
+
+## Installation
+
+Copy the plugin binary into one of the Vamp plugin directories and restart your Vamp host:
+
+**Linux** (`openae.so`)
+
+- `$HOME/vamp`
+- `/usr/local/lib/vamp`
+- `/usr/lib/vamp`
+
+**macOS** (`openae.dylib`)
+
+- `$HOME/Library/Audio/Plug-Ins/Vamp`
+- `/Library/Audio/Plug-Ins/Vamp`
+
+The binary is not notarized by Apple. macOS quarantines downloaded files and will refuse to load the plugin ("cannot be opened because the developer cannot be verified"). Remove the quarantine attribute after extracting:
+
+```sh
+xattr -d com.apple.quarantine openae.dylib
+```
+
+**Windows** (`openae.dll`)
+
+- `C:\Program Files\Vamp Plugins`
+
+Alternatively, set the `VAMP_PATH` environment variable to a custom plugin directory.
+
+## Links
+
+- Documentation: https://openae.io
+- Source code: https://github.com/openae-io/openae-lib
+- Issues: https://github.com/openae-io/openae-lib/issues