jams.JAMS

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

Bases: JObject

Top-level Jams Object

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

Create a Jams object.

Parameters:

annotationslist of Annotations: Zero or more Annotation objects
file_metadataFileMetadata (or dict), default=None: Metadata corresponding to the audio file.
sandboxSandbox (or dict), default=None: Unconstrained global sandbox for additional information.

Attributes

type

The type (class name) of a derived JObject type

Methods

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

add(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:

jamJAMS object

Object to add to this jam

on_conflictstr, 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(path_or_file, strict=True, fmt='auto')[source]

Serialize annotation as a JSON formatted stream to file.

Parameters:

path_or_filestr or file-like

Path to save the JAMS object on disk OR An open file descriptor to write into

strictbool

Force strict schema validation

fmtstr [‘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(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_timefloat: The desired start time for slicing in seconds.
end_time: The desired end time for slicing in seconds. Must be greater than start_time.
strictbool: 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(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_timefloat: 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.
strictbool: 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_trimmedJAMS: The trimmed jam with trimmed annotations, returned as a new JAMS object.

validate(strict=True)[source]

Validate a JAMS object against the schema.

Parameters:

strictbool: If True, an exception will be raised on validation failure. If False, a warning will be raised on validation failure.

Returns:

validbool: True if the object passes schema validation. False otherwise.

Raises:

SchemaError: If strict==True and the JAMS object does not match the schema