🎹 XG Synthesizer - Professional MIDI Workstation

A professional XG (eXtended General MIDI) synthesizer and real-time workstation implemented in Python, featuring advanced synthesis engines, Yamaha S.Art2 articulation, Vibexg live performance interface, comprehensive effects processing, and vectorized audio processing.

📋 Project Goals

The XG Synthesizer project aims to provide:

Complete XG Specification Implementation - Full Yamaha XG compatibility with GS extension support
Professional Audio Quality - Studio-grade synthesis and effects processing
Real-Time Performance - Low-latency (<5ms) suitable for live performance
Multiple Interface Options - Library, CLI, and workstation interfaces
Extensible Architecture - Plugin system for custom engines and effects
Cross-Platform Support - Windows, macOS, and Linux compatibility

✨ Features

🎵 Advanced Synthesis Engines

SF2/SoundFont 2.0 Engine

Full SF2 Specification - Complete SoundFont 2.0 format support
Velocity Layers - Multi-velocity zone mapping with crossfading
Loop Support - Loop start/end points with crossfade loops
Envelope Generators - AHDSR envelopes per sample
Filters - Low-pass, high-pass, band-pass filters per preset
LFO Modulation - Vibrato, tremolo, and filter modulation
Performance: 256+ voices with efficient sample caching

SFZ Engine

Modern SFZ Format - SFZ v1 and v2 opcode support
Real-Time Modulation - CC-controlled parameters
Round Robin - Multiple sample alternation
Legato - Smooth note transitions
Portamento - Glide between notes
Advanced Grouping - Sample groups with independent processing

FM-X Engine

8 Operators - Full 8-operator FM synthesis
88 Algorithms - Complete operator routing matrix
Envelope Generator - 8-stage ADSR1R1D1R2 per operator
Frequency Ratios - Fixed frequency and ratio modes
Velocity Sensitivity - Per-operator velocity curves
Output Levels - Independent operator level control

Additional Engines

Additive - Harmonic synthesis with custom spectra
Wavetable - Dynamic wavetable synthesis with morphing
Physical Modeling - Waveguide and modal synthesis
Granular - Advanced granular processing
Spectral - FFT-based spectral processing and morphing

🎻 Yamaha S.Art2 Articulation

275+ Articulations - Comprehensive articulation library
30 Articulation Presets - Ready-to-use articulation configurations
Real-time Switching - Seamless articulation transitions
Velocity Layers - Dynamic articulation response (0-127)
Expression Control - Nuanced performance expression
Crossfade Zones - Smooth articulation blending
Release Samples - Natural note decay articulations

🎛️ Professional Effects Processing

System Effects (3 Types)

Effect Type	Variations	Description
Reverb	13 types	Hall, Room, Plate, Delay, and more
Chorus	18 types	Chorus 1-4, Celeste, Flanger, Phaser
Delay	6 types	Delay L/R, Delay LCR, Echo, Cross-delay

Variation Effects (62+ Types)

Modulation: Phaser, Flanger, Symphonic, Tremolo, Rotary Speaker
Filters: EQ 2-band, EQ 3-band, Low-pass, High-pass, Band-pass
Distortion: Overdrive, Distortion, Amp Simulator, Bit Crusher
Spatial: Stereo Enhancer, Auto Pan, Reverb, Delay variations
Dynamics: Compressor, Limiter, Gate, Expander

Insertion Effects (17 Types)

Per-channel processing including:

EQ (5-band parametric)
Distortion/Overdrive
Chorus/Flanger
Reverb
Delay
Rotary Speaker
Wah/EFX

Master Processing

5-Band EQ - Parametric equalizer with shelving
Stereo Enhancer - Width control and spatial enhancement
Limiter - Peak limiting to prevent clipping
Compressor - Master bus compression

🎚️ XG/GS Implementation

XG Specification Compliance

Feature Category	Implementation	Status
Basic Messages	Note On/Off, Control Change, Program Change	✅ Complete
Channel Messages	Poly Pressure, Channel Pressure, Pitch Bend	✅ Complete
System Exclusive	XG SysEx, Parameter Changes	✅ Complete
NRPN Support	Non-Registered Parameter Numbers	✅ Complete
RPN Support	Registered Parameter Numbers	✅ Complete
Bank Select	MSB/LSB Bank Selection	✅ Complete
Drum Setup	Drum Kit Parameters, Note Shift	✅ Complete
Effects	System/variation/Insertion Effects	✅ Complete
Multi-Part	32-part Multi-timbral Operation	✅ Complete
Arpeggiator	Pattern-based Note Generation	✅ Complete
Microtonal	Scale Tuning, Master Tuning	✅ Complete

GS Compatibility

Feature	Implementation	Status
GS Reset	GM2/GS Mode Switching	✅ Complete
Bank Select	GS Bank Mapping	✅ Complete
Control Changes	GS-specific CCs	✅ Complete
NRPN	GS NRPN Parameters	✅ Complete
Drum Kit	GS Drum Kit Support	✅ Complete
JV-2080 Extensions	Advanced Parameter Control	✅ Complete

SF2 Implementation Details

Feature	Status	Notes
Preset Loading	✅ Complete	Full preset tree navigation
Sample Loading	✅ Complete	All sample formats (8/16/24-bit)
Velocity Splitting	✅ Complete	Multi-velocity zone mapping
Loop Points	✅ Complete	Loop start/end with crossfade
Envelope	✅ Complete	AHDSR per sample/instrument
Filters	✅ Complete	Low-pass with resonance
LFO	✅ Complete	Vibrato, tremolo, filter modulation
Key Tracking	✅ Complete	Pitch and filter key tracking
Velocity Curves	✅ Complete	Custom velocity response curves
Modulation Matrix	✅ Complete	Source → destination routing

🎛️ Vibexg Real-Time Workstation

Multiple MIDI Inputs: Keyboard, physical ports, virtual ports, network, file, stdin
Real-Time Audio: Low-latency output via sounddevice to any audio interface
TUI Control Surface: Rich text-based interface with live visualization
Preset Management: Save and recall complete setups with pickle serialization
MIDI Learn: Map hardware controllers to parameters with curve shaping
Demo Mode: Built-in test patterns (scale, chords, arpeggio)
Recording & Playback: Capture and replay MIDI performances
Style Engine: Auto-accompaniment with .sty/.sff file support
Metronome: Built-in click track with tempo sync
File Rendering: Render directly to WAV, FLAC, OGG, MP3, AAC, M4A

🎛️ VST3/AAX Plugin

Native Plugin Format: VST3 and AAX (Pro Tools) support
DAW Integration: Works with Ableton Live, Logic Pro, FL Studio, Pro Tools, Reaper
Full Parameter Automation: Automate all synthesizer parameters via DAW
Pattern Sequencer: Grid-based pattern editing and real-time playback
Python Integration: pybind11 bridge to XG synthesizer engine
Professional UI: JUCE-based interface with real-time controls and status display
Cross-Platform: Windows, macOS, Linux support
MIDI I/O: Full MIDI input/output support within DAW

🎚️ Advanced Control Systems

XGML v2.1 - Human-readable YAML configuration language
MPE Support - Microtonal expression with per-note control
GS Compatibility - Roland GS mode with JV-2080 enhancements
Arpeggiator - Yamaha Motif-style pattern generation (128+ patterns)
Modulation Matrix - 128 assignable modulation routings
Scale Tuning - Custom temperaments and microtonal scales

🚀 Performance & Architecture

Vectorized Processing - SIMD-optimized audio generation
Real-time Synthesis - Low-latency performance (<5ms)
Multi-format Support - WAV, AIFF, FLAC, OGG, MP3, SF2, SFZ samples
Cross-platform - Windows, macOS, Linux support
Extensible Design - Plugin architecture for custom engines
Memory Efficient - Sample caching and buffer pooling
Thread-Safe - Concurrent MIDI and audio processing

🚀 Quick Start

Installation

# Clone repository
git clone https://github.com/drbye78/syxg.git
cd syxg

# Install core package (PyAV for audio I/O)
pip install -e .

# Install with workstation features (Vibexg)
pip install -e ".[workstation]"

# Full installation with all features
pip install -e ".[full]"

# Development installation
pip install -e ".[dev,audio,visualization,workstation]"

Basic Usage

As a Library

from synth.engine.modern_xg_synthesizer import ModernXGSynthesizer

# Create synthesizer
synth = ModernXGSynthesizer(sample_rate=44100, max_channels=32)

# Load SoundFont
synth.load_soundfont("soundfonts/GM.sf2", priority=0)

# Load XGML configuration
synth.load_xgml_config("examples/simple_piano.xgdsl")

# Generate audio from MIDI
synth.render_midi_file("input.mid", "output.wav")

As a Real-Time Workstation (Vibexg)

# Run with keyboard input and TUI
python -m vibexg

# Run with physical MIDI port
python -m vibexg --midi-input "mido_port:USB MIDI Device"

# Run demo mode (test audio output)
python -m vibexg --demo scale

# List available MIDI ports
python -m vibexg --list-ports

# Render MIDI file to high-quality FLAC
python -m vibexg --midi-input "file:song.mid" --audio-output "file:output.flac"

# Network MIDI session
python -m vibexg --midi-input "network_midi:host=192.168.1.100,port=5004"

As a Command-Line Tool

# Render MIDI file to audio
render-midi input.mid output.wav

# Render with custom XGML configuration
render-midi --config my_config.xgdsl input.mid output.wav

# Convert MIDI to XGML
midi-to-xgml input.mid > config.xgdsl

As a VST3/AAX Plugin

# Build VST3 plugin (requires CMake, pybind11, JUCE)
cd vst3_plugin
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release

# Install to system VST3 directory
sudo make install  # Linux/macOS
# Or copy manually to:
# - Windows: %APPDATA%\VST3\
# - macOS: ~/Library/Audio/Plug-Ins/VST3/
# - Linux: ~/.vst3/

# Build AAX plugin for Pro Tools (requires AAX SDK)
cmake .. -DBUILD_AAX=ON -DAAX_SDK_ROOT="/path/to/aax/sdk"
cmake --build . --config Release --target XGWorkstationVST3_AAX

Usage in DAW:

Load "XG Workstation" plugin in instrument track
Click "Initialize" to start Python integration
Send MIDI notes to trigger synthesis
Use pattern sequencer for arrangement
Automate parameters via DAW automation

📖 Documentation

📚 User Guides

Getting Started - Quick start guide
User Manual - Complete usage guide
Vibexg Workstation - Real-time workstation manual
XGML Reference - XGML v2.1 specification
Configuration - All configuration options

🔧 Engine Documentation

FM-X Engine - 8-operator FM synthesis
SF2 Engine - SoundFont 2.0 playback
SFZ Engine - Modern sample playback
S.Art2 Articulation - Yamaha articulation system
Physical Modeling - Waveguide synthesis
Spectral Processing - FFT-based effects

🎛️ Plugin Documentation

VST3 Plugin - VST3/AAX plugin build and usage
Plugin Architecture - Plugin integration design
Parameter Automation - DAW automation guide

🎛️ Effects Documentation

System Effects - Reverb, Chorus, Delay
Variation Effects - 62+ effect types
Insertion Effects - Per-channel processing
Master Processing - EQ, limiting, enhancement

💻 Developer Resources

API Reference - Complete API documentation
Vibexg Package - Workstation API reference
Architecture - System design
Contributing - Development guidelines
Testing - Test suite documentation
Python 3.11 Migration - Migration guide and new features

🐍 Python 3.11 Features

The XG Synthesizer now requires Python 3.11+ and leverages modern Python features:

Pattern Matching - Clean MIDI message handling with match/case
Type Safety - Comprehensive type hints with typing.Self, TypeAlias, Annotated
Exception Groups - Better batch error handling with ExceptionGroup and except*
Exception Notes - Rich error context with add_note()
Performance - 10-60% faster audio processing (automatic Python 3.11 improvement)

See docs/PYTHON_311_FEATURES.md for details.

🎓 Examples & Tutorials

Basic Synthesis - Simple patches
Advanced Effects - Professional processing
Articulation Setup - S.Art2 configuration
Live Performance - Vibexg workstation setup
SF2 Programming - SoundFont creation

🎼 XGML Configuration Example

# XGML v2.1 Configuration
xg_dsl_version: "2.1"
description: "Professional piano with S.Art2 articulation and effects"

# Basic MIDI setup
basic_messages:
  channels:
    channel_1:
      program_change: "acoustic_grand_piano"
      bank_select: [0, 0]
      volume: 100
      pan: 64
      reverb_send: 40
      chorus_send: 20

# S.Art2 Articulation System
sart2_articulation:
  enabled: true
  articulations:
    - name: "legato"
      velocity_range: [0, 60]
      crossfade: true
      release_sample: true
    - name: "staccato"
      velocity_range: [61, 100]
      release: short
      loop_mode: one_shot
    - name: "forte"
      velocity_range: [101, 127]
      attack: fast
      filter_cutoff: 8000

# SF2 Engine Configuration
sf2_engine:
  soundfonts:
    - path: "soundfonts/GM.sf2"
      priority: 0
      blacklist: []  # Disable specific programs
      remap: {}      # Program remapping

# Professional effects
effects_configuration:
  system_effects:
    reverb:
      type: hall
      time: 2.5
      level: 0.8
      high_damp: 0.7
    chorus:
      type: chorus1
      level: 0.6
      rate: 1.2
      depth: 0.5
  
  variation_effects:
    type: eq_3band
    parameters:
      low_gain: 2.0
      low_freq: 400
      mid_gain: 0.0
      mid_freq: 2500
      high_gain: 3.0
      high_freq: 8000
  
  insertion_effects:
    channel_1:
      type: chorus
      parameters:
        rate: 1.5
        depth: 0.6
  
  master_processing:
    equalizer:
      type: "jazz"
      bands:
        low: {gain: 2.0, frequency: 80, q: 1.0}
        mid: {gain: 0.0, frequency: 2500, q: 1.5}
        high: {gain: 3.0, frequency: 8000, q: 0.7}
    limiter:
      threshold: -1.0
      release: 0.3

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    XG Synthesizer Engine                    │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────┐    │
│  │              Synthesis Engines                    │    │
│  │  ┌─────────┬─────────┬─────────┬─────────┐        │    │
│  │  │  SF2    │  SFZ    │  FM-X   │Physical │        │    │
│  │  │ Engine  │ Engine  │ Engine  │Modeling│        │    │
│  │  └─────────┴─────────┴─────────┴─────────┘        │    │
│  └─────────────────────────────────────────────────────┘    │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────┐    │
│  │         Yamaha S.Art2 Articulation                │    │
│  │  ┌─────────────────────────────────────────┐      │    │
│  │  │  275+ Articulations | 30 Presets       │      │    │
│  │  │  Real-time Switching | Velocity Layers │      │    │
│  │  └─────────────────────────────────────────┘      │    │
│  └─────────────────────────────────────────────────────┘    │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────┐    │
│  │         Vibexg Real-Time Workstation              │    │
│  │  ┌─────────┬─────────┬─────────┬─────────┐        │    │
│  │  │  MIDI   │  TUI    │ Preset  │  MIDI   │        │    │
│  │  │ Inputs  │ Control │ Manager │  Learn  │        │    │
│  │  └─────────┴─────────┴─────────┴─────────┘        │    │
│  └─────────────────────────────────────────────────────┘    │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────┐    │
│  │              Effects Processing                   │    │
│  │  ┌─────────┬─────────┬─────────┬─────────┐        │    │
│  │  │ System  │Variation│Insertion│ Master  │        │    │
│  │  │Effects  │Effects  │Effects  │Processing│      │    │
│  │  └─────────┴─────────┴─────────┴─────────┘        │    │
│  └─────────────────────────────────────────────────────┘    │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────┐    │
│  │              Audio Output                         │    │
│  │  ┌─────────┬─────────┬─────────┬─────────┐        │    │
│  │  │Vectorized│Optimized│ Multi-  │ Format  │      │    │
│  │  │Processing│Coefficients│format  │Support │      │    │
│  │  └─────────┴─────────┴─────────┴─────────┘        │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

🎯 Key Components

Synthesis Engines

Engine	Type	Polyphony	Features
SF2Engine	Sample-based	256+	Velocity layers, loops, envelopes, filters
SFZEngine	Sample-based	256+	SFZ v1/v2, round robin, legato
FMEngine	FM synthesis	128+	8 operators, 88 algorithms
PhysicalEngine	Physical modeling	64+	Waveguide, modal synthesis
SpectralEngine	Spectral	32+	FFT processing, morphing

Yamaha S.Art2 Articulation

ArticulationController: Real-time articulation switching
ArticulationPreset: 30 pre-configured articulation setups
ArticulationMapping: Velocity-based articulation zones
Modifiers: Dynamic articulation response curves

Vibexg Workstation

XGWorkstation: Main orchestrator class
MIDI Inputs: Keyboard, MidoPort, Virtual, Network, File, Stdin
Audio Outputs: SoundDevice, File rendering
Managers: PresetManager, MIDILearnManager, StyleEngineIntegration
TUI: Rich-based text user interface
Demo: Built-in test patterns (scale, chords, arpeggio)

VST3/AAX Plugin

PluginProcessor: Main VST3/AAX audio processing and MIDI handling
PythonIntegration: pybind11 bridge between C++ plugin and Python XG synthesizer
XGParameterManager: VST3 parameter management and DAW automation
PluginEditor: JUCE-based user interface with real-time controls
Pattern Sequencer: Grid-based pattern editing and playback integration
DAW Support: Ableton Live, Logic Pro, FL Studio, Pro Tools, Reaper

Control Systems

XGML Parser/Translator: Human-readable YAML to MIDI conversion
MPE Manager: Per-note expression control
Arpeggiator Engine: Pattern-based note generation (128+ patterns)
Modulation Matrix: 128 assignable modulation routings

Effects Processing

Section	Types	Description
System	37	Reverb (13), Chorus (18), Delay (6)
Variation	62+	Modulation, filters, distortion, spatial
Insertion	17	Per-channel EQ, distortion, modulation
Master	4	5-band EQ, stereo enhancer, limiter

📊 Performance

Metric	Value	Notes
Latency	<5ms	End-to-end audio processing
Polyphony	256+	Depends on engine and sample memory
CPU Usage	Optimized	Vectorized SIMD processing
Memory	Efficient	Sample caching and buffer pooling
Real-time	✅	Suitable for live performance

Benchmarks (M1 Mac, 44.1kHz, 512 buffer)

Task	CPU Usage	Latency
SF2 Playback (64 voices)	15%	3.2ms
FM-X Synthesis (32 voices)	12%	2.8ms
Full Mix (128 voices + FX)	45%	4.5ms
Vibexg Live (TUI + Audio)	25%	3.5ms

🔧 System Requirements

Minimum Requirements

Python: 3.8+
RAM: 4GB
Disk: 1GB for samples and temporary files
OS: Windows 10+, macOS 10.15+, Linux (Ubuntu 18.04+)
CPU: Dual-core processor

Recommended Requirements

Python: 3.9+
RAM: 8GB+
Disk: SSD with 10GB+ free space
OS: Windows 11+, macOS 12+, Linux (Ubuntu 22.04+)
CPU: Multi-core processor with AVX2 support
Audio Interface: ASIO/CoreAudio/ALSA compatible (for low latency)

Optional Hardware

MIDI Controller: USB MIDI keyboard or controller
Audio Interface: Low-latency USB audio interface
SoundFonts: SF2/SFZ sample libraries

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone repository
git clone https://github.com/drbye78/syxg.git
cd syxg

# Install development dependencies
pip install -e ".[dev,audio,performance,workstation]"

# Run tests
pytest tests/ -v

# Run linting
flake8 synth/ vibexg/
black synth/ vibexg/
mypy synth/ vibexg/

Code Style

Black for code formatting
Flake8 for linting
MyPy for type checking
Pytest for testing
Google/NumPy style docstrings

Areas for Contribution

Additional synthesis engines
New effect types
SoundFont/SFZ improvements
Documentation
Test coverage
Bug fixes
Performance optimizations

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Yamaha Corporation - For the XG specification and S.Art2 articulation system inspiration
SoundFont Technical Committee - For the SF2 specification
SFZ Format Community - For modern sample standards
FFmpeg/PyAV - For audio file I/O
Open Source Community - For the libraries that make this possible

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Full Documentation
Vibexg Guide: docs/WORKSTATION.md

🎹 Transform your MIDI files into professional audio with the power of modern synthesis engines, Yamaha S.Art2 articulation, comprehensive effects processing, Vibexg real-time workstation, and VST3/AAX plugin integration.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
benchmarks		benchmarks
docs		docs
examples		examples
synth		synth
tests		tests
vibexg		vibexg
vst3_plugin		vst3_plugin
.gitignore		.gitignore
.gitmodules		.gitmodules
.pre-commit-config.yaml		.pre-commit-config.yaml
CONTRIBUTING.md		CONTRIBUTING.md
INSTALL.md		INSTALL.md
LICENSE		LICENSE
README.md		README.md
config.yaml		config.yaml
config.yaml.sample		config.yaml.sample
midi_to_xgml.py		midi_to_xgml.py
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
render_midi.py		render_midi.py
requirements.txt		requirements.txt
requirements_dev.txt		requirements_dev.txt
requirements_optional.txt		requirements_optional.txt
sf2_stats.py		sf2_stats.py
vibexg.py		vibexg.py
vibexg_config.yaml		vibexg_config.yaml

Folders and files

Latest commit

History

Repository files navigation