This specification defines a simple generic data container, called an
Atom
. An atom:Atom can contain simple primitive types like integers,
floating point numbers, and strings; as well as structured data like lists and
dictionary-like Objects
. An Atom is, with one exception, Plain Old Data
(POD), meaning it can be easily copied (e.g. using memcpy
) and is
suitable for use in real-time code.
Atoms are not limited to the types defined here, but allow implementations to work with any type of POD data at all. This is possible because Atom types are URIs, but mapped to integers using the LV2 URID extension for performance reasons.
Since atoms are simple to copy, communication of any atom is simple to implement without requiring special code for every type of data. For example, plugins that mutually understand a type can be used together in a host that does not understand that type, because the host is only required to copy atoms, not interpret their contents. Similarly, plugins (such as routers, delays, or data structures) can meaningfully process atoms of a type unknown to them.
Atoms can and should be used anywhere values of various types must be stored or transmitted. The port type atom:AtomPort can be used to transmit atoms via ports. An atom:AtomPort that contains an atom:Sequence can be used for sample accurate event communication, such as MIDI, and replaces the earlier LV2 event extension.
Serialisation
Each Atom type defines a binary format for use at runtime, but also a serialisation that is natural to express in Turtle format. Thus, this specification defines a powerful real-time appropriate data model, as well as a portable way to serialise any data in that model. This is particularly useful for inter-process communication, saving/restoring state, and describing values in plugin data files.
Custom Atom Types
While it is possible to define new Atom types for any binary format, the
standard types defined here are powerful enough to describe almost anything.
Implementations SHOULD build structures out of the types provided here, rather
than define new binary formats (e.g. use atom:Tuple or atom:Object rather than
a new C struct
type). Current implementations have support for
serialising all standard types, so new binary formats are an implementation
burden which harms interoperabilty. In particular, plugins SHOULD NOT expect
UI communication or state saving with custom Atom types to work. In general,
new Atom types should only be defined where absolutely necessary due to
performance reasons and serialisation is not a concern.