Designing Audio Effect Plugins in C++ For AAX, AU, and VST3 With DSP Theory Second Edition Will C. Pirkle 13 Routledge g^^ Taylor & Francis Croup NEW YORK AND LONDON Contents List of Figures xxiii List of Tables xliii Preface xlvi Chapter 1: Introduction 1 1.1 Using This Book 1 1.2 Fundamentals of Audio Signal Processing 2 1.2.1 Acquisition of Audio Samples 3 1.3 Reconstruction of the Analog Signal 4 1.4 Numerical Representation of Audio Data 5 1.5 Analytical DSP Test Signals 6 1.5.1 DC and Step (0 Hz) 7 1.5.2 Nyquist 8 1.5.3 >/2Nyquist 8 1.5.4 ^Nyquist 8 1.5.5 Impulse 8 1.6 Signal Processing Algorithms 8 1.6.1 Bookkeeping 10 1.6.2 The One-Sample Delay 10 1.6.3 Multiplication With a Scalar Value 11 1.6.4 Addition and Subtraction 12 1.6.5 Some Algorithm Examples and Difference Equations 12 1.6.5.1 Gain, Attenuation and Phase Inversion 13 1.7 1st Order Feed-Forward and Feedback Algorithms 14 1.8 Bibliography 14 Chapter 2: Anatomy of an Audio Plugin 15 2.1 Plugin Packaging: Dynamic-Link Libraries (DLLs) 15 2.2 The Plugin Description: Simple Strings 17 2.2.1 The Plugin Description: Features and Options 18 2.3 Initialization: Defining the Plugin Parameter Interface 18 2.3.1 Initialization: Defining Channel I/O Support 20 2.3.2 Initialization: Sample Rate Dependency 21 2.4 Processing: Preparing for Audio Streaming 21 2.4.1 Processing: Audio Signal Processing (DSP) 21 2.5 Mixing Parameter Changes With Audio Processing 23 vii vlii Contents 2.5.1 Plugin Variables and Plugin Parameters 23 2.5.2 Parameter Smoothing 26 2.5.3 Pre and Post-Processing Updates 27 2.5.4 VST3 Sample Accurate Updates 27 2.5.5 Multi-Threaded Software 28 2.6 Monolithic Plugin Objects 30 2.7 Bibliography 31 Chapter 3: VST3 Programming Guide 32 3.1 Setting Up the VST3 SDK 32 3.1.1 VST3 Sample Projects 32 3.1.2 VST3 Documentation 33 3.2 VST3 Architecture and Anatomy 33 3.2.1 Single vs. Dual Component Architectures 34 3.2.2 VST3 Base Classes 35 3.2.3 MacOS Bundle ID 35 3.2.4 VST3 Programming Notes 35 3.2.5 VST3 and the GUID 36 3.2.6 VST3 Plugin Class Factory 37 3.3 Description: Plugin Description Strings 37 3.4 Description: Plugin Options/Features 38 3.4.1 Side Chain Input 38 3.4.2 Latency 38 3.4.3 Tail Time 38 3.4.4 Custom GUI 39 3.4.5 Factory Presets and State Save/Load 39 3.4.6 VST3 Support for 64-bit Audio 41 3.5 Initialization: Defining Plugin Parameters 41 3.5.1 Thread-Safe Parameter Access 43 3.5.2 Initialization: Defining Plugin Channel I/O Support 44 3.5.3 Initialization: Channel Counts and Sample Rate Information 45 3.6 The Buffer Process Cycle 45 3.6.1 Processing: Updating Plugin Parameters From GUI Controls 47 3.6.2 Processing: Resetting the Algorithm and Preparing for Streaming 49 3.6.3 Processing: Accessing the Audio Buffers 49 3.6.4 Processing: Writing Output Parameters 50 3.6.5 Processing: VST3 Soft Bypass 51 3.7 Destruction/Termination 51 3.8 Retrieving VST3 Host Information 52 3.9 Validating Your Plugin 52 3.10 Using ASPiK to Create VST3 Plugins 52 3.11 Bibliography 53 Chapter 4: AU Programming Guide 54 4.1 Setting Up the AU SDK 54 4.1.1 AU Sample Projects 54 4.1.2 AU Documentation 54 Contents ix 4.2 AU Architecture and Anatomy 55 4.2.1 AU Base Classes 56 4.2.2 MacOS Bundle ID 56 4.2.3 AU Programming Notes 56 4.3 Description: Plugin Description Strings 58 4.4 Description: Plugin Options/Features 59 4.4.1 Side Chain Input 59 4.4.2 Latency 60 4.4.3 Tail Time 60 4.4.4 Custom GUI 60 4.4.5 Factory Presets and State Save/Load 60 4.5 Initialization: Defining Plugin Parameters 61 4.5.1 Thread-Safe Parameter Access 64 4.5.2 Initialization: Defining Plugin Channel I/O Support 64 4.5.3 Initialization: Channel Counts and Sample Rate Information 65 4.6 The Buffer Process Cycle 66 4.6.1 Processing: Updating Plugin Parameters From GUI Controls 67 4.6.2 Processing: Resetting the Algorithm and Preparing for Streaming 68 4.6.3 Processing: Accessing the Audio Buffers 68 4.6.4 Processing: Writing Output Parameters 70 4.7 The AU/GUI Connection 70 4.7.1 Cocoa's Flat Namespace 72 4.7.2 The AU Event Listener System 72 4.7.2.1 The Event Lister Dispatch Callback Function 73 4.7.2.2 Creating the AU Event Listener 74 4.7.2.3 Destroying the Event Listener 75 4.8 Destruction/Termination 76 4.9 Retrieving AU Host Information 76 4.10 Validating Your Plugin 77 4.11 Using ASPiK to Create AU Plugins 77 4.12 Bibliography 77 Chapter 5: AAX Native Programming Guide 78 5.1 Setting Up the AAX SDK 79 5.1.1 AAX Sample Projects 79 5.1.2 AAX Documentation 79 5.2 AAX Architecture and Anatomy 80 5.2.1 AAX Model-Algorithm Synchronization 81 5.2.2 AAX Base Classes 82 5.2.3 MacOS Bundle ID 82 5.2.4 AAX Programming Notes 83 5.2.5 AAX Class Factory 83 5.2.6 AAX Effect Categories 83 5.2.7 AAX Algorithms: Channel-Processing Functions 84 5.2.8 AAX Algorithm Data 84 5.2.9 Algorithm Data Contents 85 Contents 5.3 Description: Plugin Description Strings 86 5.3.1 Description: Defining AAX Algorithms 88 5.4 Description: Plugin Options/Features 90 5.4.1 Side Chain Input 90 5.4.2 Latency 91 5.4.3 Tail Time 91 5.4.4 Custom GUI 91 5.4.5 Factory Presets and State Save/Load 92 5.4.6 AAX Notification System 92 5.4.7 AAX Custom Data 93 5.4.8 AAX EQ and Dynamics Curves 93 5.4.9 AAX Gain Reduction Meter 93 5.5 Initialization: Defining Plugin Parameters 94 5.5.1 Thread-Safe Parameter Access 97 5.5.2 Initialization: Defining Plugin Channel I/O Support 97 5.5.3 Initialization: Channel Counts and Sample Rate Information 97 5.6 The Buffer Process Cycle 98 5.6.1 Processing: Updating Plugin Parameters From GUI Controls 101 5.6.2 Processing: Resetting the Algorithm and Preparing for Streaming 101 5.6.3 Processing: Accessing the Audio Buffers 102 5.6.4 Processing: Writing Output Parameters 103 5.6.5 Processing: AAX Soft Bypass 104 5.7 Destruction/Termination 104 5.8 Retrieving AAX Host Information 104 5.9 Validating Your Plugin 105 5.10 Using ASPiK to Create AAX Plugins 106 5.11 Bibliography 106 Chapter 6: ASPiK Programming Guide 107 6.1 Plugin Kernel Portability and Native Plugin Shells 108 6.2 Organizing the SDKs: AAX, AU, and VST 111 6.2.1 Your C++Compiler Ill 6.2.2 Setting Up the AAX SDK Ill 6.2.3 Setting Up the AU SDK 112 6.2.4 Setting Up the VST SDK 112 6.2.5 Creating the Universal SDK Folder Hierarchy 112 6.2.6 Adding the VSTGU14 Library 112 6.2.7 CMake 113 6.3 Creating a Plugin Project With ASPiKreator: URFilters 114 6.3.1 ASPiK Project Folders 115 6.3.2 Running CMake 117 6.4 Adding Effect Objects to the PluginCore 117 6.4.1 The PluginCore Constructor 118 6.4.2 URFilters: GUI Parameter Lists 119 6.4.3 Parameter Smoothing 120 6.4.4 Handling the String-List Parameters 121 6.4.5 URFilters: Declaring Plugin Variables 123 Contents xi 6.4.6 Parameter Object Enumerations for Attributes 123 6.4.6.1 Continuous Floating Point Parameters and Discrete Integer Parameters 125 6.4.6.2 String-List Parameters 126 6.4.7 IIRFilters: Object Declarations and Reset 127 6.4.8 IIRFilters: GUI Parameter Updates 128 6.4.9 IIRFilters: Processing Audio Data 128 6.4.10 Buffer Pre-Processing 130 6.4.11 Buffer Post-Processing 130 6.4.12 Buffer vs. Frame Processing 131 6.4.13 processAudioFrame: Information About the Frame 132 6.4.14 processAudioFrame: Input and Output Samples 133 6.5 Defining Factory Presets 135 6.6 Basic Plugin GUI Design With ASPiK's PluginGUI 136 6.7 GUI Design With VSTGUI4 137 6.7.1 Modifier Keys 138 6.7.2 Zooming (Scaling the GUI) 138 6.7.3 Reserved Control Tags 138 6.7.4 VSTGUI4 Objects 139 6.7.5 Creating a GUI With VSTGUI 139 6.7.6 Important GUI Designer Terms 140 6.8 VSTGUI C++ Objects 141 6.8.1 Basic GUI Design 142 6.8.2 The GUI Designer Workspace 144 6.8.3 Changing Your GUI Canvas Size 146 6.8.4 Setting Up the Control Tags 146 6.8.5 Importing the Graphics Files 146 6.8.6 Assembling the GUI 147 6.8.7 Setting the Background 147 6.8.8 Adding the GUI Elements 147 6.8.9 Saving and Re-Building 148 6.8.10 Scaling the GUI 148 6.8.11 More ASPiK Features 149 6.9 Bibliography 149 Chapter 7: Using RackAFX to Create ASPiK Projects 150 7.1 Installing RackAFX 151 7.2 Getting Started With RackAFX 151 7.3 Setting Up Your Project Preferences and Audio Hardware 153 7.4 Installing VSTGUI4 153 7.5 Creating a Project and Adding GUI Controls 153 7.5.1 Numerical Continuous Controls 155 7.5.2 String-List Controls 156 7.5.3 Meters 158 7.6 Anatomy of Your RackAFX Project 159 7.7 Testing Audio Algorithms With RackAFX 161 7.8 RackAFX Impulse Convolver and FIR Design Tools 163 xii Contents 7.9 Designing Your Custom GUI 163 7.10 Exporting Your ASPiK.