What are scripts and how do they work?

Scripts are small programs that can interact with ID3-Sync and improve, extend or automate certain tasks. In ID3-Sync, a script is a file with source code that is dropped into the scripts folder in your ID3-Sync installation folder. The code can be written in C#, Visual Basic .NET or JScript.NET.

When ID3-Sync starts (to be precise: when the scripting engine starts) it scans the scripts folder for files with the extensions .cs, .vb and .js and tries to compile each of them into a seperate .dll (assembly as it is called in .NET). Depending on the extension a different compiler is used to compile the source code (.cs files will be compiled by the C# compiler, .vb files by the VB compiler and .js files by the JScript.NET compiler). Any errors will be reported by the "Compile error" dialog (see the screenshots).

The compilation only takes place once. When its compiled, ID3-Sync will use and call the code in the compiled .dll. On the next start ID3-Sync will check if the source code file has been changed since the last compilation, and will only recompile in this case. Otherwise it will use the existing .dll and thus save the time a compilation would have taken.

How to create a script?

We will now walk through the creation of a simple script. All we want the script to do is to start playing a song when we load it to the edit window. The script we are about the create already ships with ID3-Sync. You can find the full source code in scripts/preview.cs. There are also versions in Visual Basic and JScript.NET (scripts/preview.vb.txt and scripts/preview.js.txt). I will just discuss the C# version here, but the concepts are identical, no matter what language you use.

Every script needs a define a class that implements the ID3Sync.Scripting.IScript interface. This interface consists of a method (Initialize) and a read-only property (Description). Thats all that has to be implemented.

using System;
using ID3Sync.Scripting;

// Define a class that implements IScript.
// The name does not matter, I just called
// this one Script.
 public class Script : IScript
{
   // The value of the Description property is used by ID3-Sync
   // to show it in the script-list in the options dialog.
    public string Description
   {
      get { return ""; }
   }

   // Initialize is called once when the script is loaded.
    public void Initialize( IHost host )
   {
   }
}

Now that we have the skeleton of our script we'll take a closer what we can do with it. Since the use of the Description property should be obvious, we'll take a close look at the IHost parameter which is passed to the Initialize method. This object is our connection to ID3-Sync. It exposes a couple of events which we can subscribe to. A look at the IHost documentation tells us which events exists. We want to subscribe to the EditNext event, which will allow us to start the playback whenever a new file is loaded. To handle the EditNext event we need a event handler method which takes an IEdit object as parameter. Our code now looks like this:

using System;
using ID3Sync.Scripting;

public class Script : IScript
{
   public string Description
   {
      // Added a short description.
      get { return "automatic playback when a file is opened"; }
   }

   public void Initialize( IHost host )
   {
      // Subscribe to the EditNext event.
      host.EditNext += new EditEvent(OnEditNext);
   }

   // This is our event handler method.
    private void OnEditNext( IEdit edit )
   {
   }
}

Now our OnEditNext method will be called whenever a new file is opened for editing. The IEdit parameter, which is passed to the method represents the edit dialog and offers methods and properties to manipulate it. A look a the IEdit documentation reveals that we can use the TogglePlayback method to achieve what we want. We'll start the playback with TogglePlayback. After adding this line to OnEditNext our listing should look like this:

using System;
using ID3Sync.Scripting;

public class Script : IScript
{
   public string Description
   {
      get { return "automatic playback when a file is opened"; }
   }

   public void Initialize( IHost host )
   {
      host.EditNext += new EditEvent(OnEditNext);
   }

   private void OnEditNext( IEdit edit )
   {
      // Start the playback.
      edit.TogglePlayback();
   }
}

Our script is now finished. Of course this is a very simple example, but the basic ideas are always the same. Since your script is compiled to a .NET assembly you can use whatever classes the .NET Framework offers. This also includes the creation of own forms or other UI elements. If you have any questions, feel free to email me.