plugconfig

Configure the behavior of a plug-in

Description

Note: plug-in building for hosts other than Ableton Live is no longer supported. For more information to help you make the transition to creating plug-ins in Max for Live, see Max for Live for Pluggo Developers.

The plugconfig object lets you configure your plug-in's behavior using a script that will be familiar to users of the env and menubar objects. The script can be accessed by doubleclicking on a plugconfig object. You should only have one plugconfig object per plug-in patcher; if you have more than one, the object that loads last will be used by the runtime plug-in environment. Since it's not easy to determine which object that will be, just use one.
When you double-click on plugconfig, you'll see a short script already in place. These are the default settings, which are in fact identical to those you'd get if your patch contained no plugconfig object at all.
plugconfig is pretty much a read-only object when used within the runtime plug-in environment. The environment reads the settings from the object's script and is configured accordingly. You can send the messages view and offset to the object to scroll the patcher to a new location, but most plug-ins will allow the user to do this using the "View" menu that appears above the plug-in interface.

Arguments

None.

Messages

addview name [symbol]
x-offset [int]
y-offset [int]
initial-view (1 or 0) [int]
addview adds an additional "Interface" view to the plug-in's "View" menu with a specified x and y offset. This allows you to scroll the patcher to a different location to expose a different part of the interface that might correspond to a "page" of parameter controls. If you send the view message to plugconfig with the name of an added view as an argument, the patcher window will scroll to the view's x and y offset. This works in Max as well as in the run-time plug-in environment, allowing you to test interface configurations.
accurate 0/1 [list]
The accurate message tells the runtime plug-in environment to run the Max event (or control) scheduler at the same number-of-samples interval as the signal vector size. At 32 samples this is slightly less than 1 ms but running the scheduler this often can have some impact on the overall CPU-intensiveness of the plug-in.
By default, accurate mode is not enabled and the scheduler runs at the same interval as the I/O vector size of the host environment (typically 512 or 1024 samples). The only thing accurate mode affects is parameter updating to a plug-in, so for example if you have a control-rate LFO you may want to use this mode. The use of accurate mode will also increase the frequency of parameter updating from control-rate scheduled plugmod processes.
autosize autosize, which by default is enabled, sizes the plug-in edit window to be the height necessary to display all of the parameters, and the width of the parameter display.
defaultview name [symbol]
x-offset [int]
y-offset [int]
initial-view (1 or 0) [int]
defaultview renames the "Interface" item in the plug-in's "View" menu to the name argument, scrolling the patcher to the specified x and y offsets when the view is made visible. If the third argument (optional) to defaultview is non-zero, the view is made the initial view shown when the plug-in editing window is opened. This will be true anyway if there is no "Parameters" view (as specified by the useviews message).
dragscroll allow/disallow-flag (1 or 0) [int]
This message is currently unimplemented.
capture program-number [int]
program-name [symbol]
The word capture, followed by a program number (numbering starts at 1), saves all current pp and plugmultiparam data and adds the valude in the form of a setprogram message in the plugconfig. Sending a capture message is customarily how you create plug-in presets while creating a plug-in patch.
category category-number [int]
The word category, followed by a number that specifies a category for the plug-in, identifies the plug-in to a host application. Some hosts, such as Pro-Tools, list plug-ins based on what category of plug-in they are assigned rather than the location on the hard drive. If you choose to not define the category your plug-in will be listed in the "none" or "other" category. The following chart lists what numbers map to which categories:

None: 0 (0x0000 hex)
EQ: 1 (0x0001 hex)
Dynamics: 2 (0x0002 hex)
PitchShift: 4 (0x0004 hex)
Reverb: 8 (0x0008 hex)
Delay: 16 (0x0010 hex)
Modulation: 32 (0x0020 hex)
Harmonic: 64 (0x0040 hex)
NoiseReduction: 128 (0x0080 hex)
Dither: 256 (0x0100 hex)
SoundField: 512 (0x0200 hex)
HWGenerators: 1024 (0x0400 hex)
SWGenerators: 2048 (0x0800 hex)
WrappedPlugin: 4096 (0x1000 hex)
Effect: 8192 (0x2000 hex)
(mouse) Double-clicking on the plugconfig object will opens an editing window where you can view its contents.
infopict pict-file-name [symbol]
0 [int]
The infopict allows you to include a picture to display in the "Plug-in Info" view.
infotext text-content [list]
infotext allows you to describe the effect and have the text appear in the "Plug-in Info" view. There is a limit of about 256 words. A special symbol consisting of a less-than symbol and a greater-than symbol surrounding a capital "P" produces a carriage return. Note that all commas and semicolons in the text must be preceded by a backslash. If you do not do this, you could wipe out the rest of your script when you save it.
hintcolor 16-bit color value [int]
16-bit color value [int]
16-bit color value [int]
The word hintcolor, followed by three numbers that specify a color as a 16-bit value, sets the text color which appears in the hint area for standard pluggo-format interfaces. As an example, a black hint would be specified with hintcolor 0 0 0.
hintbg 16-bit color value [int]
16-bit color value [int]
16-bit color value [int]
The word hintbg, followed by three numbers that specify a color as a 16-bit value, sets the background color which appears in the hint area for standard pluggo-format interfaces. As an example, a medium gray would be specified with hintbg 40000 40000 40000, and a white background would be specified with hintbg 65535 65535 65535.
hintfg 16-bit color value [int]
16-bit color value [int]
16-bit color value [int]
The word hintfg, followed by three numbers that specify a color as a 16-bit value, sets the second background color which appears in the hint area for standard pluggo-format interfaces.
initialpgm program number [int]
The word initialpgm, followed by a number, specifies the program that should be loaded when the plug-in is initially opened. The default is 0, which means no program will be loaded; instead in this case, you would use loadbang objects to set the initial values of plug-in parameters. This behavior, however, is not consistent with the majority of plug-ins that get set to the values in program 1 when they are loaded (since 1 is always the initial program, unless the plug-in is being restored as part of a document for the host application). Once you have a collection of settings that you like, consider storing them in the first program inside plugconfig and adding an initialpgm 1 message. This has the added benefit of doing away with loadbang objects used to initialize your parameters. Any other program number (up to the number of programs in the plug-in specified by the numprograms message) can also be loaded, but the current program number as shown in the host sequencer's window cannot be changed by the plug-in. So, given that all host sequencers are initially set to program 1, you'll end up confusing the user if you load another program number initially.
latency number-of-samples [int]
The word latency, followed by a number that specifies the latency (in samples) inherent in a plug-in, provides latency information to the plug-in host so that the host can compensate.
noinfo This is the default behavior for plug-in information. If neither text nor picture has been provided as information about the effect, the "Plug-in Info" item does not appear in the "View" menu, even if you've enabled it with the useviews command above. If noinfo and either infopict or infotext appear together in a script, noinfo"loses" and the "info" view is displayed.
nohintarea If the nohintarea message appears in a script, the runtime plug-in environment does not provide additional space for a hint area at the bottom of the Parameters view. If however the number of egg sliders does not completely fill the edit window because its size was defined using either the windowsize or setsize messages, a hint area will be present.
numprograms number-of-programs (1 through 128) [int]
numprograms sets the number of stored programs for the plug-in. Programs are collections of values (between 0 and 1) for each of the parameters you've defined using pp and plugmultiparam objects. The default number of programs is 64, the minimum is 1, and the maximum is 128. By default, all programs are set to 0 for each parameter, but you can override this with the setprogram message.
meter level-meter-mode [int]
The word meter, followed by a number, sets the initial mode of the level meter at the top of the plug-in edit window. There is currently no way to permanently disable the meter, but it is disabled if there isn't enough space to display it fully because you've defined an edit window that is too narrow. The modes are:

1: meter the input
2: meter the output
3: off
package package code [symbol]
The word package, followed by a four-character code, is used to define a plug-in collection. This code corresponds to the Macintosh Application Creator Code (see the Collectives vignette for more information on this topic). If your collection of plug-ins with a custom package code is placed in a subfolder of the VST folder (as is done with the pluggo, Mode, Hipno and UpMix plug-in collections) most host applications will categorize them as a separate collection. The default four-character ID is ????, which is assigned for generic files and applications.
preempt priority (1 or 0) [int]
The word preempt followed by a 1 or 0 sets the priority of control messages. This message is currently ignored by the runtime plug-in environment.
offset x coordinate [int]
y coordinate [int]
The word offset, followed by a pair of numbers that specify X and Y coordinates, scrolls the patcher containing the plugconfig object to the specified coordinates.
oversampling code-number [int]
This message is currently ignored by the runtime plug-in environment.
nonrealtime 0/1 [list]
Causes the plug-in to be listed in the AudioSuite menu in Pro Tools.
pic file-name [list]
The word pic, followed by a filename, specifies a file to include in the plug-in.
product product-name [symbol]
The word product followed by a symbol, specifies a product name to be reported to the VST host application if it asks for one. This is typically specified in the plugconfig script. If no product name is given, then the default "Pluggo" is used.
setprogram program-storage-data [list]
The word setprogram, followed by a list of data described below, creates and stores a program stored in the plugconfig object's internal script. A message takes the form:

setprogram number, name, start index offset, (list of values...

Normally, you won't be typing the setprogram message into a script yourself; you'll send capture messages to the plugconfig object to generate it automatically. You might end up editing it (e.g., to change the program's name) so it's useful to know a little about the message's format. setprogram lets you name a specific program and, optionally, set some initial values for it. Program numbers (for the first argument) start at 1. The name is a symbol (if there are spaces in the name, it must be contained in double quotes). The start index offset argument sets a number added to 1 that determines the starting parameter number of the parameter values listed in the message. After this argument, one or more parameter values follow. If you don't supply enough values to set all the defined parameters, the additional ones are set to 0. You don't need to set the values at all if you want them to be 0. However, when you re-open the plugconfig object's edit window to view the script, the additional zero values will have been added. The start index offset argument is used to handle stored programs containing more than 256 parameters. 256 is the maximum size of a Max message.
setsize width (pixels) [int]
height (pixels) [int]
setsize sets the plug-in edit window to be a specific size in pixels. If you use the Parameters view, this size may be overridden if you've specified a window too narrow to display the egg sliders properly. Note that you should add approximately 30 pixels to the size of the patcher window in order to account for the height of the "View" menu and level-meter panel.
sigvschange signal-vector-size [int]
This message is currently ignored by the runtime plug-in environment. 32 is currently the only possible signal vector size.
sigvsdefault signal-vector-size [int]
This message is currently ignored by the runtime plug-in environment. 32 is currently the only possible signal vector size.
swirl 0/1 [list]
The swirl message sets the hint area background to be drawn as a swirl inspired by the pluggo packaging (which was itself inspired by the publicity poster for the classic French film musical "Les Demoiselles de Rochefort"). The default appearance of the hint area is the plain, non-swirl background. To set the swirl colors, use the hintfg and hintbg messages.
synth 0/1 [list]
The word synth, followed by a one or no arguments, tells host application that the plug-in is an instrument plug-in. If followed by a zero, it tells the host application that the plug-in is an effect plug-in. The default is that the plug-in is an effect, not an instrument.
read filename [symbol]
The word read, followed by an optional symbol, imports a file of effect programs saved in Cubase format and loads as many as possible into the plugconfig object for saving as setprogram messages. No checking is done to verify that the file contains effect programs for a plug-in with the same unique ID code as the one in the plugconfig object, nor is there any checking to ensure that the number of plugconfig object parameters match. If the symbol is present, the plugconfig object looks for a file with that name. Otherwise, a standard open file dialog is displayed, allowing you select an effect program file.
recall program number [int]
The word recall, followed by a program number (numbering starts at 1), sets all pp and plugmultiparam objects to the values stored within a setprogram message in the plugconfig object's script. The parameter numbers of the pp and plugmultiparam objects determine the values they are assigned from the contents of the setprogram message.
uniqueid number (0-255) [int]
number (0-255) [int]
number (0-255) [int]
The word uniqueid, followed by three numbers in the range 0-255, specify an ID code that will uniquely identify your plug-in. The code is used to identify a plug-in as a pluggo-based animal as well as to preserve plugmod connections between patchers. You can either use the three randomly generated numbers or something intentional. There are about 16 million possibilities. 0 0 0 is reserved and cannot be used. Using a zero for the first number is reserved for use by Cycling '74 and its registered plug-in developers. You won't need to interact with this ID code, although you might want to know that part of it will be used as the basis for a floating-point "patcher code" output by the plugmod object. The floating-point value, however, will not in any way resemble the ID you choose.
usedefault If this message appears in a script, there is no plug-in edit window. Instead, the parameter editing features of the host environment are used. By default, usedefault is not present in a script, and the plug-in's editing window appears.
useviews show-views-flags (0 or 1) [list]
useviews determines which plug-in edit window views are presented to the user. The views are specified in the following order: Parameters (the egg sliders), Interface (a Max patcher-based interface), Messages (a transcript of the Max window useful for plug-in development), and Plug-in Info (where you can brag about your plug-in). If the edit window is visible, the Pluggo Info view always appears. For example, useviews 1 0 0 0 would place only the Parameters view in the plug-in edit window's "View" menu. The user would be unable to switch to another view.
welcome welcome message [list]
The word welcome followed by a group of words and numbers, specify the welcome message to be displayed at the bottom hint area when the user opens the plug-in editing window for the first time and looks at the Parameters view, as well as when the cursor is moved into the top part of the window when the Parameters view is being used. If the nohintarea message is present in the script, the lack of a hint area in the Parameters view will cause the welcome message not to be displayed.
windowsize windowsize sets the size of the plug-in edit window to the size of the patcher window.
vendor vendor_name [symbol]
The word vendor followed by a group of words and numbers, specifies a vendor name to be reported to the VST host application if it asks for one. This is typically specified in the plugconfig script.
version version_number [int]
The word version followed by a group of words and numbers, specifies a software version number to be reported to the VST host application if it asks for one. This is typically specified in the plugconfig script.
view name of a view [list]
The word view, followed by a symbol that is the name of a view defined in the plugconfig object's script, scrolls the patcher containing the plugconfig object to the coordinate offset assigned to the view.

Information for box attributes common to all objects

Examples

See Also

Name Description
plugmod Modify plug-in parameter values in other plug-ins