{"id":6685,"library":"jams","title":"JAMS: A JSON Audio Metadata Standard","description":"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.","status":"active","version":"0.3.5","language":"en","source_language":"en","source_url":"https://github.com/marl/jams","tags":["audio","music","metadata","json","MIR","annotation"],"install":[{"cmd":"pip install jams","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core numerical operations for data storage.","package":"numpy","optional":false},{"reason":"Used for validation of JAMS objects against their schema.","package":"jsonschema","optional":false},{"reason":"Provides DataFrame capabilities for structured data handling (though JamsFrame was removed, Annotation can convert to DataFrame).","package":"pandas","optional":false},{"reason":"Provides evaluation metrics for music information retrieval tasks, integrated with JAMS for annotation evaluation.","package":"mir_eval","optional":false},{"reason":"Data structure for efficient sorted collections.","package":"sortedcontainers","optional":false},{"reason":"Used for decorator utility functions.","package":"decorator","optional":false},{"reason":"Commonly used for audio analysis in examples; not a strict runtime dependency for JAMS itself.","package":"librosa","optional":true}],"imports":[{"note":"The primary container for all JAMS data.","symbol":"JAMS","correct":"import jams\njam = jams.JAMS()"},{"note":"Represents a single annotation layer within a JAMS object.","symbol":"Annotation","correct":"import jams\nannotation = jams.Annotation(namespace='beat')"},{"note":"Metadata pertaining to a specific annotation.","symbol":"AnnotationMetadata","correct":"import jams\nmetadata = jams.AnnotationMetadata(data_source='my_source')"},{"note":"Metadata for the audio file itself.","symbol":"FileMetadata","correct":"import jams\nfile_meta = jams.FileMetadata(duration=120.0)"}],"quickstart":{"code":"import jams\nimport os\n\n# Create a new JAMS object\njam = jams.JAMS()\n\n# Set file metadata\njam.file_metadata.duration = 180.0 # Example duration in seconds\njam.file_metadata.title = 'Example Track'\njam.file_metadata.artist = 'Example Artist'\n\n# Create a new Annotation for beats\nbeat_annotation = jams.Annotation(namespace='beat')\nbeat_annotation.annotation_metadata = jams.AnnotationMetadata(\n    data_source='manual annotation',\n    curator=jams.Curator(name='AI Assistant')\n)\n\n# Add some example beat observations\nbeat_annotation.append(time=0.5, duration=0.0)\nbeat_annotation.append(time=1.0, duration=0.0)\nbeat_annotation.append(time=1.5, duration=0.0)\n\n# Add the beat annotation to the JAMS object\njam.annotations.append(beat_annotation)\n\n# Create a new Annotation for tempo\ntempo_annotation = jams.Annotation(namespace='tempo', time=0, duration=jam.file_metadata.duration)\ntempo_annotation.annotation_metadata = jams.AnnotationMetadata(\n    data_source='estimated',\n    curator=jams.Curator(name='AI Assistant')\n)\ntempo_annotation.append(time=0.0, duration=jam.file_metadata.duration, value=120.0, confidence=1.0)\n\n# Add the tempo annotation to the JAMS object\njam.annotations.append(tempo_annotation)\n\n# Print the JAMS object (its __repr__ is quite informative)\nprint(jam)\n\n# Optionally save to a .jams file\n# jam.save('example.jams')\n# To load:\n# loaded_jam = jams.load('example.jams')","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.3.0"},{"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`.","message":"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.","severity":"breaking","affected_versions":">=0.3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.3.5"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.3.4"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}