Extending ZenLibrary – Creating New Rules

Hello everyone, this is an article about my ZenLibrary program aimed at those programmers who wish to either extend it or just know more about what’s going on behind the scenes. If you’re just interested in obtaining the program, click here.

I’ve *attempted* to make it easy for any programmer to extend the rules in ZenLibrary. Since I’m releasing this tutorial at roughly the same time as the actual program, I haven’t actually had a chance to get any feedback on how I might improve the extensibility interface. I do, however, want to make it clear I have no interest in making an elaborate end-user based rule scripting engine. Doing so would a.) screw up the simplicity of the program and b.) drastically change the scope of this software. Throwing in some user-defined regular expressions is about as far as I am willing to go.

Part 0 – Getting Set Up and Getting The Source

Creating new rules in ZenLibrary does NOT require getting the source code. One simply needs to reference “ZenLibrary.RuleBase.dll” that comes with the program (version 0.3 and later). However, I think having the source on hand will make debugging things a bit easier on your part. But, it’s all your call.

This project was done in C#, using WPF, and in Visual Studio 2008. Hopefully none of that made you too uncomfortable. You’ll pretty much need Visual Studio 2008 to deal with this solution. I suppose the Express edition of C# could work, but I haven’t tried it.

The source code is controlled in subversion. Everyone has read permissions on the repository. If you’d like to contribute to the project and need write access, drop me a line. This is an open source project, released using the LGPL.

ZenLibrary SVN Host: http://inchoatethoughts.com/zenlibrarysvn

Part 1 – How It Works

Before we get into how to add our own rules, let’s talk a bit about how this program runs. First, the user chooses a directory to scan through and the rules he wants to test against, and then he presses start. The program now launches a new thread (as to not stall the user interface thread) and begins to scan each directory. This is where our first set of tests begins to run. There are two different types of tests, or “rules” (I’ll be using the terms interchangeably). There are “per-directory” rules. These rules run on any directory with music files. These sorts of rules are useful for doing things like checking for the existence of a particular image file (e.g. album artwork) inside the directory. After the “per-directory” tests run, a set of “per-file” tests will be run against each of the MP3 files in the directory. The “per-files” are useful for checking the content of specific tags, checking for proper file name, etc.

Rule Scanning Flow

Rule Scanning Flow

Forgive the terrible flowchart. Continuing on. This is a .NET program, so anyone extending this software will have the full .NET library at their disposal, which is pretty powerful in and of itself. However, since this is an audio library scanner, the program also makes use of TagLib#. TagLib, for those who aren’t already familiar, is a pretty powerful tag reader. It actually works on all sorts of media, not just MP3s with ID3 tags. TagLib# is then a .NET version of TagLib. It’s released under the LGPL, much like ZenLibrary, so packaging it and distributing it with this software is not a problem. ZenLibrary references TagLib, so when designing rules, don’t forget you have a good hunk of tagging technology to make us of. If you’re looking to do things with tags, just add a reference to “taglib-sharp.dll” as well.

Part 2 – Creating a Rule

Our task today is to essentially create one of the rules/tests that make up the meat of this program. I’ve done some work to make this as easy as possible. Here is what you’ll need to do:

  • Inherit from the “Rule” class
  • Give the rule a name (overload the Name property)
  • Define the TestType (“per-file” or “per-directory”)
  • Give it some test logic

That’s it! If you want a more elaborate rule with configurations that are persisted between application sessions, there is a ConfigurableRule class to inherit from and a few more overloads you’ll need to provide. But, let’s ignore that for now. We’re going to create a very simple rule. It’s purpose will be to detect for the presence of the “discnumber” tag in all of our music files.

Diagram for Abstract Rule Classes

Diagram for Abstract Rule Classes

Set Up The Project

First order of business is getting our add-in project created. Open up Visual Studio and create a new “Class Library” project. It doesn’t really matter what you name it, but you may want to indicate your name and that it is a file with ZenLibrary Rules in it. Pretend your name is Billy Bob. You might name the project “ZenLibrary.BillyBobsRules.” I’ve named my project “SampleRuleLibray.” Once you’ve created the Class Library project, go to your references folder, right click and select “Add Reference,” click the browse tab and go find “ZenLibrary.RuleBase.dll” (it comes packaged with ZenLibrary releases). For this particular “Discnumber” tag rule, we’re also going to be using the TagLib# library as well. Once again, add a reference using “Browse” and select “taglib-sharp.dll,” which should also be in the ZenLibrary directory.

References Defined

References Defined

Inherit From The Rule Class

Now that we have our project set up, we can go ahead and create our rule class. Create a new class file (I called mine “SampleRule.cs”). This class should inherit from “ZenLibrary.RuleBase.Rule.”

1
2
3
4
5
6
7
8
9
using ZenLibrary.RuleBase;

namespace SampleRuleLibrary
{
    public class SampleRule : Rule
    {
       
    }
}

Give The Rule A Name

The rule needs a name. The name shows up in ZenLibrary’s rule panel on the left side and is how the user will identify your rule from the other rules. To specify a name, just override the “Name” property’s get. Pretty simple!

1
2
3
4
5
6
7
8
9
10
11
12
using ZenLibrary.RuleBase;

namespace SampleRuleLibrary
{
    public class SampleRule : Rule
    {
        public override string Name
        {
            get { return "Discnumber Tag"; }
        }        
    }
}

Define The Test Type

The test type determines if your test will be run per music directory or per file. It’s just a simple optimization effort, really. The per-directory test exists so that we don’t have to check for the existence of “folder.jpg” in the directory on every file scan. Conversely, the per-file test exists so we don’t have to rewrite logic to scan all of the files every time we run on a music directory. To define our Test Type, we override the “TestType” property’s get and specify “TestType.FileScan” for per-file and “TestType.DirectoryScan” for per-directory. Our test case is something that needs to be done a per-file basis, so we’ll use “TestType.FileScan” in the example.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
using ZenLibrary.RuleBase;

namespace SampleRuleLibrary
{
    public class SampleRule : Rule
    {
        public override string Name
        {
            get { return "Discnumber Tag"; }
        }

        public override TestType TestType
        {
            get { return TestType.FileScan; }
        }        
    }
}

Give The Test Some Logic

Finally, the meat of the program. Our test. This is where the magic happens. The magic that you define, that is. Anything can happen here, really. Override the “RunTest()” method. You’ll be provided with either a “System.IO.FileInfo” for the file you’re scanning (on a per-file scan) or a “System.IO.DirectoryInfo” for the scanning directory (on a per-directory scan). If the scan is per-file, the DirectoryInfo parameter will be the directory where the file is. If the scan is per-directory, the FileInfo parameter will be null. From here on out, it’s up to you what to do with them. All that matters now is that you return a “RuleTestResult” at the end indicating whether the test has passed or failed. If the test has passed, mark “TestPassed” in the “RuleTestResult.IsPassed” property to true and return it. If it is has failed, mark “RuleTestResult.IsPassed” as false. Also, assign the “RuleTestResult.RuleTestFailedString.” This string is the message that will be displayed in the results box on the ZenLibrary UI. Additionally, you’ll want to specify the location where it failed by assigning “RuleTestResult.ResultPath.” This can pretty much always be the “FullName” property of the provided “DirectoryInfo.”

For the sample test case, I’ve added some logic, using TagLib#, to check whether the “Discnumber” tag is “0.” This is an indication that the “Discnumber” tag has not been assigned, and thus, fails our test.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
using ZenLibrary.RuleBase;

namespace SampleRuleLibrary
{
    public class SampleRule : Rule
    {
        public override string Name
        {
            get { return "Discnumber Tag"; }
        }

        public override TestType TestType
        {
            get { return TestType.FileScan; }
        }

        public override RuleTestResult RunTest(System.IO.DirectoryInfo directoryInfo, System.IO.FileInfo fileInfo)
        {            
            TagLib.File file = TagLib.File.Create(fileInfo.FullName);
            RuleTestResult result = new RuleTestResult();
            if (file.Tag.Disc != 0)
            {
                result.TestPassed = true;
                return result;
            }
            result.ResultPath = directoryInfo.FullName;
            result.RuleTestFailedString = string.Format("File "{0}" does not have the discnumber tag defined.", fileInfo.FullName);
            result.TestPassed = false;
            return result;
        }
    }
}

Boom! We’re done! Yep, that’s really all there is to it. Compile your Class Library and drop the output DLL in the same directory as ZenLibrary.exe. You don’t need to register it or anything. ZenLibrary will automatically detect its presence and instantiate any rules within.

The Sample Rule Running!

The Sample Rule Running!

If you want to see more elaborate rules with custom configuration dialogs and the likes, you can grab the source code from the subversion repository and check out the included rules in the ZenLibrary.RuleBase assembly. You may also want to check out how to write a light plug-in infrastructure via reflection by taking a look in “RuleSet.cs” to see how I instantiate all the rules without programmers having to manually register them.

You can also download the sample rule project here.

Thanks for reading!

ZenLibrary – Cleanse Your Music Library (And Thus Your Soul)

ZenLibrary's Main Screen

ZenLibrary's Main Screen

Here’s my latest “weekend project.” It was supposed to be a little tool I wrote for myself on a lazy Sunday afternoon. Then I decided I would release it to you all, and that causes a project to really balloon in scope. I had to worry about it crashing, clean up my code so no one could blackmail me with it later, restructure the architecture to be generic, blah, blah, blah. But, I’ll save all those boring details for the next blog post aimed at programmers. This is supposed to be the post where I tell you what this project does.

Thus, I present to you: ZenLibrary. It’s a simple tool for all of you people as obsessed with sanitizing your media library as I am. You give it your music library, and it tells you all the things wrong with it (presumably so you can fix them). Step 1, you tell it where your music library is. Step 2, you choose what rules you want to test against your music library. Step 3, you fix the problems it finds.

Here’s the feature list:

  • Simple, streamlined UI.
  • Comes with a set of common criteria for sanitizing a music library
  • Easily extensible rule architecture
  • User preferences saved between sessions.
  • Integrates with MP3Tag to quickly launch an editor on any errors it finds.
  • Double clicking any result takes you straight to that folder (again, for easy editing)

Requirements:

Download ZenLibrary 0.4

For people interested in extending it or getting their hands on the source code, be sure to check out my next post on doing just that.

Version Updates:

9-14-2009: Release 0.4

– Fixed icon error causing crashes in Windows XP and Vista
– Moved included rules out to their own assembly.

9-13-2009: Release 0.3

– Created ZenLibrary.Rulebase.dll for plugin support

9-12-2009: Release 0.2

– Added initial support for M4A, OGG, and FLAC files.
– Added detailed error information for tests that are unable to complete (red exclamation circles).
– Changed “Stereo” test method to a simple check on the number of audio channels.
– Fixed bug in album art directory scanning
– Disabled rule options while scanning (to prevent thread collisions)

Custom Drawing Controls in C# – Manual Double Buffering

I feel like this article is about four years too late. All the cool kids have moved on to WPF or something really awesome, like XNA, for their graphics needs. However, there are still a lot of us playing around in the .NET 2.0 mucky muck for various reasons. Of those still doing .NET 2.0 / WinForms / GDI+ programming, I’m surprised to see how many people draw their custom controls the wrong way. Yep, I said “wrong.” I blame the majority of the C# books out there. Most of them, in the chapter on System.Drawing, just tell everyone to draw their stuff in OnPaint() or in response to a paint event. PLEASE, STOP DOING THIS. I’ll explain why.

One should not have a lot going on in one’s OnPaint method. It should be very small, very straight forward. In 95% of my custom controls, my paint event looks something like this:

1
2
3
4
5
protected override void OnPaint(PaintEventArgs e)
{
    if (!isDisposing && backbufferGraphics != null)
        backbufferGraphics.Render(e.Graphics);
}

That’s it. Just two lines. Here’s what’s going on. OnPaint is the .NET equivalent of the Win32 WM_PAINT message being raised. It happens when a region of your control is “invalidated.” Invalidation occurs when Windows thinks your control needs to be redrawn for some reason. Examples include your control being resized, another window moving in front of it, your window losing and regaining focus, etc. Because OnPaint() is called so frequently and unpredictably, it is not wise to have a lot of complex and CPU-intensive operations going on inside of it.

You may be wondering what we do instead. You be smart and efficient about it. Because the drawing logic is often complex and expensive, you’ll want to do it only as often as necessary. This means having an off-screen buffer that you draw to. When it comes time to actually paint your control on to the screen, your control can just go take a look at our off-screen buffer and copy it to the display. Pretty simple. Now, there is added complexity when you consider that you may be drawing to this buffer at the exact same time your control needs to draw it to the screen. In this scenario, your control would have to site around and wait with an invalidated region until you’ve finished drawing to your buffer. What this usually looks like to the end user is an irritating flicker on the control. The flicker they see is a rapid switch between invalidated control regions (which are usually painted pure white, black, or some other random bit of color) and the drawn buffer.

A quick look around the net will reveal that the solution to flicker is “double buffering.” Now, mind you, none of this is a new concept. People have been doing this for about as long as computer graphics have existed. The difference is, it’s a lot easier now. .NET literally makes it as easy as setting a property on your forms or controls. Beyond that, a programmer used to have to actually manage two buffers manually and swap between them. This is more automated with the introduction of the BufferedGraphics and BufferedGraphicsContext classes. Basically, you draw to the BufferedGraphics class, and it takes care of the double buffering for you. Here is an example constructor and buffer creation routine.

Constructor setting up the form’s double buffering properties:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
public DoubleBufferedControl()
{
    InitializeComponent();

    // Set the control style to double buffer.
    this.SetStyle(ControlStyles.AllPaintingInWmPaint | ControlStyles.UserPaint, true);
    this.SetStyle(ControlStyles.SupportsTransparentBackColor, false);
    this.SetStyle(ControlStyles.OptimizedDoubleBuffer, true);

    // Assign our buffer context.
    backbufferContext = BufferedGraphicsManager.Current;
    initializationComplete = true;

    RecreateBuffers();

    Redraw();
}

And here is an example of creating the buffers

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
private void RecreateBuffers()
{
    // Check initialization has completed so we know backbufferContext has been assigned.
    // Check that we aren't disposing or this could be invalid.
    if (!initializationComplete || isDisposing)
    return;

    // We recreate the buffer with a width and height of the control. The "+ 1"
    // guarantees we never have a buffer with a width or height of 0.
    backbufferContext.MaximumBuffer = new Size(this.Width + 1, this.Height + 1);

    // Dispose of old backbufferGraphics (if one has been created already)
    if (backbufferGraphics != null)
        backbufferGraphics.Dispose();

    // Create new backbufferGrpahics that matches the current size of buffer.
    backbufferGraphics = backbufferContext.Allocate(this.CreateGraphics(),
    new Rectangle(0, 0, Math.Max(this.Width, 1), Math.Max(this.Height, 1)));

    // Assign the Graphics object on backbufferGraphics to "drawingGraphics" for easy reference elsewhere.
    drawingGraphics = backbufferGraphics.Graphics;

    // This is a good place to assign drawingGraphics.SmoothingMode if you want a better anti-aliasing technique.

    // Invalidate the control so a repaint gets called somewhere down the line.
    this.Invalidate();
}

Now, there is one critical place where we make sure to call RecreateBuffers(). That is when the control is resized. The buffers we create in RecreateBuffers() are all sized to match the control’s size. If the buffer wasn’t the size of the control, the control would repaint with a large region of invalid graphics. So, just make sure you have a call to RecreateBuffers in OnResize for your control:

1
2
3
4
5
6
protected override void OnResize(EventArgs e)
{
    base.OnResize(e);
    RecreateBuffers();
    Redraw();
}

That’s pretty much all you need to get a custom double buffered control going. You may have noted that I made a few calls to “Redraw().” Redraw() is where I put my actual drawing logic. What goes in Redraw() is the meat of how you render your control. Just remember, call it only when needed. Don’t go and put the call to Redraw() in OnPaint(). That would be against everything this article tried to teach. This method of rendering is very powerful and I’ve created a number of real-time fast-rendering controls with this mechanism. I’ve been using this method for many years now, so it is tried and true. One of the first times I started double buffering on a custom control was for a custom chart and spectrogram I made for some spectrum analyzer software I was working on. Here is a screenshot:

Realtime Graph and Spectrogram

Realtime Graph and Spectrogram

Thanks for reading. If it helps anyone, I’ve attached a very simple sample project below that contains all the code I’ve shown above. If you have any questions or comments, feel free to use the comments below.

Download Sample Project

iPhone Apps for Drummers

There are a lot of iPhone apps out there, and a lot of them are aimed at drummers. There are metronomes, practice tools, tuners, drum machines, recorders, etc. I’ll be honest. I’ve bought a lot of them. Of those I’ve bought or downloaded, I actually use an incredibly small percentage of of them on any sort of regular basis. In fact, I’d wager I’ll never touch 90% of them again. However, some of the ones I use regularly are incredibly useful, so I figured I would share.

Amazing Slow Downer

Amazing Slow Downer

Amazing Slow Downer

Amazing Slow Downer is, hands down, the best tool in my arsenal for learning how to play (or transcribe) other people’s music. What it does is simple in a sense. It slows down the song, but manages to keep the pitch. How much you slow down the song is variable. As you can see from the screenshot, there’s a whole host of sliders you can adjust, and they’re all pretty useful.  Aside from slowing down songs, Amazing Slow Downer is incredibly useful for setting up and repeating difficult parts of songs. At $14.99 at the time of this writing, Amazing Slow Downer is one of the more expensive applications in the iTunes App Store. However, it’s totally worth it. And, compared to the $49.95 the Mac/PC version costs, it doesn’t feel like a bad deal at all.

Setlist Metronome

Setlist Metronome

Setlist Metronome

There are way too many metronomes available for the iPhone. I’ve tried quite a few of them, both paid-for and free. This has been my favorite of the bunch. For a drummer, any metronome that uses only audible cues is pretty worthless. Setlist Metronome is, of course, a metronome with both visual and audible cues (otherwise it wouldn’t be earning my recommendation).  Beyond that, what sets it apart, and earns it its name, is the ability to create a setlist. You define a bunch of tempos and time signatures, load them all in a certain order, and then go play your gig/practice using them. Easy as that! It really doesn’t do much more, but why would you want it to? Keep it simple and useful. This is another one that costs a bit more than most apps  ($7.99 when this was written). Personally, I still find it worth it.

Cleartune – Chromatic Tuner

Cleartune

Cleartune - Chromatic Tuner

I don’t know if this is something all drummers would need or use, but I’m one of those that relies on a tuner when I’m doing my snare and toms, at least to get me started. There are also a lot of tuners out there. This one seemed to be the best (most accurate and quick to respond) of the tuners I tried. It works great on guitars and other “normal” instruments, but it’s quick enough to react to a drum hits too. At $3.99 during this writing, I’d say it is definitely a solid purchase.