{"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":"python","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,"search_vec":"'0.3.5':80 'activ':73 'allow':28 'also':54 'annot':18,26,32,44,70,91 'audio':4,86 'base':16 'beat':47 'chord':48 'current':77 'definit':38 'detect':57 'error':56 'eval':67 'evalu':69 'featur':55 'file':34 'formal':22 'format':19 'generic':25 'implement':12 'includ':36 'interfac':64 'jam':1,7 'json':3,15,89 'json-bas':14 'layer':62 'librari':11,53 'like':46 'maintain':74 'metadata':5,88 'mir':66,90 'multipl':31 'music':17,87 'per':33 'provid':20 'python':10,84 'rang':42 'recent':83 'schema':23,37 'segment':49 'standard':6 'store':30 'support':82 'tag':51 'translat':61 'type':45 'valid':58 'version':78,85 'wide':41","created_at":"2026-04-15T18:38:32.959830+00:00","updated_at":"2026-04-16T15:50:16.778410+00:00","problems":[{"fix":"Run `pip install jams` in your terminal to install the library.","cause":"The 'jams' library is not installed in your Python environment or the environment where your script is being run.","error":"ModuleNotFoundError: No module named 'jams'"},{"fix":"Ensure 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.","cause":"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.","error":"ParameterError: Unknown JAMS extension format: \"jams\""},{"fix":"Consult 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.","cause":"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.","error":"NamespaceError: Unknown namespace: 'segment_isophonics'"},{"fix":"Instead 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.","cause":"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()`.","error":"AttributeError: 'Annotation' object has no attribute 'value'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.3.5","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/marl/jams","docs":null,"changelog":null,"pypi":"https://pypi.org/project/jams/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}