Introduction to scripting

MediaMonkey can be customized through the use of custom scripts. Scripts are relatively simple computer programs written in a scripting language, such as VBScript. Unlike most computer programs, these scripts do not have to be compiled, which allows them to be tested and modified more easily than with more advanced languages. Still, writing MediaMonkey scripts can be a challenging experience so potential script writers should consider alternatives, particularly if they have little previous experience writing scripts.

Considerations

Before writing their own scripts, users of MediaMonkey may wish to consider the following issues:

• In addition to supporting scripting, MediaMonkey has a plug-in interface that allows a large number of Winamp and MediaMonkey plug-ins to be used. There may be no need to write a script if the desired features are already provided by a plug-in.
• Some users of MediaMonkey are willing to share the scripts that they have written with other users. An existing script may already provide the desired features or be relatively easily modified so that it does. The best place to find such scripts or to get support for them is the Scripts and Components forum.
• Although, in theory, MediaMonkey supports both of the VBScript (*.vbs) and JScript (*.js) scripting languages, the implementation for JScript is only partial (see Scripting Tips & Tricks for some issues), so for some applications VBScript is required. Programmers not wishing to deal with VBScript may wish to create an external script or application using their preferred language and use a script written in VBScript (or JScript) to launch it.
• Other than tags embedded in media files, virtually all of MediaMonkey’s data is stored in a SQLite database from MediaMonkey version 3.0. It is possible to manipulate MediaMonkey’s data, while minimizing the use of MediaMonkey’s API, by using SQL. MediaMonkey's API can be (almost, except string collations) completely bypassed by using an interface provided by the underlying engine to access the database. (MediaMonkey 2.x used Microsoft Jet relational database. It could accessed through Jet or ODBC, or even opened directly by Microsoft Access, for example.)

Types of scripts

There are three major types of scripts that can be launched internally by MediaMonkey:

• 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. If more than one script exists in the Auto folder the scripts are run in alphabetical order.
• Other scripts, such as Search scripts and Auto-DJ scripts are intended for specific types of customization, but are also defined in the Scripts\Scripts.ini file.

In addition to the scripts that are launched by MediaMonkey (internal scripts), you can also work with MediaMonkey by using 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 or, if you are already up to it, take a look at the code of some actively developed scripts on the forum (most of them are distributed in MM installation packages).

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 VBScript, but not JScript, scripts in the Scripts\Auto folder are automatically checked during MM start-up, and the OnStartup procedure (if present) is called. Auto-scripts make it possible to add user interface enhancements such as 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.

You can choose to dynamically add an entry to the Scripts.ini from your code, so your script can be accessed from the Tools > Scripts submenu just like normal scripts. However, most auto-scripts add UI items (e.g. menu items) directly to the MediaMonkey user interface to be more tightly integrated.

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 > Create Reports 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. This script type is obsolete, rather register OnPlay event. Also note, that this is the only case, when multiple instances of one script can be executed by MediaMonkey, otherwise only one instance is always executed.
• 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+’, singly or combined, followed a single letter or number, or the name of a special key - BkSp, Tab, Enter, Esc, Space, PgUp, PgDn, End, Home, Left, Up, Right, Down, Ins, Del.

About external scripts and applications

(see also Interaction with MediaMonkey from outside)

Besides supporting al large part of the Winamp plug-in model and messages (1,2), MediaMonkey exposes an API via the Microsoft COM model. This allows external applications to access and control MediaMonkey directly. These applications can be written in any language that can access COM objects. VBScript can be used to produce external scripts, but regular Visual Basic (or any COM-aware language) can be used as well, producing a full-fledged application.

In order to work with MediaMonkey’s objects from an external script or application, you need to create a reference to the SDB object (an instance of the SDBApplication class) yourself. For .NET-based applications, you must also add a reference to MediaMonkey's COM object "MediaMonkey Library" to your Visual Studio project, so that the compiler can find MediaMonkey and the SongsDB namespace.

If MediaMonkey is already running, creating a SDBApplication object instance will return a reference to the running instance. If MediaMonkey is not running yet, it will be started and a reference will be returned. In addition, if MediaMonkey was was not running before, it will normally shut down automatically when the external script/application exits. This can be prevented (so MediaMonkey will remain running) 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.SDBApplication SDB = new SongsDB.SDBApplication();

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

C++/CLI sample:

SongsDB::SDBApplication^ SDB = gcnew SongsDB::SDBApplication();

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

Delphi sample:

var 
  SDB : Variant; 
begin 
  SDB := CreateObject('SongsDB.SDBApplication');
  SDB.ShutdownAfterDisconnect := false;    // in case you want to keep an opened instance open after disconnecting the SDB object

PHP sample: (shows initialization only)

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

Python (with PyWin32) sample:

try:
      import win32com.client
except:
      print "Install PyWin32"
# Open connection to COM object
try:
      SDB = win32com.client.Dispatch("SongsDB.SDBApplication")
except:
      print "Is MediaMonkey up and running?"

SDB.ShutdownAfterDisconnect = False

Perl sample: (shows initialization only)

use Win32::OLE;
my $SDB = Win32::OLE->GetActiveObject('SongsDB.SDBApplication') || Win32::OLE->new('SongsDB.SDBApplication', '');
$SDB->ShutdownAfterDisconnect(true);

Developers that require MediaMonkey type library information (e.g. for C++/Delphi, as newer languages usually don't need this) can extract this from the MediaMonkey.exe file (more information), or can use #import on the Exe file as explained in this MSDN page.

Further reading

• Scripting main page
• .NET Tips page
• MediaMonkey Interface Definition Language (IDL) file