jams.JAMS¶

class jams.JAMS(annotations=None, file_metadata=None, sandbox=None)[source]¶

Bases: jams.core.JObject

Top-level Jams Object

__init__(self, annotations=None, file_metadata=None, sandbox=None)[source]¶

Create a Jams object.

Parameters:	annotations : list of Annotations Zero or more Annotation objects file_metadata : FileMetadata (or dict), default=None Metadata corresponding to the audio file. sandbox : Sandbox (or dict), default=None Unconstrained global sandbox for additional information.

Attributes

type The type (class name) of a derived JObject type

Methods

`__init__`(self[, annotations, file_metadata, …])	Create a Jams object.
`add`(self, jam[, on_conflict])	Add the contents of another jam to this object.
`dumps`(self, \\kwargs)	Serialize the JObject to a string.
`keys`(self)	Return a list of the attributes of the object.
`loads`(string)	De-serialize a JObject
`save`(self, path_or_file[, strict, fmt])	Serialize annotation as a JSON formatted stream to file.
`search`(self, \\kwargs)	Search a JAMS object for matching objects.
`slice`(self, start_time, end_time[, strict])	Slice all the annotations inside the jam and return as a new `JAMS` object.
`trim`(self, start_time, end_time[, strict])	Trim all the annotations inside the jam and return as a new `JAMS` object.
`update`(self, \\kwargs)	Update the attributes of a JObject.
`validate`(self[, strict])	Validate a JAMS object against the schema.

add(self, jam, on_conflict='fail')[source]¶

Add the contents of another jam to this object.

Note that, by default, this method fails if file_metadata is not identical and raises a ValueError; either resolve this manually (because conflicts should almost never happen), force an ‘overwrite’, or tell the method to ‘ignore’ the metadata of the object being added.

Parameters:	jam: JAMS object Object to add to this jam on_conflict: str, default=’fail’ Strategy for resolving metadata conflicts; one of [‘fail’, ‘overwrite’, or ‘ignore’].
Raises:	ParameterError if on_conflict is an unknown value JamsError If a conflict is detected and on_conflict=’fail’

save(self, path_or_file, strict=True, fmt='auto')[source]¶

Serialize annotation as a JSON formatted stream to file.

Parameters:	path_or_file : str or file-like Path to save the JAMS object on disk OR An open file descriptor to write into strict : bool Force strict schema validation fmt : str [‘auto’, ‘jams’, ‘jamz’] The output encoding format. If auto, it is inferred from the file name. If the input is an open file handle, `jams` encoding is used.
Raises:	SchemaError If strict == True and the JAMS object fails schema or namespace validation.

See also

JObject.search
AnnotationArray.search

Examples

A simple query to get all beat annotations

>>> beats = my_jams.search(namespace='beat')

slice(self, start_time, end_time, strict=False)[source]¶

Slice all the annotations inside the jam and return as a new JAMS object.

See Annotation.slice for details about how the annotations are sliced.

This operation is also documented in the jam-level sandbox with a list keyed by JAMS.sandbox.slice containing a tuple for each jam-level slice of the form (start_time, end_time).

Since slicing is implemented using trimming, the operation will also be documented in JAMS.sandbox.trim as described in JAMS.trim.

This function also copies over all of the file metadata from the original jam.

Note: slicing will affect the duration of the jam, i.e. the new value of JAMS.file_metadata.duration will be end_time - start_time.

Parameters:

start_time : float: The desired start time for slicing in seconds.
end_time: The desired end time for slicing in seconds. Must be greater than start_time.
strict : bool: When False (default) observations that lie at the boundaries of the slicing range (see Annotation.slice for details), will have their time and/or duration adjusted such that only the part of the observation that lies within the slice range is kept. When True such observations are discarded and not included in the sliced annotation.

Returns:

jam_sliced: JAMS: The sliced jam with sliced annotations, returned as a new JAMS object.

trim(self, start_time, end_time, strict=False)[source]¶

Trim all the annotations inside the jam and return as a new JAMS object.

See Annotation.trim for details about how the annotations are trimmed.

This operation is also documented in the jam-level sandbox with a list keyed by JAMS.sandbox.trim containing a tuple for each jam-level trim of the form (start_time, end_time).

This function also copies over all of the file metadata from the original jam.

Note: trimming does not affect the duration of the jam, i.e. the value of JAMS.file_metadata.duration will be the same for the original and trimmed jams.

Parameters:

start_time : float: The desired start time for the trimmed annotations in seconds.
end_time: The desired end time for trimmed annotations in seconds. Must be greater than start_time.
strict : bool: When False (default) observations that lie at the boundaries of the trimming range (see Annotation.trim for details), will have their time and/or duration adjusted such that only the part of the observation that lies within the trim range is kept. When True such observations are discarded and not included in the trimmed annotation.

Returns:

jam_trimmed : JAMS: The trimmed jam with trimmed annotations, returned as a new JAMS object.

validate(self, strict=True)[source]¶

Validate a JAMS object against the schema.

Parameters:	strict : bool If True, an exception will be raised on validation failure. If False, a warning will be raised on validation failure.
Returns:	valid : bool True if the object passes schema validation. False otherwise.
Raises:	SchemaError If strict==True and the JAMS object does not match the schema