Synthesizer V Studio Scripting Manual

English | 日本語

Synthesizer V Studio Pro supports scripting. Users can add new features to the editor with their own scripts.

The idea of scripting is similar to a plugin system but instead of loading dynamically linked objects (e.g. .dll), Synthesizer V Studio loads scripts in the source code form. Therefore a text editor is all what's needed for developing scripts. Once written, the scripts are portable across all platforms Synthesizer V Studio supports (Windows, Linux and macOS).

Supported Languages

• JavaScript (ECMAScript 5.1, powered by Duktape)
• Lua 5.4 (the official implementation)

Capabilities

What is possible with scripting?

• Read, add, edit and remove notes/groups/parameters/tracks...
• Access and modify the current selection (of notes and groups)
• Navigate across the project (e.g. scroll and zoom onto a certain range)
• Control the playback
• Interact with the user via customizable dialogs
• Asynchronous callback capabilities (e.g. call SV#setTimeout to delay the execution of a function)
  • This means that a script can run in the background for as long as possible.

How to get started

• Look at the A Minimal Example.
• Here is a more advanced example.
• Learn from the test scripts.
• If you don't understand, check the class reference.
• Use Localization in your scripts and go international.
• Advanced users: understand Memory Management.

Programming Concepts

Synthesizer V Studio's scripting API is object-oriented. JavaScript and Lua scripts share the same API, albeit with slightly different calling conventions (see next section).

There are two types of objects the user can interact with: data objects and UI state objects.

• Data objects are parts of a project that can be tracks, notes, parameters ..., and you may already be familiar with these if you have worked with similar scriptable software.
• UI state objects are more interesting. They are an abstraction of the user interface. For example, a PlaybackControl object manages play, pause, loop and seek behaviors.

Differences from VOCALOID Job Plugins

Yamaha's VOCALOID also supports Lua scripting ("Job Plugin"). The scripts for VOCALOID are not compatible with Synthesizer V Studio. The main differences are

• In Job Plugin all APIs are exposed as global function; in Synthesizer V Studio API the only global object is the host object SV and most interactions with the data structure are through methods of the data types.
• Job Plugin API uses an event-based data model. For example, notes must be accessed sequentially. Synthesizer V Studio API provides random access to notes, parameters, groups and tracks.

Important Differences between JavaScript and Lua

Indexing

JavaScript uses zero-based indexing and Lua uses one-based indexing. This also applies to the scripting API.

For example, NoteGroup.getNote(0) in JavaScript is the same as NoteGroup:getNote(1) in Lua.

Calling methods

Object-oriented programming is prototype-based in JavaScript API, which means the calling convention is Class.Method(...).

The Lua API is based on metatable, and the calling convention is Class:Method(...).

However, member objects are still accessed with dot even in Lua (e.g. SV#QUARTER).