port-groups
type: Specification
license: mit
name: LV2 Port Groups
shortdesc: Multi-channel groups of LV2 ports.
comment: Defines semantic groupings of LV2 ports
maintainer: Lars Luthman
maintainer: David Robillard

LV2 Port Group
type: Class
subclass of: Restriction
  on property: symbol
  some values from: string
  cardinality: 1
  comment: A pg:Group MUST have exactly one string lv2:symbol. This symbol must be unique according to the same rules as the lv2:symbol for an lv2:Port, where group symbols and port symbols reside in the same namespace. In other words, a group on a plugin MUST NOT have the same symbol as another group or a port on that plugin. Rationale: Hosts or bindings may find it useful to construct an identifier to refer to groups for the same reasons this is useful for ports.
subclass of: Restriction
  on property: Has port with role
  some values from: Role Assignment
  min cardinality: 1
  comment: A Group MUST have at least one role assignment
comment: A grouping of ports that can be logically considered a single "stream", e.g. two audio ports in a group may form a stereo stream. The pg:source predicate can also be used to describe this correspondence between separate ports/groups.

index
type: Property
domain: Role Assignment
range: nonNegativeInteger
comment: Index of a role within some group

Role Assignment
type: Class
comment: A numbered role within some Group.
subclass of: Restriction
  on property: index
  cardinality: 1
  comment: A RoleAssignment MUST have exactly one index.
subclass of: Restriction
  on property: Role
  cardinality: 1
  comment: A RoleAssignment MUST have exactly one role.
comment: All group definitions MUST define the order of channels. Note that this does not have anything to do with port indices, this information is only defined here for use by other extensions. For simply assigning groups and roles to a basic LV2 plugin, index is irrelevant.

Has port with role
type: Property
domain: LV2 Port Group
range: Port role
comment: Indicates that a group always has a port with a particular role.

May have port with role
type: Property
domain: LV2 Port Group
range: Port role
comment: Indicates that a group may have a port with a particular role.

Side-chain of
type: Property
domain: LV2 Port Group
domain: Port
range: LV2 Port Group
range: Port
comment: Indicates that this port or group should be considered a "side chain" of some other port or group. The precise definition of "side chain" depends on the plugin, but in general this group should be considered a modifier to some other group, rather than an independent input itself.

Sub-group of
type: Property
domain: LV2 Port Group
range: LV2 Port Group
comment: Indicates that this group is a child of another group. This property has no meaning with respect to plugin execution, but the host may find this information useful (e.g. to provide a compact user interface). Note that all groups on a plugin MUST have a unique symbol with respect to the plugin as documented for pg:Group, i.e. sub-groups must have a unique symbol among all groups and ports on the plugin.

Source group
type: Property
domain: LV2 Port Group
domain: Port
range: LV2 Port Group
range: Port
comment: Indicates that this port or group should be considered the "result" of some other port or group. This property only makes sense on groups with outputs when the source is a group with inputs. This can be used to convey a relationship between corresponding input and output groups with different types, e.g. a mono->stereo plugin.

Main port group
type: Property
domain: Plugin
range: LV2 Port Group
comment: Indicates that this group should be considered the "main" inputs/outputs of the plugin, e.g. it probably makes sense to just connect main groups and set some controls. A plugin MUST NOT have more than one :mainGroup property. High-level hosts that simply want to insert an plugin in a given stream should use this property to determine where the plugin 'fits'.

In port group
type: Property
domain: Port
range: LV2 Port Group
comment: Indicates that this port is a part of a group of ports on the plugin. Ports that have a meaningful "role" that may be useful to hosts SHOULD also have a :role property, otherwise ports in the group have no meaningful order.

Port role
type: Class
comment: The role of a port with respect to its plugin or group. If the port is a member of a group (has an :inGroup property) the role is relevant with respect to that group. Otherwise the role is relevant with respect to the plugin.

Role
type: Property
range: Port role
comment: Indicates that this port has a particular role with respect to its enclosing plugin or group (whichever is smaller). A port may have several roles if it makes sense to do so (though some Role or Group definition may forbid this).

DiscreteGroup
type: Class
subclass of: LV2 Port Group
comment: "Discrete" channel configurations. These groups are divided into channels where each represents a particular speaker location. The position of sound in one of these groups depends on a particular speaker configuration.

Left
type: Port role

Right
type: Port role

Center
type: Port role

Side
type: Port role

Center Left
type: Port role

Center Right
type: Port role

Side Left
type: Port role

Side Right
type: Port role

Rear Left
type: Port role

Rear Right
type: Port role

Rear Center
type: Port role

Sub (LFE)
type: Port role

Mono
type: Class
subclass of: DiscreteGroup
Has port with role:
  index: 0
  Role: Center

Stereo
type: Class
subclass of: DiscreteGroup
Has port with role:
  index: 0
  Role: Left
Has port with role:
  index: 1
  Role: Right

Mid-Side Stereo
type: Class
subclass of: DiscreteGroup
Has port with role:
  index: 0
  Role: Center
Has port with role:
  index: 1
  Role: Side

3.0 Surround
type: Class
subclass of: DiscreteGroup
Has port with role:
  index: 0
  Role: Left
Has port with role:
  index: 1
  Role: Right
Has port with role:
  index: 2
  Role: Rear Center

4.0 Surround (Quadraphonic)
type: Class
subclass of: DiscreteGroup
Has port with role:
  index: 0
  Role: Left
Has port with role:
  index: 1
  Role: Center
Has port with role:
  index: 2
  Role: Right
Has port with role:
  index: 3
  Role: Rear Center

5.0 Surround (3-2 stereo)
type: Class
subclass of: DiscreteGroup
Has port with role:
  index: 0
  Role: Left
Has port with role:
  index: 1
  Role: Center
Has port with role:
  index: 2
  Role: Right
Has port with role:
  index: 3
  Role: Rear Left
Has port with role:
  index: 4
  Role: Rear Right

5.1 Surround (3-2 stereo)
type: Class
subclass of: DiscreteGroup
Has port with role:
  index: 0
  Role: Left
Has port with role:
  index: 1
  Role: Center
Has port with role:
  index: 2
  Role: Right
Has port with role:
  index: 3
  Role: Rear Left
Has port with role:
  index: 4
  Role: Rear Right
Has port with role:
  index: 5
  Role: Sub (LFE)

6.1 Surround
type: Class
subclass of: DiscreteGroup
Has port with role:
  index: 0
  Role: Left
Has port with role:
  index: 1
  Role: Center
Has port with role:
  index: 2
  Role: Right
Has port with role:
  index: 3
  Role: Side Left
Has port with role:
  index: 4
  Role: Side Right
Has port with role:
  index: 5
  Role: Rear Center
Has port with role:
  index: 6
  Role: Sub (LFE)

7.1 Surround
type: Class
subclass of: DiscreteGroup
Has port with role:
  index: 0
  Role: Left
Has port with role:
  index: 1
  Role: Center
Has port with role:
  index: 2
  Role: Right
Has port with role:
  index: 3
  Role: Side Left
Has port with role:
  index: 4
  Role: Side Right
Has port with role:
  index: 5
  Role: Rear Left
Has port with role:
  index: 6
  Role: Rear Right
Has port with role:
  index: 7
  Role: Sub (LFE)

7.1 Surround (Wide)
type: Class
subclass of: DiscreteGroup
Has port with role:
  index: 0
  Role: Left
Has port with role:
  index: 1
  Role: Center Left
Has port with role:
  index: 2
  Role: Center
Has port with role:
  index: 3
  Role: Center Right
Has port with role:
  index: 4
  Role: Right
Has port with role:
  index: 5
  Role: Rear Left
Has port with role:
  index: 6
  Role: Rear Right
Has port with role:
  index: 7
  Role: Sub (LFE)

AmbisonicGroup
type: Class
subclass of: LV2 Port Group
comment: "Ambisonic" channel configurations. These groups are divided into channels which together represent a position in an abstract n-dimensional space. The position of sound in one of these groups does not depend on a particular speaker configuration; a decoder can be used to convert an ambisonic stream for any speaker configuration.

Ambisonic B stream of horizontal order 1 and peripheral order 0.
type: Class
subclass of: AmbisonicGroup
Has port with role:
  index: 0
  Role: ACN0
Has port with role:
  index: 1
  Role: ACN1
Has port with role:
  index: 2
  Role: ACN3

Ambisonic B stream of horizontal order 1 and peripheral order 1.
type: Class
subclass of: AmbisonicGroup
Has port with role:
  index: 0
  Role: ACN0
Has port with role:
  index: 1
  Role: ACN1
Has port with role:
  index: 2
  Role: ACN2
Has port with role:
  index: 3
  Role: ACN3

Ambisonic B stream of horizontal order 2 and peripheral order 0.
type: Class
subclass of: AmbisonicGroup
Has port with role:
  index: 0
  Role: ACN0
Has port with role:
  index: 1
  Role: ACN1
Has port with role:
  index: 2
  Role: ACN3
Has port with role:
  index: 3
  Role: ACN4
Has port with role:
  index: 4
  Role: ACN8

Ambisonic B stream of horizontal order 2 and peripheral order 1.
type: Class
subclass of: AmbisonicGroup
Has port with role:
  index: 0
  Role: ACN0
Has port with role:
  index: 1
  Role: ACN1
Has port with role:
  index: 2
  Role: ACN2
Has port with role:
  index: 3
  Role: ACN3
Has port with role:
  index: 4
  Role: ACN4
Has port with role:
  index: 5
  Role: ACN8

Ambisonic B stream of horizontal order 2 and peripheral order 2.
type: Class
subclass of: AmbisonicGroup
Has port with role:
  index: 0
  Role: ACN0
Has port with role:
  index: 1
  Role: ACN1
Has port with role:
  index: 2
  Role: ACN2
Has port with role:
  index: 3
  Role: ACN3
Has port with role:
  index: 4
  Role: ACN4
Has port with role:
  index: 5
  Role: ACN5
Has port with role:
  index: 6
  Role: ACN6
Has port with role:
  index: 7
  Role: ACN7
Has port with role:
  index: 8
  Role: ACN8

Ambisonic B stream of horizontal order 3 and peripheral order 0.
type: Class
subclass of: AmbisonicGroup
Has port with role:
  index: 0
  Role: ACN0
Has port with role:
  index: 1
  Role: ACN1
Has port with role:
  index: 2
  Role: ACN3
Has port with role:
  index: 3
  Role: ACN4
Has port with role:
  index: 4
  Role: ACN8
Has port with role:
  index: 5
  Role: ACN9
Has port with role:
  index: 6
  Role: ACN15

Ambisonic B stream of horizontal order 3 and peripheral order 1.
type: Class
subclass of: AmbisonicGroup
Has port with role:
  index: 0
  Role: ACN0
Has port with role:
  index: 1
  Role: ACN1
Has port with role:
  index: 2
  Role: ACN2
Has port with role:
  index: 3
  Role: ACN3
Has port with role:
  index: 4
  Role: ACN4
Has port with role:
  index: 5
  Role: ACN8
Has port with role:
  index: 6
  Role: ACN9
Has port with role:
  index: 7
  Role: ACN15

Ambisonic B stream of horizontal order 3 and peripheral order 2.
type: Class
subclass of: AmbisonicGroup
Has port with role:
  index: 0
  Role: ACN0
Has port with role:
  index: 1
  Role: ACN1
Has port with role:
  index: 2
  Role: ACN2
Has port with role:
  index: 3
  Role: ACN3
Has port with role:
  index: 4
  Role: ACN4
Has port with role:
  index: 5
  Role: ACN5
Has port with role:
  index: 6
  Role: ACN6
Has port with role:
  index: 7
  Role: ACN7
Has port with role:
  index: 8
  Role: ACN8
Has port with role:
  index: 9
  Role: ACN9
Has port with role:
  index: 10
  Role: ACN15

Ambisonic B stream of horizontal order 3 and peripheral order 3.
type: Class
subclass of: AmbisonicGroup
Has port with role:
  index: 0
  Role: ACN0
Has port with role:
  index: 1
  Role: ACN1
Has port with role:
  index: 2
  Role: ACN2
Has port with role:
  index: 3
  Role: ACN3
Has port with role:
  index: 4
  Role: ACN4
Has port with role:
  index: 5
  Role: ACN5
Has port with role:
  index: 6
  Role: ACN6
Has port with role:
  index: 7
  Role: ACN7
Has port with role:
  index: 8
  Role: ACN8
Has port with role:
  index: 9
  Role: ACN9
Has port with role:
  index: 10
  Role: ACN10
Has port with role:
  index: 11
  Role: ACN11
Has port with role:
  index: 12
  Role: ACN12
Has port with role:
  index: 13
  Role: ACN13
Has port with role:
  index: 14
  Role: ACN14
Has port with role:
  index: 15
  Role: ACN15

ControlGroup
type: Class
subclass of: LV2 Port Group
comment: A group representing a set of associated controls.

Amplitude
type: Port role

Attack
type: Port role

Cutoff Frequency
type: Port role

Decay
type: Port role

Delay
type: Port role

Frequency
type: Port role

Hold
type: Port role

Pulse Width
type: Port role

Ratio
type: Port role

Release
type: Port role

Resonance
type: Port role

Sustain
type: Port role

Threshold
type: Port role

Waveform
type: Port role

Controls for a DAHDSR envelope.
type: Class
subclass of: ControlGroup
May have port with role: Delay
May have port with role: Attack
May have port with role: Hold
May have port with role: Decay
May have port with role: Sustain
May have port with role: Release

Controls for an oscillator.
type: Class
subclass of: ControlGroup
May have port with role: Frequency
May have port with role: Amplitude
May have port with role: Waveform
May have port with role: Pulse Width

Controls for a filter.
type: Class
subclass of: ControlGroup
May have port with role: Cutoff Frequency
May have port with role: Resonance

Controls for a compressor.
type: Class
subclass of: ControlGroup
May have port with role: Threshold
May have port with role: Ratio