FinaleScript plug-in

 

How to get there

From the Menu, choose Miscellaneous, and then FinaleScript Palette.

What it does

The FinaleScript Plug-in, created by Robert Piéchaud, is Finale's integrated scripting utility, which allows you to specify and execute a series of commands in order to automate repetitive tasks. For example, instead of opening, changing the spacing, transposing, and adjusting the layout manually, this plug-in allows you to run all of these commands in succession, accomplishing simple or complicated procedures instantly.

Use FinaleScript to automate repetitive tasks, create customized pseudo-plug-ins, and even apply changes to several documents at once using the commands listed in this section. This powerful utility essentially opens up a new world of editing capability. The potential of this plug-in is only limited by the available commands and your own imagination. Every Finale menu and virtually all dialog box settings are accessible through FinaleScript.

The instructions in this section guide you through creating a new script and a list of the available commands follows. Commands can either be written into a script or entered directly into the "Command Line" text box. Press the play button to run the script or command. Alternatively, you can choose scripts from the Finale Script submenu, or run it using a keyboard shortcut you have assigned to it.

Choose a Script and click the View Current Script button to see examples. To familiarize yourself with this utility, you will find pre-defined scripts in the FinaleScript Palette a helpful reference. You can also refer to the Command Reminder script that lists all of the commands.

Here is a description of the FinaleScript Palette's interface:

 

 Contextual menus

Contextual menus are reached by control-clicking a script in the FinaleScript 2.0 palette. A contextual menu will be displayed where you can select various items.

 

Menu item

What it does

Edit

Opens the script in the FinaleScript - Editor dialog box

Edit keyboard shortcut

Opens the FinaleScript - Shortcut Editor dialog box where you can assign the script to a different keyboard shortcut

Run

Runs the selected script

Rename

Opens the FinaleScript - Rename dialog box where you can rename the script

Duplicate

Duplicates the selected script

Insert new script

Inserts a new "Untitled" script to the script list

Insert new folder

Adds a new folder to the script list

Delete

Deletes the script

Help

Opens the FinaleScript Help Topic of the Finale User Manual

 

To Create a New Script

FinaleScript Commands

FinaleScript allows you to call any menu item and virtually any dialog box command. Commands can be entered into the either the text box at the bottom of the FinaleScript dialog box, or within the FinaleScript Editor dialog box.

Invoking a menu item, dialog command, or plug-in is completely independent from case, punctuation, dash, line feed, carriage return, etc.

Script examples are indicated by yellow highlighting

 

Command explanations are indicated with green highlighting

"//" can always be used to indicate a comment, which will be ignored by FinaleScript.

//FinaleScript will ignore this text

As you enter, you will notice the script language you enter is colored automatically based on its function. See Script Syntax Coloring for details.

Menu Scripting commands

You can call any menu item using the full hierarchical specification...

menu item "File/New/Exercise Wizard"

But, the full specification is not required. Alternatively, you could type:

menu item "exercise wizard" //or

plug-in "apply human playback"

Also, you can activate or deactivate menu settings...

check/uncheck menu item "display in concert pitch"

As a shortcut, you can use the truncation character ‘*’ or ‘%’ for long menu item names. For example:

menu item "compile*" //instead of "compile postscript listing"

plugin "band in a box*" //instead of "band in a box auto-harmonizing"

Dialog Box Scripting Commands

Buttons:

Buttons in dialog boxes can be invoked using the following FinaleScript commands:

button "ok" //preferred

press "ok" //preferred

hit "ok" //same

hit ok //same 

strike "ok" //fine

click "ok" //not recommended (potential ambiguity with other controls with same name)

hit "cancel" //same

hit cancel //same

The most common types of buttons do not require quotes, including ok, cancel, save, delete, set font, and select. The other buttons do require quotes.

 

Note that only text-based buttons are scriptable, unless a tab/click workaround is used (see mouse clicks below).

 

When several buttons with same text are displayed in a dialog box, you must specify the desired button by adding a ‘neighborhood specifier' to the command. For example, in the Edit Staff Attributes dialog box, there are 5 different Select buttons. Use the following neighborhood specifiers to indicate which one you want to call...

staff tool //to select the Staff Tool

menu item "edit staff attributes" //to open the Staff Attributes

button "select" //press the first button found of this name

button "select" near "notation style" //more specific

button "select" near "alternate not*" //another one

button "select" near "transposition cl*" //another one

button "select" near "notehead font" //another one

 

Check Boxes and Radio Buttons

The commands "check," "uncheck," and "click," are used for these types of items:

check "allow undo"//check it (no action if already checked) 

uncheck "use score colors" //uncheck it (no action if already unchecked

click "automatic music spacing"//set if unset, unset if set (toggle)

click radio "update manually" //radio buttons

select radio "update manually"//same

click "update manually" //will work, but less specific (not recommended)

click "measure" near "through end of piece" //’near’ specifier

click "measure" near "to next time change" //’near’ specifier

As notes, if several checkboxes or radio buttons have the same name (rare), you must use a ‘near’ specifier.

 

The "Expect" Command

You can combine any of the previous commands with the word ‘expect’ to indicate that FinaleScript should wait until the desired item is available. Note that when in ‘expect’ mode, blocking dialog boxes are not bypassed.

query source folder //choose source batch folder

query destination folder //choose source batch folder

menu item "file maintenance"

uncheck "test file integrity"

hit ok //launch the file maintenance

expect to hit ok //wait until 'ok' is available

save append "_checked"

close

 

Typing Text and Numbers

The command "type" simulates typing strings and numbers with the keyboard...

type 15.7 //fill the current text box (if on focus) with this value  

type "15.7" //same thing type "Hi" //fill with this string

type 15.7 near "outer tip" //value in a text box with label “Outer Tip”

type "15.7" near "minimum measure width" //same thing type "Hi" near "name" //string in a text with label “Name

 

Here is an example:

select meas 1 plugin "create tempo marking"

check "display tempo text"

type "Allegro non troppo" near "display tempo text"

type 96 near "="

press "OK"

 

In the Create Tempo Marking plug-in, notice the Display Tempo Text check box controls the state (enable/disable) of the text box that is just below. So, FinaleScript makes the visual connection between the two as we do based on proximity.

 

Some more examples:

This is a common situation: the static text label is to the left of the text box.

type 1800 near "maximum measure width"

 

Here is a static label with multiple lines, which makes special difference.

type 48 near "minimum distance between notes%"

 

Here the text box is between two labels, so you can use either:

type 96 near "change every" //or

type 1 near "measures"

 

Here, because these values are visually embedded in a 2X2 array, which FinaleScript can't understand directly, you must use the tab command:

menu item "document options"

list "ties"

check "time"

type 8 near "time"

tab

type 9

check "key"

type 7 near "key"

tab

type 6

press "ok"

 

Also, there are some Macintosh lists that are inaccessible from FinaleScript. A typical example is the font list. In the Font dialog box, you may select a font either with the mouse, or type directly its name "P-E-T-R-U-C-C-I" to make it work. For this type of specification, use the ‘raw’ attribute:

menu item "set default music font"

type raw "petrucci"

type "22" near size

hit ok

 

Selecting an Item from a Popup list

popup "layer 4" //  

select "layer 4" //may work but not recommended

popup "first upstem*" near "music char*" //another ‘near’ specifier

 

Selecting an item from a List

FinaleScript supports selecting from simple text-only lists. Simple lists can be found in the Measure Number Regions dialog box, Program Options dialog box, or Document Options dialog box.

 

Note that most of Finale lists are not supported directly by FinaleScript, including the following dialog boxes:Expression Selection, Percussion Map Selection, Articulation Selection, andInstrument List.

 

The following commands are equivalent:

select list "display colors"

list "display colors"

 

Selecting a Tab from a Tabbed dialog box

Several dialog boxes, such as the Expression Designer dialog box, use tabs. Use the following commands to specify a tab.

select tab "playback"

click tab "playback" //same

hit tab "playback" //same

click "playback" //generally works, but less specific

 

Here is an example of script which combines tabs, popup menus, text boxes, and buttons. To apply this script to an expression, you would click the expression's handle and call the script.

//modify expression definition:

hit return //display the Expression Designer for this expression

click "positioning" //select this tab

popup "left"

popup "start of music"

type 12 near "additional horiz%"

popup "staff reference line"

type 24 near "additional base%"

button "ok"

 

Note that only standard upper tabs are supported by FinaleScript (left, right, and bottom tabs are not supported).

Selecting Windows

If several modeless (floating) windows are visible on you screen simultaneously, use the "select window" to select a window before scripting the desired actions:

select window "align move*"

click "to nearest element"

button "go"

 

To expand dialog a dialog box (such as the expandable Playback Controls):

select window "playback controls"

expand window

click "leftmost measure"

click "end of piece"

Simulating Keytrokes

Instead of typing actual text or numbers, you can use special keystrokes (e.g. for navigating dialog boxes):

tab //moves the focus

shift tab //moves the focus backward

tab 2 //moves the focus twice

shift tab 4 //moves the focus 4 times backward //

press enter //as if the Enter key were pressed

enter key //same

enter //same

return //

cmnd enter // ‘power’ enter

ctrl return // ‘power’ return

shift return //

left arrow

right arrow

up arrow 2 //twice

down arrow 5 //5 times

space bar

spacebar //same

press del

press delete //same

delete key //same

del key //same

shift ctrl return //in combination with modifiers

alt cmnd spacebar //other combination

ctrl apple return //apple key=cmnd key

home key

end key

page up key

page down key

 

The Tab, Enter, Return, left/right/up/down arrows, Spacebar, Home, End, Page Up, Page Down, and Delete keys can all be used in combination with Shift, Option and Command (Apple) modifiers.

Moreover, simple keystrokes such as Shift+1 can be scripted:

strike shift 1 //the number must be simple digit {0…9}

press shift 1 //same

press shift "1" //same

press shift "A" //with alphabetic key

 

Here is a example of such keytrokes used to program a transposition metatool:

//program a transposition metatool:

selection tool

press apple shift 6

click "up"

click "chromatically"

popup "minor third"

type 1 near "plus"

check "preserve*"

button "ok"

 

Sliders

Sliders are supported by FinaleScript:

menu item "audio setup"

move slider "mic level" 110

check "enable micnotator"

hit ok

 

Simulating Mouse Clicks

You can emulate single and double-clicks (and double-clicks in combination with Command/Shift/Option) from the current position of the mouse. This is useful when calling a script with a keyboard shortcut (e.g. to process an action on a handle).

control click

shift click

double click

shift double click

control shift double click

 

Assigning a Keyboard Shortcut to a Script

Any script can be added to the FinaleScript submenu and/or be equipped with a keyboard shortcut. To do so:

  1. Open the FinaleScript Palette ( > FinaleScript > FinaleScript Palette).
  2. Double-click a script to open it in the FinaleScript Editor dialog box.
  3. Check Show In Menu. The script is now assigned to display in the FinaleScript submenu.
  4. Check Use Shortcut and click the adjacent Select button. The FinaleScript Shortcut Editor appears as shown below.

  1. Press the desired keystroke. If it is taken, FinaleScript will notify you there is a conflict (and list the associated conflicting command). Click Find One! to ask FinaleScript to suggest an available keyboard shortcut.
  2. Click OK. You can now use the keyboard shortcut you defined to run the script.

Note that the combination of FinaleScript keyboard shortcuts and the command "execute menu item" allows virtually any keyboard remapping. Script menu items themselves cannot be called with FinaleScript plug-in or menu item commands.

 

The "Hide Palette" Command

In the FinaleScript Options dialog box, you can choose to display the palette when a script is invoked with a keyboard shortcut (see the Don’t Show FinaleScript Palette option). If this option is unchecked, you can override it for a given a script with the command ‘hide palette’:

hide palette

control click

type raw "engr"

arrow right

arrow down 2

type enter

 

Source and Destination Folders

In FinaleScript, you can select the source (load) and destination folder for batch processing through the FinaleScript Options dialog box. But these options are global for all scripts. If you want to override the locations the following script commands can be used, which override the global settings:

source batch folder "/Users/main/Desktop/Music"

load folder "/Users/main/Desktop/Music"

load folder "Mac HD:Users:main:Desktop:Music" //same, ‘HFS’ style

load folder "\Users\main\Desktop\Music"

destination batch folder "/Users/main/Pictures/EPS"

save folder "/Users/main/Pictures/EPS" //same

Note that on the Mac, both POSIX, HFS and Windows path styles can be used and are detected by FinaleScript automatically.

 

Important: The source and destination batch folders only apply to the FinaleScript Save command (with possible parameters). These settings do not apply to saving documents in the normal way (or while exporting graphics, MIDI files, etc.).

Stop and Pause

The keyboard shorcut to pause a script is the same as the Palette itself (default = Ctrl+Cmd+F). Pressing the shortcut pauses it. You may then decide to either continue (by pressing the flashing play/pause button) or press the stop button.

 

Report Font

The command "report fonts" writes the full document font list into a report. Missing fonts are specified. That this command works only within a script, not in the command line.

TGTools

FinaleScript includes a direct command to TGTools:

 

FinaleScript Helpers

Developing scripts quickly and easily requires access to all FinaleScript's extensive library of commands. Because of this, FinaleScript includes instant access to all commands in its dictionary through a context menu available in the FinaleScript Editor. If you are unsure of the exact language of a command, type your best guess, and then Control-click to display all commands that resemble the abbreviated text. Choose the desired command to enter it into the FinaleScript Editor (see below).

Similarly, FinaleScript allows easy access to source and destination folders through the same context menu. Simply choose "Insert Patch, navigate to the desired folder, and click Open to insert the path (see below).

 

You can also use the context menu to easily comment/uncomment lines of text in the FinaleScript Editor. Simply highlight the desired text, Control-click, and choose Comment/uncomment (see below). :

 

General FinaleScript Commands

 

Note: You can also see a list of FinaleScript commands by opening the script "Commands Reminder" in the FinaleScript window.

 

process all open (Without it, only the current document will be processed.)

dont process active doc (Will process the other open docs.)

batch process folder

process subfolders

switch to main document

Switch to previous/active/next doc (following Window Menu order)

stop, end

Document Options Handling

FinaleScript gives direct access to numerous Document Options, equivalent to check boxes, popup menus or text boxes. In a script, these commands are written as they appear in the Document Options dialog box. Options that are value can be followed by the unit (evpus, space, inches, centimeters, millimeters...), otherwise the current measurement unit is used. 

Examples:

staff line thickness = 2.7 evpus

check Use Straight Flags

select Flatten All Beams

uncheck Allow Rest To Float //Options that are checkboxes can be combined with 'no' or 'don't' (ex: 'don’t use smart hyphens').

(don't) use engraver slurs

(don't) use cross-layer accidentals

(don't) use smart hyphens

(don't) use smart extensions

 

The following is a list of document options that can be accessed directly in FinaleScript.

space between accidental and note //accidentals

space between dot and note //augmentation dots

close barline at the end of each system //barlines

heavy line thickness //barlines

thin line thickness //barlines

base slop on end notes only //beams

flatten beams based on standard notes //beams

flatten beams based on extreme notes //beams

flatten all beams //beams

allow primary beam within a space //beams

allow rest to float //beams

extend beams over rests //beams

extend secondary beams over rests //beams

beam thickness //beams

broken beam length //beams

maximum slope //beams

maximum distance from middle staff line //beams

display clef only on first staff system //clefs

spacing before clef //clefs

spacing after clef //clefs

clef change reduction //clefs

clef change offset //clefs

use standard/straight flags //flags

flag spacing //flags

secondary group adjust //flags

music font = “font name” //fonts

grace notes size/spacing //grace notes

always slash fagged grace notes //grace notes

display key signatures only on first staff system //key signatures

cancel outgoing key signature //key signatures

display courtesy key signature at end of staff system //key signatures

space before key signature //key signatures

space after key signature //key signatures

space after canceled key //key signatures

space between key signature accidentals //key signatures

staff line thickness //lines & curves

start number at 5 measures //multimeasure rests

minimum/maximum measure width //music spacing

minimum distance between items //music spacing

minimum distance between notes with ties //music spacing

spacing before/after music //notes and rests

scale manual positioning of notes //notes and rests

heavy/thin repeat line thickness //repeats

normal stem length //stems

shortened stem length //stems

stem line thickness //stems

use outer placement //ties

space before/after time signature //time signatures

display courtesy time signature //time signatures

use engraver slurs

Copy/paste Document Options Between Documents

The following commands can be used to copy document options from one document to another, or many other documents. 

For example, if you like the Music Spacing and Beaming Options in one document, you can use the file as a template and apply these settings (or all document options) to hundreds of files, to match a house style for instance. To do this, open the template file. In FinaleScript vocabulary, this file is the "Main Document". In the FinaleScript dialog box, choose the folder that you want to batch process. (If you want to transfer Document Options to other documents, you can also open them and then return focus to the main document before running the script instead of batch processing a folder). Open the FinaleScript plug-in, and write the script.

Example:

batch process the folder

import music spacing options from main document

import beaming options from main document

respace

update layout

 

The same way, if you have created piano braces that you want to "paste" to the other files, you could write:

batch process the folder

import piano braces from main document

update layout

 

The final step is to launch the script with the main document open (the main document is the active document when you launch the script). Options that can be copied and pasted using the above procedure are:

import doc options (or) import house style //All document options

import accidental options through import tuplet options

page format for score

page format for parts

import extract parts options

import human playback options

slur contour

smartshape placement

smartshape options (including regular options, Smart Slur Options and Guitar Bend Options.)

 

Selecting and Deleting Measures

Use the following commands to select and delete measures:

select meas 3

select first meas

select last meas

select meas 1 to 5

select meas 6 to the end

select first meas to 6

//

delete meas 3

delete first meas

delete last meas

delete meas 1 to 5

delete meas 6 to the end

delete first meas to 6

 

Tool Commands

selection tool

page layout tool

pge layout

layout //Select any tool by typing its name. Note that the Special Tools cannot be selected in this fashion. For tools in the Special Tools palette, use Finale's Tools menu instead.)

View Commands

unit evpu(s)

inches (i, inch)

centimeters (cent, c)

millimeters (mill, mm)

spaces (s, sp, spce)

picas

show all layers

all layers

show active layer only

active layer only

hide others

zoom (50, 75, 100, 200, 400)

fit in window

home

go to page 5, page 5, pge 1

go to measure 124, meas 124

Page Layout Commands

FinaleScript has several powerful commands devoted to the page layout. Note that these commands are generally applied to the entire document. Like many Selection Tool operations, many Page Layout commands can be typed on the fly without changing tool.

(don’t) display in concert pitch

resize pages to 75%

resize systems to 80%

staff height = 0.3 inch

resize staff to 65% (applied to selection)

page format A4 (or A4)

page format Letter landscape

page format portrait (or Portrait)

page format 21x29 cm

reverse page margins, reverse margins

apply page format (for score)

fit 4 measures (per system)

update layout, updt layt

reorganize Layout, reorganize, reorg (Update Layout with maximum options)

redraw, refresh

Clef Tool Commands

first clef/default clef

treble // (or ’g’)

bass //(or ’f’)

tenor //(or treble + ’8’)

alto //(or ’c’- this is the C clef on the third line). This command applies to the whole staff and clears other clef changes.

Utilities Menu Commands and Miscellaneous

Most of the following commands require a selection. If there is no selection, FinaleScript assumes that the operation is for the entire document. Note that it is not necessary to invoke the Selection Tool before any operation, it is all automatic

note spacing //or respace

beat spacing

time signature spacing

rebar

rebeam

check accidentals

check ties

convert mirrors

fill with rests

move layer 1 to 2 //This deletes the source layer afterwards

freeze stems down/up

remove manual slur adjustments

remove stem changes

respell notes

retranscribe

lock/unlock systems

transpose to G major/minor (+ attributes)

Fit Measures 4 meas //per system

chord style Nashville A //or any other available style

show/hide fretboards

resize fretboards to 80%

update hyphens

update word extensions //or update extensions

execute plug-in "flat beams" (or run plug-in "xxx", plugin "yyy", pi "zzz")

"..." after the plug-in’s name to open dialog box.)

delete lyrics

delete chords

swap layers x and y

Edit Menu Commands

The following are examples of commands you can use to select, delete, copy, or paste.

undo

redo

[select] layer 3, layer 3, l 3

work on layer 3 (select layer 3 + show active layer only + show layer 3)

select measure 1 to 15

select staves “flute” to “ saxophone” (no case checking)

select “piano” (group name)

select instrument 2 to 5 (score visual order)

select “clarinet” to bottom

select staves “flute” to 5 (mix name and #)

select top to “horns”

select pages 2 to 5

select systems 1 to 10

select/deselect all

delete staff (= the currently selected staff(ves))

delete measures (the selection)

clear measures (notes and smartshapes only)

copy, cp, cpy

paste, replace entries, replace

insert, ins

(disable) automatic music spacing, auto spacing

(disable) automatic update layout, auto update

File Menu Commands

quit, q

close,c

new, n (default document)

open, o, open midi, open mus, open etf, open ftm, open all

open ? (to call Finale's Open dialog box from within a script)

save, sv, save and append, new, save as midi, save as

print, p (’print’ alone prints the entire doc with the current Page Setup settings)

Print attributes: 2-up, 4-up, even, odd, page 3 to 18, to page 20, (you can also specify a "print string", such as "2, 4, 6-9).

print booklet //Prints 16-page booklets automatically, both sides. You can specify the number of pages per booklet. If your printer can't print both sides, you might precise 'recto', and then 'verso' after reversing the pages in the printer to get the booklet right.

Other Commands

transpose instrument to Bb //instrument transposition

run plug-in "flat beams" //no need to specify a subfolder - you can specify any plug-in

display in concert pitch

uncheck display in concert pitch

create/break multimeasure rest

Add/insert Staves. Ex: add 1 staff, append piano staves "Piano", add 3 staves bass clef, insert 1 staff "Clarinet in B^b"

apply staff style

clear staff style

show/hide measure numbers

title

composer

copyright

description

staff name

left/right/top/bottom page/system margin

Text Search and Replace

FinaleScript includes Text Search and Replace. From a script, calls to Search and Replace can be as follows:

search “© Music Sales” replace with “© Neverland Publishing”

search “Violin” replace “Violon”, match case

search “Clarinet in A” replace “Trumpet in B^b” (note the use the caret)

search [Times] and replace [Chicago]

search font “Times” and replace “Chicago” (equivalent)

search “Cl.” [Palatino] 12 italic bold replace with “Fl.” [Times] 13 non bold, in staff names

 

For the above items, you can also add the following attributes:

(non) italic

(non) bold

(non) plain

(non) fixed size

(non) underline

(non) hidden

[font name] (always in brackets)

size: 48 (number only)

match case

whole words

expressions

staff names

text blocks

file info

 

Note: All these Text Search and Replace features are also available from within the Text Search and Replace dialog box(Edit Menu).

 

Smart Shapes

(No attribute means all text items.)

Use the caret for specific matches

^l = line feed

^t = tab

^© = copyright symbol insert

^c = copyright text

^C = composer insert

^T = title insert

^d = file description

^# (or ^s) = sharp insert

^b = flat insert

^n = natural insert

^S = double sharp insert

^B = double flat insert

^^ = caret character

<65> ASCII character

 

Font Commands

(No attribute means all text items.)

Use the caret for specific matches

Music Font [maestro wide] //The font name can also be written between quotes. Attrbutes: size and 'bold'.)

Swap Font [times] with [JazzText] //Font names can be between quotes. No attributes, this is global for the document.)

 

Playback

FinaleScript has several playback-oriented commands, among them is Human Playback.

Use the caret for specific matches

playback, play, listen (performs a non-scrolling playback. If there is a selection, will perform the selected staves only.)

wait 3 seconds (a timer that can creates pause between file performances)

wait for a key

internal speaker playback

uncheck internal speaker playback

human playback style Romantic/none, standard, classical, romantic, jazz, rock, etc.

import human playback custom style from main document

 

image\btn_Table_of_Contents64.gif