Key Text Renderer beaTlet

Starting with version 4.0.4, beaTunes allows the definition of custom renderers for its tonal key values. This means you can make beaTunes display any value you want for - say - C Major. Which renderer is used can be configured in the beaTunes general preferences under the heading Key Display Format.

To write your own renderer you merely have to implement the interface KeyTextRenderer.

Here's an example. To install one of the beaTlets, simply place it as a file called CustomKeyRenderer.py, CustomKeyRenderer.rb, CustomKeyRenderer.js, or CustomKeyRenderer.groovy into the plugin directory and restart beaTunes.

# Jython

from com.tagtraum.audiokern.key import Key
from com.tagtraum.beatunes import KeyTextRenderer

class CustomKeyRenderer(KeyTextRenderer):

    # Create a textual representation for a Key object.
    def toKeyString(self, key):
        # key.ordinal is a number starting with C Major = 0 and A Minor = 0,
        # then following the order in the Circle of Fifths.
        # Let's shift by 8 and make sure 0 is converted to 12.
        i = (key.ordinal() + 8) % 12
        i = 12 if i==0 else i
        # i = i == 0 ? 12 : i
        ab = "A" if key.isMinor() else "B"
        # create the final string
        return str(i) + ab

    # Create a tooltip representation for a key object.
    # This may also include html-tags.
    def toToolTip(self, key):
        return self.toKeyString(key)

    # Short name of this renderer. To be used in the user interface.
    def getName(self):
        return "Custom.py"

// Groovy

import com.tagtraum.audiokern.key.Key
import com.tagtraum.beatunes.KeyTextRenderer

class CustomKeyRenderer implements KeyTextRenderer {

    /**
     * Create a textual representation for a Key object.
     *
     * @param key key
     * @return textual representation
     */
    def String toKeyString(Key key) {
        // key.ordinal() is a number starting with C Major = 0 and A Minor = 0,
        // then following the order in the Circle of Fifths.
        // Let's shift by 8 and make sure 0 is converted to 12.
        int i = (key.ordinal() + 8) % 12
        i = i == 0 ? 12 : i
        String ab = key.isMinor() ? "A" : "B"
        // create the final string
        return "$i$ab"
    }

    /**
     * Create a tooltip representation for a key object.
     * This may also include html-tags.
     *
     * @param key key
     * @return tooltip representation
     */
    def String toToolTip(Key key) {
        toKeyString(key)
    }

    /**
     * Short name of this renderer. To be used in the user interface.
     *
     * @return name
     */
    def String getName() {
        "Custom.groovy"
    }

}

# JRuby

require 'java'

java_import com.tagtraum.audiokern.key.Key
java_import com.tagtraum.beatunes.KeyTextRenderer

class CustomKeyRenderer

# Implement KeyTextRenderer interface
include Java::com.tagtraum.beatunes.KeyTextRenderer

    # Create a textual representation for a key object.
    def toKeyString(key)
        # key.ordinal is a number starting with C Major = 0 and A Minor = 0,
        # then following the order in the Circle of Fifths.
        # Let's shift by 8 and make sure 0 is converted to 12.
        i = (key.ordinal + 8) % 12
        i = i == 0 ? 12 : i
        ab = key.isMinor ? "A" : "B"
        # create the final string
        return "#{i}#{ab}"
    end

    # Create a tooltip representation for a key object.
    # This may also include html-tags.
    def toToolTip(key)
        return toKeyString(key)
    end

    # Short name of this renderer. To be used in the user interface.
    def getName()
        return "Custom.rb"
    end

end

// JavaScript

/*
 * These type vars basically act as imports for Java classes.
 */
var KeyTextRenderer = Java.type("com.tagtraum.beatunes.KeyTextRenderer");

var beatlet = new KeyTextRenderer() {

    /* Create a textual representation for a Key object. */
    toKeyString: function(key) {
        // key.ordinal() is a number starting with C Major = 0 and A Minor = 0,
        // then following the order in the Circle of Fifths.
        // Let's shift by 8 and make sure 0 is converted to 12.
        var i = (key.ordinal() + 8) % 12
        i = i == 0 ? 12 : i
        var ab = key.isMinor() ? "A" : "B"
        // create the final string
        return "" + i + ab;
    },

    /* Create a tooltip representation for a key object. */
    toToolTip: function(key) {
        return beatlet.toKeyString(key);
    },

    /* Short name of this renderer. To be used in the user interface. */
    getName: function() {
        return "Custom.js";
    }
}

// Put "beatlet" into the last line, so that it is returned to beaTunes
// when this script is eval'd.
beatlet;

Other beaTlet samples:

• Getting Started
• Context Action
• Library Batch Action
• Playlist Exporter
• Song Analysis Task
• beaTlet Plugin Descriptor
• Song Context View
• Song Property Analyzer

All sample beaTlets are also on GitHub .