# Copilot Instructions for aubio-ledfx

## Project Overview

**aubio-ledfx** is a maintained fork of the aubio audio analysis library, providing Python 3.8-3.13 support with pre-built wheels. This fork migrated from waf to **Meson build system** and uses **vcpkg** for cross-platform dependency management.

- **Purpose**: Provide reliable, up-to-date aubio releases for projects like LedFx
- **Core**: C library (`libaubio`) for real-time audio analysis (onset detection, pitch tracking, tempo, MFCC)
- **Python**: NumPy-integrated extension module built via `meson-python`
- **Platforms**: Linux (x64/ARM64), macOS (Intel/Apple Silicon), Windows (AMD64)

## Build System Architecture

### Meson + vcpkg Workflow

**Critical**: This project uses Meson (NOT waf anymore). All build configuration is in `meson.build`, `meson_options.txt`, and `pyproject.toml`.

```bash
# Standard C library build
meson setup builddir
meson compile -C builddir

# Python wheel build (uses meson-python)
pip install .  # or: uv build --wheel
```

**vcpkg integration** (`vcpkg.json`):
- Dependencies (libsndfile, libsamplerate, fftw3, rubberband, ffmpeg) are installed automatically
- Meson's `meson.build` lines 66-149 handle vcpkg triplet detection and installation
- GitHub Actions runners use pre-installed vcpkg at `$VCPKG_INSTALLATION_ROOT`

### Build Directory Structure

```
builddir/                 # Meson build output (C library)
├── src/                  # Compiled libaubio
└── python/              # Python extension (_aubio.so/.pyd)

vcpkg_installed/         # vcpkg dependencies (auto-generated)
├── x64-linux/           # or arm64-osx, x64-windows, etc.
│   ├── lib/
│   └── include/
```

**Never** manually edit `vcpkg_installed/` - it's regenerated by vcpkg.

## Python Package Build

### meson-python Integration

The Python package uses **meson-python** (PEP 517 backend) instead of setuptools:

1. **Entry point**: `pyproject.toml` (NOT `setup.py` - deleted during migration)
2. **Build config**: `python/meson.build` orchestrates:
   - Code generation via `python/lib/gen_external.py` (wraps C API)
   - Static linking against `libaubio_static` for portable wheels
   - NumPy integration (requires `numpy.get_include()`)

3. **Generated code**: `python/gen/gen-*.c` files are auto-generated at build time from `src/aubio.h`

### Critical Build Details

**Windows**: Only static `libaubio.a` is built (no DLL) because aubio lacks `dllexport` declarations. Python extension links statically.

**macOS**: 
- Deployment targets: 10.15 (x86_64), 11.0 (ARM64)
- Rubberband requires `libc++` linker flag (see `meson.build` line 342)

**Linux**: Uses `gcc-toolset-14` in manylinux containers for C++17 compatibility (rubberband dependency)

## CI/CD (`.github/workflows/build.yml`)

**cibuildwheel** builds wheels for cp310-cp313 on all platforms:

```yaml
matrix:
  include:
    - os: ubuntu-latest, arch: x86_64
    - os: ubuntu-24.04-arm, arch: aarch64  # Native ARM (no QEMU!)
    - os: windows-latest, arch: AMD64
    - os: macos-15-intel, arch: x86_64
    - os: macos-latest, arch: arm64
```

**Platform-specific vcpkg setup**:
- **macOS**: Pre-install vcpkg deps with correct deployment target before cibuildwheel
- **Linux/Windows**: `before-all` installs vcpkg inside manylinux/Windows container

**Environment variables matter**:
- `CMAKE_PREFIX_PATH` / `PKG_CONFIG_PATH`: Point Meson to vcpkg-installed libs
- `VCPKG_ROOT`: Pre-installed vcpkg on GH runners
- `MACOSX_DEPLOYMENT_TARGET`: Platform compatibility (10.15/11.0)

## Key Files & Their Roles

### Build System
- `meson.build` (446 lines): Root build file, handles vcpkg, dependencies, library compilation
- `src/meson.build` (271 lines): Compiles libaubio (shared + static), installs headers
- `python/meson.build` (123 lines): Python extension build, links static libaubio
- `meson_options.txt`: Build options (double precision, FFT backend, dependencies)
- `pyproject.toml`: Python packaging (meson-python backend, cibuildwheel config)

### Code Generation
- `python/lib/gen_external.py`: Parses `src/aubio.h`, generates Python C API wrappers
  - **Removed distutils dependency** (PR #13): Now uses direct compiler detection
  - Generates `gen-onset.c`, `gen-pitch.c`, etc. at build time
  
### Dependency Management
- `vcpkg.json`: Manifest declaring all C library dependencies
- `doc/vcpkg_integration.md`: Explains vcpkg workflow and troubleshooting

## Common Tasks

### Adding a Meson Build Option

1. Add to `meson_options.txt`:
   ```meson
   option('new-feature', type: 'feature', value: 'auto', description: '...')
   ```
2. Use in `meson.build`:
   ```meson
   if get_option('new-feature').enabled()
     conf_data.set('HAVE_NEW_FEATURE', 1)
   endif
   ```

### Adding a vcpkg Dependency

1. Edit `vcpkg.json`, add package name
2. Update `meson.build` to use dependency:
   ```meson
   new_dep = dependency('newlib', required: get_option('new-feature'))
   if new_dep.found()
     dependencies += new_dep
   endif
   ```

### Testing Locally

```bash
# C tests
meson setup builddir -Dtests=true
meson test -C builddir

# Python tests
pip install -e . --no-build-isolation
pytest python/tests/
```

### Debugging Build Issues

**Check Meson logs**: `builddir/meson-logs/meson-log.txt` shows dependency detection

**Verify vcpkg**: `ls vcpkg_installed/<triplet>/lib/pkgconfig/` should list `.pc` files

**Python build issues**: 
- Use `--no-build-isolation` to see environment variables
- Check NumPy is installed: `python -c "import numpy; print(numpy.get_include())"`

## Project-Specific Conventions

### Library Structure
- **Core types**: `fvec_t` (float vector), `cvec_t` (complex), `fmat_t` (matrix) - see `src/types.h`
- **Modules**: Organized by function (`onset/`, `pitch/`, `spectral/`, `temporal/`)
- **Object pattern**: All objects use `new_aubio_<type>()` / `del_aubio_<type>()` / `aubio_<type>_do()` convention

### FFT Backends (Priority Order)
1. **fftw3f** (single precision, recommended)
2. **Accelerate** (macOS, auto-detected)
3. **Intel IPP** (Windows/Linux, optional)
4. **ooura** (fallback, always compiled)

Configured via `meson_options.txt`, detected in `meson.build` lines 229-255.

### Platform-Specific Code Paths

- **macOS**: Uses Accelerate framework, CoreAudio for I/O (`src/io/source_apple_audio.c`)
- **Windows**: `src/utils/windll.c` for DLL entry point, static-only builds
- **All**: Conditional compilation via `config.h` defines (`HAVE_SNDFILE`, `HAVE_LIBAV`, etc.)

## Migration Context (waf → Meson)

**What changed in PR #13**:
- Removed: `waf`, `wscript*`, `setup.py`, `Makefile`, `python/lib/moresetuptools.py`
- Added: `meson.build` files, `meson_options.txt`, `vcpkg.json`
- Python: Now uses `meson-python` backend (declarative `pyproject.toml`)
- CI: Switched from per-platform matrix to cibuildwheel with vcpkg

**Old commands → New equivalents**:
- `./waf configure` → `meson setup builddir`
- `./waf build` → `meson compile -C builddir`
- `./waf install` → `meson install -C builddir`
- `python setup.py build` → `pip install .`

See `doc/meson_reference.rst` for comprehensive command reference.

## When Editing C Code

1. **Header changes**: If modifying `src/aubio.h`, Python wrappers regenerate automatically
2. **New source files**: Add to `aubio_sources` in `src/meson.build`
3. **New dependencies**: Update `dependencies` list in `meson.build`
4. **Config defines**: Use `conf_data.set()` in `meson.build`, access via `config.h`

## When Editing CI

- **vcpkg versions**: Pinned in `vcpkg.json` (no version= means latest)
- **Python versions**: `build = ["cp310-*", "cp311-*", ...]` in `pyproject.toml`
- **Architecture changes**: Update `matrix` in `.github/workflows/build.yml`
- **Testing changes**: Disabled in CI (tests are `|| true`) - fix tests before enabling

## External References

- Meson docs: https://mesonbuild.com/
- vcpkg: https://vcpkg.io/en/docs/users/manifests.html
- meson-python: https://meson-python.readthedocs.io/
- aubio docs: https://aubio.org/documentation

## Questions to Clarify

If you encounter unclear areas, consider:
- Are tests fully working? (Currently allowed to fail in CI)
- Should Windows build shared library with proper exports?
- Optimal vcpkg caching strategy for faster CI builds?
