Skip to content

The Nendo Collection¤

Together with the NendoTrack, the class NendoCollection is an instrumental object in Nendo Core. In essence, it's an ordered list of NendoTrack objects and provides various functions that make it easy to work with large numbers of audio artifacts at once and to group them logically. For example, a NendoCollection could be an album, a playlist, a set of stems obtained from a specific track, a dataset used to train a model, and so on.

Developer info

If you are a developer, you might as well just directly dive into the API Referece. This page looks at the basic concepts from a user's perspective.

Fields

Field Type Description
id uuid The unique ID of the collection.
uder_id uuid The ID of the user who "owns" the collection.
name str The name of the collection
description str A description of the collection
collection_type str A free-form type descriptor that can be used by developers to further differentiate between different kinds of collection objects. Unless explicitly set by the developer, "collection" is used as a placeholder value.
visibility Visibility A special field that can be used by developers to assign different visibilities to collections that can be used to isolate collections between users. Possible values are public, private and deleted.
meta dict A dictionary that can be used to store additional metadata related to the collection.

Manually changing fields

It is not recommended to overwrite the fields mentioned in the above table manually! Instead, you should be using the functions described in the following paragraphs. If you end up manipulating the fields directly, be aware that things might break and that you need to manually persist any changes by saving the track.

Adding, accessing and removing tracks

Example

# collection = ...
# track = ...
collection.add_track(track.id)

To get a list of all tracks contained in a given collection, use the collection.tracks() shorthand:

Example

# collection = ...
all_collection_tracks = collection.tracks()
# all_collection_tracks is now a list of NendoTracks

Collection size

To count the number of tracks in a given collection, you can simply use len(collection).

Example

# collection = ...
# track = ...
collection.remove_track(track.id)

Saving, exporting and deleting a collection

When you change a collection by writing to any of its fields directly or delete the in-memory object by using python's del collection, the changes are not persisted to the nendo library. You have to call the corresponding collection functions to persist your changes:

Example

# collection = ...
collection.save()

A collection can be exported to directory in a given format using the NendoCollection.export() function. The filenames will be automatically generated based on the track's original_filename, the filename_suffix (which is a function parameter) and the desired file_format.

Example

# collection = ...
collection.export(
    export_path="/path/to/export/to/",
    filename_suffix="my_collection",
    file_format="wav",
)
# the resulting filenames will follow the pattern
# "/path/to/export/to/{original_filename}_my_collection_{timestamp}.wav"

Supported formats

When exporting a track this way, the supported formats are wav, mp3 and ogg.

Example

# collection = ...
collection.delete()
# Now, the collection has been removed from the nendo library.
# To also delete the object from memory, call:
del collection

Working with relationships

As stated above, it is possible for collections in Nendo Core to have relationships to other collections, as well as to tracks. The following functions can be used to add and check for relationships between collections.

To add a new collection to nendo that has a relationship to an existing given collection:

Example

# collection_1 = ...
# track_1 = ...
collection_2 = collection_1.add_related_collection(
    track_ids=[track_1.id],
    name="related collection",
    description="collection with a relationship to another collection",
)

To check whether a NendoCollection has any relationships, you can use:

Example

>>> # collection = ...
>>> collection.has_relationship()
True

And to check only for a specific relationship_type:

Example

>>> # collection = ...
>>> track.has_relationship(relationship_type="stem")
False

To check whether a given collection has a relationship to another given collection:

Example

>>> # collection_1 = ...
>>> # collection_2 = collection_1.add_related_collection(...)
>>> collection_1.has_related_collection(collection_2.id)
True

The NendoCollection.related_collections field contains a list of NendoRelationship objects. To obtain a list of all NendoCollection objects that are connected to the current collection by means of a NendoRelationship, you can use the NendoCollection.get_related_collections() method.

Example

# collection = ...
related_collections = collection.get_related_collections()

Please refer to the API reference to see the full list of parameters for this function.

Running a plugin on a collection

To run a plugin on a given NendoCollection, you can use the NendoCollection.process() function. The following example will run the classify_core plugin on all tracks in the given collection:

Example

# collection = ...
collection.process("classify_core")

Working with a collection's metadata¤

Collections in nendo have metadata attached to them, in the form of the NendoCollection.meta dictionary. For example, upon importing track into the nendo library from a file, its parsed ID3 information is stored to NendoCollection.meta.

Note

The NendoCollection.meta field is a normal dictionary, whose fields can be accessed simply via collection.meta['source'] and added via collection.meta.update({"source": "internet"}). However, manipulating the meta dictionary directly like that will not persist the changes to the nendo library, which is why the functions below exist and should be used: They will take care of persisting any changes to the meta dictionary into the nendo library.

Arbitrary metadata can be added to NendoCollection.meta by passing a dictionary with the desired key: value pairs:

Example

# collection = ...
collection.set_meta({"source": "internet"})

The NendoCollection.meta field is a normal dictionary, whose fields can be accessed simply via collection.meta['source']. However, there is also a convenience function that will return None if the key can not be found (instead of raising a KeyError):

Example

>>> # collection = ...
>>> existing_meta_value = collection.get_meta("source")
>>> print(existing_meta_value)
'internet'
>>> missing_meta_value = collection.get_meta("something")
>>> print(missing_meta_value)
>>>

To check whether a given collection has metadata belonging to a specific key:

Example

>>> # collection = ...
>>> collection.has_meta("source")
True
>>> collection.has_meta("something")
False

To remove a specific field from a collection's metadata:

Example

# collection = ...
collection.remove_meta("album")

Success

That's all you need to know about the NendoCollection. Next up, get familiar with the nendo library.