ArtSong Scripting

Scripting has been added in ArtSong 6 to provide advanced algorithmic and experimental composers with a powerful, flexible, general-purpose solution to any custom compositional-process need. Scripts can be used for:

1. composing,
2. filtering and selecting events for editing,
3. editing,
4. performing musical analyses,
5. implementing custom algorithms.

ArtSong supports both Pascal and Basic language scripts with complete script development and runtime environments. This includes syntax-sensitive source-code editors with keyword highlighting, integrated debugging, and a large library of built-in objects and functions.

The library of built-in objects includes extensive facilities for building event-driven graphical user interfaces. Although provided for custom input forms, you can actually ‘script’ entire custom algorithmic composition ‘programs’ within the ArtSong scripting environment to take advantage of existing ArtSong facilities for playing and saving your compositions!

For best results we recommend that you browse these scripting informative materials before starting the Tutorials.

Script Editors

Scripts are ‘written’ in a script editor. Language specific script editors for both Pascal and Basic are provided in the Pascal and Basic scripting algorithms respectively. This algorithms can be found on the ‘General’ tab of the Algorithms Palette. Both scripting editors share a similar user interface:

• A top button bar for saving, loading, running, and debugging scripts,
• A large central text area for entering and editing scripts,
• A list of registered composition variables that can be assigned to a custom script algorithm,
• A list of Library files that can be included,
• A bottom console panel for displaying messages generated by the script.

Important Short Cuts

ESC (Escape Key) – Aborts current script execution.

Ctrl-Shift – Toggles on / off playing the current sequence

New: Clears the current script and creates a new blank script

Load: Opens a file dialog window for loading a previously saved script

Save: Opens a file dialog window for saving the current script

Run: Compiles and executes the current script

Debug: Compiles and starts the debugger and sets the current execution point at the first executable line of code. Activates the debugging tools

Debugging Tools: A set of tools for setting up ‘breakpoints’ stepping through the code and setting up ‘watched variables’.

Breakpoints: Breaks points can be toggled at the current executable line by clicking the ‘Toggle Break point’ tool button or clicking in the ‘Line Number’ area of the script editor.

Script execution will stop at breakpoints.

Watches

Adds a variable to the watched variables list.

Watch variables allow you to view changes to the values of particular variables during the execution of the script.

Displays the current list of watched variables.

Watch Window Short Cuts

• INSERT – Add a new watched variable
• DELETE – Remove the selected watched variable
• ENTER – Edit the selected watched variable
• ESCAPE – Close the watch window

Script Functionality

Writing scripts involves harnessing functionality from three separate sources:

1. The language implementation provides the standard constructs for declaring variables, making decisions, defining loops, defining functions, controlling the flow of script execution. The sections on Pascal and Basic Syntax in this Help file covers language implementation.
2. ArtSong’s Music Object Model provides an interface between the script engine and ArtSong’s composition engine, tracks, and note events, etc. This includes several special script functions that are called by the composition engine during the composition process and special script objects used to represent the underlying ArtSong track components and note events. This model is discussed in the Help file section on the Music Objects Model.
3. External libraries provide numerous objects and functions for creating graphical user interfaces (GUI). ArtSong provides script access to most of the same underlying library that ArtSong uses for GUIs: Borland®’s Visual Component Library™. Currently this is covered primarily in script examples; an introductory-level book on Object Pascal will be helpful.

Script Structure

All scripts consist of two principal code blocks, or code sections: a MAIN section and a FUNCTIONS section. Both sections are optional, but at least one should be present in script. When both sections are present in a script the FUNCTIONS section must precede the MAIN section. The two sections are described below:

BEGIN SCRIPT

FUNCTIONS Section – defines functions (subroutines, procedures) that can be called from either the MAIN section, other functions in the FUNCTIONS section, or from the composition engine.

MAIN Section – contains any necessary code that must be run each time the script is executed, such as setups or initializations. Script execution always begins with the MAIN section.

END SCRIPT

Each time a script is run, by clicking on the Run, Debug, or Compose button, the script is compiled and execution begins in the MAIN code section. Execution continues through the MAIN code section until it is exited.

Functions defined in the FUNCTIONS section of the compiled script remain active in the scripting engine even after the MAIN code section finishes execution. These subroutines or procedures remain accessible to the ArtSong composition engine.

Running Scripts

Scripts can be run ‘immediately’ or in conjunction with the composition engine. The method you chose will depend on your objectives.

• Whenever you click on the Run (or Debug) button in a script editor the script will be immediately compiled and executed. If script errors are encountered during compiling the message will be displayed in a pop up window and in the Console window. If a compile error occurs, no further compilation will take place and the script will not be executed.
• When you click on the main screen’s Compose button the sequence of events is different.
  • Whenever the Compose button is clicked:
    • A composition initialization function (BeforeCompose) is executed for each project component in hierarchical order. During the initialization of track components all current events within the composition time span are erased.
    • A compose function (Compose) is executed for each project component in hierarchical order, for each increment in composition time.
    • After the composition time reaches the specified end-time a composition cleanup function (AfterCompose) is executed for each project component in hierarchical order.
• Script algorithms are processed in normal project component hierarchical order. The script will be compiled and executed during the scripting component’s composition ‘initialization’ phase. Any defined composition engine hook functions will be called as described in item 1 above.

Note: If track events are being generated tracks from a script these events will end up being erased as each track is initialized. You can prevent this erasure by setting a track’s composition mode to ‘off’ (click on track’s instrument panel from General Project Editor) so the composition engine will ignore the track.