Install & Compatibility
Where this runs
tested against v0.3.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 3.767s · 311.5MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 12.2s · import 3.551s · 298MB
311MB installed
● package 311MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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')
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'jams'
The 'jams' library is not installed in your Python environment or the environment where your script is being run.
fixRun `pip install jams` in your terminal to install the library.
ParameterError: Unknown JAMS extension format: "jams"
This error typically occurs when `jams.load()` encounters a JAMS file that is corrupted, uses an unrecognized internal format, or has a file extension that leads the loader to misinterpret its structure.
fixEnsure your JAMS file is valid and consistent with the expected schema for your `jams` library version. If the issue persists, try validating the JAMS file with `jams.validate()` or inspect the file for corruption.
NamespaceError: Unknown namespace: 'segment_isophonics'
You are attempting to create or access a JAMS annotation using a namespace (e.g., 'segment_isophonics') that is not defined or has been deprecated in the version of the `jams` library you are using.
fixConsult the `jams` library's documentation or the `jams.schema` module to find a list of valid and current namespaces. For example, 'segment_isophonics' was renamed to 'segment_open'. Update your code to use a recognized namespace.
AttributeError: 'Annotation' object has no attribute 'value'
You are trying to directly access or set an attribute (like 'value' or 'confidence') on a `jams.Annotation` object, but that specific attribute is not available for the annotation's defined namespace or is handled through specific methods like `append()`.
fixInstead of direct assignment, use the `append()` method to add data to an annotation, passing `value` as a keyword argument if the namespace supports it (e.g., `annotation.append(time=..., duration=..., value=...)`). Always refer to the schema for the specific namespace to understand its data structure.
Upgrade
Version history
0.3.5latest on PyPI · released Jun 18, 2025
Audit
Dependencies
numpyrequiredCore numerical operations for data storage.
jsonschemarequiredUsed for validation of JAMS objects against their schema.
pandasrequiredProvides DataFrame capabilities for structured data handling (though JamsFrame was removed, Annotation can convert to DataFrame).
mir_evalrequiredProvides evaluation metrics for music information retrieval tasks, integrated with JAMS for annotation evaluation.
sortedcontainersrequiredData structure for efficient sorted collections.
decoratorrequiredUsed for decorator utility functions.
librosaoptionalCommonly used for audio analysis in examples; not a strict runtime dependency for JAMS itself.