LedFx · Copilot · Nov 17, 2025 · Nov 17, 2025 · Nov 17, 2025 · Nov 17, 2025
diff --git a/.github/COPILOT_SETUP_README.md b/.github/COPILOT_SETUP_README.md
@@ -0,0 +1,187 @@
+# Copilot Setup Steps Documentation
+
+This document explains the `.github/copilot-setup-steps.yml` file and how it provides a development environment setup for aubio-ledfx.
+
+## Overview
+
+The `copilot-setup-steps.yml` file is a GitHub Actions workflow that can be used to set up a complete development environment for aubio-ledfx. It installs all necessary tools and dependencies for building, testing, and developing the project.
+
+## What Gets Installed
+
+### 1. System Build Tools
+- **Compilers**: gcc, g++ (C99-compliant for aubio)
+- **Build systems**: ninja-build (used by Meson)
+- **Build utilities**: pkg-config, git
+- **Development libraries**: 
+  - libfftw3-dev (FFT library)
+  - libsndfile1-dev (audio file I/O)
+  - libsamplerate0-dev (sample rate conversion)
+  - libjack-dev (JACK audio)
+  - libavcodec-dev, libavformat-dev, libswresample-dev (FFmpeg)
+  - librubberband-dev (pitch shifting/time stretching)
+
+### 2. Python Build Environment
+- **Python 3.11**: Set up via actions/setup-python
+- **Meson**: >=1.9.0 (primary build system)
+- **meson-python**: PEP 517 build backend for Python packages
+- **ninja**: Build tool (also installed as Python package)
+- **NumPy**: >=1.26.4 (required for aubio Python bindings)
+- **pip, setuptools, wheel**: Updated to latest versions
+
+### 3. Testing Tools
+- **pytest**: Python test runner
+- **pytest-cov**: Code coverage for tests
+- **build**: Python package build tool
+- **uv**: Modern, fast Python package manager
+
+### 4. Security Testing Tools
+- **libasan6**: AddressSanitizer runtime library
+- **libubsan1**: UndefinedBehaviorSanitizer runtime library
+- **valgrind**: Memory error detection tool
+
+These tools enable running the security test suite defined in `.github/workflows/sanitizers.yml`.
+
+### 5. Environment Configuration
+Sets up environment variables:
+- `PKG_CONFIG_PATH`: Includes system pkg-config paths
+
+## Key Changes from Previous Version
+
+**Removed vcpkg**: The setup now uses system-provided dependencies instead of building them from source with vcpkg. This simplifies the setup and makes it faster, as Ubuntu's package repository provides all necessary libraries.
+
+**System Dependencies**: All C/C++ dependencies are now installed via apt-get:
+- Audio codecs and formats via libavcodec-dev, libavformat-dev
+- Rubberband for pitch/time manipulation via librubberband-dev
+- No need to build these from source
+### 6. Verification
+- Displays versions of all installed tools
+- Lists available system libraries via pkg-config
+- Shows installed Python packages
+- Provides usage instructions
+
+## How It Works
+
+The `copilot-setup-steps.yml` file is a standard GitHub Actions workflow that can be:
+
+1. Run manually via workflow_dispatch
+2. Referenced as a reusable workflow
+3. Used as a template for setting up development environments
+
+The workflow has a single job called "setup" that runs on ubuntu-latest and executes 8 steps to configure the environment.
+
+## Usage Examples
+
+After running the setup workflow (manually via GitHub Actions), you can:
+
+### Build the C Library
+```bash
+meson setup builddir
+meson compile -C builddir
+```
+
+### Build with Tests Enabled
+```bash
+meson setup builddir -Dtests=true
+meson compile -C builddir
+meson test -C builddir
+```
+
+### Build with Security Sanitizers
+```bash
+meson setup builddir -Db_sanitize=address,undefined -Dtests=true
+meson compile -C builddir
+meson test -C builddir
+```
+
+### Build Python Wheel
+```bash
+# Using uv (faster)
+uv build --wheel
+
+# Using pip
+pip wheel . --no-deps
+```
+
+### Run Tests
+```bash
+# C tests
+meson test -C builddir --print-errorlogs
+
+# Python tests
+pytest python/tests/
+```
+
+## Benefits
+
+1. **Simplified Setup**: Uses system packages instead of building from source
+2. **Faster Setup**: No need to compile dependencies with vcpkg
+3. **Complete Toolchain**: All build, test, and security tools available
+4. **Standard Workflow**: Follows GitHub Actions best practices
+
+## Maintenance
+
+### Adding New Tools
+
+To add a new tool to the setup:
+
+1. Edit `.github/copilot-setup-steps.yml`
+2. Add a new step in the `jobs.setup.steps` section
+3. Test the workflow by running it manually
+4. Update this documentation
+
+### Adding New Dependencies
+
+For Python dependencies:
+- Add to the pip install command in the "Install Python build tools" or "Install Python testing and development tools" step
+
+For system packages:
+- Add to the apt-get install command in the "Install system build tools and dependencies" step
+
+## Platform Notes
+
+This setup workflow is designed for **Ubuntu Linux** environments (ubuntu-latest in GitHub Actions).
+
+For local development on other platforms:
+- **macOS**: Use Homebrew for system packages (`brew install` instead of `apt-get`)
+- **Windows**: Use vcpkg or system package managers, MSVC or MinGW-w64 for compilation
+
+See the main README.md for platform-specific instructions.
+
+## Related Files
+
+- **`.github/copilot-instructions.md`**: Custom instructions for Copilot's behavior
+- **`vcpkg.json`**: Declares C/C++ dependencies
+- **`pyproject.toml`**: Python package configuration
+- **`meson.build`**: Main build system configuration
+- **`meson_options.txt`**: Build options and feature toggles
+- **`.github/workflows/build.yml`**: CI/CD build workflow
+- **`.github/workflows/sanitizers.yml`**: Security testing workflow
+
+## Troubleshooting
+
+### Workflow Fails to Run
+
+If the workflow fails to run, check:
+1. GitHub Actions permissions in repository settings
+2. Workflow file syntax (validate YAML)
+3. Internet connectivity (for downloading packages)
+
+### Missing Dependencies
+
+If dependencies are missing after setup:
+```bash
+# Manually install system packages
+sudo apt-get update
+sudo apt-get install -y libfftw3-dev libsndfile1-dev libsamplerate0-dev
+
+# Verify packages are available
+pkg-config --list-all | grep -E "fftw3|sndfile|samplerate"
+```
+
+## References
+
+- [GitHub Actions Workflow Syntax](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)
+- [Meson Build System](https://mesonbuild.com/)
+- [meson-python](https://meson-python.readthedocs.io/)
+- [aubio-ledfx Build Documentation](../doc/building.rst)
+- [aubio-ledfx Meson Reference](../doc/meson_reference.rst)
diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml
@@ -0,0 +1,94 @@
+# GitHub Copilot Coding Agent Environment Setup
+# This file sets up a complete development environment for aubio-ledfx
+# Reference: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
+
+name: Copilot Environment Setup
+
+# Automatically run the setup steps when they are changed to allow for easy validation, and
+# allow manual testing through the repository's "Actions" tab
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install system build tools and dependencies
+        run: |
+          sudo apt-get update && sudo apt-get install -y \
+            build-essential \
+            gcc \
+            g++ \
+            pkg-config \
+            git \
+            ninja-build \
+            libfftw3-dev \
+            libsndfile1-dev \
+            libsamplerate0-dev \
+            libjack-dev \
+            libavcodec-dev \
+            libavformat-dev \
+            libswresample-dev \
+            librubberband-dev
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+
+      - name: Install Python build tools
+        run: |
+          python3 -m pip install --upgrade pip setuptools wheel
+          pip install "meson>=1.9.0" meson-python ninja "numpy>=1.26.4"
+
+      - name: Install Python testing and development tools
+        run: |
+          pip install pytest pytest-cov build uv
+
+      - name: Install sanitizer tools for security testing
+        run: |
+          sudo apt-get install -y \
+            libasan6 \
+            libubsan1 \
+            valgrind
+
+      - name: Configure environment
+        run: |
+          echo "PKG_CONFIG_PATH=/usr/lib/x86_64-linux-gnu/pkgconfig:/usr/share/pkgconfig" >> $GITHUB_ENV
+
+      - name: Verify installation
+        run: |
+          echo "=== Installed Tools ==="
+          python3 --version
+          meson --version
+          ninja --version
+          pkg-config --version
+          gcc --version
+          pytest --version
+
+          echo ""
+          echo "=== System Libraries ==="
+          pkg-config --list-all | grep -E "fftw3|sndfile|samplerate|jack|libav|rubberband" || true
+
+          echo ""
+          echo "=== Python Packages ==="
+          pip list | grep -E "meson|numpy|pytest|uv"
+
+          echo ""
+          echo "=== Environment Setup Complete ==="
+          echo "You can now:"
+          echo "  - Build C library: meson setup builddir && meson compile -C builddir"
+          echo "  - Build with tests: meson setup builddir -Dtests=true && meson compile -C builddir"
+          echo "  - Build with sanitizers: meson setup builddir -Db_sanitize=address,undefined -Dtests=true"
+          echo "  - Build Python wheel: uv build --wheel (or pip wheel .)"
+          echo "  - Run tests: meson test -C builddir (C) or pytest python/tests/ (Python)"
diff --git a/.gitignore b/.gitignore
@@ -59,3 +59,9 @@ vcpkg_installed/
 _codeql_detected_source_root
 .vscode/settings.json
 tmp_aubio_*
+
+# Generated test audio files
+test_bpm_changes.wav
+test_bpm_gradual.wav
+test_bpm_changes_ground_truth.json
+test_bpm_gradual_ground_truth.json
diff --git a/README.md b/README.md
@@ -213,6 +213,10 @@ Contributing
 Patches are welcome: please fork the latest git repository and create a feature
 branch. Submitted requests should pass all continuous integration tests.
 
+### GitHub Copilot Support
+
+This repository includes automated environment setup for GitHub Copilot Coding Agent. The `.github/copilot-setup-steps.yml` file ensures that Copilot has all necessary build tools, dependencies, and testing infrastructure pre-installed. For details, see [`.github/COPILOT_SETUP_README.md`](.github/COPILOT_SETUP_README.md).
+
 For optimization and modernization priorities, see:
 - [**OPTIMIZATION_SUMMARY.md**](OPTIMIZATION_SUMMARY.md) - Quick reference guide
 - [**OPTIMIZATION_ROADMAP.md**](OPTIMIZATION_ROADMAP.md) - Detailed implementation roadmap
diff --git a/COMPREHENSIVE_FIX_SUMMARY.md → ...RITY/reports/COMPREHENSIVE_FIX_SUMMARY.md b/COMPREHENSIVE_FIX_SUMMARY.md → ...RITY/reports/COMPREHENSIVE_FIX_SUMMARY.md
diff --git a/FUTURE_ACTIONS.md → SECURITY/reports/FUTURE_ACTIONS.md b/FUTURE_ACTIONS.md → SECURITY/reports/FUTURE_ACTIONS.md
diff --git a/IMPLEMENTATION_PLAN.md → SECURITY/reports/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md → SECURITY/reports/IMPLEMENTATION_PLAN.md
diff --git a/ISSUE_433_SUMMARY.md → SECURITY/reports/ISSUE_433_SUMMARY.md b/ISSUE_433_SUMMARY.md → SECURITY/reports/ISSUE_433_SUMMARY.md
diff --git a/TEST_COVERAGE_SUMMARY.md → SECURITY/reports/TEST_COVERAGE_SUMMARY.md b/TEST_COVERAGE_SUMMARY.md → SECURITY/reports/TEST_COVERAGE_SUMMARY.md
diff --git a/OPTIMIZATION_ROADMAP.md → copilot/OPTIMIZATION_ROADMAP.md b/OPTIMIZATION_ROADMAP.md → copilot/OPTIMIZATION_ROADMAP.md
diff --git a/OPTIMIZATION_SUMMARY.md → copilot/OPTIMIZATION_SUMMARY.md b/OPTIMIZATION_SUMMARY.md → copilot/OPTIMIZATION_SUMMARY.md
diff --git a/OPTIMIZATION_VISUAL.md → copilot/OPTIMIZATION_VISUAL.md b/OPTIMIZATION_VISUAL.md → copilot/OPTIMIZATION_VISUAL.md