JAMS: A JSON Audio Metadata Standard

0.3.5 · active · verified Wed Apr 15

JAMS is a Python library implementing a JSON-based music annotation format, providing a formal schema for generic annotations. It allows for storing multiple annotations per file and includes schema definitions for a wide range of annotation types like beats, chords, segments, and tags. The library also features error detection, validation, and a translation layer to interface with `mir_eval` for evaluating annotations. It is actively maintained, with the current version being 0.3.5, and supports recent Python versions.

Warnings

breaking The `JamsFrame` class was removed in version 0.3.0 in favor of a simpler observation storage structure. Code directly using `pandas.DataFrame` methods on `Annotation.data` will break.
Fix: Migrate to directly manipulating `Annotation` objects and using methods like `Annotation.to_interval_values()` or `Annotation.to_dataframe()` for DataFrame conversion when needed. The underlying data structure is now simpler, and direct observation handling is preferred.
breaking The behavior of `jams.import_lab()` changed in version 0.3.0. It now returns a single `Annotation` object instead of constructing and returning a full `JAMS` object.
Fix: Adjust code that expects a full `JAMS` object from `import_lab` to handle the returned `Annotation` object. You may need to create a `JAMS` object manually and append the imported `Annotation`.
gotcha Internal changes in v0.3.5 migrated from the deprecated `imp` package to `importlib` and replaced `np.float_` with `np.float64`. While primarily internal, advanced users interacting with JAMS's internals or specific numerical types might observe changes.
Fix: Ensure your environment uses modern Python 3, and generally avoid direct reliance on internal implementation details. If working with numerical types exposed by JAMS, prefer `numpy.float64` for consistency.
gotcha Starting from version 0.3.4, `jams` explicitly requires `jsonschema >= 3.0` (and `numpy >= 1.20.0`, `pandas >= 1.2.0`, `mir_eval >= 0.8.2`, `sortedcontainers >= 2.1.0`, `decorator` as per v0.3.5 `setup.cfg`). Using older versions of these dependencies might lead to validation or runtime issues.
Fix: Upgrade `jsonschema` and other core dependencies (numpy, pandas, mir_eval, sortedcontainers, decorator) to the specified versions or newer to ensure compatibility and proper functionality.

Install

pip install jams Install stable version

Imports

JAMS
```
import jams
jam = jams.JAMS()
```
The primary container for all JAMS data.
Annotation
```
import jams
annotation = jams.Annotation(namespace='beat')
```
Represents a single annotation layer within a JAMS object.

AnnotationMetadata

import jams
metadata = jams.AnnotationMetadata(data_source='my_source')

Metadata pertaining to a specific annotation.

FileMetadata

import jams
file_meta = jams.FileMetadata(duration=120.0)

Metadata for the audio file itself.

Quickstart

This quickstart demonstrates how to create a `jams.JAMS` object, populate its `file_metadata`, and add `Annotation` objects for 'beat' and 'tempo'. It shows how to add individual observations to annotations and structure the metadata. The example uses placeholder values to avoid external dependencies like `librosa` for initial setup.

import jams
import os

# Create a new JAMS object
jam = jams.JAMS()

# Set file metadata
jam.file_metadata.duration = 180.0 # Example duration in seconds
jam.file_metadata.title = 'Example Track'
jam.file_metadata.artist = 'Example Artist'

# Create a new Annotation for beats
beat_annotation = jams.Annotation(namespace='beat')
beat_annotation.annotation_metadata = jams.AnnotationMetadata(
    data_source='manual annotation',
    curator=jams.Curator(name='AI Assistant')
)

# Add some example beat observations
beat_annotation.append(time=0.5, duration=0.0)
beat_annotation.append(time=1.0, duration=0.0)
beat_annotation.append(time=1.5, duration=0.0)

# Add the beat annotation to the JAMS object
jam.annotations.append(beat_annotation)

# Create a new Annotation for tempo
tempo_annotation = jams.Annotation(namespace='tempo', time=0, duration=jam.file_metadata.duration)
tempo_annotation.annotation_metadata = jams.AnnotationMetadata(
    data_source='estimated',
    curator=jams.Curator(name='AI Assistant')
)
tempo_annotation.append(time=0.0, duration=jam.file_metadata.duration, value=120.0, confidence=1.0)

# Add the tempo annotation to the JAMS object
jam.annotations.append(tempo_annotation)

# Print the JAMS object (its __repr__ is quite informative)
print(jam)

# Optionally save to a .jams file
# jam.save('example.jams')
# To load:
# loaded_jam = jams.load('example.jams')

view raw JSON →