+
+#### Table 55. *HangingPoint Attributes*
+
+| XML Attribute Name | Value Type | Description |
+|----|----|----|
+| Name | [Name](#user-content-attrtype-name ) | The unique name of the geometry. |
+| Model | [Name](#user-content-attrtype-name ) | Link to the corresponding model. |
+| Position | [Matrix](#user-content-attrtype-matrix ) | Relative position of geometry; Default value: Identity Matrix |
+
+The hanging point geometry has the same children types as the geometry
collect (see [table 34](#user-content-table-34 )).
+### Geometry Type Speaker
+
+This type of geometry is used to describe a speaker in a audio device. (XML node `
`). The currently
+defined XML attributes of a speaker geometry are specified in
+[table 55](#user-content-table-XX ).
+
+
+
+
+#### Table XX. *Speaker Attributes*
+
+| XML Attribute Name | Value Type | Description |
+|----|----|----|
+| Name | [Name](#user-content-attrtype-name ) | The unique name of the geometry. |
+| Model | [Name](#user-content-attrtype-name ) | Link to the corresponding model. |
+| Position | [Matrix](#user-content-attrtype-matrix ) | Relative position of geometry; Default value: Identity Matrix |
+| LinkedConsumer | [Node](#user-content-attrtype-node ) | Name of the Wire Geometry that this speaker is connected to. Need to an consumer type. |
+| Impedance | [Float](#user-content-attrtype-float ) | Nominal impedance of the speaker, Ohms. |
+| VerticalCoverageUp | [Float](#user-content-attrtype-float ) | Vertical Coverage of the sound angle ?? (todo: define the axis) direction. (Degrees) Note that this values are defined in the Global Coordinate System of the GDTF. |
+| VerticalCoverageDown | [Float](#user-content-attrtype-float ) | Vertical Coverage of the sound angle ?? (todo: define the axis) direction. (Degrees) Note that this values are defined in the Global Coordinate System of the GDTF. |
+| HorizontalCoverageLeft | [Float](#user-content-attrtype-float ) | Horizontal Coverage of the sound angle ?? (todo: define the axis) direction. (Degrees) Note that this values are defined in the Global Coordinate System of the GDTF. |
+| HorizontalCoverageRight | [Float](#user-content-attrtype-float ) | Horizontal Coverage of the sound angle ?? (todo: define the axis) direction. (Degrees) Note that this values are defined in the Global Coordinate System of the GDTF. |
+| SoundAngleRotationMax | | [Float](#user-content-attrtype-float ) |Maximum rotation of the sound dispersion around the speaker axis ?? which axis |
+| FrequencyRangeMin | [Float](#user-content-attrtype-float ) | Minimal frequency of the speaker at the -6 dB mark. |
+| FrequencyRangeMax | [Float](#user-content-attrtype-float ) | Maximal frequency of the speaker at the -6 dB mark. |
+| MaxSPL | [Float](#user-content-attrtype-float ) | Maximum sound pressure level measured at 1 meter from the speaker. The value is interpreted together with the SPL format attributes below. |
+
+#### Table XX. *MaxSPL Attributes*
+| XML Attribute Name | Value Type | Description |
+|----|----|----|
+|ExcitationSignal | [String](#user-content-attrtype-string) | Pink noise, IEC60268, EIA426B, AES75 (enums?)|
+|FrequencyWeighting | [String](#user-content-attrtype-string) | None, A-Weighting, C-Weighting (enums?)|
+|Unit | [String](#user-content-attrtype-string) | DBZ, dB, DBSPL, dBA, dBC (enums?)|
+|UnitMark | [String](#user-content-attrtype-string) | Leq, Laeq, LCeq, F, S |
+|TimeWeighting | [String](#user-content-attrtype-string) | Fast, Slow, Leq, Peak, (enums?)|
+
+
+
+TODO: Define default orientation of the speaker. Clarify if the values are for one speaker object ("speaker") or for the whole "speaker box". (Needed for MVR linking to the SoundAngleRotationMax and for the LinkedConsumer )
+
+
## DMX Mode Collect
### General
diff --git a/mvr-spec.md b/mvr-spec.md
index 657e49dc..9bd5fd1d 100644
--- a/mvr-spec.md
+++ b/mvr-spec.md
@@ -123,6 +123,7 @@ as a prefix to denote negative numbers. E.g. `15` or `-6`|
| Vector | Three Float values separated by ',' defining a 3D vector's X, Y, and Z components.
Eg `1.0,2.0,3.0`|
| FileName | The case-sensitive name of a file within the archive including the extension.
The filename must not contain any FAT32 or NTFS reserved characters.
The extension is delimited from the base name by full stop '.' and the base name shall not be empty.
It is recommended to limit filenames to the POSIX "Fully Portable Filenames" character set: [A-Z], [a-z], [0-9], the symbols '\_' (U+005F), '-' (U+002D) and a maximum of one '.' (U+002E)
Eg `My-Fixture_5.gdtf`|
| CIE Color | CIE 1931 xyY absolute color point.
Formatted as three Floats `x,y,Y`
Eg `0.314303,0.328065,87.699166`|
+|Vector3 | {float,float,float} | Vector with 3 float components|
| IPv4 Address | Common IPv4 Address in the format of dotted decimal notation.
Eg `192.168.1.10` |
| IPv6 Address | Common IPv6 Address in the format of hexadecimal notation.
Eg `2001:0db8:85a3:0000:0000:8a2e:0370:7344` |
@@ -367,6 +368,7 @@ The child list (Table 18) contains a list of the following nodes:
| [Truss](#node-definition-truss) | A definition of a truss. |
| [VideoScreen](#node-definition-videoscreen) | A definition of a video screen. |
| [Projector](#node-definition-projector) | A definition of a projector. |
+| [ListeningPlane](#node-definition-listeningplane) | A definition of a audio listening plane. |
## Node Definition for Parametric Objects
@@ -800,6 +802,179 @@ EXAMPLE An example of a node definition is shown below:
```
+## Node Definition: ListeningPlane
+
+This node defines a listening plane object. The defined ListeningPlane Node Attributes are specified in Table XX.
+
+Node name: `ListeningPlane`
+
+##### Table XX — *ListeningPlane Node Attributes*
+
+| Attribute Name | Attribute Value Type | Default Value when Optional | Description |
+| -------------- | --------------------------------------- | --------------------------- | ------------------------------------ |
+| uuid | [UUID](#user-content-attrtype-uuid) | Not Optional | The unique identifier of the object. |
+| name | [String](#user-content-attrtype-string) | Empty | The name of the object. |
+| AudioDescriptionFile | [FileName](#user-content-attrtype-filename) | Empty | The file name, including extension, of the external XML file in the archive. The file contains a `ListeningPlaneHeatMaps` root node with one or more listening-plane heat maps. |
+
+The child list (Table XX) contains a list of one of the following nodes:
+
+##### Table XX — *ListeningPlane Node Childs*
+
+| Child Node | Allowed Count | Value Type | Description |
+| ------------------------------------------------- | ------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Matrix](#node-definition-matrix) | 0 or 1 | | The location of the object inside the parent coordinate system. |
+| [Classing](#node-definition-class) | 0 or 1 | [UUID](#user-content-attrtype-uuid) | The Class the object belongs to. |
+| [Geometries](#node-definition-geometries) | 1 | | The geometry that represents the listening-plane surface. The geometry is used as the spatial target for calculation and result mapping. |
+| GridSpacingX | 0 or 1 | [Float](#user-content-attrtype-float) | Spacing of the measurement grid in the X direction in mm. |
+| GridSpacingY | 0 or 1 | [Float](#user-content-attrtype-float) | Spacing of the measurement grid in the Y direction in mm. |
+
+EXAMPLE An example of a node definition is shown below:
+```xml
+
+
+
+
+ 261F2B44-373C-491C-8D6A-316295DE9B6A
+
+```
+
+## Node Definition: ListeningPlaneHeatMaps
+
+This node defines the root element of the external listening-plane audio description file.
+
+Node name: `ListeningPlaneHeatMaps`
+
+The child list (Table XX) contains a list of the following nodes:
+
+##### Table XX — *ListeningPlaneHeatMaps Node Childs*
+
+| Child Node | Allowed Count | Attribute Value Type | Description |
+| ------------------------------------------------------------- | ------------- | -----------------------------------------------| -------------------------------------- |
+| [ListeningPlaneHeatMap](#node-definition-listeningplaneheatmap) | 1 or more | | A heat map for a specific frequency. |
+| [Classing](#node-definition-class) | 0 or 1 | [UUID](#user-content-attrtype-uuid) | The Class the object belongs to. |
+
+## Node Definition: ListeningPlaneHeatMap
+
+This node defines a listening-plane heat map at one frequency.
+
+Node name: `ListeningPlaneHeatMap`
+
+##### Table XX — *ListeningPlaneHeatMap Node Attributes*
+
+| Attribute Name | Attribute Value Type | Default Value when Optional | Description |
+| -------------- | --------------------------------------- | --------------------------- | --------------------------------------------------------- |
+| Frequency | [Float](#user-content-attrtype-float) | Not Optional | Reports the frequency of the calculated results in Hz. |
+| Units | [Enum](#user-content-attrtype-enum) | Not Optional | Measurement units. DBZ, dB, dBSPL, dBA, dBC |
+
+The child list (Table XX) contains a list of the following nodes:
+
+##### Table XX — *ListeningPlaneHeatMap Node Childs*
+
+| Child Node | Allowed Count | Description |
+| --------------------------------------------- | ------------- | --------------------------------------------------------------------------- |
+| [Face](#node-definition-face) | 1 or more | A triangular heat-map face. |
+
+
+## Node Definition: Face
+
+This node defines one triangular face of a listening-plane heat map.
+
+Node name: `Face`
+
+##### Table XX — *Face Node Attributes*
+
+| Attribute Name | Attribute Value Type | Default Value when Optional | Description |
+| -------------- | --------------------------------------- | --------------------------- | --------------------------------------------------------- |
+| Amplitude | [Float](#user-content-attrtype-float) | 0 | Relative volume level represented by this face. |
+
+The child list (Table XX) contains a list of the following nodes:
+
+##### Table XX — *Face Node Childs*
+
+| Child Node | Allowed Count | Description |
+| ------------------------------------------- | ------------- | -------------------------------------------- |
+| [Vertex](#node-definition-vertex) | 3 | The three vertices of the triangular face. |
+| [Color](#node-definition-color) | 1 | The face color used to represent the value. |
+
+
+## Node Definition: Vertex
+
+This node defines a 3D vertex used by a listening-plane heat-map face.
+
+Node name: `Vertex`
+
+The defined Vertex Node Value Types are specified in Table XX.
+
+##### Table XX — *Vertex Node Value Types*
+
+| Value Type | Default Value When Missing | Description |
+| --------------------------------------- | -------------------------- | -------------------------------------- |
+| [Vector3](#user-content-attrtype-vector3) | Not Optional | The vertex position in millimeters. |
+
+## Node Definition: Color
+
+This node defines a CIE color used by a listening-plane heat-map face.
+
+Node name: `Color`
+
+The defined Color Node Value Types are specified in Table XX.
+
+##### Table XX — *Color Node Value Types*
+
+| Value Type | Default Value When Missing | Description |
+| --------------------------------------- | -------------------------- | -------------------------------------- |
+| [CIE Color](#user-content-attrtype-ciecolor) | Not Optional | The face color used to represent the value. |
+
+EXAMPLE An example of a node definition is shown below:
+```xml
+
+
+ E61F2E44-373C-491C-8D6A-316295DE9B6A
+
+ 0,0,0
+ 11800,0,0
+ 11800,-31600,0
+ 0.314303,0.328065,87.699166
+
+
+ 0,0,0
+ 11800,-31600,0
+ 0,-31600,0
+ 0.314303,0.328065,87.699166
+
+
+
+```
+
+## Node Definition: Speaker
+
+This node defines a Speaker object. The defined Speaker Node Attributes are specified in Table XX.
+
+Node name: `Speaker`
+
+##### Table XX — *Speaker Node Attributes*
+
+| Attribute Name | Attribute Value Type | Default Value when Optional | Description |
+| -------------- | --------------------------------------- | --------------------------- | ------------------------------------ |
+| uuid | [UUID](#user-content-attrtype-uuid) | Not Optional | The unique identifier of the object. |
+| name | [String](#user-content-attrtype-string) | Empty | The name of the object. |
+
+The child list (Table XX) contains a list of one of the following nodes:
+
+##### Table XX — *Speaker Node Childs*
+
+| Child Node | Allowed Count | Value Type | Description |
+| ------------------------------------------------- | ------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Matrix](#node-definition-matrix) | 0 or 1 | | The location of the object inside the parent coordinate system. |
+| [Classing](#node-definition-class) | 0 or 1 | [UUID](#user-content-attrtype-uuid) | The Class the object belongs to. |
+| GDTFSpec | 0 or 1 | [FileName](#user-content-attrtype-filename) | The name of the file containing the GDTF information for this object, conforming to the DIN SPEC 15800. |
+| [Addresses](#node-definition-addresses) | 0 or 1 | | The container for DMX Addresses for this object. |
+| [Alignments](#node-definition-alignments) | 0 or 1 | | The container for Alignments for this object. |
+| [CustomCommands](#node-definition-customcommands) | 0 or 1 | | The container for custom command for this object. |
+| [Overwrites](#node-definition-overwrites) | 0 or 1 | | The container for overwrites for this object. |
+| [Connections](#node-definition-connections) | 0 or 1 | | The container for connections for this object. |
+| [ChildList](#node-definition-childlist) | 0 or 1 | | A list of graphic objects that are part of the layer. |
+| [Rotation] (#node-definition-float) | 0 or 1 | | Rotation of the internal sound source. |
## Other Node Definition
@@ -1779,4 +1954,3 @@ UUIDs are randomly generated numbers which are, practically speaking, unique and
One of the most important aspects of UUIDs in MVR is that they are persistent. A UUID should identify an item throughout its entire life cycle. This means that if a document is exported, then objects should have the same UUID every time an export is performed.
One use case for UUIDs is importing or merging MVRs into an existing document. This is one reason that persistent UUIDs are valuable. If you export an MVR from one program, open it in another, and make modifications, then you may want to incorporate those changes into the original document. By cross referencing UUIDs, you can avoid creating duplicate objects and instead update existing ones.
UUIDs are also used inside of the MVR file format as a form of reference. For example, a symbol instance shall refer to a symbol definition. Because the symbol definition is given a UUID, the symbol instance can reference its symbol through the use of this UUID.
-
diff --git a/proposal/audio-support/proposal.md b/proposal/audio-support/proposal.md
new file mode 100644
index 00000000..2fc165b3
--- /dev/null
+++ b/proposal/audio-support/proposal.md
@@ -0,0 +1,159 @@
+# Support for Audio Devices in MVR and GDTF
+
+## Linked Issue
+
+
+# Problem
+
+We want to fully express audio devices in GDTF and MVR.
+
+We need to express the relevant data for:
+- Speakers
+- Amplifiers
+- Signal Processors
+- Cabling
+- Power Calculation
+- Networking
+
+
+# Proposal
+
+
+## GDTF
+
+### New Geometry Type Speaker
+
+We will add a new geometry type `Speaker`. This represents one speaker inside the device and acts as the origin of the audio source. By default, an audio device with two "real-world" speakers can have one GDTF `Speaker` geometry if the properties for visualization and planning are combined.
+
+The attributes in addition to the default geometry attributes are:
+
+| Attribute Name | Value Type / Unit | Description |
+|----|----|----|
+| Frequency Min | Number / Hertz | Minimal frequency of the speaker at the -6 dB mark. |
+| Frequency Max | Number / Hertz | Maximal frequency of the speaker at the -6 dB mark. |
+| Sound Angle Horizontal Left | Number / Degree | Horizontal dispersion angle to the left side of the speaker axis. |
+| Sound Angle Horizontal Right | Number / Degree | Horizontal dispersion angle to the right side of the speaker axis. |
+| Sound Angle Vertical Up | Number / Degree | Vertical dispersion angle above the speaker axis. |
+| Sound Angle Vertical Down | Number / Degree | Vertical dispersion angle below the speaker axis. |
+| Sound Angle Rotation | Number / Degree | Rotation of the sound dispersion around the speaker axis. This allows asymmetric dispersion, for example an asymmetric sound field rotated by 45 degrees. |
+| Max SPL | Number | Maximum sound pressure level measured at 1 meter from the speaker. The value is interpreted together with the SPL format attributes below. |
+| Max SPL Excitation Signal | Enum | `PinkNoise`, `IEC60268ProgramSimulationNoise`, `EIA426BLoudspeakerTestSignal`, `AES75MNoise`. |
+| Max SPL Frequency Weighting | Enum | `None`, `A`, `C`. |
+| Max SPL Level Unit | Enum | `dB`, `dBZ`, `dBSPL`, `dBA`, `dBC`. |
+| Max SPL Time Weighting | Enum | `Fast`, `Slow`, `Leq`, `Peak`. |
+| Max SPL Time Unit | Enum | `F`, `S`, `Leq`, `LAeq`, `LCeq`. |
+| Impedance | Number / Ohm | Nominal impedance of the speaker. |
+
+TODO: define defaults, exact attribute names.
+
+Sound angles are intentionally not defined as adjustable ranges in this proposal. The proposal defines the actual sound dispersion with independent left, right, up, and down angles plus one rotation value. This supports asymmetric dispersion without requiring separate min/max angle ranges.
+
+The SPL excitation signal, frequency weighting, level unit, time weighting, and time unit are independent metadata fields and can be used in any valid combination. The format only describes the stored value; applications should not convert the value when the format changes. If an application changes the SPL format for an existing value, it should clear the value and require a new value to be entered.
+
+### New Geometry Type Listening Plane
+
+We will add a new geometry type `ListeningPlane`. A listening plane defines an infinitesimally thin area that can be used to calculate acoustic data. The listening plane is placed in the GDTF hierarchy like other geometries, so spots of interest can be defined directly in a GDTF. Example use cases are audience areas or the ear position of a person sitting in a chair.
+
+A listening plane is defined by a referenced `Geometry3D` file. This allows a polygon with any number of points instead of a fixed set of parametric shapes. The surface has no height range, width, depth, or volume; it is a single thin layer located by the geometry transform.
+
+Example:
+
+```xml
+
+
+
+
+
+```
+
+The referenced geometry should contain the polygonal listening surface. Applications that calculate acoustic data can use this surface as the target area for result data such as sound pressure level maps.
+
+
+## New geometry Amplifier object
+
+Add amplifiers as GDTF-described audio devices, with MVR carrying placed instances and wiring between amplifiers, speakers, DSP/network devices, and power. Existing MVR `Connections`, `Protocols`, `Addresses`, and GDTF `WiringObject` should be reused instead of creating a separate MVR-only amplifier graph.
+
+- Add a GDTF geometry type `Amplifier` under Geometry Collect.
+- `Amplifier` uses standard geometry fields: `Name`, `Model`, `Position`.
+- Add amplifier-level attributes:
+ - `ChannelCount` integer.
+ - `AmplifierClass` enum/string, e.g. `A`, `AB`, `D`, `Other`.
+ - `DSP` bool.
+ - `SupportedSpeakerPreset` string or repeated child node, for manufacturer speaker setup/preset names.
+ - `Latency` float, milliseconds.
+ - `CoolingType` enum/string, e.g. `Passive`, `Fan`, `Other`.
+- Add child node `AmplifierChannel` under `Amplifier`, repeated once per output channel or logical output group.
+- `AmplifierChannel` attributes:
+ - `Name` required.
+ - `ChannelIndex` integer.
+ - `Mode` enum: `SingleEnded`, `Bridge`, `ParallelBridge`, `HighImpedance70V`, `HighImpedance100V`, `Other`.
+ - `OutputPower` float, watts.
+ - `LoadImpedance` float, ohms.
+ - `MinLoadImpedance` float, ohms.
+ - `MaxOutputVoltage` float, volts peak or RMS, with `VoltageMeasurement` enum `Peak`/`RMS`.
+ - `MaxOutputCurrent` float, amperes peak or RMS, with `CurrentMeasurement` enum `Peak`/`RMS`.
+ - `THDN` float, percent, optional.
+ - `CrestFactor` float, dB, optional.
+ - `FrequencyRangeMin` and `FrequencyRangeMax` float, hertz.
+ - `LinkedOutput` node reference to a GDTF `WiringObject` with speaker-level output signal.
+- Keep mains input, audio input, speaker output, network, and control interfaces as `WiringObject` nodes:
+ - Power input: `SignalType="Power"`, `ComponentType="Consumer"` plus existing power payload/voltage/frequency fields.
+ - Speaker outputs: `SignalType="AnalogAudio"` or new predefined `AmplifiedAudio`, `ComponentType="Output"`, connector types such as `NL4`, `NL8`, terminal blocks, or custom names.
+ - Analog/AES3/network audio inputs: existing `AnalogAudio`, `AES`, `Protocol`, `NetworkInput`, `NetworkInOut`.
+- Add predefined protocol names where needed:
+ - In GDTF supported protocols and MVR protocol type guidance, add `AES67`, `AES70`, `Milan`, `Dante`, and `Ravenna` as recognized audio-related names while still allowing custom protocol strings.
+- Add predefined connector types if missing:
+ - `NL2`, `NL8`, common Euroblock/Phoenix speaker terminal naming, and optionally `etherCON`; keep existing `NL4`, XLR, RJ45, and power connectors.
+- Update the `Speaker` proposal so speaker impedance can be matched against amplifier channel load and speaker wiring:
+ - Keep `Impedance` on `Speaker`.
+ - Clarify that amplifier-to-speaker links are represented through `WiringObject` plus MVR `Connection`, not by directly nesting speakers under amplifiers.
+
+In MVR:
+
+- Represent amplifier racks or standalone amplifiers as `Amplifiers` of fixtures? As `Fixture` when they need IDs, addresses, protocols, or GDTF device behavior; otherwise allow `SceneObject` with `GDTFSpec`.
+- Use existing MVR `Connections` to connect amplifier output wiring objects to speaker input wiring objects.
+- Use existing MVR `Protocols` and `Addresses/Network` for amplifier control and audio network assignment.
+
+## MVR
+
+We need to add data for the venue transfer.
+
+We need to add data for how the individual speakers, amplifiers, signal processors, cabling, and networks are placed and wired.
+
+We need a flag that defines whether an object is an obstacle for the audio calculation or should be ignored.
+
+Listening planes should be transferred as scene objects that reference GDTF data containing a `ListeningPlane`, instead of defining an MVR-only listening plane object.
+
+We need to define how line arrays describe the load that they add to the truss.
+
+| Attribute Name | Value Type / Unit | Description |
+|----|----|----|
+| Audio Type | Enum | `Obstacle`, `Ignore`. |
+| Audio Material Name | String | Name of the material to use for audio analysis. This is used by receiving applications to derive reflectiveness or other acoustic properties. MVR only transfers the material name and does not define the acoustic material model. |
+
+## User Story
+
+Acceptance Criteria:
+
+**Data Export from Various Sources:**
+- Ability to export MVR files containing complete scenes and all objects from software such as Blender, Capture, Depence, grandMA3, Production Assist, Unreal Engine, Vectorworks, WYSIWYG, zactrack.
+- Ensure that all relevant data, including geometric information and object properties, are correctly encapsulated in the MVR files.
+
+**Importing and Building the Venue in Array Calc:**
+- Import the MVR containing 3D data and geometries into Array Calc.
+- Use the imported data to construct a detailed 3D venue that includes audience areas.
+
+**Audio System Configuration in Array Calc:**
+- Place and align arrays and speakers according to the predefined truss configurations within the MVR.
+- Configure the cabling, digital signal processing (DSP) settings, and verify sight lines for optimal audio distribution and audience visibility.
+
+**Export from Array Calc:**
+- Export the newly positioned arrays and speakers with updated tilt angles.
+- Export the bumper with load calculations for both front and rear attachments.
+- Ensure all components such as cabling, DSP/amps settings, and speaker orientations are exported accurately.
+- Export SPL (Sound Pressure Level) textures mapping on audience areas, if applicable.
+
+**Reintegration into Other MVR-Compatible Software:**
+- Import the updated MVR files into another MVR-compatible application.
+- Adjust the positioning of arrays and speakers to maintain sight lines.
+- Display the SPL textures to visually represent the sound levels across different audience zones.