DISTRHO
/
JUCE
mirror of https://github.com/DISTRHO/JUCE
1
0
Fork 0
Code Releases 1 Activity
The JUCE cross-platform C++ framework, with DISTRHO/KXStudio specific changes
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
5576 Commits
9 Branches
3.5GB
Tree: ddcd78eae8
Branches Tags
${ item.name }
Create branch ${ searchTerm }
from 'ddcd78eae8'
${ noResults }
JUCE/examples/audio plugin demo/How to use this framework.txt

340 lines
21KB
Raw Blame History 

  1. 

  2.                             The Juce Polymorphic Plugin Project!

  3.                             ====================================

  4. 

  5. (c) 2015 by ROLI, visit www.juce.com for more info.

  6. 

  7. -----------------------------------------------------------------------------------------------------

  8. 

  9. The purpose of this framework is to make is simple to write an audio plugin in a generic

  10. way, which can then be compiled as a VST, AudioUnit, RTAS, or any combination of these. 

  11. 

  12. It's "polymorphic" because the output is a single binary module that acts as all of the 

  13. different plugin formats at the same time. This means that you only need to maintain one 

  14. project, and only need to perform one build to create a multi-format plugin.

  15. 

  16. Also included are some helper classes that make it easy to create a stand-alone app to

  17. run your plugin without a host. This might be useful in its own right, but can also be very 

  18. handy when developing your plugin, because you can build, test and debug it without needing

  19. to keep restarting a 3rd-party host.

  20. 

  21.                                     How does it work?

  22.                                     =================

  23. 

  24. To create your plugin, you just create a subclass of the AudioPluginInstance class to 

  25. perform the processing. And your plugin UI is written like any normal Juce UI component.

  26. 

  27. All the platform-specific code is hidden away in wrapper classes that you just add to 

  28. your project - you should (hopefully) never need to even see the inner workings of these.

  29. 

  30. 

  31.                                     Licensing issues

  32.                                     ================

  33. 

  34. Juce is released under the GPL (Gnu Public License) - this means that you're free to use

  35. and redistribute it as long as your products are also released under the GPL. Basically

  36. this means that if you use it, you also have to give away your source code. 

  37. If you want to release a closed-source application, you can buy a commercial license 

  38. that lets you avoid this restriction - see http://www.juce.com for more info, 

  39. or see the comments at the top of all the Juce source files.

  40. 

  41. If you're building the VST projects or releasing a VST, you'll need have a look at Steinberg's 

  42. developer site to see what licensing rules apply these days. Their website's at

  43. http://www.steinberg.net

  44. 

  45. If you're building an RTAS then you'll need to sign Digidesign's developer license to get

  46. their SDK. Visit http://www.digidesign.com for more info.

  47. 

  48. 

  49. 

  50.                                     Getting Started

  51.                                     ===============

  52. 

  53. The best advice for creating a plugin is to USE THE INTROJUCER! This will auto-generate a

  54. cross-platform project for you with all the correct settings, and some framework classes to

  55. get you started.

  56. 

  57. If you choose to go it alone and not use the introjucer, then you'll have a lot of painful

  58. project set-up to do, and will need to scour this document and the juce forum for the details.

  59. 

  60. There's a demo plugin in the juce/extras folder - this contains an example plugin which can 

  61. be built in all the different formats.

  62. 

  63. Have a look at the demo classes to see how it works, and then to create a real plugin, 

  64. you'll need to replace the demo files with your own code.

  65. 

  66. I've tried to add helpful comments where you might run across common compile errors, to

  67. help describe what you might be doing wrong, as getting a build set-up for some of these 

  68. formats can be a bit of a pain. Please let me know if you find there's anything missing

  69. from these instructions or anything I could change to help smooth the build process along

  70. a bit.

  71. 

  72. 

  73. -----------------------------------------------------------------------------------------------------

  74. 

  75.                             Prerequisites for building a VST

  76.                             ================================

  77. 

  78. - Visit http://www.steinberg.net and jump through whatever hoops are necessary to download 

  79.   and install the VST SDK.

  80. 

  81. -----------------------------------------------------------------------------------------------------

  82. 

  83.                             Prerequisites for building an RTAS

  84.                             ==================================

  85. 

  86. - Contact Digidesign, ask to become a Digidesign Development Partner, sign the relevent

  87.   agreements and NDAs.

  88. - From the Digidesign website, download their latest Plug-In SDK

  89. - Install the SDK and build some of the demo plugins to make sure it all works.

  90. - In Visual Studio: Using the Digidesign demo projects in the SDK, make sure you've compiled

  91.   debug and release versions of the following static libraries:

  92.     DAE.lib, DigiExt.lib, DSI.lib, PlugInLib.lib.

  93. - In XCode: After installing the Digidesign SDK, make sure you've run the config_SDK_for_Mac 

  94.   command in the SDK's root directory. This sets up some of the tools that it needs.

  95. 

  96. 

  97. -----------------------------------------------------------------------------------------------------

  98. 

  99.                         Choosing the formats to build

  100.                         =============================

  101. 

  102. Each plugin project needs to contain an AppConfig.h file, which holds all the plugin-specific build details. 

  103. (The introjucer will auto-generate this file for you when you create a project). In here, there are three macros

  104. that you can set to enable each of the available formats:

  105. 

  106. #define JucePlugin_Build_VST     1

  107. #define JucePlugin_Build_RTAS    1

  108. #define JucePlugin_Build_AU      1

  109. 

  110. The introjucer contains options in its config panel that let you set these values automatically without

  111. needing to manually change any files.

  112. 

  113. 

  114. -----------------------------------------------------------------------------------------------------

  115. 

  116.                     Manually Creating a PC VST/RTAS plugin in Visual Studio

  117.                     =======================================================

  118. 

  119. 

  120. NOTE! That the following tips are provided only for the case where you're not using the introjucer..

  121. If you're sensible, you'll let the introjucer do all the heavy lifting, and won't need to read this.

  122. 

  123. 

  124. - First try loading the VST demo project in JuceAudioPlugin/demo/build. Hopefully this

  125.   should build correctly.

  126. - Create a new, empty, win32 project using Visual Studio. Choose "DLL" as the type of 

  127.   product to build

  128. - If building an RTAS, add to your project all the juce_RTAS_*.cpp files from the wrapper/RTAS folder.

  129. - If building a VST, add to your project all the juce_VST_*.cpp files from the wrapper/VST folder.

  130. 

  131. - Create yourself a JucePluginCharacteristics.h file, starting with a copy of the one in the

  132.   demo project. Go through each item inside it carefully, and set them to the appropriate value

  133.   for your plugin.

  134. 

  135. - Under "Additional Include Directories", add the folder in which you're going to put 

  136.   your JucePluginCharacteristics.h file.

  137. 

  138. - If you're doing an RTAS, change these project settings (these can all be ignored if you're only doing a VST):

  139.     - Make sure all of these are on your include path:

  140.         c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\EffectClasses

  141.         c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\ProcessClasses

  142.         c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\ProcessClasses\Interfaces

  143.         c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\Utilities

  144.         c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\RTASP_Adapt

  145.         c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\CoreClasses

  146.         c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\Controls

  147.         c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\Meters

  148.         c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\ViewClasses

  149.         c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\DSPClasses

  150.         c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\PluginLibrary\Interfaces

  151.         c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\common

  152.         c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\common\Platform

  153.         c:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugins\SignalProcessing\Public

  154.         C:\yourdirectory\PT_80_SDK\AlturaPorts\TDMPlugIns\DSPManager\Interfaces

  155.         c:\yourdirectory\PT_80_SDK\AlturaPorts\SADriver\Interfaces

  156.         c:\yourdirectory\PT_80_SDK\AlturaPorts\DigiPublic\Interfaces

  157.         c:\yourdirectory\PT_80_SDK\AlturaPorts\Fic\Interfaces\DAEClient

  158.         c:\yourdirectory\PT_80_SDK\AlturaPorts\NewFileLibs\Cmn

  159.         c:\yourdirectory\PT_80_SDK\AlturaPorts\NewFileLibs\DOA

  160.         c:\yourdirectory\PT_80_SDK\AlturaPorts\AlturaSource\PPC_H

  161.         c:\yourdirectory\PT_80_SDK\AlturaPorts\AlturaSource\AppSupport

  162.         c:\yourdirectory\PT_80_SDK\AvidCode\AVX2sdk\AVX\avx2\avx2sdk\inc

  163.         C:\yourdirectory\PT_80_SDK\xplat\AVX\avx2\avx2sdk\inc

  164.     - Set "C++/Code Generation/Runtime Library" to be "Multi-threaded DLL" or "Multi-threaded Debug DLL"

  165.     - Set the "Linker/Input/Module Definition file" to point to "wrapper/RTAS/juce_RTAS_WinExports.def"

  166.     - Under "Linker/Input/Delay loaded DLLs", add the following: 

  167.         "DAE.dll; DigiExt.dll; DSI.dll; PluginLib.dll; DSPManager.dll"

  168.     - You may (or may not) need to add "libcmtd.lib; libcmt.lib" to the "Linker/Input/Ignore Specific Library" setting.

  169.     - For ONLY the following files:

  170.         juce_RTAS_Wrapper.cpp, juce_RTAS_DigiCode1.cpp, juce_RTAS_DigiCode2.cpp, juce_RTAS_DigiCode3.cpp,

  171.       change their "C++/Advanced/Calling Convention" property to "__stdcall". All other files should 

  172.       be left with the default calling convention of "__cdecl"

  173.     - Set the "Linker/General/Output File" property to "$(OutDir)\$(ProjectName).dpm" (If you're building 

  174.       a polymorphic VST/RTAS, then you can simply copy or rename the finished .dpm file to a .dll, and 

  175.       it'll function as a VST)

  176.     - Under "Custom build step", add the following command:

  177.         copy /Y "\yourdirectory\juce\extras\audio plugins\wrapper\RTAS\juce_RTAS_WinResources.rsr" "$(TargetPath)".rsr

  178.       The corresponding "Outputs" setting for this must be set to "$(TargetPath)".rsr

  179.       (This will copy and rename the juce_RTAS_WinResources.rsr file to sit next to the finished .dpm file. It's

  180.       a dummy resource file, but PT will refuse to load the plugin unless it has a corresponding .rsr file)

  181.     - Because the RTAS code duplicates some win32 constants, you might need to force it to link correctly

  182.       by adding "/FORCE:multiple" to the linker's additional command line options.

  183.     - You might want to change the output directory to "\Program Files\Common Files\Digidesign\DAE\Plug-Ins\"

  184.       if you want the built plugin to go directly into the PT plugins folder

  185.     - When setting properties, remember to change them for both your debug and release builds!

  186. 

  187. - Create your actual plugin classes and add them to the project. Obviously this is the hard bit!

  188. 

  189. - Add the amalgamated juce source file to the project - have a look at the demo app for neat ways of doing this.

  190. 

  191. - NOTE: on Windows, because RTAS uses the altura mac-style code, there are annoying clashes caused if

  192.   you also include the Apple QuickTime headers, so you might need to turn off quicktime by setting the

  193.   juce config macro: #define JUCE_QUICKTIME 0

  194. 

  195. - NOTE: If you're using MSVC2005 to build your plugin, the users will need to

  196.   have the Microsoft VC8 Runtime installed on their machines, otherwise the DLL will 

  197.   silently fail to load. You should probably add the runtime to your plugin's installer, 

  198.   and you can get a copy of it here:

  199.   http://www.microsoft.com/downloads/details.aspx?FamilyID=32bc1bee-a3f9-4c13-9c99-220b62a191ee&DisplayLang=en

  200. 

  201. 

  202. 

  203. -----------------------------------------------------------------------------------------------------

  204. 

  205.                             Creating a Mac AU/VST/RTAS plugin in XCode

  206.                             ==========================================

  207. 

  208. NOTE! That the following tips are provided only for the case where you're not using the introjucer..

  209. If you're sensible, you'll let the introjucer do all the heavy lifting, and won't need to read this.

  210. 

  211. - Some of the RTAS SDK files in the demo project might be highlighted red to indicate that they're

  212.   missing - if you're not bulding an RTAS, then you can just delete them from the project. If you are

  213.   building an RTAS and have the SDK, you might need to update their paths to match your SDK location.

  214. - For an AU, there are a bunch of Apple cpp files that need to be included directly in your project - these

  215.   used to be found in /Developer/Examples/CoreAudio/ but in the 10.6 SDK, Apple have moved them to a slightly

  216.   more sensible location at /Developer/Extras/CoreAudio. The Juce demo is hardwired to refer to their new

  217.   10.6 location, so if you haven't yet installed the 10.6 SDK, the easiest way to make it all happy is just 

  218.   to duplicate your /Developer/Examples/CoreAudio folder as /Developer/Extras/CoreAudio. That way old and new

  219.   juce plugin projects will all compile without changing any project paths.

  220. - For an AU, make sure that the JucePlugin_Build_AU is enabled in your JucePluginCharacteristics.h

  221. - In XCode, create a new project based on the "Audio Unit Effect" template

  222. - XCode will create a bunch of template source files for you - you can remove all of these from the project

  223.   and delete them

  224. - In the target settings, clear the "Exported Symbols File" setting. The exports are specified by directives

  225.   within the wrapper code, so don't need to be listed explicitly.

  226. - All all the Apple frameworks that Juce normally requires to the "External Frameworks" list

  227. - Add all the juce_AU_* files from the /wrapper/AU directory to your project

  228. - The template project creates an AUPublic group that contains lots of AudioUnit source files. But

  229.   it leaves out files that it thinks you might not need, e.g. if you chose an "Audio Unit Effect" project,

  230.   then it won't add the classes for handling MIDI. So you'll probably need to go into this folder

  231.   and check that it contains AUMIDIBase.cpp, AUMidiEffectBase.cpp, MusicDeviceBase.cpp, etc

  232. - As for the PC, you'll need to make sure your project contains a correctly set-up JucePluginCharacteristics.h

  233.   file - start with a copy of the one in the demo plugin project, and go through it making sure that

  234.   all the values make sense for your plugin.

  235. - The JucePluginCharacteristics.h file is included not only by the code, but also by the resources files - so it

  236.   needs to be locatable on both your normal header search path, and also on your resource include path, which is

  237.   the project setting called 'Rez Search Paths'

  238. - Because of the flat naming structure used by Objective-C, if a host loads several different plugins which

  239.   all contain slightly different versions of the juce library, you can get nasty situations where all their obj-C

  240.   classes are cross-linked to the similarly-named class in other modules, and everything turns into a big mess...

  241.   To avoid this, you're advised to set a unique JUCE_ObjCExtraSuffix value (you'll find this in juce_mac_NativeCode.mm,

  242.   or if you're using the amalgamated version, you can just set it before including juce_amalgamated.cpp). Choose a 

  243.   suffix that's unique to both the name and version of your plugin.

  244. - Create your actual plugin classes and add them to the project. Obviously this is the hard bit!

  245. 

  246. You should now be able to build a functional AU! If you want VST support as well, then read on...

  247. 

  248. - Make sure that the JucePlugin_Build_VST is enabled in your JucePluginCharacteristics.h

  249. - For VST support, add all the juce_VST_* files from /wrapper/VST

  250. - In your target info settings, add the vstsdk2_4 folder to your "Header Search Paths" list

  251. - Make sure that in your Info.plist, the "Bundle Name" value is correctly set to the name of your plugin.

  252. 

  253. Now, if you compile, the resulting bundle should work as both a VST and AU - you can simply copy or rename it,

  254. changing the suffix to ".vst", and put it in your VST folder.

  255. 

  256. NOTE! In order to copy and rename the plugin to the various different plugin folders, the demo plugin project

  257. contains a VERY useful script, which you'll almost certainly want to copy into your own projects - have

  258. a look in the demo target for the build phase called "Copy into the different plugin folders", and use the

  259. inspector to have a look at the script. It uses advanced cunningness to copy only to the correct target

  260. folders for the types of plugin you're targeting, and should be able to be used in your own project 

  261. without needing to edit it.

  262. 

  263. NOTE! If you use the Finder to rename your xyz.component file to xyz.vst, it might look like it's done

  264. exactly this... but in fact, the Finder may have secretly renamed it as "xyz.vst.component", even though 

  265. it shows "xyz.vst" as the name on the screen. I have wasted quite a lot of time angrily wondering why my VSTs 

  266. don't seem to work, before realising that this is what has happened. You should use the command-line to rename 

  267. it correctly.

  268. 

  269. If you also want to build an RTAS, then carry on reading...

  270. 

  271. 

  272. - Make sure that the JucePlugin_Build_RTAS is enabled in your JucePluginCharacteristics.h

  273. - After installing the Digidesign SDK, make sure you've run the config_SDK_for_Mac command in

  274.   its root directory. This sets up some of the tools that it needs.

  275. - Add the files from /wrapper/RTAS to your project. Obviously a couple of these are for Windows, so

  276.   you shouldn't add those

  277. - In the Digi SDK, in /AlturaPorts/TDMPlugins/common/mac, there are two config files:

  278.     CommonDebugSettings.xconfig and CommonReleaseSettings.xconfig

  279.   These contain lots of Digi hackery to get their stuff to compile, so you should add them to your project

  280.   and change your project's settings to use these files as their base config. Even so, it's all a bit of a mess, 

  281.   and you may need to tweak them a bit to get it to work on your system.

  282. - In your target settings, add a custom build setting called "MacBag", and set this to the path where the 

  283.   "MacBag" folder of the Digi SDK lives.

  284. - Add the following to your "Header Search Paths" setting (it's easiest to copy-and-paste this setting from 

  285.   the demo project):

  286.     "$(MacBag)/../AlturaPorts/TDMPlugIns/PlugInLibrary/**"

  287.     "$(MacBag)/../AlturaPorts/TDMPlugIns/DSPManager/**"

  288.     "$(MacBag)/../AlturaPorts/TDMPlugIns/SupplementalPlugInLib/Encryption"

  289.     "$(MacBag)/../AlturaPorts/TDMPlugIns/SupplementalPlugInLib/GraphicsExtensions"

  290.     "$(MacBag)/../AlturaPorts/TDMPlugIns/common"

  291.     "$(MacBag)/../AlturaPorts/TDMPlugIns/common/PI_LibInterface"

  292.     "$(MacBag)/../AlturaPorts/TDMPlugIns/PACEProtection/**" 

  293.     "$(MacBag)/../AlturaPorts/OMS/Headers" 

  294.     "$(MacBag)/../AlturaPorts/Fic/Interfaces/**" 

  295.     "$(MacBag)/../AlturaPorts/Fic/Source/SignalNets" 

  296.     "$(MacBag)/../AlturaPorts/DSIPublicInterface/PublicHeaders" 

  297.     "$(MacBag)/../DAEWin/Include"

  298.     "$(MacBag)/../AlturaPorts/DigiPublic/Interfaces"

  299.     "$(MacBag)/../AlturaPorts/DigiPublic"

  300.     "$(MacBag)/../AlturaPorts/NewFileLibs/DOA"

  301.     "$(MacBag)/../AlturaPorts/NewFileLibs/Cmn"

  302.     "$(MacBag)/../AlturaPorts/TDMPlugIns/SignalProcessing/**" 

  303.     "$(MacBag)/../AvidCode/AVX2sdk/AVX/avx2/avx2sdk/inc" 

  304.     "$(MacBag)/../AvidCode/AVX2sdk/AVX/avx2/avx2sdk/utils"

  305. - If you're using the Digi files CommonDebugSettings.xcconfig and CommonReleaseSettings.xcconfig,

  306.   then you'll probably have to remove the "-x c++" option from their OTHER_CFLAGS setting, because

  307.   that prevents it compiling obj-C. Also, you might need to comment-out the GCC_PREFIX_HEADER setting,

  308.   unless you can persuade precompiled headers to work (I've never managed to get them working myself..)

  309.   You'll also probably want to add a "MacBag" setting to these files, rather than putting it into

  310.   your project - e.g. "MacBag = /Users/jules/SDKs/PT_80_SDK/MacBag"

  311. - If you get include errors compiling some of the DigiDesign code, you may need to

  312.   add "/Developer/Headers/FlatCarbon" to your header search path.

  313. - In the SDK, find the PluginLibrary.xcodeproj file, and add this to your "External frameworks and Libraries".

  314.   If you've already compiled this library, you can open its item in your XCode project treeview, to find 

  315.   the "libPluginLibrary.a" item inside it. Drag this subitem down to your Target/"Link Binary With Libraries" 

  316.   build stage and drop it there to add it to the link process.

  317. - In your Info.plist, change the "Bundle OS Type Code" to "TDMw", and the "Bundle Creator OS Type Code" to

  318.   "PTul".

  319. - You may need to remove the "OTHER_CFLAGS = -x c++" from the RTAS settings file to stop it complaining about 

  320.   obj-C code

  321. 

  322. You should now be able to build an RTAS! Again, just renaming the finished bundle to ".dpm" and

  323. putting it in your RTAS folder should be do the trick.

  324.   

  325. If you get any weird build problems, a good tip is to try comparing the demo plugin's build settings with your 

  326. own - this should usually show up what's missing.

  327. 

  328. 

  329. Note about exported symbols: 

  330.   When XCode builds the plugin, I've had unpredictable results when trying to stop it from exporting 

  331.   all of the internal functions as public symbols. There are some flags that are supposed to turn this

  332.   off, but sometimes they don't seem to have any effect, and using an explicit exports file also

  333.   seems a bit hit-and-miss. (If anyone knows better and can get this working, please let me know!)

  334.   Anyway, as well as being wasteful and showing everyone what's inside your plugin, leaving all

  335.   the symbols in there will cause fatal crashes when used with Tracktion, or alongside any other

  336.   Juce-based plugins. A way of making sure your plugin is stripped is to use the command

  337.   "strip -x -S YourPlugin.vst/Contents/MacOS/YourPlugin" after bulding it, which removes the

  338.   unnecessary symbols (although in my experience this also doesn't seem to work all the time, 

  339.   so it's a good idea to check it using the unix "nm" command).