Introduction to scripting

There are 2 major kinds of MediaMonkey scripts:

• Normal scripts are located in the Scripts folder and are executed according to the script's entry in the Scripts\Scripts.ini file.
• Auto-scripts are located in the Scripts\Auto folder and its OnStartup method is executed when MediaMonkey starts.

It's recommended to create VBScript (*.vbs) scripts. JScript (*.js) scripts are possible too, but they have only limited support.

Next to the scripts that are launched by MediaMonkey (MediaMonkey scripts), you can also work with MediaMonkey through external scripts and applications.

How to create a normal script

1. Create a plain text file in the Scripts folder, e.g. MyNormalScript.vbs.
2. Write your VBScript script and make sure you have a procedure that can be called, e.g.

   Sub CallMe
   
       ' This script will pop up a simple message box when the procedure CallMe is called.
       MsgBox "CallMe was called by the action defined in the Scripts.ini file."
   
   End Sub

3. Create a new entry for your script's CallMe procedure in the Scripts.ini file.

From within a MediaMonkey script, a reference to the SDB object (an instance of the SDBApplication class) is always present. By accessing its properties and methods, you can interact with many aspects of MediaMonkey. Check out the MediaMonkey Automation objects page for other MediaMonkey objects that can be created starting from the SDB object. Another available object reference is the Script object (an instance of the SDBScriptControl class), that contains methods to control the running script's environment, usually to attach to events of MediaMonkey and its player and controls (see examples 1 and 2).

The script Scripts\MediaMonkey init.vbs is always executed just before any other script. It contains some constants that can be used in your own script.

A good and quite complex example is Scripts\Export.vbs (distributed with MediaMonkey) which contains code that takes care of all export features of MediaMonkey. For more examples, check out the sample scripts page.

More information about scripting in general can be found at Microsoft Scripting (with official VBScript and JScript documentation).

How to create an auto-script

1. Create a plain text file in the Scripts\Auto folder, e.g. MyAutoScript.vbs.
2. Write your VBScript script and use the procedure OnStartup as start point for execution, e.g.

   Sub OnStartup
   
       ' This script will pop up a simple "Hello World!" message box when you start MediaMonkey.
       MsgBox "Hello World!"
   
   End Sub

All .vbs scripts in Scripts\Auto folder are automatically checked during MM start-up, and the OnStartup procedure (if present) is called. Auto-scripts e.g. allow to add user interface enhancements like new menu or toolbar items, new option sheets, etc.

Except that these scripts are automatically executed when MediaMonkey starts, they behave identical as the normal scripts. They also get a reference to the SDB object, and the constants defined in Scripts\MediaMonkey init.vbs are always usable.

Format of the Scripts.ini file

[AutoIncTrackN]
FileName=AutoIncTrackN.vbs
ProcName=AutoIncTrackNumbers
Order=1
DisplayName=Auto-&increment Track #s...
Description=Sequentially numbers Tracks
Language=VBScript
ScriptType=0

Sample Scripts.ini entry

This Scripts\Scripts.ini file is a standard .ini file where each section defines a procedure in a script. The section starts with a section identifier [SectionName], where ‘SectionName’ is a unique name of the script entry. These are the entry's properties:

Filename

Path of a script file where the procedure is located, relative to the Scripts folder, e.g. ‘MyScripts.vbs’.

ProcName

Name of an existing procedure to be called when the script (specifiedby ‘Filename’) is executed in MM.

ScriptType

Defines type of the script:

• 0 = A standard script that appears in the Tools > Scripts submenu.
• 1 = An export script that can be found in the File > Export submenu.
• 2 = A track-start script that is activated whenever a new track is started. This script doesn’t appear in any menu, it’s simply called in the background. When this procedure is executed, a variable 'CurrentTrack' (object of the SDBSongData class) is defined, and you can use it to get information about the started track.
• 3 = A search script that allows custom searches to be programmed in the "Auto-tag from Web" dialog. See Search scripts for more information about this more complex script type.
• 4 = An Auto-DJ script that can handle content added by Auto-DJ. See Auto-DJ scripts for more details.

Order

Defines the order of the script in its section. These numbers are sorted and scripts are listed according to the order.

DisplayName

The script is listed as menu item with this name.

Description

Message shown as tooltip when the mouse is moved over the menu item.

Language

The script language of the referenced script. Usually VBScript, but can be JScript too (although this is not recommended).

Shortcut

Specifies a shortcut that invokes the script in MM. You can use any of the strings ‘Shift+’, ‘Ctrl+’ or ‘Alt+’, even combined together and followed either by a single letter or a special key (BkSp, Tab, Enter, Esc, Space, PgUp, PgDn, End, Home, Left, Up, Right, Down, Ins, Del).

About external scripts and applications

External scripts are called from outside MediaMonkey. They can be scripts that are executed from inside a MediaMonkey script (e.g. helper scripts), or from other places outside MediaMonkey (normal *.vbs scripts, local html pages, ASP server pages, ...). The same information applies to applications that are not a part of MediaMonkey, but want to use its COM object (the COM and the scripting API are the same).

In order to work with MediaMonkey’s objects from outside a MediaMonkey script, you need to create a reference to the SDB object (an instance of the SDBApplication class) yourself. For external applications, make sure that you have added a reference to the SongsDB library first.

If MediaMonkey is already running, a call to the SDB object will return a reference to the running instance. If MediaMonkey is not running yet, it will be started and then a reference will be returned. When MediaMonkey is started by an SDB call when it wasn't running before, it will automatically shut down when the external script/application exits. You can prevent this (and keep MediaMonkey open) by setting SDB's ShutdownAfterDisconnect property to False.

Visual Basic / VBScript sample:

Dim SDB : Set SDB = CreateObject("SongsDB.SDBApplication")

SDB.ShutdownAfterDisconnect = False    ' in case you want to keep an opened instance open after disconnecting the SDB object

C# sample:

SongsDB.SDBApplicationClass SDB = new SongsDB.SDBApplicationClass();

SDB.ShutdownAfterDisconnect = false;    // in case you want to keep an opened instance open after disconnecting the SDB object

Delphi sample: (shows initialization only)

var 
  SDB : Variant; 
begin 
  SDB := CreateObject('SongsDB.SDBApplication');

PHP sample: (shows initialization only)

$objSDB = new COM('SongsDB.SDBApplication') or die('Cannot create MediaMonkey SDB Object');