Commands
Commands are sent to GameSynth via TCP. The default communication settings are:
- IP address: local host (127.0.0.1)
- Port number: 28542
- Text encoding: UTF-8
- Delimiting character: 13 (Carriage Return)
They can be modified in the Settings window of GameSynth.
GameSynth
get_version
Returns the version of the GameSynth tool. The format is "YYYY.M.m.r" (YYYY for the year, M for the major version number, m for minor version number, and r for the revision). This can be used to maintain compatibility with various versions of the tool in the client code.
get_commands
Returns the list of available commands in this version of the API, separated by commas.
get_models
Returns the list of models in this version of GameSynth, separated by commas. This can be used to determine if plug-ins such as the Engines plug-in are installed or not.
select_model name
Selects the model whose name is specified. This is the equivalent of clicking on a model tab or pressing a function key in GameSynth. The name is case-insensitive. "No data found" will be returned if the model is not present (e.g., the Engines plug-in is not installed, or there is a typo).
Example:
select_model Impact
get_path path
Returns a system path as set in the GameSynth settings window. If no path has been assigned yet, the function will return "No data found". Possible values for the path requested are:
PATCH_FOLDER: the default patch path
BANK_FOLDER: the default bank path
BINARY_FOLDER: the default path for export of binary banks
MIDDLEWARE_FOLDER: the default path for export to middleware
RENDERING_FOLDER: the default path for audio rendering
AUDIOASSETS_FOLDER: the default path for audio assets
PICTURES_FOLDER: the default path for pictures (for instance in the Impact and Footsteps models)
VIDEO_FOLDER: the default path for the videos
SCRIPTS_FOLDER: the default path for the scripts (for the Sketch Pad or Script module)
REPOSITORY_FOLDER: the path where the repository data is stored
RANDOMPATCH_FOLDER: the path where audio assets can be used by the random patch creator
AUDIOEDITOR_EXE: the path to the default audio editor
Example:
get_path PATCH_FOLDER
get_samplerate
Returns the sample rate that is selected in the settings. The value returned is expressed in Hz.
set_samplerate value
Sets the sample rate in the GameSynth settings. The value must be expressed in Hz and the possible choices are currently limited to 44100 or 48000.
Attempting to change the sample rate while a patch is playing will trigger an error.
Example:
set_samplerate 44100
Repository
query_patchnames text name category tags
Returns the names of patches from the repository that match the search parameters, separated by commas. If no matching patch names are found, "No data found" is returned.
‘text’ is the text that the name, categories or tags must include.
‘name’ is 1 if the search look into the patch names, 0 otherwise.
‘category’ is 1 if the search look into the category names, 0 otherwise.
‘tags’ is 1 if the search look into the tag names, 0 otherwise.
Examples:
query_patchnames Magic 1 0 1
query_patchnames "natural disaster" 0 1 0
query_patch name
Gets a patch from the repository and makes it the current patch.
The patch name should be exactly like it appears in the repository (i.e., no path, no extension).
Patch names can be obtained via the query_patchnames function.
Examples:
query_patch Ascent
query_patch "Alien Fowl"
query_categories
Returns the names of all the categories assigned to patches in the repository, separated by commas.
query_tags
Returns the names of all the tags assigned to patches in the repository, separated by commas.
Patch
load_patch path
Loads a patch in GameSynth whose path is specified. The patch must be passed between quotes if it contains a space, and the extension must be present.
Examples:
load_patch D:\patches\blip.gspatch
load_patch "D:\patches\blip 2.gspatch"
save_patch path
Saves the current patch to the path indicated.
Examples:
save_patch D:\patches\blip.gspatch
save_patch "D:\patches\blip 2.gspatch"
render_patch path bits channels duration
Renders the patch to the indicated path. If a file already exists at this location, it will be overwritten.
The bit-depth and number of channels must be specified. The valid values for the bit-depth are: 8, 16, 24, and 32. The channels number can be set to 1 or 2.
The duration is expressed in seconds and is only used if the patch has an infinite duration. It is safe to set this value to 0 when the patch terminates by itself. The maximum allowed duration is set to 3 minutes (i.e., a value of 180).
Examples:
render_patch D:\patches\blip.wav 16 1 0
render_patch "D:\patches\ambient loop.wav" 24 2 10
get_modelname
Returns the name of the model used by the current patch.
get_patchname
Returns the name of the current patch. If the patch has not been saved yet and has no name, "unnamed" is returned.
get_variation
Returns the percentage of random variation currently assigned to the patch.
The value returned is in the range [0…100].
set_variation value
Sets the percentage of random variation of the patch to the given value.
The value must be between 0 and 100 and will be clipped if necessary.
Example:
set_variation 50
get_drawing index
Returns the curve drawn in the Sketch Pad of the current patch.
The index parameter starts at 0 and allows for the selection of any curve in the case of models allowing for multiple curves simultaneously on the Sketch Pad, such has the Whoosh model. For models with a single curve, simply pass 0.
The curve information is returned as a series of quadruplets (t, x, y, p) between parentheses, e.g. (0,0,0,1)(0.5,0.5557,0.49837,1)(1,0.801083,0.104,0.096)
t: corresponds to the time in seconds [0….60].
x: corresponds to the horizontal position on the Sketch Pad from left to right [0…1].
y: corresponds to the vertical position on the Sketch Pad from top to bottom [0…1].
p: corresponds to the amount of pressure applied when drawing [0…1].
Note: this function does not return the curve from a "Sketch Pad" module in the Modular model.
Example:
get_drawing 0
set_drawing points
Sets the curve in the Sketch Pad of the current patch.
The curve information is passed as a series of quadruplets (t, x, y, p) between parentheses (similar to the information returned by the get_drawing function).
t: corresponds to the time in seconds [0….60]. The GameSynth API will sort the points by increasing time if necessary.
x: corresponds to the horizontal position on the Sketch Pad from left to right [0…1]. The value will be clamped if necessary.
y: corresponds to the vertical position on the Sketch Pad from top to bottom [0…1]. The value will be clamped if necessary.
p: corresponds to the amount of pressure applied when drawing [0…1]. The value will be clamped if necessary.
Notes: this function cannot set the curve of a "Sketch Pad" module in the Modular model. When used with the Whoosh model, it will clear all previous curves.
Example:
set_drawing (0,0,0,1),(0.5,0.5,0.5,1),(1,0.8,0.1,0.1)
meta-parameters
get_metacount
Returns the number of meta-parameters in the current patch.
get_metanames
Returns the list of the names of the meta-parameters in the current patch, separated by commas.
If no meta-parameters are present in the patch, "No data found" is returned.
get_metaname index
Returns the name of the meta-parameter in the current patch whose index is passed as argument.
The index is 0-based and must be in the range from 0 to the value returned by the get_metacount function -1.
Example:
get_metaname 3
get_metavalue info_type info
Returns the value of a specific meta-parameter in the current patch. The meta-parameter is either described by its index or by its name, passed in the info argument. The info_type is set to BY_NAME or BY_INDEX to determine which one is expected.
When getting the value with info_type set to BY_INDEX, the index is 0-based and must be in the range from 0 to the value returned by the get_metacount function -1.
When getting the value with info_type set to BY_NAME, the valid meta-parameter names can be obtained by calling the get_metanames function.
The value returned is in the range [0…1].
Examples:
get_metavalue BY_INDEX 2
get_metavalue BY_NAME "cutoff freq"
set_metavalue info_type info value
Sets the value of a specific meta-parameter in the current patch. The meta-parameter is either described by its index or by its name, passed in the info argument. The info_type is set to BY_NAME or BY_INDEX to determine which one is expected.
Valid meta-parameter names can be obtained by calling the get_metanames function.
The value is a floating-point number that will be clipped between 0 and 1.
Examples:
set_metavalue BY_INDEX 1 0.3
set_metavalue BY_NAME "cutoff freq" 0.7
automation-curves
get_curvescount
Returns the number of automation curves in the current patch.
get_curvenames
Returns the list of the names of the automation curves in the current patch, separated by commas. If no automation curves are present in the patch, "No data found" is returned.
get_curvename index
Returns the name of the automation curve in the current patch whose index is passed as argument. The index is 0-based and must be in the range from 0 to the value returned by the get_curvescount function -1.
Example:
get_curvename 3
get_curvevalue info_type info
Return the points of a specific automation curve in the current patch. The automation curve is either described by its index or by its name, passed in the info argument. The info_type is set to BY_NAME or BY_INDEX to determine which one is expected.
When getting the value with info_type set to BY_INDEX, the index is 0-based and must be in the range from 0 to the value returned by the get_curvescount function -1.
When getting the value with info_type set to BY_NAME, the valid automation curve names can be obtained by calling the get_curvenames function.
The function returns a series of points, a duration, and a loop flag, separated by spaces.
The points are passed as a series of coordinates (X,Y) between parentheses, e.g. (0,1)(1,0.5) and the range of both X and Y values is [0…1].
The duration of the curve is expressed in seconds (it is limited to 60 seconds).
The looping information is passed as 0 (no loop) or 1 (looping).
Examples:
get_curvevalue BY_INDEX 2
get_curvevalue BY_NAME "cutoff freq"
set_curvevalue info_type info points duration loop
Sets the value of a specific automation curve in the current patch. The automation curve is either described by its index or by its name, passed in the info argument. The info_type is set to BY_NAME or BY_INDEX to determine which one is expected.
When setting the value with info_type set to BY_NAME, existing automation curve names can be obtained by calling the get_curvenames function.
When setting the value with info_type set to BY_INDEX, the index is 0-based and must be in the range from 0 to the value returned by the get_curvescount function -1
If an automation curve with the specified name or index already exists, its curve and parameters are replaced by the curve and parameters passed to the function.
If no automation curve with the provided name exists, a new one is created, using the specified points to set its curve.
The points are passed as a series of coordinates (X,Y) between parentheses, e.g. (0,1)(1,0.5).
The range of both X and Y values is [0…1]. If the first of the X values is not 0 and/or the last of the X values is not 1, the X coordinates are remapped to the range [0…1].
If some of the Y values are over 1.0 or below 0, they are clipped to fit in the range [0…1].
The duration of the curve is expressed in seconds (it is limited to 60 seconds).
The looping information is passed as 0 (no loop) or 1 (looping).
Examples:
set_curvevalue BY_NAME volume (0,0.3)(0.5,1)(1,0) 2.5 1
set_curvevalue BY_INDEX 1 "(0, 0.3) (0.5, 1) (1, 0)" 3 0
Playback
play
Plays the current patch.
stop
Stops the current patch if it is playing.
is_playing
Returns 1 if the current patch is playing, 0 otherwise.
is_infinite
Returns 1 if the current patch is infinite, 0 if it can terminate by itself.
is_randomized
Returns 1 if the current patch can generate variations, i.e., if random ranges are assigned to some of its parameters, or some combo box items are ticked for random selection, or some inherently random parameters are set to a non-zero value (e.g., movement variation in the Whoosh model, variation parameter of the Envelope module in the Modular model etc…).
If no random settings could be found, the command returns 0.
enable_events value
Enables (when value is 1) or disable (when value is 0) the notification of the synthesis events when they are received from GameSynth.
By default, the notifications are disabled.
When an event notification is received, the text follows this convention:
EVENT: name of the event
User Interface
window_back
Sends the main GameSynth window to the back, making sure other tools are visible.
window_front
Brings the main GameSynth window to the top, making sure it is visible.
window_message text buttons
Displays a message box that allows the user to interact with a script, for example to confirm or cancel an action.
The text of the message is passed between quotes as the first parameter. In addition, the buttons to be displayed must be specified. Several combinations are available:
OK, OK_CANCEL, YES_NO, and RETRY_EXIT.
The function will return the name of the button pressed (in caps), i.e., OK, CANCEL, RETRY etc…
Example:
window_message "The data will be overwritten. Do you want to continue?" OK_CANCEL
window_parameters parameter1 parameter2...
Displays a dialog box that allows the user to specify the values of parameters used by a script.
Each parameter description is passed between brackets, with fields separated by commas. The general format a parameter description is therefore: {type, name, field1, field2, …}.
4 types of parameters are available: Number, Boolean, String, and Enum. A Label type is also provided. It does not store a value, but allows to display additional instructions in the window.
A numerical parameter will appear as a text box and is defined as:
{NUMBER, "Name", Type, "Unit", Min, Max, Def, Decimals}
- NUMBER is the type of the parameter
- Name is the name of the parameter as it will be displayed in front of the text box
- Type is the subtype of the number: FLOAT or INTEGER
- Unit is a string which will be displayed after the value of the parameter
- Min is the minimum value the parameter can take
- Max is the maximum value the parameter can take
- Def is the default value of the parameter
- Decimals is only used for numbers of subtype FLOAT and represent the number of decimals that will be displayed (up to 5).
Examples:
{NUMBER, "Sample Rate", INTEGER, "Hz", 8000, 48000, 44100, 0}
{NUMBER, "Duration", FLOAT, "s", 0.1, 10, 1, 3}
A boolean parameter will appear as a checkbox and is defined as:
{BOOL, "Name", Def}
- BOOL is the type of the parameter
- Name is the name of the parameter as it will be displayed in front of the checkbox
- Def is the default value of the parameter. For a boolean parameter, it is either TRUE or FALSE
Example:
{BOOL, "Looping", TRUE}
A string parameter will appear as text box and is defined as:
{STRING, "Name", Type, Def}
- STRING is the type of the parameter
- Name is the name of the parameter as it will be displayed in front of the text box.
- Type is the subtype of the string. It can take the following values:
- NORMAL: to enter a regular string
- FILELOAD: to select the path of a file to load (an extra browse button will be displayed)
- FILESAVE: to select the path of a file to save (an extra browse button will be displayed)
- FOLDER: to select the path of a folder (an extra browse button will be displayed)
- Def is the default value of the string
Examples:
{STRING, "Rendering Folder", FOLDER, "C:\GameSynth\Wave Files"}
{STRING, "Patch", FILELOAD, "C:\GameSynth\Patches\Droid.gspatch"}
{STRING, "Track Name", NORMAL, "New Track"}
An enumeration parameter will appear either as a combo box or a list box based on its subtype, and is defined as:
{ENUM, "Name", Type, "Choice1, Choice2…", Def}
- ENUM is the type of the parameter
- Name is the name of the parameter as it will be displayed
- Type is the subtype of the enumeration, which determines the control used:
- LIST: display the choices in a list box (recommended for large numbers of choices)
- COMBO: display the choices in a combo box
- Choices is a list of possible values for the parameter. The choices are listed between quotes and separated by commas
- Def is the default value of the parameter (i.e., one of the choices)
Example:
{ENUM, "Container Type", COMBO, "None,Sequential,Random,Random No Repeat,Shuffle", Random}
Finally, a label will appear as simple text. It is mostly used as a section delimiter and to give information about the parameters. It is defined as:
{LABEL, "Text", Type, Alignment}
- LABEL is the type of the parameter
- Text is the text that will be displayed
- Type is the subtype of the label. It defines the font used to display the text
- TEXT: the same font than for the name of the parameters is used
- HEADER: a slightly bigger font - in bold - is used
- Alignment : the horizontal alignment of the text in the dialog box
- LEFT : the text is aligned on the left of the dialog box
- RIGHT : the text is aligned on the right of the dialog box
- CENTER : the text is centered in the dialog box
Example:
{LABEL, "The parameters below define how the sound variations are generated.", TEXT, LEFT}
Once the dialog box is closed, the function returns the values of the parameters separated by commas.
window_rendering show_duration show_variations
Displays a dialog box that allows the user to specify rendering options. It is a preconfigured version of the window_parameters command, which displays controls for the following parameters:
- Bit depth : the bit depth used to render the file (8, 16, 24 or 32-bit)
- Sample Rate : the sample rate used to generate the audio file (44100 or 48000 Hz)
- Channels : the number of channels (mono or stereo).
The show_duration and show_variations parameters can be set to 0 or 1 to show or hide extra parameters, depending on the needs of your application:
- Duration : displays the rendering duration for infinite patches (if show_duration is set to 1)
- Variations : displays the number of sound variations to render (if show_variations is set to 1)
Example:
window_rendering 1 0
window_test
Displays a dialogue box showcasing the different types of parameters and controls that can be used when creating your own dialog boxes.
load_patch path
Loads a patch in GameSynth whose path is specified. The patch must be passed between quotes if it contains a space, and the extension must be present.
Examples:
load_patch D:\patches\blip.gspatch
load_patch "D:\patches\blip 2.gspatch"
save_patch path
Saves the current patch to the path indicated.
Examples:
save_patch D:\patches\blip.gspatch
save_patch "D:\patches\blip 2.gspatch"
render_patch path bits channels duration
Renders the patch to the indicated path. If a file already exists at this location, it will be overwritten.
The bit-depth and number of channels must be specified. The valid values for the bit-depth are: 8, 16, 24, and 32. The channels number can be set to 1 or 2.
The duration is expressed in seconds and is only used if the patch has an infinite duration. It is safe to set this value to 0 when the patch terminates by itself. The maximum allowed duration is set to 3 minutes (i.e., a value of 180).
Examples:
render_patch D:\patches\blip.wav 16 1 0
render_patch "D:\patches\ambient loop.wav" 24 2 10
get_modelname
Returns the name of the model used by the current patch.
get_patchname
Returns the name of the current patch. If the patch has not been saved yet and has no name, "unnamed" is returned.
get_variation
Returns the percentage of random variation currently assigned to the patch.
The value returned is in the range [0…100].
set_variation value
Sets the percentage of random variation of the patch to the given value.
The value must be between 0 and 100 and will be clipped if necessary.
Example:
set_variation 50
get_drawing index
Returns the curve drawn in the Sketch Pad of the current patch.
The index parameter starts at 0 and allows for the selection of any curve in the case of models allowing for multiple curves simultaneously on the Sketch Pad, such has the Whoosh model. For models with a single curve, simply pass 0.
The curve information is returned as a series of quadruplets (t, x, y, p) between parentheses, e.g. (0,0,0,1)(0.5,0.5557,0.49837,1)(1,0.801083,0.104,0.096)
t: corresponds to the time in seconds [0….60].
x: corresponds to the horizontal position on the Sketch Pad from left to right [0…1].
y: corresponds to the vertical position on the Sketch Pad from top to bottom [0…1].
p: corresponds to the amount of pressure applied when drawing [0…1].
Note: this function does not return the curve from a "Sketch Pad" module in the Modular model.
Example:
get_drawing 0
set_drawing points
Sets the curve in the Sketch Pad of the current patch.
The curve information is passed as a series of quadruplets (t, x, y, p) between parentheses (similar to the information returned by the get_drawing function).
t: corresponds to the time in seconds [0….60]. The GameSynth API will sort the points by increasing time if necessary.
x: corresponds to the horizontal position on the Sketch Pad from left to right [0…1]. The value will be clamped if necessary.
y: corresponds to the vertical position on the Sketch Pad from top to bottom [0…1]. The value will be clamped if necessary.
p: corresponds to the amount of pressure applied when drawing [0…1]. The value will be clamped if necessary.
Notes: this function cannot set the curve of a "Sketch Pad" module in the Modular model. When used with the Whoosh model, it will clear all previous curves.
Example:
set_drawing (0,0,0,1),(0.5,0.5,0.5,1),(1,0.8,0.1,0.1)
get_metacount
Returns the number of meta-parameters in the current patch.
get_metanames
Returns the list of the names of the meta-parameters in the current patch, separated by commas.
If no meta-parameters are present in the patch, "No data found" is returned.
get_metaname index
Returns the name of the meta-parameter in the current patch whose index is passed as argument.
The index is 0-based and must be in the range from 0 to the value returned by the get_metacount function -1.
Example:
get_metaname 3
get_metavalue info_type info
Returns the value of a specific meta-parameter in the current patch. The meta-parameter is either described by its index or by its name, passed in the info argument. The info_type is set to BY_NAME or BY_INDEX to determine which one is expected.
When getting the value with info_type set to BY_INDEX, the index is 0-based and must be in the range from 0 to the value returned by the get_metacount function -1.
When getting the value with info_type set to BY_NAME, the valid meta-parameter names can be obtained by calling the get_metanames function.
The value returned is in the range [0…1].
Examples:
get_metavalue BY_INDEX 2
get_metavalue BY_NAME "cutoff freq"
set_metavalue info_type info value
Sets the value of a specific meta-parameter in the current patch. The meta-parameter is either described by its index or by its name, passed in the info argument. The info_type is set to BY_NAME or BY_INDEX to determine which one is expected.
Valid meta-parameter names can be obtained by calling the get_metanames function.
The value is a floating-point number that will be clipped between 0 and 1.
Examples:
set_metavalue BY_INDEX 1 0.3
set_metavalue BY_NAME "cutoff freq" 0.7
get_curvescount
Returns the number of automation curves in the current patch.
get_curvenames
Returns the list of the names of the automation curves in the current patch, separated by commas. If no automation curves are present in the patch, "No data found" is returned.
get_curvename index
Returns the name of the automation curve in the current patch whose index is passed as argument. The index is 0-based and must be in the range from 0 to the value returned by the get_curvescount function -1.
Example:
get_curvename 3
get_curvevalue info_type info
Return the points of a specific automation curve in the current patch. The automation curve is either described by its index or by its name, passed in the info argument. The info_type is set to BY_NAME or BY_INDEX to determine which one is expected.
When getting the value with info_type set to BY_INDEX, the index is 0-based and must be in the range from 0 to the value returned by the get_curvescount function -1.
When getting the value with info_type set to BY_NAME, the valid automation curve names can be obtained by calling the get_curvenames function.
The function returns a series of points, a duration, and a loop flag, separated by spaces.
The points are passed as a series of coordinates (X,Y) between parentheses, e.g. (0,1)(1,0.5) and the range of both X and Y values is [0…1].
The duration of the curve is expressed in seconds (it is limited to 60 seconds).
The looping information is passed as 0 (no loop) or 1 (looping).
Examples:
get_curvevalue BY_INDEX 2
get_curvevalue BY_NAME "cutoff freq"
set_curvevalue info_type info points duration loop
Sets the value of a specific automation curve in the current patch. The automation curve is either described by its index or by its name, passed in the info argument. The info_type is set to BY_NAME or BY_INDEX to determine which one is expected.
When setting the value with info_type set to BY_NAME, existing automation curve names can be obtained by calling the get_curvenames function.
When setting the value with info_type set to BY_INDEX, the index is 0-based and must be in the range from 0 to the value returned by the get_curvescount function -1
If an automation curve with the specified name or index already exists, its curve and parameters are replaced by the curve and parameters passed to the function.
If no automation curve with the provided name exists, a new one is created, using the specified points to set its curve.
The points are passed as a series of coordinates (X,Y) between parentheses, e.g. (0,1)(1,0.5).
The range of both X and Y values is [0…1]. If the first of the X values is not 0 and/or the last of the X values is not 1, the X coordinates are remapped to the range [0…1].
If some of the Y values are over 1.0 or below 0, they are clipped to fit in the range [0…1].
The duration of the curve is expressed in seconds (it is limited to 60 seconds).
The looping information is passed as 0 (no loop) or 1 (looping).
Examples:
set_curvevalue BY_NAME volume (0,0.3)(0.5,1)(1,0) 2.5 1
set_curvevalue BY_INDEX 1 "(0, 0.3) (0.5, 1) (1, 0)" 3 0
play
Plays the current patch.
stop
Stops the current patch if it is playing.
is_playing
Returns 1 if the current patch is playing, 0 otherwise.
is_infinite
Returns 1 if the current patch is infinite, 0 if it can terminate by itself.
is_randomized
Returns 1 if the current patch can generate variations, i.e., if random ranges are assigned to some of its parameters, or some combo box items are ticked for random selection, or some inherently random parameters are set to a non-zero value (e.g., movement variation in the Whoosh model, variation parameter of the Envelope module in the Modular model etc…).
If no random settings could be found, the command returns 0.
enable_events value
Enables (when value is 1) or disable (when value is 0) the notification of the synthesis events when they are received from GameSynth.
By default, the notifications are disabled.
When an event notification is received, the text follows this convention:
EVENT: name of the event
window_back
Sends the main GameSynth window to the back, making sure other tools are visible.
window_front
Brings the main GameSynth window to the top, making sure it is visible.
window_message text buttons
Displays a message box that allows the user to interact with a script, for example to confirm or cancel an action.
The text of the message is passed between quotes as the first parameter. In addition, the buttons to be displayed must be specified. Several combinations are available:
OK, OK_CANCEL, YES_NO, and RETRY_EXIT.
The function will return the name of the button pressed (in caps), i.e., OK, CANCEL, RETRY etc…
Example:
window_message "The data will be overwritten. Do you want to continue?" OK_CANCEL
window_parameters parameter1 parameter2...
Displays a dialog box that allows the user to specify the values of parameters used by a script.
Each parameter description is passed between brackets, with fields separated by commas. The general format a parameter description is therefore: {type, name, field1, field2, …}.
4 types of parameters are available: Number, Boolean, String, and Enum. A Label type is also provided. It does not store a value, but allows to display additional instructions in the window.
A numerical parameter will appear as a text box and is defined as:
{NUMBER, "Name", Type, "Unit", Min, Max, Def, Decimals}
- NUMBER is the type of the parameter
- Name is the name of the parameter as it will be displayed in front of the text box
- Type is the subtype of the number: FLOAT or INTEGER
- Unit is a string which will be displayed after the value of the parameter
- Min is the minimum value the parameter can take
- Max is the maximum value the parameter can take
- Def is the default value of the parameter
- Decimals is only used for numbers of subtype FLOAT and represent the number of decimals that will be displayed (up to 5).
- BOOL is the type of the parameter
- Name is the name of the parameter as it will be displayed in front of the checkbox
- Def is the default value of the parameter. For a boolean parameter, it is either TRUE or FALSE
- STRING is the type of the parameter
- Name is the name of the parameter as it will be displayed in front of the text box.
- Type is the subtype of the string. It can take the following values:
- NORMAL: to enter a regular string
- FILELOAD: to select the path of a file to load (an extra browse button will be displayed)
- FILESAVE: to select the path of a file to save (an extra browse button will be displayed)
- FOLDER: to select the path of a folder (an extra browse button will be displayed)
- Def is the default value of the string
- ENUM is the type of the parameter
- Name is the name of the parameter as it will be displayed
- Type is the subtype of the enumeration, which determines the control used:
- LIST: display the choices in a list box (recommended for large numbers of choices)
- COMBO: display the choices in a combo box
- Choices is a list of possible values for the parameter. The choices are listed between quotes and separated by commas
- Def is the default value of the parameter (i.e., one of the choices)
- LABEL is the type of the parameter
- Text is the text that will be displayed
- Type is the subtype of the label. It defines the font used to display the text
- TEXT: the same font than for the name of the parameters is used
- HEADER: a slightly bigger font - in bold - is used
- Alignment : the horizontal alignment of the text in the dialog box
- LEFT : the text is aligned on the left of the dialog box
- RIGHT : the text is aligned on the right of the dialog box
- CENTER : the text is centered in the dialog box
Examples:
{NUMBER, "Sample Rate", INTEGER, "Hz", 8000, 48000, 44100, 0}
{NUMBER, "Duration", FLOAT, "s", 0.1, 10, 1, 3}
A boolean parameter will appear as a checkbox and is defined as:
{BOOL, "Name", Def}
Example:
{BOOL, "Looping", TRUE}
A string parameter will appear as text box and is defined as:
{STRING, "Name", Type, Def}
Examples:
{STRING, "Rendering Folder", FOLDER, "C:\GameSynth\Wave Files"}
{STRING, "Patch", FILELOAD, "C:\GameSynth\Patches\Droid.gspatch"}
{STRING, "Track Name", NORMAL, "New Track"}
An enumeration parameter will appear either as a combo box or a list box based on its subtype, and is defined as:
{ENUM, "Name", Type, "Choice1, Choice2…", Def}
Example:
{ENUM, "Container Type", COMBO, "None,Sequential,Random,Random No Repeat,Shuffle", Random}
Finally, a label will appear as simple text. It is mostly used as a section delimiter and to give information about the parameters. It is defined as:
{LABEL, "Text", Type, Alignment}
Example:
{LABEL, "The parameters below define how the sound variations are generated.", TEXT, LEFT}
Once the dialog box is closed, the function returns the values of the parameters separated by commas.
window_rendering show_duration show_variations
Displays a dialog box that allows the user to specify rendering options. It is a preconfigured version of the window_parameters command, which displays controls for the following parameters:
- Bit depth : the bit depth used to render the file (8, 16, 24 or 32-bit)
- Sample Rate : the sample rate used to generate the audio file (44100 or 48000 Hz)
- Channels : the number of channels (mono or stereo).
- Duration : displays the rendering duration for infinite patches (if show_duration is set to 1)
- Variations : displays the number of sound variations to render (if show_variations is set to 1)
The show_duration and show_variations parameters can be set to 0 or 1 to show or hide extra parameters, depending on the needs of your application:
Example:
window_rendering 1 0
window_test
Displays a dialogue box showcasing the different types of parameters and controls that can be used when creating your own dialog boxes.