Task namespaces

In JAMS v0.2.0, the concept of task namespaces was introduced. Broadly speaking, a namespace defines the syntax (and some semantics) of a particular type of annotation.

For example, the chord namespace requires that all observed value fields are valid strings within a pre-defined grammar. Similarly, the tempo namespace requires that value fields be non-negative numbers, and the confidence fields lie within the range [0, 1].

JAMS ships with 26 pre-defined namespaces, covering a variety of common music informatics tasks. This collection should not be assumed to be complete, however, and more namespaces may be added in subsequent versions. Please refer to Namespace definitions for a comprehensive description of the existing namespaces.

Namespace specification format

In this section, we’ll demonstrate how to define a task namespace, using tempo as our running example. Namespaces are defined by JSON objects that contain partial JSON schema specifications for the value and confidence fields of the Annotation, as well as additional meta-data to describe the namespace and encoding.

tempo.json is reproduced here:

{"tempo":
    {
        "value": {
            "type": "number",
            "minimum": 0
        },
        "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1.0
        },
        "dense": false,
        "description": "Tempo measurements, in beats per minute (BPM)"
    }
}

The key “tempo” at line 1 is the string with which this namespace will be identified in JAMS objects by the annotation’s namespace field. This string must be a unique identifier.

Lines 3–6 specify the valid contents of the value field for tempo annotations. In this case, values must be numeric and non-negative. Any valid JSON schema definition can be substituted here, allowing for structured observation objects. (See pattern_jku for an example of this.)

Similarly, lines 7–11 specify valid contents of the confidence field. Most namespaces do not enforce specific constraints on confidence, so this block is optional. In the case of tempo, confidence must be a numeric value in the range [0, 1].

Line 12 dense is a boolean which specifies whether the annotation should be densely encoded during serialization or not. There is functionally no difference between dense and sparse encoding, but dense coding is more space-efficient for high-frequency observations such as melody contours.

Finally, line 13 contains a brief description of the namespace and corresponding task.

Local namespaces

The JAMS namespace management architecture is modular and extensible, so it is relatively straightforward to create a new namespace schema and add it to JAMS at run-time:

>>> jams.schema.add_namespace('/path/to/my/new/namespace.json')

Beginning with JAMS 0.2.1, a custom schema directory can be provided by setting the JAMS_SCHEMA_DIR environment variable prior to importing jams. This allows local customizations to be added automatically at run-time without having to manually add each schema file individually.