### Manual Installation: Building zynaddsubfx with zyn-fusion

Source: https://github.com/johanneslorenz/lmms-zyn-fusion-test/blob/master/README.md

This involves building the 'zynaddsubfx' component, integrating it with zyn-fusion. It requires setting the PKG_CONFIG_PATH to include the spa configuration and specifying CMake variables for the zyn-fusion directory and GUI module. The output is a spa plugin that should allow zynaddsubfx to start.

```shell
git clone -b osc-plugin git@github.com:zynaddsubfx/zynaddsubfx.git
# Build like in the README, but prepend PKG_CONFIG_PATH and add CMake variables
# Example: PKG_CONFIG_PATH=$PKG_CONFIG_PATH:<spa pkg config directory>
cmake -DZynFusionDir=<path to where fusion is>/package -DGuiModule=zest <path to zynaddsubfx source>
# The output spa plugin path is usually ending on src/Output/libzynaddsubfx_spa.so
```

--------------------------------

### Manual Installation: Compiling mruby-zest-build

Source: https://github.com/johanneslorenz/lmms-zyn-fusion-test/blob/master/README.md

This step involves compiling the 'mruby-zest-build' component. It requires cloning the repository and then executing the 'make pack' command. This is part of the manual installation procedure for the LMMS-zyn-fusion test setup.

```shell
git clone -b master git@github.com:mruby-zest/mruby-zest-build.git
# Compile like in the README
make pack
```

--------------------------------

### Manual Installation: Cloning and Building spa

Source: https://github.com/johanneslorenz/lmms-zyn-fusion-test/blob/master/README.md

This section details the manual installation process, focusing on cloning and building the 'spa' library. It requires a C++11 compiler and specifies cloning from a GitLab repository. After successful compilation, the location of the PKG config file needs to be recorded for subsequent steps.

```shell
git clone -b master https://gitlab.com/simple-plugin-api/spa.git
# Follow README instructions for a normal install
# Record the PKG config file's directory (e.g., ~/cprogs/spa/install/lib64/pkgconfig)
```

--------------------------------

### LMMS File Operations Example

Source: https://context7.com/johanneslorenz/lmms-zyn-fusion-test/llms.txt

Demonstrates common file operations within LMMS, including loading projects, previewing and loading presets (.xmz files), converting old Zyn instruments to SPA-based plugins, and exporting songs to audio files. A command-line export example is also provided.

```bash
# Launch LMMS
./lmms

# Workflow within LMMS GUI:
# 1. Load existing project with Zyn instruments
#    File → Open → select .mmp file

# 2. Preview XMZ presets from sidebar
#    - Navigate to 'My Presets' in left sidebar
#    - Click on any .xmz preset file
#    - Audio preview plays automatically

# 3. Drag-drop XMZ preset onto song
#    - Drag .xmz file from 'My Presets'
#    - Drop onto track in song editor
#    - Creates new instrument track with preset loaded

# 4. Convert old Zyn instruments to new format
#    - Drag Zyn instrument icon onto old Zyn track
#    - Converts to SPA-based Zyn-Fusion plugin
#    - Preserves settings and parameters

# 5. Export song to audio file
#    File → Export → select format (WAV recommended)
#    Choose output path and quality settings

# Command-line export example:
./lmms render myproject.mmp --format wav --output song.wav
```

--------------------------------

### Manual SPA Library Compilation

Source: https://context7.com/johanneslorenz/lmms-zyn-fusion-test/llms.txt

This bash script outlines the steps for manually compiling the Simple Plugin API (SPA) library, typically used for communication between hosts and plugins. It includes configuring the build with CMake, specifying the compiler, installation prefix, build type, and then performing the compilation and installation. It also shows how to verify the installation of the pkg-config file for the SPA library.

```bash
# Manual SPA compilation (if not using build.sh)
cd spa
mkdir build-gcc
cd build-gcc

# Configure with compiler selection
cmake -DCOMPILER=gcc \
  -DCMAKE_INSTALL_PREFIX=$PWD/../install-gcc \
  -DCMAKE_BUILD_TYPE=Release \
  ..

make -j4
make install

# Verify pkg-config installation
ls ../install-gcc/lib64/pkgconfig/spa.pc
# or
ls ../install-gcc/lib/pkgconfig/spa.pc

# The spa.pc file enables other components to link against SPA
# Using pkg-config during dependent builds:
PKG_CONFIG_PATH=/path/to/spa/install-gcc/lib64/pkgconfig:$PKG_CONFIG_PATH
```

--------------------------------

### Build LMMS with SPA Plugin Host

Source: https://context7.com/johanneslorenz/lmms-zyn-fusion-test/llms.txt

Compiles LMMS with SPA plugin hosting capabilities. This process involves configuring CMake with SPA integration, building the project, and installing it. The example shows how to launch LMMS with the ZynAddSubFX plugin loaded by setting the SPA_PATH environment variable.

```bash
# Manual LMMS build with SPA support
cd new-lmms
mkdir build-gcc
cd build-gcc

# Configure with SPA integration
PKG_CONFIG_PATH=/path/to/spa/install/lib64/pkgconfig:$PKG_CONFIG_PATH \
cmake \
  -DCMAKE_C_COMPILER=gcc \
  -DCMAKE_CXX_COMPILER=g++ \
  -DCMAKE_INSTALL_PREFIX=$PWD/../install-gcc \
  -DCMAKE_BUILD_TYPE=Release \
  ..

make -j4
make install

# Launch LMMS with ZynAddSubFX plugin
SPA_PATH=/path/to/zynaddsubfx/build-gcc/src/Output \
  ../install-gcc/bin/lmms

# Verify plugin appears in LMMS instrument list
# Look for ZynAddSubFX with Zest logo icon
```

--------------------------------

### Manual Installation: Building LMMS with spa Plugin Support

Source: https://github.com/johanneslorenz/lmms-zyn-fusion-test/blob/master/README.md

This step focuses on building the LMMS application to support the spa plugin. Similar to building zynaddsubfx, it requires setting the PKG_CONFIG_PATH. An installation step is not mandatory. To run LMMS, the SPA_PATH environment variable must be set to the location of the zyn spa library.

```shell
git clone -b osc-plugin git@github.com:JohannesLorenz/lmms.git
# Build like in the README, but prepend PKG_CONFIG_PATH
# Example: PKG_CONFIG_PATH=$PKG_CONFIG_PATH:<spa pkg config directory>
cmake <path to lmms source>
# To start LMMS: SPA_PATH=<path to where zyn's spa lib is> ./lmms
```

--------------------------------

### Automated Installation Script for LMMS-zyn-fusion

Source: https://github.com/johanneslorenz/lmms-zyn-fusion-test/blob/master/README.md

This script automates the process of cloning necessary repositories, building, and running the LMMS-zyn-fusion test environment. It is suitable for users with ample bandwidth and disk space who do not intend to modify the source code. The process may take a considerable amount of time due to large submodule downloads.

```shell
./build.sh
./lmms
```

--------------------------------

### LMMS Automation Workflow Example

Source: https://context7.com/johanneslorenz/lmms-zyn-fusion-test/llms.txt

Details the process of connecting Zyn-Fusion parameters to LMMS automation. It explains how to open the ZynAddSubFX instrument window, create an automation track, drag-drop parameters (using the F1 key modifier), edit automation curves, and notes a limitation regarding direct controller connections.

```bash
# Launch and configure automation
./lmms myproject.mmp

# Within LMMS:
# 1. Open ZynAddSubFX instrument window
#    - Double-click Zyn instrument in Song Editor
#    - Fusion GUI appears with synthesizer controls

# 2. Create automation pattern
#    - Right-click parameter knob in Zyn GUI
#    - Select "Create Automation Track"

# 3. Drag-drop widget to automation pattern
#    **IMPORTANT: Hold F1 key during drag-drop**
#    (Not Ctrl like standard LMMS - this is specific to SPA plugins)
#    - Click and hold F1 key
#    - Drag parameter from Zyn window
#    - Drop onto automation pattern in timeline
#    - Release F1 key

# 4. Edit automation curve
#    - Click automation pattern to open editor
#    - Draw curves using standard LMMS automation tools
#    - Parameter changes are transmitted via OSC to Zyn

# Known limitation: Direct LMMS controller connections not yet supported
# Workaround: Use automation patterns for all parameter control
```

--------------------------------

### Check LMMS/Zyn-Fusion Issues and System Info

Source: https://context7.com/johanneslorenz/lmms-zyn-fusion-test/llms.txt

Provides commands and instructions for checking existing issues, verifying the build environment, and reporting problems for the LMMS Zyn-Fusion project. It includes commands to view the changelog, get Git commit information, check tool versions (LMMS, GCC, system), and suggests a structure for bug reports.

```bash
# Check current known issues
cat CHANGELOG.md
# Shows version history and breaking changes

# Before reporting, verify the issue:
# 1. Check if project loading takes >10 seconds (may cause crash)
# 2. Test with low volume to protect audio equipment
# 3. Note that saved files are incompatible with upstream LMMS

# File issues at:
# - Plugin-related (LMMS/Zyn/Fusion): This repository
# - SPA library design: https://gitlab.com/simple-plugin-api/spa/issues
# - SPA mirror: https://github.com/JohannesLorenz/spa/issues

# Include in bug reports:
git log -1 --oneline  # Current commit
./lmms --version      # LMMS version info
gcc --version         # Compiler version
uname -a             # System information

# Example bug report structure:
# Title: "LMMS crashes when loading project with multiple Zyn instances"
# Environment:
#   - Commit: a938189
#   - Compiler: GCC 11.2.0
#   - OS: Arch Linux 5.15.10
```

--------------------------------

### Checking Git Submodule Status

Source: https://github.com/johanneslorenz/lmms-zyn-fusion-test/blob/master/README.md

This command is used to check the status of git submodules within a repository. It is particularly relevant during the manual installation process to ensure that all necessary external dependencies have been correctly linked and updated.

```shell
git submodule status
```

--------------------------------

### Build ZynAddSubFX Plugin with Zest GUI

Source: https://context7.com/johanneslorenz/lmms-zyn-fusion-test/llms.txt

Builds the ZynAddSubFX plugin with OSC plugin support and Zest GUI integration using CMake. It configures the build with specific compilers, SPA, and Zest GUI settings, and verifies the generated SPA plugin. The output plugin can be used by LMMS after setting the SPA_PATH environment variable.

```bash
# Manual ZynAddSubFX build with all dependencies
cd zynaddsubfx
mkdir build-gcc
cd build-gcc

# Configure with SPA and Zest integration
PKG_CONFIG_PATH=/path/to/spa/install/lib64/pkgconfig:$PKG_CONFIG_PATH \
cmake \
  -DCMAKE_C_COMPILER=gcc \
  -DCMAKE_CXX_COMPILER=g++ \
  -DCMAKE_BUILD_TYPE=Release \
  -DGuiModule=zest \
  -DZynFusionDir=/path/to/mruby-zest-build/package \
  ..

make -j4

# Verify plugin was built
ls src/Output/libzynaddsubfx_spa.so
# This is the SPA plugin that LMMS will load

# Test standalone ZynAddSubFX with Fusion GUI
./src/zynaddsubfx
# Should launch with graphical Zest interface

# The plugin location must be added to SPA_PATH for LMMS:
# SPA_PATH=/path/to/zynaddsubfx/build-gcc/src/Output
```

--------------------------------

### Environment Variables for Plugin Configuration

Source: https://context7.com/johanneslorenz/lmms-zyn-fusion-test/llms.txt

These environment variables are used to control plugin discovery and loading behavior for SPA-based instruments within LMMS. SPA_PATH specifies directories to search for plugins, while PKG_CONFIG_PATH helps the build system locate necessary library configuration files.

```bash
# Set plugin search path for SPA-based instruments
export SPA_PATH=/path/to/zynaddsubfx/build-gcc/src/Output

# Add multiple plugin directories (colon-separated)
export SPA_PATH=/path/to/plugins1:/path/to/plugins2

# Configure pkg-config to find SPA library during compilation
export PKG_CONFIG_PATH=/path/to/spa/install/lib64/pkgconfig:$PKG_CONFIG_PATH

# Full build example with environment setup
PKG_CONFIG_PATH=/home/user/spa/install/lib64/pkgconfig cmake \
  -DCMAKE_BUILD_TYPE=Release \
  -DGuiModule=zest \
  -DZynFusionDir=/home/user/mruby-zest-build/package \
  /path/to/zynaddsubfx
make -j4

# Launch with custom plugin path
SPA_PATH=/custom/plugins ./new-lmms/install-gcc/bin/lmms
```

--------------------------------

### LMMS Launch Wrapper Script

Source: https://context7.com/johanneslorenz/lmms-zyn-fusion-test/llms.txt

This bash script is automatically generated by the build process to launch the customized LMMS application. It ensures that the correct plugin paths and environment variables, specifically SPA_PATH, are set, allowing LMMS to discover and load the ZynAddSubFX SPA plugin.

```bash
#!/bin/bash
# Generated automatically by build.sh
# Sets SPA_PATH to zynaddsubfx plugin location
# Usage examples:

# Launch LMMS GUI
./lmms

# Open a specific project file
./lmms myproject.mmp

# Launch with custom settings
./lmms --geometry 1920x1080

# The wrapper sets:
# SPA_PATH=/path/to/zynaddsubfx/build-gcc/src/Output
# This enables LMMS to discover the libzynaddsubfx_spa.so plugin
```

--------------------------------

### Automated Build Script for LMMS Zyn-Fusion

Source: https://context7.com/johanneslorenz/lmms-zyn-fusion-test/llms.txt

This bash script orchestrates the entire build process for the LMMS Zyn-Fusion integration project. It handles cloning the repository, initializing submodules, and compiling all components (SPA library, mruby-zest-build, ZynAddSubFX, and LMMS) using a specified compiler and parallel job count. It also supports shallow cloning and launching the built LMMS application.

```bash
#!/bin/bash
# Clone the repository with submodules
git clone --recursive https://github.com/johanneslorenz/lmms-zyn-fusion-test.git
cd lmms-zyn-fusion-test

# Build with GCC using 4 parallel jobs
./build.sh gcc 4

# Alternative: Build with Clang using 8 parallel jobs
./build.sh clang 8

# Alternative: Shallow clone for bandwidth savings (depth >100 recommended)
./build.sh gcc 4 150

# Launch LMMS after successful build
./lmms

# The build script will:
# 1. Initialize and update all git submodules recursively
# 2. Build SPA library with specified compiler
# 3. Compile mruby-zest-build and create fusion package
# 4. Build ZynAddSubFX with OSC plugin and Zest GUI
# 5. Compile LMMS with SPA integration
# 6. Generate executable wrapper script with proper environment
```

--------------------------------

### Compile mruby-zest-build

Source: https://context7.com/johanneslorenz/lmms-zyn-fusion-test/llms.txt

Compiles the mruby-zest-build project using a specified C compiler. It supports creating a distributable package that can be passed to ZynAddSubFX's CMake configuration. Includes cleaning and rebuilding steps.

```bash
cd mruby-zest-build

# Compile with specific C compiler
CC=gcc make -j4

# Create distributable package
CC=gcc make pack

# Verify package creation
ls package/
# Expected: Contains zest interface files and dependencies
# This package directory path is passed to ZynAddSubFX cmake:
# -DZynFusionDir=/path/to/mruby-zest-build/package

# Clean and rebuild
make clean
CC=clang make -j8
CC=clang make pack
```

--------------------------------

### Fix and Rerun LMMS Build Script

Source: https://context7.com/johanneslorenz/lmms-zyn-fusion-test/llms.txt

Instructions for fixing issues in the build system, rerunning the build script, and testing the changes. Assumes familiarity with Vim and shell commands.

```bash
# If build.sh fails, you can fix and rerun:
#   1. Edit build.sh to fix the issue
vim build.sh

#   2. Rerun the build (usually safe to restart)
./build.sh gcc 4

#   3. Test the fix thoroughly
./lmms
# Verify all functionality works

#   4. Submit pull request with fix
git checkout -b fix-build-issue
git add build.sh
git commit -m "Fix: Handle missing pkg-config path in spa build"
git push origin fix-build-issue
# Open PR on GitHub with description of fix

# Example fixes that are welcome:
# - Improved error handling in build.sh
# - Support for additional compilers/platforms
# - Better detection of pkg-config paths
# - Dependency verification before build
```

--------------------------------

### Updating Git Submodules

Source: https://github.com/johanneslorenz/lmms-zyn-fusion-test/blob/master/README.md

This command recursively initializes and updates git submodules. It is crucial for ensuring that the project has access to the correct versions of its dependencies, especially when working with multiple git worktrees or after cloning a repository with submodules.

```shell
git submodule update --init --recursive
```

--------------------------------

### Reproduce LMMS Crash with Zyn Tracks

Source: https://context7.com/johanneslorenz/lmms-zyn-fusion-test/llms.txt

Steps to reproduce a segfault crash in LMMS when loading a project with multiple Zyn tracks. No specific dependencies or outputs, primarily for issue identification.

```text
# Steps to reproduce:
#   1. ./lmms
#   2. Load project.mmp with 5+ Zyn tracks
#   3. Wait 15 seconds
# Expected: Project loads successfully
# Actual: LMMS crashes with segfault
```

--------------------------------

### LMMS Project File Format for ZynAddSubFX

Source: https://context7.com/johanneslorenz/lmms-zyn-fusion-test/llms.txt

This XML snippet demonstrates how an LMMS project file (.mmp) references a ZynAddSubFX plugin using the SPA naming convention. It specifies the plugin's SPA identifier and allows for plugin-specific settings. Note that files saved with this experimental version might not be compatible with upstream LMMS due to changes in the plugin attribute format.

```xml
<?xml version="1.0"?>
<!DOCTYPE lmms-project>
<lmms-project version="1.0" creator="LMMS" creatorversion="1.2">
  <head/>
  <song>
    <trackcontainer>
      <track type="0" name="Zyn Track">
        <instrumenttrack>
          <!-- ZynAddSubFX plugin reference with SPA identifier -->
          <instrument name="zynaddsubfx">
            <attribute name="plugin" value="github.com::zynaddsubfx::osc-plugin::ZASF"/>
            <!-- Plugin-specific settings and parameters -->
          </instrument>
        </instrumenttrack>
      </track>
    </trackcontainer>
  </song>
</lmms-project>

<!-- Note: Files saved with this experimental version may not be
     compatible with upstream LMMS. The plugin attribute format changed
     from version 0.1.0 to 0.2.0. Update old files by replacing the
     plugin attribute value with the format shown above. -->
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.