See also FinaleScript Options dialog box.
Choose Plug-ins > FinaleScript > FinaleScript Palette.
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 "
Choose a Script and click the View Current Script button to see examples. To familiarize yourself with this utility, you will find predefined 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:
.
Click this button to play the script selected in the Script List.
.
Click this button to interrupt a script process at any time.
. Click this button to open the Script Editor dialog box
where you can create and save a new script.
. Click this button to open the Script Editor dialog
box where you can edit the script selected in the Script List. See Script
Editor dialog box.
. Click this button to duplicate the currently selected script.
. Click this button to delete the script selected in the
Script List.
. Click this button to create a new folder in the script list. Context-click and choose Rename to rename the folder. Simply drag and drop to add scripts to the folder.
.
Click this button to display a script report if one exists. This report
(or log file) displays information regarding the success or failure of
commands from the most recently run script. You will also see the folders
and subfolders that were processed.
. Click this button to open the FinaleScript Options dialog box where you can change many aspects of FinaleScript's behavior.See also:
Contextual menus are reached by
|
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 |
. Or, select and existing script and click the Duplicate button , then click the button. The FinaleScript Editor dialog box appears.. After the script
processes the document(s), click the blinking report button to view a
report of the commands applied. Alternatively, you can choose this script from the Plug-ins > FinaleScript submenu or press the keyboard shortcut you defined.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.
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" |
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.
Tip: 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 t dialog box, there are 2 different Settings 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 "settings" //press the first button found of this name button "settings" near "use note shapes" //more specific button "select" near "use not*" //another one |
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 check boxes or radio buttons have the same name (rare), you must use a ‘near’ specifier.
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 |
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" |
Tip: 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 Mac 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
|
dropdown "layer 4" // select "layer 4" //may work but not recommended dropdown "nothing" near "number" //with ‘near’ specifier dropdown "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, Preferences dialog box, or Document Options dialog box.
Tip: Note that most of Finale lists are not supported directly by FinaleScript, including the following dialog boxes:Expression Selection, Percussion Layout Selection, Articulation Selection, and ScoreManager.
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, pop-up 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 pop-up "left" pop-up "start of music" type 12 near "additional horiz%" pop-up "staff reference line" type 24 near "additional base%" button "ok" |
Tip: Note that only standard upper tabs are supported by FinaleScript (left, right, and bottom tabs are not supported).
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" |
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 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/FIGHT/UP/DOWN ARROWs, SPACEBAR, HOME, END, PAGE UP, PAGE DOWN, and DELETE keys can all be used in combination with SHIFT,
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 keystrokes used to program a transposition Metatool:
|
//program a transposition Metatool: selection tool press ctrl shift 6 click "up" click "chromatically" dropdown "minor third" type 1 near "plus" check "preserve*" button "ok" |
Sliders are supported by FinaleScript:
|
menu item "audio setup" move slider "mic level" 110 check "enable micnotator" hit ok |
You can emulate single and double-clicks (and double-clicks in combination with
|
control click shift click double click shift double click control shift double click |
Any script can be added to the FinaleScript submenu and/or be equipped with a keyboard shortcut. To do so:
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.
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 |
Note: 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.).
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 "c:\scores\source" load folder "c:\music\scores" save folder "c:\scores\converted" |
Note that on the Mac, both POSIX, HFS and Windows path styles can be used and are detected by FinaleScript automatically.
The keyboard shortcut to pause a script is the same as the Palette itself (default =
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.
FinaleScript includes a direct command to TGTools:
|
tgtool "harmonics" //calls full TGTool item tgtools "harmonics" //same tgtool "easy harmonics" //calls lite TGtool item |
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
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,
Tip: 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 |
FinaleScript gives direct access to numerous
Document Options, equivalent to check boxes,
Examples:
|
staff line thickness = 2.7 evpus check Use Straight Flags select Flatten All Beams uncheck Allow Rest To Float //Options that are check boxes 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
|
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.) |
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 |
|
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.) |
|
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 |
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 |
|
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. |
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 |
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 |
|
quit, q close,c new, n (default document) open, o, open midi, open mus, 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. |
|
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 |
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 |
Tip: All these Text Search and Replace features are also available from within the Text Search and Replace dialog box(Edit menu).
(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 |
(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.) |
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 |
|
Finale User Manual Home
|
|