We have introduced how to directly write the manipulated target object's name, e.g. Work Unit, Cue Sheet, in the Scripts.
However, if you want to apply the same processing while changing the manipulated target, you may need to edit the codes directly which is time-consuming and may result in human error.
We provide a function called the Extension for Script Editor to solve this problem.
This function displays the comment information described in the Script in the Script list or menu, and makes it easy to update the variables defined in the Script by operating the editor GUI.
By using the extended format for the Script editor, you can reduce the human error and improve iteration time.

In this tutorial, use the User Variable function of the Extension for Script Editor to create a Script to set by Cue's "Pitch" parameter in the GUI.

This tutorial will use the project created by Creating a project and registering Waveform file to a Cue tutorial.
Before starting this tutorial, if this project is not open, please open the project or execute the Script created in the Creating a project and registering Waveform file to a Cue tutorial.

Preparing a Script file

Select "Script list..." in the Script menu to display the Script list window.
Click the New button in the Script list window to create a Script file with the name below:

Save location of Script	Script file name
tutorials [CRI]	tutorial06-1_user_variable.py

Script Description

Double-click the created Script to open by Run the Script from the Script Editor .
After the "Importing modules" Script description, in order to get an overview of the Script in the Script list window, write the Script description as follows:

# --Description:[Tutorial] Cue "Pitch" parameter change using user variables

Importing Module

Once you have written the Script description, import the following modules to work with CRI Atom Craft in your Script.

import cri.atomcraft.project
import cri.atomcraft.project as acproject
import cri.atomcraft.debug as acdebug

Import the Project Module to work with the project and import the Debug Module for log output. When defining a user variable that handles an object, you need to import "cri.atomcraft.project" without replacing the import name.

Definition of variables that are user variables

First, in order to set the range for user variables, write a Script with codes of "# --BeginUserVariable ~ # --EndUserVariable".
Variables defined within the range of "# --BeginUserVariable ~ # --EndUserVariable" will be treated as the user variables in Run the Script from the Script Editor .

To change the Pitch of the Cue, write the following variables in "# --BeginUserVariable ~ # --EndUserVariable".

Cue variables to change the parameter
Variable to set the parameter field name to change
Variable to set the parameter value

Write a Script with a series of contents as follows:

# --BeginUserVariable
VARIABLE_CUE = None
VARIABLE_PARAMETER_NAME = ""
VARIABLE_PARAMETER_VALUE = 0
# --EndUserVariable

Please set the initial value for the defined variable.

Define the information to display in the user variable settings

Define the information to display the defined user variable on the user variable screen.
Write the following with three double quotes (") in the docstring - Variable name, Type, Description before the defined variables.

"""
Variable name:
  type: Variable type
  comment: Description of parameter
"""

There are three types of "type", and the type specified depends on the variable contents.

Types	Description
object	Specifies when the variable is an object
string	Specifies when the variable is a string
number	Specifies when the variable is a value

The Script is written as follows:

# --BeginUserVariable
"""
VARIABLE_CUE:
  type: object
  comment: Cue to change parameter
VARIABLE_PARAMETER_NAME:
  type: string
  comment: Field name of parameter
VARIABLE_PARAMETER_VALUE:
  type: number
  comment: Parameter value
"""
VARIABLE_CUE = None
VARIABLE_PARAMETER_NAME = ""
VARIABLE_PARAMETER_VALUE = 0
# --EndUserVariable

By clicking the "Update" button on the Script Editor toolbar, the user variable information that was written in the "User variable" of the Script Editor will be displayed on the right side of the Script Editor.

Parameter settings to user variable

After displaying the user information set in the Script in the "<b>User Variables</b>" of the Script Editor, set each user variables.
Drag and drop from CRI Atom Craft tree to set in the VARIABLE_CUE .
Set the following values for VARIABLE_PARAMETER_NAME and VARIABLE_PARAMETER_VALUE.

Variable name	Value
VARIABLE_PARAMETER_NAME	Pitch
VARIABLE_PARAMETER_VALUE	100

Click "Apply" to show the contents of "User variables" of the Script Editor in the Script.

Use the defined "User variable" to update the Cue parameter

You can use the user variable function to set the user variable value.
Use this user variable to update the Cue parameter.
Write a Script to update the Cue parameter as follows:

acproject.set_value(VARIABLE_CUE, VARIABLE_PARAMETER_NAME, VARIABLE_PARAMETER_VALUE)
 
acdebug.log ("[Tutorial] Cue "Pitch" parameter change completed using user variables")

Saving and running the Script

This concludes the scripting portion of this tutorial.
Save and run the Script.
If the Script runs successfully, it will update the Cue Pitch value to the value set in the user variable dialog as shown below.

This tutorial has introduced a Script that uses user variable functions to change the pitch of Cue.
You can specify this Script target as Track and other objects instead of Cues.
Also, parameter names other than "Pitch" can be specified.
You may edit the Script to test for different effects.