vst-chip/.junie/guidelines.md

VST Chip Synthesizer Development Guidelines

Project Overview

VST Chip is a Kotlin multiplatform project that implements a chip-style synthesizer with a web interface. The project consists of:

• JVM backend that serves the web application
• JS frontend that runs in the browser
• Audio worklet processor for real-time audio processing

Build/Configuration Instructions

Prerequisites

• JDK 11 or higher
• Gradle 7.x or higher
• Node.js and npm (for JS development)

Building the Project

1. Full Build:

   ./gradlew build
   

2. JS Build Only:

   ./gradlew buildJS
   

3. Deployment:

   ./gradlew deploy
   

   This will build the project, copy web assets, and deploy to the configured server location.

Configuration

• Server port: 9005 (configured in Main.kt)
• JDBC stats port: 6005
• Deployment directory: configured in build.gradle.kts as vst-chip.midi-vst.com

Testing Information

• Do not generate tests for this project. The audio processing code is highly specialized and requires manual testing with audio equipment.
• Manual testing should be performed using MIDI controllers and audio monitoring tools.

Development Information

Project Structure

• src/commonMain: Shared code between JS and JVM
• src/jsMain: Browser-specific code
• src/jvmMain: Server-specific code
• audio-worklet: Audio processing code that runs in a separate thread in the browser

Key Components

1. JVM Server (src/jvmMain/kotlin/nl/astraeus/vst/chip/Main.kt):

   • Undertow server that serves the web application
   • Database initialization
   • Logging setup

2. JS Frontend (src/jsMain/kotlin/nl/astraeus/vst/chip/Main.kt):

   • UI implementation using Komponent library
   • MIDI handling
   • WebSocket client for server communication

3. Audio Processor (audio-worklet/src/jsMain/kotlin/nl/astraeus/vst/chip/ChipProcessor.kt):

   • Real-time audio synthesis
   • MIDI message handling
   • Sound generation with multiple waveforms (sine, square, triangle, sawtooth)
   • Effects processing (FM, AM, ADSR envelope, delay, feedback)

Development Workflow

1. Make changes to the code
2. Run ./gradlew buildJS to build the JS part
3. Run the JVM application to test locally
4. Use ./gradlew deploy to deploy to the server

Audio Worklet Development

The audio worklet runs in a separate thread in the browser and handles real-time audio processing. When modifying the audio worklet code:

1. Understand that it runs in a separate context from the main JS code
2. Communication happens via message passing
3. Performance is critical - avoid garbage collection and heavy operations in the audio processing loop

MIDI Implementation

The synthesizer responds to standard MIDI messages:

• Note On/Off (0x90/0x80)
• Control Change (0xb0) for various parameters
• Program Change (0xc9) for waveform selection

Deployment

The project is configured to deploy to a specific server location. The deployment process:

1. Builds the project
2. Copies web assets
3. Creates a symbolic link for the latest version