noise-repellent Development Rules

This file contains consolidated development rules for noise-repellent that work with both Cursor and Antigravity IDEs.

LV2 Plugin Development Guidelines

description: "LV2 plugin development and maintenance guidelines for noise-repellent" alwaysApply: true

CRITICAL: Always rebuild and test after modifying plugin code or TTL files.

Plugin Architecture

Plugin Types

nrepellent: Standard noise reduction plugin (manual noise profile)
nrepellent-adaptive: Adaptive noise reduction plugin (automatic noise learning)

Port Management

trigger: file_modified glob: ["plugins/.c", "lv2ttl/.ttl.in"] description: "TTL file and port index synchronization checker"

Port Index Synchronization

CRITICAL: Port indices in C code and TTL files MUST be synchronized.

When removing/adding ports:

Update
```
PortIndex
```
enum in C code
Update corresponding
```
.ttl.in
```
files
Shift all subsequent port indices
Rebuild to regenerate TTL files

Example: Removing Enable Control

C Code Changes:
- Remove NOISEREPELLENT_ENABLE from PortIndex enum
- Shift subsequent indices: LATENCY (7), INPUT_1 (8), OUTPUT_1 (9)
- Remove enable field from plugin struct
- Remove enable case from connect_port()
- Change signal_crossfade_run() to always pass 'true'

TTL Changes:
- Remove enable port definition (index 7)
- Shift subsequent ports: latency (7), input (8), output (9)

Common Port Operations

Adding a Port

Add entry to
```
PortIndex
```
enum in C file
Add port definition to corresponding
```
.ttl.in
```
file
Shift subsequent port indices if inserting in middle
Rebuild to verify:
```
meson compile -C build
```

Removing a Port

Remove from
```
PortIndex
```
enum
Remove from
```
.ttl.in
```
file
Shift subsequent indices down by 1
Update connect_port() switch cases
Rebuild and test

Validation Commands

# Check generated TTL files
grep "lv2:index" build/*.ttl

# Verify C enum values
grep "NOISEREPELLENT_" plugins/*.c

# Rebuild after changes
meson compile -C build

TTL File Management

File Structure

.ttl.in
files: Templates in
```
lv2ttl/
```
directory
Generated
.ttl
files: Built in
```
build/
```
directory
Never edit generated
.ttl
files directly

Port Definitions

lv2:port [
  a lv2:ControlPort, lv2:InputPort ;
  lv2:index 0 ;
  lv2:symbol "reduction" ;
  lv2:name "Reduction amount" ;
  lv2:minimum 0.0 ;
  lv2:maximum 20.0 ;
  lv2:default 10.0 ;
  units:unit units:db ;
]

Plugin Registration

Each plugin needs:

URI definition (e.g.,
```
NOISEREPELLENT_ADAPTIVE_URI
```
)
Descriptor struct (
```
LV2_Descriptor
```
)
```
lv2_descriptor()
```
function entry

Build System

trigger: file_modified glob: ["plugins/.c", "src/.c", "lv2ttl/*.ttl.in"] description: "Plugin compilation and testing workflow"

Meson Configuration

# Configure build
meson setup build --wrap-mode=forcefallback

# Build project
meson compile -C build

# Clean rebuild
rm -rf build && meson setup build --wrap-mode=forcefallback

Subproject Management

For libspecbleach development:

# Create symlink to local libspecbleach
cd subprojects
ln -sf ../../../libspecbleach libspecbleach

# Force meson to use local version
meson setup build --wrap-mode=forcefallback

Plugin Development Workflow

1. Code Changes

Modify plugin C files in
```
plugins/
```
Update port indices if needed
Update TTL templates in
```
lv2ttl/
```

2. Build and Test

# Build plugins
meson compile -C build

# Check generated files
ls -la build/*.dylib build/*.ttl

3. Verify Port Synchronization

# Check that port indices match between C and TTL
grep -n "lv2:index" build/*.ttl
grep -n "NOISEREPELLENT_" plugins/*.c

LV2 Plugin Development Patterns

trigger: file_modified glob: ["plugins/*.c"] description: "LV2 plugin development best practices and patterns"

Plugin Structure Requirements

Required Functions

```
instantiate()
```
: Create plugin instance
```
connect_port()
```
: Connect control/audio ports
```
activate()
```
: Prepare for processing
```
run()
```
: Process audio (required)
```
deactivate()
```
: Optional cleanup
```
cleanup()
```
: Destroy instance

Port Connection Patterns

typedef enum PortIndex {
  CONTROL_PARAM_1 = 0,
  CONTROL_PARAM_2 = 1,
  // ... more controls
  LATENCY_REPORT = N,
  AUDIO_INPUT = N+1,
  AUDIO_OUTPUT = N+2,
} PortIndex;

Memory Management

Allocation

Use
```
calloc()
```
for zero-initialized memory
Check allocation success
Store pointers in plugin struct

Cleanup

Free all allocated memory in
```
cleanup()
```
Set pointers to NULL after freeing
Handle partial initialization failures

Audio Processing

Buffer Handling

Support both separate and in-place buffers
Copy input buffers when in-place processing needed
Use crossfade for smooth parameter transitions

Sample Rate Handling

Store sample rate from
```
instantiate()
```
Use for latency calculations
Size buffers appropriately

Error Handling

Validation

Check all required features in
```
instantiate()
```
Validate allocation success
Log errors with
```
lv2_log_error()
```

Recovery

Return NULL on critical failures
Clean up partial allocations
Provide meaningful error messages

Plugin Variants

Mono/Stereo Patterns

Separate descriptor functions for each variant
Share common processing code
Different connect_port functions for stereo

URI Management

Define unique URIs for each variant
Include version info in URIs
Document URI patterns

libspecbleach Integration

trigger: always_on glob: description: "Subproject development workflow for libspecbleach integration"

When working on libspecbleach changes that affect noise-repellent:

Setup Local Development

Create symlink:

cd subprojects
ln -sf ../../../libspecbleach libspecbleach

Configure with forcefallback:

meson setup build --wrap-mode=forcefallback

Verify symlink usage:

meson compile -C build -v | grep libspecbleach

Development Workflow

Make changes to libspecbleach
Format libspecbleach code:
```
ninja -C libspecbleach/build format
```
Rebuild noise-repellent:
```
meson compile -C build
```
Test plugin functionality

Common Issues

API Changes

Function signatures modified → Update noise-repellent calls
Struct definitions changed → Update plugin structs
Constants redefined → Update enum values

Build Conflicts

Header not found → Check include paths
Linker errors → Verify library versions
Symbol conflicts → Check for duplicate definitions

Testing Integration

Plugin crashes → Check API compatibility
Audio artifacts → Verify parameter ranges
Performance issues → Profile with new libspecbleach

Reconfiguration

# If libspecbleach API changes significantly
rm -rf build
meson setup build --wrap-mode=forcefallback

# Or reconfigure existing build
meson setup --reconfigure build --wrap-mode=forcefallback

Version Management

Use git submodules for stable releases
Use symlinks for active development
Tag releases when API stabilizes

Common Issues

Port Index Mismatches

Symptoms: Plugin loads but controls don't work Solution: Verify port indices match between C enum and TTL files

TTL Generation Issues

Symptoms: Build succeeds but plugin doesn't appear in host Solution: Check that

.ttl.in

files are valid Turtle syntax

Subproject Issues

Symptoms: Link errors or API mismatches Solution: Use

--wrap-mode=forcefallback

and verify symlinks

Plugin Testing

Manual Testing

Load plugin in DAW (Ardour, Reaper, etc.)
Verify all controls work
Test mono/stereo versions
Check latency reporting

Audio Quality Testing

Use examples from libspecbleach
Test with various noise types
Verify adaptive learning works
Manual Learning Testing: Enable learning, play noise, disable learning, verify reduction applies
Mode Testing: Test all 3 reduction modes (Mean/Median/Max) for different noise characteristics
Reset Functionality: Verify noise profile reset clears old profiles before new learning

Code Organization

noise-repellent/
├── plugins/              # LV2 plugin implementations
├── lv2ttl/              # TTL file templates
├── src/                 # Shared utilities
├── subprojects/         # Dependencies (libspecbleach)
├── meson.build         # Build configuration
└── meson_options.txt   # Build options

Plugin Parameters

Control Ranges

Reduction Amount: 0.0-20.0 dB (default: 10.0)
Noise Scaling Type: 0-2 (integer, default: 2)
Noise Offset: 0.0-12.0 dB (default: 2.0)
Post-filter Threshold: -10.0-10.0 dB (default: -10.0)
Smoothing: 0.0-100.0% (default: 0.0)
Whitening: 0.0-100.0% (default: 0.0)

Audio Ports

Mono Plugin: Input (index 8), Output (index 9)
Stereo Plugin: Left Input (8), Left Output (9), Right Input (10), Right Output (11)

LV2 Plugin Safety and Reliability Rules

Control Port Safety

CRITICAL: Always protect against unconnected control ports in

run()

functions.

Pattern:

// Safe parameter access with defaults
self->parameters.param = self->param_port ?
    *self->param_port : DEFAULT_VALUE;

Why: LV2 hosts may not connect all control ports. Null pointer dereferences cause crashes.

Audio Port Validation

CRITICAL: Validate audio ports before processing.

Pattern:

if (!self->input || !self->output) {
    return;  // Silent failure is safer than crash
}

Why: Audio ports are mandatory but hosts might pass NULL under error conditions.

Latency Compensation Handling

CRITICAL: Handle initial latency periods in crossfade and delay compensation logic.

Pattern:

// During startup, pass through audio unchanged
if (samples_processed < latency) {
    output[k] = input[k];
    // Continue filling buffers for future processing
}

Why: Delay buffers start empty, causing silence. Audio must flow immediately on startup.

Processing State Management

IMPORTANT: Always call core processing functions regardless of UI state.

Pattern:

// Call processing function unconditionally
process_audio(input, output, parameters);

// Route output based on processing state
if (bypass_enabled) {
    apply_crossfade(input, output, false);  // Pass through
} else {
    apply_crossfade(input, output, true);   // Apply processing
}

Why: Processing libraries often handle multiple modes internally. Separate processing from output routing.

Parameter Validation

RECOMMENDED: Validate parameter ranges before passing to processing functions.

Pattern:

// Clamp parameters to valid ranges
param = fmaxf(fminf(param, MAX_VALUE), MIN_VALUE);

Why: Prevents undefined behavior from out-of-range parameters.

Quality Assurance

Build Verification

All plugins compile without warnings
TTL files generate correctly
Port indices are synchronized
Plugin binaries load in test host

Code Review Checklist

Port management follows guidelines
TTL syntax is valid
Memory management is correct
Error handling implemented
Crossfade logic preserved for smooth transitions
Control port safety rules applied (null checks with defaults)
Audio port validation present
Latency compensation handles startup period correctly
Processing called unconditionally, output routing controlled separately

Development Environment

Required Tools

C compiler (clang/gcc)
LV2 SDK headers
Meson build system
Ninja build tool

Recommended Tools

DAW for testing (Ardour, Reaper)
LV2 plugin host for validation
Audio analysis tools

Performance Considerations

Real-time Requirements

Low latency processing (< 10ms typical)
Efficient STFT implementation via libspecbleach
Memory-aligned allocations
Smooth parameter transitions via crossfade

Resource Management

Proper cleanup in
```
cleanup()
```
function
No memory leaks in instantiate/destroy cycle
Efficient buffer reuse for in-place processing

noise-repellent Development Rules

This file contains consolidated development rules for noise-repellent that work with both Cursor and Antigravity IDEs.

LV2 Plugin Development Guidelines

description: "LV2 plugin development and maintenance guidelines for noise-repellent" alwaysApply: true

CRITICAL: Always rebuild and test after modifying plugin code or TTL files.

Plugin Architecture

Plugin Types

nrepellent: Standard noise reduction plugin (manual noise profile)
nrepellent-adaptive: Adaptive noise reduction plugin (automatic noise learning)

Port Management

trigger: file_modified glob: ["plugins/.c", "lv2ttl/.ttl.in"] description: "TTL file and port index synchronization checker"

Port Index Synchronization

CRITICAL: Port indices in C code and TTL files MUST be synchronized.

When removing/adding ports:

Update
```
PortIndex
```
enum in C code
Update corresponding
```
.ttl.in
```
files
Shift all subsequent port indices
Rebuild to regenerate TTL files

Example: Removing Enable Control

C Code Changes:
- Remove NOISEREPELLENT_ENABLE from PortIndex enum
- Shift subsequent indices: LATENCY (7), INPUT_1 (8), OUTPUT_1 (9)
- Remove enable field from plugin struct
- Remove enable case from connect_port()
- Change signal_crossfade_run() to always pass 'true'

TTL Changes:
- Remove enable port definition (index 7)
- Shift subsequent ports: latency (7), input (8), output (9)

Common Port Operations

Adding a Port

Add entry to
```
PortIndex
```
enum in C file
Add port definition to corresponding
```
.ttl.in
```
file
Shift subsequent port indices if inserting in middle
Rebuild to verify:
```
meson compile -C build
```

Removing a Port

Remove from
```
PortIndex
```
enum
Remove from
```
.ttl.in
```
file
Shift subsequent indices down by 1
Update connect_port() switch cases
Rebuild and test

Validation Commands

# Check generated TTL files
grep "lv2:index" build/*.ttl

# Verify C enum values
grep "NOISEREPELLENT_" plugins/*.c

# Rebuild after changes
meson compile -C build

TTL File Management

File Structure

.ttl.in
files: Templates in
```
lv2ttl/
```
directory
Generated
.ttl
files: Built in
```
build/
```
directory
Never edit generated
.ttl
files directly

Port Definitions

lv2:port [
  a lv2:ControlPort, lv2:InputPort ;
  lv2:index 0 ;
  lv2:symbol "reduction" ;
  lv2:name "Reduction amount" ;
  lv2:minimum 0.0 ;
  lv2:maximum 20.0 ;
  lv2:default 10.0 ;
  units:unit units:db ;
]

Plugin Registration

Each plugin needs:

URI definition (e.g.,
```
NOISEREPELLENT_ADAPTIVE_URI
```
)
Descriptor struct (
```
LV2_Descriptor
```
)
```
lv2_descriptor()
```
function entry

Build System

trigger: file_modified glob: ["plugins/.c", "src/.c", "lv2ttl/*.ttl.in"] description: "Plugin compilation and testing workflow"

Meson Configuration

# Configure build
meson setup build --wrap-mode=forcefallback

# Build project
meson compile -C build

# Clean rebuild
rm -rf build && meson setup build --wrap-mode=forcefallback

Subproject Management

For libspecbleach development:

# Create symlink to local libspecbleach
cd subprojects
ln -sf ../../../libspecbleach libspecbleach

# Force meson to use local version
meson setup build --wrap-mode=forcefallback

Plugin Development Workflow

1. Code Changes

Modify plugin C files in
```
plugins/
```
Update port indices if needed
Update TTL templates in
```
lv2ttl/
```

2. Build and Test

# Build plugins
meson compile -C build

# Check generated files
ls -la build/*.dylib build/*.ttl

3. Verify Port Synchronization

# Check that port indices match between C and TTL
grep -n "lv2:index" build/*.ttl
grep -n "NOISEREPELLENT_" plugins/*.c

LV2 Plugin Development Patterns

trigger: file_modified glob: ["plugins/*.c"] description: "LV2 plugin development best practices and patterns"

Plugin Structure Requirements

Required Functions

```
instantiate()
```
: Create plugin instance
```
connect_port()
```
: Connect control/audio ports
```
activate()
```
: Prepare for processing
```
run()
```
: Process audio (required)
```
deactivate()
```
: Optional cleanup
```
cleanup()
```
: Destroy instance

Port Connection Patterns

typedef enum PortIndex {
  CONTROL_PARAM_1 = 0,
  CONTROL_PARAM_2 = 1,
  // ... more controls
  LATENCY_REPORT = N,
  AUDIO_INPUT = N+1,
  AUDIO_OUTPUT = N+2,
} PortIndex;

Memory Management

Allocation

Use
```
calloc()
```
for zero-initialized memory
Check allocation success
Store pointers in plugin struct

Cleanup

Free all allocated memory in
```
cleanup()
```
Set pointers to NULL after freeing
Handle partial initialization failures

Audio Processing

Buffer Handling

Support both separate and in-place buffers
Copy input buffers when in-place processing needed
Use crossfade for smooth parameter transitions

Sample Rate Handling

Store sample rate from
```
instantiate()
```
Use for latency calculations
Size buffers appropriately

Error Handling

Validation

Check all required features in
```
instantiate()
```
Validate allocation success
Log errors with
```
lv2_log_error()
```

Recovery

Return NULL on critical failures
Clean up partial allocations
Provide meaningful error messages

Plugin Variants

Mono/Stereo Patterns

Separate descriptor functions for each variant
Share common processing code
Different connect_port functions for stereo

URI Management

Define unique URIs for each variant
Include version info in URIs
Document URI patterns

libspecbleach Integration

trigger: always_on glob: description: "Subproject development workflow for libspecbleach integration"

When working on libspecbleach changes that affect noise-repellent:

Setup Local Development

Create symlink:

cd subprojects
ln -sf ../../../libspecbleach libspecbleach

Configure with forcefallback:

meson setup build --wrap-mode=forcefallback

Verify symlink usage:

meson compile -C build -v | grep libspecbleach

Development Workflow

Make changes to libspecbleach
Format libspecbleach code:
```
ninja -C libspecbleach/build format
```
Rebuild noise-repellent:
```
meson compile -C build
```
Test plugin functionality

Common Issues

API Changes

Function signatures modified → Update noise-repellent calls
Struct definitions changed → Update plugin structs
Constants redefined → Update enum values

Build Conflicts

Header not found → Check include paths
Linker errors → Verify library versions
Symbol conflicts → Check for duplicate definitions

Testing Integration

Plugin crashes → Check API compatibility
Audio artifacts → Verify parameter ranges
Performance issues → Profile with new libspecbleach

Reconfiguration

# If libspecbleach API changes significantly
rm -rf build
meson setup build --wrap-mode=forcefallback

# Or reconfigure existing build
meson setup --reconfigure build --wrap-mode=forcefallback

Version Management

Use git submodules for stable releases
Use symlinks for active development
Tag releases when API stabilizes

Common Issues

Port Index Mismatches

Symptoms: Plugin loads but controls don't work Solution: Verify port indices match between C enum and TTL files

TTL Generation Issues

Symptoms: Build succeeds but plugin doesn't appear in host Solution: Check that

.ttl.in

files are valid Turtle syntax

Subproject Issues

Symptoms: Link errors or API mismatches Solution: Use

--wrap-mode=forcefallback

and verify symlinks

Plugin Testing

Manual Testing

Load plugin in DAW (Ardour, Reaper, etc.)
Verify all controls work
Test mono/stereo versions
Check latency reporting

Audio Quality Testing

Use examples from libspecbleach
Test with various noise types
Verify adaptive learning works
Manual Learning Testing: Enable learning, play noise, disable learning, verify reduction applies
Mode Testing: Test all 3 reduction modes (Mean/Median/Max) for different noise characteristics
Reset Functionality: Verify noise profile reset clears old profiles before new learning

Code Organization

noise-repellent/
├── plugins/              # LV2 plugin implementations
├── lv2ttl/              # TTL file templates
├── src/                 # Shared utilities
├── subprojects/         # Dependencies (libspecbleach)
├── meson.build         # Build configuration
└── meson_options.txt   # Build options

Plugin Parameters

Control Ranges

Reduction Amount: 0.0-20.0 dB (default: 10.0)
Noise Scaling Type: 0-2 (integer, default: 2)
Noise Offset: 0.0-12.0 dB (default: 2.0)
Post-filter Threshold: -10.0-10.0 dB (default: -10.0)
Smoothing: 0.0-100.0% (default: 0.0)
Whitening: 0.0-100.0% (default: 0.0)

Audio Ports

Mono Plugin: Input (index 8), Output (index 9)
Stereo Plugin: Left Input (8), Left Output (9), Right Input (10), Right Output (11)

LV2 Plugin Safety and Reliability Rules

Control Port Safety

CRITICAL: Always protect against unconnected control ports in

run()

functions.

Pattern:

// Safe parameter access with defaults
self->parameters.param = self->param_port ?
    *self->param_port : DEFAULT_VALUE;

Why: LV2 hosts may not connect all control ports. Null pointer dereferences cause crashes.

Audio Port Validation

CRITICAL: Validate audio ports before processing.

Pattern:

if (!self->input || !self->output) {
    return;  // Silent failure is safer than crash
}

Why: Audio ports are mandatory but hosts might pass NULL under error conditions.

Latency Compensation Handling

CRITICAL: Handle initial latency periods in crossfade and delay compensation logic.

Pattern:

// During startup, pass through audio unchanged
if (samples_processed < latency) {
    output[k] = input[k];
    // Continue filling buffers for future processing
}

Why: Delay buffers start empty, causing silence. Audio must flow immediately on startup.

Processing State Management

IMPORTANT: Always call core processing functions regardless of UI state.

Pattern:

// Call processing function unconditionally
process_audio(input, output, parameters);

// Route output based on processing state
if (bypass_enabled) {
    apply_crossfade(input, output, false);  // Pass through
} else {
    apply_crossfade(input, output, true);   // Apply processing
}

Why: Processing libraries often handle multiple modes internally. Separate processing from output routing.

Parameter Validation

RECOMMENDED: Validate parameter ranges before passing to processing functions.

Pattern:

// Clamp parameters to valid ranges
param = fmaxf(fminf(param, MAX_VALUE), MIN_VALUE);

Why: Prevents undefined behavior from out-of-range parameters.

Quality Assurance

Build Verification

All plugins compile without warnings
TTL files generate correctly
Port indices are synchronized
Plugin binaries load in test host

Code Review Checklist

Port management follows guidelines
TTL syntax is valid
Memory management is correct
Error handling implemented
Crossfade logic preserved for smooth transitions
Control port safety rules applied (null checks with defaults)
Audio port validation present
Latency compensation handles startup period correctly
Processing called unconditionally, output routing controlled separately

noise-repellent Development Rules

Related Skills

Markdown Converter

Nano Banana Pro

1password