Getting started

Creating a JAMS data structure from scratch

First, create the top-level JAMS container:

>>> import jams
>>> jam = jams.JAMS()

A track in JAMS must have a duration (in seconds). For this example, we’ll make up a fake number, but in reality, you would compute the track duration from the source audio.

>>> jam.file_metadata.duration = 8.0

Now we can create a beat annotation:

>>> ann = jams.Annotation(namespace='beat', time=0, duration=jam.file_metadata.duration)
>>> ann.append(time=0.33, duration=0.0, confidence=1, value=1)

Then, we’ll update the annotation’s metadata by directly setting its fields:

>>> ann.annotation_metadata = jams.AnnotationMetadata(data_source='Well paid students')
>>> ann.annotation_metadata.curator = jams.Curator(name='Rincewind',
...                                                email='rincewind@unseen.edu')

Add our new annotation to the jam:

>>> jam.annotations.append(ann)

We can update the annotation at any time, and add a new observation:

>>> ann.append(time=0.66, duration=0.0, confidence=1, value=1)

Once you’ve added all your data, you can serialize the annotation to a string:

>>> jam.dumps(indent=2)
{
  "sandbox": {},
  "annotations": [
    {
      "data": [
        {
          "duration": 0.0,
          "confidence": 1.0,
          "value": 1.0,
          "time": 0.33
        },
        {
          "duration": 0.0,
          "confidence": 1.0,
          "value": 1.0,
          "time": 0.66
        }
      ],
      "annotation_metadata": {
        "annotation_tools": "",
        "curator": {
          "name": "Rincewind",
          "email": "rincewind@unseen.edu"
        },
        "annotator": {},
        "version": "",
        "corpus": "",
        "annotation_rules": "",
        "validation": "",
        "data_source": "Well paid students"
      },
      "namespace": "beat",
      "sandbox": {}
    }
  ],
  "file_metadata": {
    "jams_version": "0.2.0",
    "title": "",
    "identifiers": {},
    "release": "",
    "duration": 8.0,
    "artist": ""
  }
}

Or save to a file using the built-in save function:

>>> jam.save("these_are_still_my.jams")

Reading a JAMS file

Assuming you already have a JAMS file on-disk, say at ‘these_are_also_my.jams’, you can easily read it back into memory:

>>> another_jam = jams.load('these_are_also_my.jams')