Synthesizer V Studio Scripting Manual

https://resource.dreamtonics.com/scripting/
Admin
Synthesizer V Studio 2 Pro supports scripting, allowing users to extend editor functionality with...
Tokens:42,194
Snippets:452
Trust Score:9.5
Update:4 months ago
Show doc for...
Tokens:
Raw
### Toy Example: Selected Note Counter

Source: https://resource.dreamtonics.com/scripting/tutorial-Custom%20Side%20Panel%20Sections.html

A complete example of a side panel section that counts selected notes and provides a button to set their lyrics. It demonstrates client info, widget creation, event handling, and UI layout.

```javascript
var SCRIPT_TITLE = "Selected Note Counter";

function getClientInfo() {
  return {
    "name": SCRIPT_TITLE,
    "category": "Utilities",
    "author": "Dreamtonics",
    "versionNumber": 1,
    "minEditorVersion": 131330,
    "type": "SidePanelSection"
  };
}

var countValue = SV.create("WidgetValue");
var setLyricsButtonValue = SV.create("WidgetValue");

countValue.setValue("0 notes selected");
countValue.setEnabled(false);

function updateSelectionCount() {
  var selection = SV.getMainEditor().getSelection();
  var selectedNotes = selection.getSelectedNotes();
  var count = selectedNotes.length;

  countValue.setValue(count + " note" + (count === 1 ? "" : "s") + " selected");
  setLyricsButtonValue.setEnabled(count > 0);
}

setLyricsButtonValue.setValueChangeCallback(function() {
  var selection = SV.getMainEditor().getSelection();
  var selectedNotes = selection.getSelectedNotes();

  if(selectedNotes.length === 0) return;

  SV.getProject().newUndoRecord();

  for(var i = 0; i < selectedNotes.length; i ++) {
    selectedNotes[i].setLyrics("a");
  }
});

// Register selection callbacks to update count automatically
SV.getMainEditor().getSelection().registerSelectionCallback(function(selectionType, isSelected) {
  if(selectionType == "note") {
    updateSelectionCount();
  }
});

SV.getMainEditor().getSelection().registerClearCallback(function(selectionType) {
  if(selectionType == "notes") {
    updateSelectionCount();
  }
});

// Initialize
updateSelectionCount();

function getSidePanelSectionState() {
  return {
    "title": SCRIPT_TITLE,
    "rows": [
      {
        "type": "Label",
        "text": "Selection:"
      },
      {
        "type": "Container",
        "columns": [
          {
            "type": "TextBox",
            "value": countValue,
            "width": 1.0
          }
        ]
      },
      {
        "type": "Container",
        "columns": [
          {
            "type": "Button",
            "text": "Set lyrics to 'a'",
            "value": setLyricsButtonValue,
            "width": 1.0
          }
        ]
      }
    ]
  };
}
```

--------------------------------

### PlaybackControl.play

Source: https://resource.dreamtonics.com/scripting/PlaybackControl.html

Starts audio playback.

```APIDOC
## play()

### Description
Start playing audio.
```

--------------------------------

### Lua Method Call Example

Source: https://resource.dreamtonics.com/scripting/index.html

Illustrates the metatable-based method calling convention in Lua.

```lua
Class:Method(...)
```

--------------------------------

### Lua Note Access Example

Source: https://resource.dreamtonics.com/scripting/index.html

Demonstrates accessing the first note within a NoteGroup using one-based indexing in Lua.

```lua
NoteGroup:getNote(1)
```

--------------------------------

### JavaScript Method Call Example

Source: https://resource.dreamtonics.com/scripting/index.html

Illustrates the prototype-based method calling convention in JavaScript.

```javascript
Class.Method(...)
```

--------------------------------

### PlaybackControl.loop

Source: https://resource.dreamtonics.com/scripting/PlaybackControl.html

Starts looping playback between the specified start and end times in seconds.

```APIDOC
## loop(tBegin, tEnd)

### Description
Start looping between `tBegin` and `tEnd` in seconds.

### Parameters:
#### Path Parameters
- **tBegin** (number) - Required - The start time for the loop in seconds.
- **tEnd** (number) - Required - The end time for the loop in seconds.
```

--------------------------------

### JavaScript Note Access Example

Source: https://resource.dreamtonics.com/scripting/index.html

Demonstrates accessing the first note within a NoteGroup using zero-based indexing in JavaScript.

```javascript
NoteGroup.getNote(0)
```

--------------------------------

### setOnset(t)

Source: https://resource.dreamtonics.com/scripting/Note.html

Moves the note to start at a specified time `t` (in blicks) without altering its duration.

```APIDOC
## setOnset(t)

### Description
Move the note to start at `t`. The unit is blicks. This does not change the duration.

### Parameters:

#### Path Parameters
*   **t** (number) - Required - The new onset time in blicks
```

--------------------------------

### Lua Member Access Example

Source: https://resource.dreamtonics.com/scripting/index.html

Shows how member objects are accessed using dot notation in Lua, even with metatable-based method calls.

```lua
SV.QUARTER
```

--------------------------------

### Move Note Onset

Source: https://resource.dreamtonics.com/scripting/Note.html

Adjust the start time of a note to a new value in blicks without altering its duration.

```javascript
note.setOnset(200);
```

--------------------------------

### setTimeRange(onset, duration)

Source: https://resource.dreamtonics.com/scripting/NoteGroupReference.html

Defines the absolute onset and duration for this group, independent of its time offset. This method can be used to adjust the start and end points of the group.

```APIDOC
## setTimeRange(onset, duration)

### Description
Set the absolute onset and duration of a group. This does not affect the time offset and can be used to shorten or extend a group from either left or right.
(supported since 2.1.0)

### Method
N/A (Method signature provided)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **onset** (number) - Required - The absolute onset time.
- **duration** (number) - Required - The duration of the group.

### Request Example
N/A

### Response
N/A (No return value specified)

### Response Example
N/A
```

--------------------------------

### newUndoRecord

Source: https://resource.dreamtonics.com/scripting/Project.html

Adds a new undo record for the Project. Edits after this record will be undone/redone together. An undo record is automatically added at the start of script execution.

```APIDOC
## newUndoRecord()

### Description
Adds a new undo record for this `Project`. This means that all edits following the last undo record will be undone/redone together when the users press `Ctrl + Z` or `Ctrl + Y`. A new undo record is automatically added to the currently open project at the beginning of script execution.

### Method
newUndoRecord
```

--------------------------------

### getIndexInParent()

Source: https://resource.dreamtonics.com/scripting/ArrangementSelectionState.html

Gets the index of the current object within its parent. Indexing starts from 1 in Lua and 0 in JavaScript.

```APIDOC
## getIndexInParent()

### Description
Get index of the current object in its parent. In Lua, this index starts from 1. In JavaScript, this index starts from 0.

### Method
N/A (This is a method of an object)

### Returns
- **number**: The index of the object in its parent.
```

--------------------------------

### Create and Initialize WidgetValue

Source: https://resource.dreamtonics.com/scripting/tutorial-Custom%20Side%20Panel%20Sections.html

Demonstrates how to create a WidgetValue object, initialize its value, and enable/disable it. Includes setting up a callback for value changes.

```javascript
var myValue = SV.create("WidgetValue");
myValue.setValue(0);  // Initialize
myValue.setEnabled(true);  // Enable/disable the widget

// React to changes
myValue.setValueChangeCallback(function(newValue) {
  // Handle value change
});
```

--------------------------------

### getIndexInParent()

Source: https://resource.dreamtonics.com/scripting/TrackMixer.html

Gets the index of the current TrackMixer object within its parent. Indexing starts from 1 in Lua and 0 in JavaScript.

```APIDOC
## getIndexInParent()

### Description
Get index of the current object in its parent. In Lua, this index starts from 1. In JavaScript, this index starts from 0.

### Method
N/A (This is a method call, not an HTTP request)

### Parameters
None

### Returns
- **index** (number) - The index of the object in its parent.
```

--------------------------------

### PlaybackControl.getPlayhead

Source: https://resource.dreamtonics.com/scripting/PlaybackControl.html

Gets the current playhead position in seconds. This can be used with the project's TimeAxis to get the position in blicks.

```APIDOC
## getPlayhead()

### Description
Get the current playhead position in seconds. To get the position in blicks, use this with the current project's `TimeAxis`.

### Returns:
- **number**: The current playhead position in seconds.
```

--------------------------------

### Button Widget Configuration

Source: https://resource.dreamtonics.com/scripting/tutorial-Custom%20Side%20Panel%20Sections.html

Sets up a clickable Button widget. The value is primarily for callbacks and state management. Demonstrates how to handle button clicks with a message box.

```javascript
// The value inside isn't important.
// It is created only for receiving callbacks and setting enabled/disabled states.
var buttonValue = SV.create("WidgetValue");
buttonValue.setValueChangeCallback(function() {
  // Button clicked
  SV.showMessageBox("Info", "Button pressed!");
});

{
  "type": "Button",
  "text": "Click Me",
  "value": buttonValue,
}
```

--------------------------------

### PlaybackControl.stop

Source: https://resource.dreamtonics.com/scripting/PlaybackControl.html

Stops audio playback and resets the playhead to the starting position.

```APIDOC
## stop()

### Description
Stop playing and reset the playhead to where the playback started.
```

--------------------------------

### getHostInfo

Source: https://resource.dreamtonics.com/scripting/SV.html

Fetches system and host information, including operating system type and name, host name (e.g., Synthesizer V Studio Pro/Basic), host version, and the language code for the UI.

```APIDOC
## getHostInfo()

### Description
Get an object with the following properties.

### Returns
Type: object
Properties:
- **osType**: string - taking one of "Windows", "macOS", "Linux", "Unknown"
- **osName**: string - the full name of the operating system
- **hostName**: string - "Synthesizer V Studio Pro" or "Synthesizer V Studio Basic"
- **hostVersion**: string - the version string of Synthesizer V Studio e.g. "1.0.4"
- **hostVersionNumber**: number - the version number defined as taking major, minor and revision as 2-digit hexadecimals (e.g. 0x010004 for "1.0.4")
- **languageCode**: string - language code for the UI, e.g. "en-us", "ja-jp", "zh-cn"
```

--------------------------------

### getValueAt(time)

Source: https://resource.dreamtonics.com/scripting/PitchControlCurve.html

Gets the interpolated pitch value at a specific time position, in semitones.

```APIDOC
## getValueAt(time)

### Description
Gets the interpolated pitch value at a specific time position. Returns the pitch offset in semitones at the given time, interpolated from the curve's control points.

### Method
N/A (Method call)

### Parameters
#### Path Parameters
- **time** (number) - Required - Time in blicks relative to the curve's position

### Returns
#### Success Response
- **number** (number) - Pitch offset in semitones.
```

--------------------------------

### CheckBox Widget Configuration

Source: https://resource.dreamtonics.com/scripting/tutorial-Custom%20Side%20Panel%20Sections.html

Sets up a CheckBox widget for boolean toggling. Shows how to set an initial boolean value.

```javascript
var checkValue = SV.create("WidgetValue");
checkValue.setValue(true);

{
  "type": "CheckBox",
  "text": "Apply this to all notes in the group",
  "value": checkValue,
}
```

--------------------------------

### SV.create

Source: https://resource.dreamtonics.com/scripting/SV.html

Creates a new object of a specified type.

```APIDOC
## SV.create(type)

### Description
Create a new object. `type` can be one of the following type-specifying strings.
`type` | Description  
---|---
`"Note"` | A note defined by pitch, lyrics, onset, duration, etc.  
`"Automation"` | A set of points controlling a particular parameter type (e.g. Pitch Deviation) inside a `NoteGroup`.  
`"PitchControlPoint"` | A discrete anchor point for guiding the pitch generation inside a `NoteGroup`.  
`"PitchControlCurve"` | A continuous curve for overriding the generated pitch inside a `NoteGroup`.  
`"NoteGroup"` | A set of notes and parameters grouped together for convenient reuse.  
`"NoteGroupReference"` | A reference to a `NoteGroup` with optional time and pitch offset and voice/database properties.  
`"TrackMixer"` | A set of attributes describing the mixer states of a track (e.g. gain, pan, mute, solo).  
`"Track"` | A collection of `NoteGroupReference`.  
`"TimeAxis"` | A project-wide object storing tempo and time signature marks; handles the conversion between physical time and musical time.  
`"Project"` | The largest object to be worked with. Contains `Track`, `TimeAxis`, `NoteGroup`, etc.  
`"WidgetValue"` | A helper object for binding custom UI widgets in the script panel with variables controlled by the script.  

### Method
SV.create

### Parameters
#### Parameters
- **type** (string) - Description: A type-specifying string.  

### Returns
#### Returns
- **object** - Description: 
```

--------------------------------

### SV.T

Source: https://resource.dreamtonics.com/scripting/SV.html

Gets a localized version of the provided text based on the current UI language settings.

```APIDOC
## SV.T(text)

### Description
Gets a localized version of `text` based on the current UI language settings.
See Localization for more information.

### Method
SV.T

### Parameters
#### Parameters
- **text** (string) - Description: 

### Returns
#### Returns
- **string** - Description: 
```

--------------------------------

### PlaybackControl.getIndexInParent

Source: https://resource.dreamtonics.com/scripting/PlaybackControl.html

Gets the index of the current object within its parent. The index is 1-based in Lua and 0-based in JavaScript.

```APIDOC
## getIndexInParent()

### Description
Get index of the current object in its parent. In Lua, this index starts from 1. In JavaScript, this index starts from 0.

### Returns:
- **number**: The index of the object in its parent.
```

--------------------------------

### CoordinateSystem Methods

Source: https://resource.dreamtonics.com/scripting/CoordinateSystem.html

This section details the methods available on the CoordinateSystem object for interacting with its state and performing conversions.

```APIDOC
## CoordinateSystem Methods

### getIndexInParent()

Get index of the current object in its parent. In Lua, this index starts from 1. In JavaScript, this index starts from 0.

*   **Returns:**
    *   Type: `number`

### getParent()

Get the parent `NestedObject`. Return `undefined` if the current object is not attached to a parent.

*   **Returns:**
    *   Type: `NestedObject | undefined`

### getTimePxPerUnit()

Get the scaling factor in the horizontal direction. The unit is pixels per blick so expect this to be a very small number.

*   **Returns:**
    *   Type: `number`

### getTimeViewRange()

Get the current visible time range. It returns an array with two `number` elements corresponding to the starting time and ending time. The time unit is blicks.

*   **Returns:**
    *   an `array` of `number`
    *   Type: `array`

### getValuePxPerUnit()

Get the scaling factor in the vertical direction. For the piano roll, the unit is pixels per semitone.

*   **Returns:**
    *   Type: `number`

### getValueViewRange()

Get the current visible value range. It returns an array with two `number` elements corresponding to the lower value and upper value. For the piano roll, the unit is MIDI number (semitones); for arrangement view, its value bears no meaning.

*   **Returns:**
    *   an `array` of `number`
    *   Type: `array`

### isMemoryManaged()

Check whether or not the current object is memory managed (i.e. garbage collected by the script environment).

*   **Returns:**
    *   Type: `boolean`

### setTimeLeft(time)

Move the visible area so the left end is at `time`.

*   **Parameters:**
    *   `time` (number) - 

### setTimeRight(time)

Move the visible area so the right end is at `time`.

*   **Parameters:**
    *   `time` (number) - 

### setTimeScale(scale)

Set the horizontal scaling factor to `scale`. The unit is pixels per blick so it expects a very small number.

*   **Parameters:**
    *   `scale` (number) - 

### setValueCenter(v)

Move the visible area so the vertical center is at `v`.

*   **Parameters:**
    *   `v` (number) - 

### snap(b)

Round a time position `b` based on snapping settings.

*   **Parameters:**
    *   `b` (number) - 
*   **Returns:**
    *   Type: `number`

### t2x(t)

Convert a time position to an x-position (pixels).

*   **Parameters:**
    *   `t` (number) - 
*   **Returns:**
    *   Type: `number`

### v2y(v)

Convert a value to a y-position (pixels).

*   **Parameters:**
    *   `v` (number) - 
*   **Returns:**
    *   Type: `number`

### x2t(x)

Convert an x-position (pixels) to a time position.

*   **Parameters:**
    *   `x` (number) - 
*   **Returns:**
    *   Type: `number`

### y2v(y)

Convert a y-position (pixels) to a value.

*   **Parameters:**
    *   `y` (number) - 
*   **Returns:**
    *   Type: `number`
```

--------------------------------

### getHostClipboard

Source: https://resource.dreamtonics.com/scripting/SV.html

Retrieves the text content currently stored on the system clipboard.

```APIDOC
## getHostClipboard()

### Description
Get the text on the system clipboard.

### Returns
Type: string
```

--------------------------------

### Creating Side-by-Side Widgets with Columns

Source: https://resource.dreamtonics.com/scripting/tutorial-Custom%20Side%20Panel%20Sections.html

Shows how to use a Container widget with a `columns` array to arrange multiple widgets horizontally, specifying their relative widths.

```javascript
{
  "type": "Container",
  "columns": [
    {
      "type": "Button",
      "text": "Left",
      "value": leftButtonValue,
      "width": 0.3  // Takes 30% of width
    },
    {
      "type": "Button",
      "text": "Right",
      "value": rightButtonValue,
      "width": 0.7  // Takes 70% of width
    }
  ]
}
```

--------------------------------

### getIndexInParent()

Source: https://resource.dreamtonics.com/scripting/PitchControlCurve.html

Retrieves the index of the current object within its parent. Indices start from 1 in Lua and 0 in JavaScript.

```APIDOC
## getIndexInParent()

### Description
Retrieves the index of the current object within its parent. Indices start from 1 in Lua and 0 in JavaScript.

### Method
N/A (Method call)

### Parameters
None

### Returns
#### Success Response
- **number** (number) - The index of the object in its parent.
```

--------------------------------

### setHostClipboard

Source: https://resource.dreamtonics.com/scripting/SV.html

Sets the system clipboard to the provided text. This allows scripts to interact with the user's clipboard.

```APIDOC
## setHostClipboard

### Description
Set the system clipboard.

### Parameters:
#### Parameters:
- **text** (string) - The text to set to the system clipboard.
```

--------------------------------

### hasUnfinishedEdits()

Source: https://resource.dreamtonics.com/scripting/SelectionStateBase.html

Checks if there are any unfinished edits on the selected objects. This is true if, for example, the user is dragging objects but has not yet released the mouse.

```APIDOC
## hasUnfinishedEdits()

### Description
Checks if there are any unfinished edits on the selected objects. For example, this will return true if the user is dragging around a few notes/control points but has not yet released the mouse.

### Method
N/A (SDK Method)

### Returns:
- **boolean**: True if there are unfinished edits, false otherwise.
```

--------------------------------

### Note Methods

Source: https://resource.dreamtonics.com/scripting/Note.html

This section details the methods available for interacting with a Note object, allowing retrieval and manipulation of its musical properties.

```APIDOC
## clearScriptData()

### Description
Remove all script data from the object's storage. Use with caution as this could also remove data created by other scripts.

### Method
clearScriptData()

### Inherited From
ScriptableNestedObject#clearScriptData

## clone()

### Description
Creates a deep copy of the current Note object.

### Method
clone()

### Returns
Type: Note

## getAttributes()

### Description
Retrieves an object containing various properties of the note, including rap tone, intonation, pitch vibrato modulation, expression pad parameters, phoneme attributes, mute status, syllable duration splitting, and language/phoneset overrides.

### Method
getAttributes()

### Returns
Type: object
Properties:
- `rTone` (number) rap - tone (since 1.9.0b2)
- `rIntonation` (number) rap - intonation (since 1.9.0b2)
- `dF0VbrMod` (number) pitch - vibrato modulation (since 1.9.0b2)
- `expValueX` (number) expression pad parameter X (since 2.1.1)
- `expValueY` (number) expression pad parameter Y (since 2.1.1)
- `phonemes` (array of objects) for per-phoneme attributes (since 2.1.1)
  - `leftOffset` (number) offset added to the phoneme's left boundary
  - `position` (number) phoneme position
  - `activity` (number) phoneme activity
  - `strength` (number) phoneme pronunciation strength
- `muted` (boolean) whether the note is muted (since 2.1.1)
- `evenSyllableDuration` (boolean) whether to split the note evenly when there are multiple syllables (since 2.1.1)
- `languageOverride` (string) override the group's language setting for this note (since 2.1.1)
- `phonesetOverride` (string) override the group's phoneset setting for this note (since 2.1.1)

Properties only available in version 1:
- `tF0Offset` (number) pitch transition - offset (seconds)
- `tF0Left` (number) pitch transition - duration left (seconds)
- `tF0Right` (number) pitch transition - duration right (seconds)
- `dF0Left` (number) pitch transition - depth left (semitones)
- `dF0Right` (number) pitch transition - depth right (semitones)
- `tF0VbrStart` (number) vibrato - start (seconds)
- `tF0VbrLeft` (number) vibrato - left (seconds)
- `tF0VbrRight` (number) vibrato - right (seconds)
- `dF0Vbr` (number) vibrato - depth (semitones)
- `pF0Vbr` (number) vibrato - phase (radian, from -π to π)
- `fF0Vbr` (number) vibrato - frequency (Hz)
- `tNoteOffset` (number) timing and phonemes - note offset (seconds)
- `exprGroup` (optional) (string) expression group
- `dur` (array of number) for phoneme duration scaling
- `alt` (array of number) for phoneme alternative pronunciation

Note: For numeric properties, the value is NaN if the note uses the default value based on the `NoteGroupReference` it is in.

## getDetune()

### Description
Gets the pitch adjustment in cents. 100 cents equals one semitone. This adjustment is applied on top of the base pitch of the note. (supported since 2.1.1)

### Method
getDetune()

### Returns
Type: number

## getDuration()

### Description
Gets the duration of the note in blicks.

### Method
getDuration()

### Returns
Type: number

## getEnd()

### Description
Gets the end position (start + duration) of the note in blicks.

### Method
getEnd()

### Returns
Type: number

## getIndexInParent()

### Description
Gets the index of the current object in its parent. In Lua, this index starts from 1. In JavaScript, this index starts from 0.

### Method
getIndexInParent()

### Inherited From
NestedObject#getIndexInParent

### Returns
Type: number

## getLanguageOverride()

### Description
Gets the note-specific language. Returns an empty string when the note is using the group/track's default language. (supported since 1.9.0b2)

### Method
getLanguageOverride()

### Returns
Type: string

## getLyrics()

### Description
Gets the lyrics for this note.

### Method
getLyrics()

### Returns
Type: string

## getMusicalType()

### Description
Gets the type of the note ("sing" or "rap"). (supported since 1.9.0b2)

### Method
getMusicalType()

### Returns
Type: string

## getOnset()

### Description
Gets the start position of the note in blicks.

### Method
getOnset()

### Returns
Type: number

## getParent()

### Description
Gets the parent `NestedObject`. Returns `undefined` if the current object is not attached to a parent.

### Method
getParent()

### Inherited From
NestedObject#getParent

### Returns
Type: NestedObject | undefined

## getPhonemes()

### Description
Returns the user-specified phonemes, delimited by spaces. For example, "hh ah ll ow". If there's no phoneme specified, this will return an empty string, instead of the default pronunciation (see `SV#getPhonemesForGroup`).

### Method
getPhonemes()

### Returns
Type: string

## getPitch()

### Description
Gets the pitch as a MIDI number. C4 maps to 60.

### Method
getPitch()

### Returns
Type: number

## getPitchAutoMode()

### Description
Gets the pitch mode of the note: true for auto, false for manual. (supported since 1.9.0b2)

### Method
getPitchAutoMode()

### Returns
Type: boolean

## getRapAccent()

### Description
Gets the accent (if available) for a rap note. (supported since 1.9.0b2)

### Method
getRapAccent()

### Returns
Type: string

```

--------------------------------

### print

Source: https://resource.dreamtonics.com/scripting/SV.html

Prints any number of arguments to the standard output stream. This function is primarily for debugging and requires running Synthesizer V Studio from the command line to view the output.

```APIDOC
## print

### Description
Prints any number of arguments to the standard output stream. This is only useful for debugging your script. To see the output, you need to run Synthesizer V Studio from the command line.
(supported since 2.1.1)

### Parameters:
#### Parameters:
- **args** (any) - repeatable - Arguments to print to standard output.
```

--------------------------------

### Resize Note Duration

Source: https://resource.dreamtonics.com/scripting/Note.html

Change the duration of a note to a new value in blicks. This affects the note's end time but not its start time.

```javascript
note.setDuration(500);
```

--------------------------------

### ComboBox Widget Configuration

Source: https://resource.dreamtonics.com/scripting/tutorial-Custom%20Side%20Panel%20Sections.html

Configures a ComboBox widget for dropdown selection. Shows how to define the available choices and set the initial selected item by its index.

```javascript
var comboValue = SV.create("WidgetValue");
comboValue.setValue(0);  // Index of selected item

{
  "type": "ComboBox",
  "choices": ["Option 1", "Option 2", "Option 3"],
  "value": comboValue,
}
```

--------------------------------

### TextArea Widget Configuration

Source: https://resource.dreamtonics.com/scripting/tutorial-Custom%20Side%20Panel%20Sections.html

Configures a TextArea widget for multi-line text input. Includes setting an initial value and specifying the widget's height in pixels.

```javascript
var textAreaValue = SV.create("WidgetValue");	extAreaValue.setValue("Multi-line\ntext here");

{
  "type": "TextArea",
  "value": textAreaValue,
  "height": 80,      // Height in pixels
}
```

--------------------------------

### getPlayback

Source: https://resource.dreamtonics.com/scripting/SV.html

Returns the UI state object for controlling the playback functionality of Synthesizer V Studio.

```APIDOC
## getPlayback()

### Description
Get the UI state object for controlling the playback.

### Returns
Type: PlayBackControl
```

--------------------------------

### ArrangementView Methods

Source: https://resource.dreamtonics.com/scripting/ArrangementView.html

Provides access to various aspects of the arrangement view, including its index in the parent, coordinate system, selection state, and parent object.

```APIDOC
## getIndexInParent()

### Description
Get index of the current object in its parent. In Lua, this index starts from 1. In JavaScript, this index starts from 0.

### Method
GET

### Endpoint
ArrangementView.getIndexInParent()

### Returns:
- **number**: The index of the object in its parent.
```

```APIDOC
## getNavigation()

### Description
Get the coordinate system for the track arrangement area.

### Method
GET

### Endpoint
ArrangementView.getNavigation()

### Returns:
- **CoordinateSystem**: The coordinate system object for the arrangement area.
```

```APIDOC
## getParent()

### Description
Get the parent `NestedObject`. Return `undefined` if the current object is not attached to a parent.

### Method
GET

### Endpoint
ArrangementView.getParent()

### Returns:
- **NestedObject | undefined**: The parent NestedObject or undefined if it has no parent.
```

```APIDOC
## getSelection()

### Description
Get the selection state object for arrangement view.

### Method
GET

### Endpoint
ArrangementView.getSelection()

### Returns:
- **ArrangementSelectionState**: The selection state object.
```

```APIDOC
## isMemoryManaged()

### Description
Check whether or not the current object is memory managed (i.e. garbage collected by the script environment).

### Method
GET

### Endpoint
ArrangementView.isMemoryManaged()

### Returns:
- **boolean**: True if the object is memory managed, false otherwise.
```

--------------------------------

### TextBox Widget Configuration

Source: https://resource.dreamtonics.com/scripting/tutorial-Custom%20Side%20Panel%20Sections.html

Configures a TextBox widget for single-line text input. Shows initial value setting and the JSON structure for defining the widget.

```javascript
var textValue = SV.create("WidgetValue");
textValue.setValue("initial text");

{
  "type": "TextBox",
  "value": textValue,
}
```

--------------------------------

### getFileName

Source: https://resource.dreamtonics.com/scripting/Project.html

Returns the absolute file system path of the project.

```APIDOC
## getFileName()

### Description
Gets the absolute path of the project on the file system.

### Method
getFileName

### Returns
Type: string - The absolute path of the project.
```

--------------------------------

### showInputBoxAsync

Source: https://resource.dreamtonics.com/scripting/SV.html

Asynchronously displays an input box without blocking script execution. A callback function is invoked upon dialog closure with the user's text input.

```APIDOC
## showInputBoxAsync

### Description
Display a dialog with a text box and an "OK" button, without blocking the script execution. `callback` will be invoked once the dialog is closed. The callback function takes one `string` argument that is the content of the text box.

### Parameters:
#### Parameters:
- **title** (string) - The title of the input box.
- **message** (string) - The message to display in the input box.
- **defaultText** (string) - The default text to pre-fill in the input field.
- **callback** (function) - The function to be called when the dialog is closed.
```

--------------------------------

### Minimal Lua Script

Source: https://resource.dreamtonics.com/scripting/tutorial-A%20Minimal%20Example.html

A basic Lua script for Synthesizer V Studio. It defines script metadata and a main function to display a message.

```lua
function getClientInfo()
  return {
    name = "My Script",
    category = "Example",
    author = "Bob Alice",
    versionNumber = 1,
    minEditorVersion = 65540
  }
end

function main()
  SV:showMessageBox("My Script", "Hello, world!")
  SV:finish()
end
```

--------------------------------

### setSolo(solo)

Source: https://resource.dreamtonics.com/scripting/TrackMixer.html

Sets the solo state of the track. Set to `true` to solo, `false` to unsolo.

```APIDOC
## setSolo(solo)

### Description
Set the solo state of the track.

### Method
N/A (This is a method call, not an HTTP request)

### Parameters
#### Path Parameters
- **solo** (boolean) - Required - True to solo the track, false to unsolo

### Returns
None
```

--------------------------------

### getProject

Source: https://resource.dreamtonics.com/scripting/SV.html

Retrieves the currently open project object, allowing access to project-level data and settings.

```APIDOC
## getProject()

### Description
Get the currently open project.

### Returns
Type: Project
```

--------------------------------

### showOkCancelBoxAsync

Source: https://resource.dreamtonics.com/scripting/SV.html

Displays an asynchronous message box with OK and Cancel buttons. Script execution continues immediately. A callback function is invoked when the box is closed, receiving a boolean indicating if OK was pressed.

```APIDOC
## showOkCancelBoxAsync(title, message, callback)

### Description
Displays an asynchronous message box with OK and Cancel buttons. Script execution is not blocked. A callback function is executed upon closing, receiving a boolean indicating if the OK button was pressed.

### Method
Asynchronous function call

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **title** (string) - Required - The title of the message box.
- **message** (string) - Required - The content message to display in the box.
- **callback** (function) - Required - A function to be called when the message box is closed. It receives one boolean argument: `true` if OK was pressed, `false` otherwise.

### Returns
None (asynchronous operation with callback)
```

--------------------------------

### Slider Widget Configuration

Source: https://resource.dreamtonics.com/scripting/tutorial-Custom%20Side%20Panel%20Sections.html

Configures a Slider widget for numeric input with custom range, interval, and formatting. Shows how to set an initial value and define display format using printf-style strings.

```javascript
var sliderValue = SV.create("WidgetValue");
sliderValue.setValue(3);

{
  "type": "Slider",
  "text": "Volume",
  "format": "%3.1f dB",  // printf-style format string
  "minValue": -6,
  "maxValue": 6,
  "interval": 0.1,
  "value": sliderValue,
}
```

--------------------------------

### setPoints(points)

Source: https://resource.dreamtonics.com/scripting/PitchControlCurve.html

Sets all control points of this pitch control curve. Each point should be an array of [time, value].

```APIDOC
## setPoints(points)

### Description
Sets all control points of this pitch control curve. Each point should be an array of [time, value] where time is in blicks relative to the curve's anchor position and value is the pitch offset from the anchor position in semitones.

### Method
N/A (Method call)

### Parameters
#### Path Parameters
- **points** (Array.<Array.<number>>) - Required - Array of [time, value] pairs
```

--------------------------------

### showInputBox

Source: https://resource.dreamtonics.com/scripting/SV.html

Displays a synchronous input box, blocking script execution until the user provides input and closes the dialog. Returns the text entered by the user.

```APIDOC
## showInputBox

### Description
The synchronous version of `SV#showInputBoxAsync` that blocks the script execution until the user closes the dialog. It returns the text input from the user.

### Parameters:
#### Parameters:
- **title** (string) - The title of the input box.
- **message** (string) - The message to display in the input box.
- **defaultText** (string) - The default text to pre-fill in the input field.

### Returns:
- **string** - The text input from the user.
```

--------------------------------

### Accessing ArrangementSelectionState

Source: https://resource.dreamtonics.com/scripting/ArrangementSelectionState.html

Demonstrates how to access the ArrangementSelectionState object using JavaScript and Lua.

```APIDOC
## Accessing ArrangementSelectionState

To access the `ArrangementSelectionState` object:

### JavaScript
```javascript
SV.getArrangement().getSelection()
```

### Lua
```lua
SV:getArrangement():getSelection()
```
```

--------------------------------

### getNumTracks

Source: https://resource.dreamtonics.com/scripting/Project.html

Returns the total number of tracks in the project.

```APIDOC
## getNumTracks()

### Description
Gets the number of tracks.

### Method
getNumTracks

### Returns
Type: number - The number of tracks.
```

--------------------------------

### Track Methods

Source: https://resource.dreamtonics.com/scripting/Track.html

This section details the various methods available for interacting with a Track object, including managing its note groups, retrieving properties, and handling script data.

```APIDOC
## addGroupReference(group)

### Description
Adds a NoteGroupReference to this Track and returns the index of the added group. It keeps all groups sorted by onset position.

### Method
add

### Parameters
#### Path Parameters
- **group** (NoteGroupReference) - Description: None provided

### Returns
#### Success Response
- **number** - The index of the added group.
```

```APIDOC
## clone()

### Description
Creates a deep copy of the current Track object.

### Method
clone

### Returns
#### Success Response
- **Track** - A deep copy of the Track object.
```

```APIDOC
## getDisplayColor()

### Description
Retrieves the track's color as a hex string.

### Method
getDisplayColor

### Returns
#### Success Response
- **string** - The track's color in hex format.
```

```APIDOC
## getDisplayOrder()

### Description
Gets the display order of the track within its parent Project. This order determines how tracks are displayed in the arrangement view.

### Method
getDisplayOrder

### Returns
#### Success Response
- **number** - The display order of the track.
```

```APIDOC
## getDuration()

### Description
Calculates and returns the duration of the Track in blicks, determined by the ending position of the last NoteGroupReference.

### Method
getDuration

### Returns
#### Success Response
- **number** - The duration of the track in blicks.
```

```APIDOC
## getGroupReference(index)

### Description
Retrieves a specific NoteGroupReference from the track by its index. The first group is always the main group.

### Method
getGroupReference

### Parameters
#### Path Parameters
- **index** (number) - Description: The index of the NoteGroupReference to retrieve.

### Returns
#### Success Response
- **NoteGroupReference** - The requested NoteGroupReference.
```

```APIDOC
## getMixer()

### Description
Retrieves the track's mixer, which allows for adjusting gain, pan, mute, and solo settings. (Supported since version 2.1.1).

### Method
getMixer

### Returns
#### Success Response
- **TrackMixer** - The TrackMixer object for the track.
```

```APIDOC
## getName()

### Description
Gets the name of the track.

### Method
getName

### Returns
#### Success Response
- **string** - The name of the track.
```

```APIDOC
## getNumGroups()

### Description
Returns the total number of NoteGroupReferences in this Track, including the main group.

### Method
getNumGroups

### Returns
#### Success Response
- **number** - The number of group references.
```

```APIDOC
## isBounced()

### Description
Checks if the track is set to be exported to files, as shown in the Render Panel.

### Method
isBounced

### Returns
#### Success Response
- **boolean** - True if the track is set to be bounced, false otherwise.
```

```APIDOC
## removeGroupReference(index)

### Description
Removes the NoteGroupReference at the specified index from this Track.

### Method
removeGroupReference

### Parameters
#### Path Parameters
- **index** (number) - Description: The index of the NoteGroupReference to remove.
```

```APIDOC
## setBounced(enabled)

### Description
Sets whether or not the Track should be exported to files. This corresponds to the `Track#isBounced` property.

### Method
setBounced

### Parameters
#### Path Parameters
- **enabled** (boolean) - Description: Set to true to enable bouncing, false to disable.
```

--------------------------------

### getRetakes()

Source: https://resource.dreamtonics.com/scripting/Note.html

Retrieves the list of retakes for the current note. Retakes enable the generation of different rendering variations by utilizing distinct seeds for duration, pitch, and timbre parameters.

```APIDOC
## getRetakes()

### Description
Get the retake list for this note. Retakes allow generating different rendering variations for the same note by using different seeds for duration, pitch, and timbre parameters.
(supported since 2.1.1)

### Returns:

*   **RetakeList** - The list of retakes for the note.
```

--------------------------------

### showOkCancelBox

Source: https://resource.dreamtonics.com/scripting/SV.html

Displays a synchronous message box with OK and Cancel buttons. The script execution is blocked until the user closes the box. Returns true if the OK button is pressed.

```APIDOC
## showOkCancelBox(title, message)

### Description
Displays a synchronous message box with OK and Cancel buttons, blocking script execution until closed. Returns `true` if the OK button is pressed, otherwise `false`.

### Method
Synchronous function call

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **title** (string) - Required - The title of the message box.
- **message** (string) - Required - The content message to display in the box.

### Returns
- **boolean** - `true` if the OK button is pressed, `false` otherwise.
```

--------------------------------

### showCustomDialog

Source: https://resource.dreamtonics.com/scripting/SV.html

Displays a custom dialog synchronously, blocking script execution until the user closes it. Returns the user's input from the completed form.

```APIDOC
## showCustomDialog

### Description
The synchronous version of `SV#showCustomDialogAsync` that blocks the script execution until the user closes the dialog. It returns the inputs (the completed form) from the user.

### Parameters:
#### Parameters:
- **form** (object) - The custom dialog form definition.

### Returns:
- **object** - The user's input from the completed form.
```

--------------------------------

### generateTake(newDuration, newPitch, newTimbre)

Source: https://resource.dreamtonics.com/scripting/RetakeList.html

Generates a new retake with specified variation parameters and returns its ID. The parameters control whether to generate new duration, pitch, or timbre variations.

```APIDOC
## generateTake(newDuration, newPitch, newTimbre) → {number}

### Description
Generate a new retake with the specified variation parameters. Returns the ID of the newly generated retake.

### Method
N/A (Method call)

### Parameters
#### Path Parameters
- **newDuration** (boolean) - Required - whether to generate new duration variation
- **newPitch** (boolean) - Required - whether to generate new pitch variation
- **newTimbre** (boolean) - Required - whether to generate new timbre variation

### Returns
#### Success Response
- **return value** (number) - the ID of the newly generated retake
```

--------------------------------

### Automation Methods

Source: https://resource.dreamtonics.com/scripting/Automation.html

Provides methods for interacting with automation control points, including adding, retrieving, and managing points and their definitions.

```APIDOC
## Automation Methods

### Description
Provides methods for interacting with automation control points, including adding, retrieving, and managing points and their definitions.

### Methods

#### add(b, v) 
Adds a control point with a specified position and parameter value. Updates the value if a point already exists at the position.

*   **Parameters**:
    *   `b` (number): The position of the control point in blicks.
    *   `v` (number): The parameter value for the control point.
*   **Returns**: boolean - True if a new point was created.

#### clearScriptData()
Removes all script data associated with this automation object.

#### clone()
Creates a deep copy of the current Automation object.

*   **Returns**: Automation - A new Automation object that is a deep copy of the original.

#### get(b)
Retrieves the interpolated parameter value at a specific position.

*   **Parameters**:
    *   `b` (number): The position in blicks at which to retrieve the value.
*   **Returns**: number - The interpolated parameter value.

#### getAllPoints()
Retrieves all control points for this automation object across the entire range.

*   **Returns**: array - An array of control points, where each point is an array of [position, value].

#### getDefinition()
Retrieves the definition of the parameter type being automated.

*   **Returns**: object - An object containing `displayName`, `typeName`, `range`, and `defaultValue`.

#### getIndexInParent()
Gets the index of this object within its parent.

*   **Returns**: number - The index of the object.

#### getInterpolationMethod()
Returns the current interpolation method used between control points.

*   **Returns**: string - The interpolation method ('Linear', 'Cosine', or 'Cubic').

#### getLinear(b)
Retrieves the parameter value at a specific position using linear interpolation, regardless of the set interpolation method.

*   **Parameters**:
    *   `b` (number): The position in blicks.
*   **Returns**: number - The parameter value interpolated linearly.

#### getParent()
Retrieves the parent object.

*   **Returns**: NestedObject | undefined - The parent object or undefined if it has no parent.

#### getPoints(begin, end)
Retrieves control points within a specified range.

*   **Parameters**:
    *   `begin` (number): The starting position in blicks.
    *   `end` (number): The ending position in blicks.
*   **Returns**: array - An array of control points within the specified range.

#### getScriptData(key)
Retrieves a script data value by its key.

*   **Parameters**:
    *   `key` (string): The key of the script data to retrieve.
*   **Returns**: any - The stored script data value or undefined if the key does not exist.

#### getScriptDataKeys()
Retrieves all keys stored in the script data.

*   **Returns**: Array.<string> - An array of all script data keys.

#### getType()
Gets the parameter type of this automation object.

*   **Returns**: string - The parameter type name.
```

--------------------------------

### Minimal JavaScript Script

Source: https://resource.dreamtonics.com/scripting/tutorial-A%20Minimal%20Example.html

A basic JavaScript script for Synthesizer V Studio. It defines script metadata and a main function to display a message.

```javascript
function getClientInfo() {
  return {
    "name" : "My Script",
    "category" : "Example",
    "author" : "Bob Alice",
    "versionNumber" : 1,
    "minEditorVersion" : 65540
  };
}

function main() {
  SV.showMessageBox("My Script", "Hello, world!");
  SV.finish();
}
```

--------------------------------

### Basic Side Panel Section Structure

Source: https://resource.dreamtonics.com/scripting/tutorial-Custom%20Side%20Panel%20Sections.html

Defines the essential `getClientInfo` and `getSidePanelSectionState` functions required for a side panel section script. Ensure `minEditorVersion` is set to 131330 or higher.

```javascript
function getClientInfo() {
  return {
    "name": "My Panel",
    "category": "Utilities",
    "author": "Your Name",
    "versionNumber": 1,
    "minEditorVersion": 131330,
    "type": "SidePanelSection"
  };
}

function getSidePanelSectionState() {
  return {
    "title": "My Panel",
    "rows": [
      // UI widgets defined here
    ]
  };
}
```
Tokens:
Raw