Skip to content

Draft for Audio Support #179

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
moritzstaffel wants to merge 24 commits into
base: next
Choose a base branch
from
+505 −4
Open

Draft for Audio Support #179

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
8d43ff4
Speaker Geometry
moritzstaffel Feb 11, 2024
a4ab9d0
Create proposal.md
moritzstaffel Feb 11, 2024
7f6335d
Update proposal.md
moritzstaffel Apr 5, 2024
4bc35bd
Merge branch 'next' into audio-proposal
moritzstaffel Apr 17, 2024
8aa14bc
Add Properties of Speaker
moritzstaffel Apr 18, 2024
6196614
Add listenting plane
moritzstaffel Apr 18, 2024
5e70ae3
Update proposal.md
moritzstaffel Apr 18, 2024
3c2362f
Update proposal.md
moritzstaffel Apr 18, 2024
167cdc2
Update proposal.md
moritzstaffel Apr 18, 2024
3bb7fc4
Update the proposal based on latest feedback/comments
petrvanekrobe May 12, 2026
6d19ab3
Add initial Amplifier specification
petrvanekrobe May 12, 2026
729f0a6
Define ListeningPlane node and its attributes
klinzey May 14, 2026
a22f2d9
Revise speaker and MaxSPL attributes in gdtf-spec
klinzey May 14, 2026
9db2c0f
Define Speaker node with attributes and children
klinzey May 14, 2026
0f0e268
Adjusting attributes and their definitions, adding some todo items
petrvanekrobe May 14, 2026
4e0a1c0
Further definitions for Audio proposal
petrvanekrobe Jun 11, 2026
6a050f9
Extend the definition for the ListeningPlaneHeatMaps
petrvanekrobe Jun 11, 2026
ef17329
Remove old ListeningPlane example
petrvanekrobe Jun 11, 2026
c496c7e
Refine ListeningPlaneHeatMap and Face node definitions
klinzey Jun 17, 2026
001c1ce
Revise speaker attributes and add XML example
klinzey Jun 18, 2026
48f2a38
Fix table
petrvanekrobe Jun 18, 2026
7ba9d7e
Revise speaker geometry and SPL attributes
klinzey Jun 24, 2026
3b8625d
Merge pull request #312 from mvrdevelopment/GDTF-Speaker-Sample
klinzey Jun 24, 2026
1962cc5
Add Amplifier object
petrvanekrobe Jun 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
174 changes: 171 additions & 3 deletions gdtf-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1214,6 +1214,8 @@ of geometry collect are specified in [table 34](#user-content-table-34 ).
| [Structure](#user-content-geometry-type-structure ) | Any | Geometry that describes the internal framing of an object (like members). |
| [Support](#user-content-geometry-type-support ) | Any | Geometry that describes a support like a base plate or a hoist. |
| [Magnet](#user-content-geometry-type-magnet ) | Any | Geometry that describes a point where other geometries should be attached. |
| [Speaker](#user-content-geometry-type-audio ) | Any | Geometry that describes a audio source. |
| [Amplifier](#user-content-geometry-type-amplifier ) | Any | Geometry that describes an audio amplifier. |


</div>
Expand Down Expand Up @@ -1716,7 +1718,7 @@ defined XML attributes of a structure geometry are specified in
| 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 |
| LinkedGeometry | [Name](#user-content-attrtype-name ) | The linked geometry. |
| StructureType | [Enum](#user-content-attrtype-enum ) | The type of structure. Defined values are "CenterLineBased", "Detail". |
| StructureType | [Enum](#user-content-attrtype-enum ) | The type of structure. Defined values are "CenterLineBased", "Detail", "SpeakerBumper". |
| CrossSectionType <a id="attrtype-crosssectiontype" /> | [Enum](#user-content-attrtype-enum ) | The type of cross section. Defined values are "TrussFramework", "Tube". |
| CrossSectionHeight | [Float](#user-content-attrtype-float ) | The height of the cross section. Only for [Tubes](#user-content-attrtype-crosssectiontype ). Unit: meter. |
| CrossSectionWallThickness | [Float](#user-content-attrtype-float ) | The thickness of the wall of the cross section.Only for [Tubes](#user-content-attrtype-crosssectiontype ). Unit: meter. |
Expand Down Expand Up @@ -1783,12 +1785,178 @@ defined XML attributes of a magnet geometry are specified in
| 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 magnet geometry has the same children types as the geometry
collect (see [table 34](#user-content-table-34 )).

</div>
### Geometry Type HangingPoint

The magnet geometry has the same children types as the geometry
This type of geometry is used to describe a hanging point, a point for attachment (XML node `<HangingPoint>`). The currently
defined XML attributes of a hanging point geometry are specified in
[table xx](#user-content-table-xx ).

<div id="table-xx">

#### 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 `<Speaker>`). The currently
defined XML attributes of a speaker geometry are specified in
[table 55](#user-content-table-XX ).

Note: `<Speaker>` data is typically represents the completed speaker assembly and not the individual emitters; however mutiple `<Speaker>` nodes can be used if required.

<div id="table-XX">

#### Table XX. *Speaker Attributes*

| XML Attribute Name | Value Type | Description |
|----|----|----|
| Model | [Name](#user-content-attrtype-name ) | Optional. Link to the corresponding model. Can be empty. |
| Position | [Matrix](#user-content-attrtype-matrix ) | Relative position of model location and point of orign for coverage calculation and sound emission. Default value: Identity Matrix |
| 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.|
| SPLExcitationSignal | [Enum](#user-content-attrtype-enum ) | The currently defined unit values are: Pink noise, IEC60268, EIA426B, AES75|
| SPLFrequencyWeighting | [Enum](#user-content-attrtype-enum ) | The currently defined unit values are: None, A-Weighting, C-Weighting |
| SPLUnit | [Enum](#user-content-attrtype-enum ) | The currently defined unit values are: DBZ, dB, DBSPL, dBA, dBC |
| SPLUnitMark | [Enum](#user-content-attrtype-enum ) | The currently defined unit values are: Leq, Laeq, LCeq, F, S |
| SPLTimeWeighting | [Enum](#user-content-attrtype-enum ) | The currently defined unit values are: Fast, Slow, Leq, Peak |

</div>

TODO: Define default orientation of the speaker.

EXAMPLE An example of a node definition is shown below:
```xml
<FixtureType CanHaveChildren="No" Description="" FixtureTypeID="DEB0148A-286C-4B42-A360-9852A0DEE350" LongName="Speaker" Manufacturer="VladiTest" Name="TestSpeaker" RefFT="" ShortName="Speaker" Thumbnail="" ThumbnailOffsetX="0" ThumbnailOffsetY="0">
<PhysicalDescriptions>
<Properties>
<OperatingTemperature High="40.000000" Low="0.000000"/>
<Weight Value="0.000000"/>
<Speaker
Model="Speaker1"
Position="{1.000000,0.000000,0.000000,0.000000}{0.000000,1.000000,0.000000,-0.247247}{0.000000,0.000000,1.000000,0.217105}{0,0,0,1}"
Impedance="200.000000"
VerticalCoverageUp="30.000000"
VerticalCoverageDown="30.000000"
HorizontalCoverageUp="30.000000"
HorizontalCoverageDown="30.000000"
SoundAngleRotationMax="30.000000"
FrequencyMin="120.000000"
FrequencyMax="20.000000"
MaxSPL="55.000000"
SPLExcitationSignal="Pink noise"
SPLFrequencyWeighting=None"
SPLUnit="DBX"
SPLUnitMark="Leq"
SPLTimeWeighting="Fast"/>
</Properties>
</PhysicalDescriptions>
<Models>
<Model File="" Height="1.000000" Length="0.500000" Name="AudioDevice" PrimitiveType="Cube" SVGFrontOffsetX="0.000000" SVGFrontOffsetY="0.000000" SVGOffsetX="0.000000" SVGOffsetY="0.000000" SVGSideOffsetX="0.000000" SVGSideOffsetY="0.000000" Width="0.500000"/>
</Models>
<Geometries>
<Geometry Model="AudioDevice" Name="AudioDevice" Position="{1.000000,0.000000,0.000000,0.000000}{0.000000,1.000000,0.000000,0.000000}{0.000000,0.000000,1.000000,0.000000}{0,0,0,1}">
</Geometry>
</Geometries>
</FixtureType>
```
ToDO: *MaxSPL Attributes* Do we need to restructure above to support the attributes

### Geometry Type Amplifier

This type of geometry is used to describe an amplifier in an audio device. (XML node `<Amplifier>`). The currently
defined XML attributes of an Amplifier geometry are specified in [table xx](#user-content-table-XX ).


#### Table XX. *Amplifier Attributes*

| Attribute Name | Value Type / Unit | Description |
| -------------- | ----------------: | -------------------------------------------- |
| Name | [Name](#user-content-attrtype-name ) | 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 |
| AmplifierClass | [Enum](#user-content-attrtype-enum ) |Defined values are: `A`, `AB`, `D`, `Other`. Default: Other |
| DSP | [Enum](#user-content-attrtype-enum )| Defines whether the amplifier includes DSP. Defined values are "Yes", "No". Default value: "No"
| Latency | [Float](#user-content-attrtype-float ) | Amplifier or amplifier/DSP latency. Unit: ms. Default: 0 |
| CoolingType | [Enum](#user-content-attrtype-enum )|Defined values are: `Passive`, `Fan`, `Other`. Default value: Other |

As children the Amplifier has a list of [Amplifier Channel](#user-content-amplifier-channel).

#### AmplifierChannel

AmplifierChannel describes one amplifier output channel. The currently defined
XML attributes of AmplifierChannel are specified in [table
xx](#user-content-table-xx).

#### Table xx. *Amplifier Channel Attributes*

| Attribute Name | Value Type / Unit | Description |
| ------------------ | ----------------: | ---------------------------------------------------------------------------------------------------------------------- |
| Name | [Name](#user-content-attrtype-name ) | Required unique channel name. |
| ChannelIndex | [Int](#user-content-attrtype-int ) | Channel index. |
| Mode | [Enum](#user-content-attrtype-enum ) | Defined values are: `SingleEnded`, `Bridge`, `ParallelBridge`, `HighImpedance70V`, `HighImpedance100V`, `Other`. Default value: Other |
| OutputPower | [Float](#user-content-attrtype-float )| Rated output power for the documented condition. Unit: watt. Default value: 0 |
| LoadImpedance | [Float](#user-content-attrtype-float ) | Nominal load impedance for the rating. Unit: ohm. Default value: 0 |
| MinLoadImpedance | [Float](#user-content-attrtype-float ) | Minimum supported load impedance. Unit: ohm. Default value: 0 |
| MaxOutputVoltage | [Float](#user-content-attrtype-float ) | Maximum output voltage. Unit: volt. Default value: 0 |
| VoltageMeasurement | [Enum](#user-content-attrtype-enum ) | Defined values are: `Peak`, `RMS`. Default value: TBD. |
| MaxOutputCurrent | [Float](#user-content-attrtype-float ) | Maximum output current. Unit: ampere. Default value: 0 |
| CurrentMeasurement | [Enum](#user-content-attrtype-enum ) | Defined values are: `Peak`, `RMS`. Default value: TBD |
| THDN | [Float](#user-content-attrtype-float ) | Optional total harmonic distortion plus noise. Unit: percent. Default value: 0 |
| CrestFactor | [Float](#user-content-attrtype-float ) | Optional crest factor for the rating. Unit: decibel. Default value: 0 |
| FrequencyRangeMin | [Float](#user-content-attrtype-float ) | Minimum frequency of the amplifier channel. Unit: hertz. Default value: 0 |
| FrequencyRangeMax | [Float](#user-content-attrtype-float ) | Maximum frequency of the amplifier channel. Unit: hertz. Default value: 0 |
| LinkedOutput | [Node](#user-content-attrtype-node ) | Optional link to the GDTF `WiringObject` that represents the amplifier channel output. Starting point is the[Geometries Collect](#user-content-geometry-collect)|
| LinkedSpeaker | [Node](#user-content-attrtype-node ) | Optional link to the `Speaker` geometry fed by this amplifier channel when the speaker is inside the same GDTF device. Starting point is the [Geometries Collect](#user-content-geometry-collect)|

For a self-powered loudspeaker, the `Amplifier` and `Speaker` should normally be children of the same device hierarchy.

The amplifier channel may link to the internal speaker output `WiringObject` and/or directly to the `Speaker` geometry through `LinkedSpeaker`.

For a passive loudspeaker driven by an external amplifier, do not directly link the external amplifier’s GDTF to the passive speaker’s GDTF. The instance-to-instance relationship belongs in MVR using `Connections`.

EXAMPLE:

```xml
<Amplifier
Name="AmplifierModule"
Model="AmplifierModule"
Position="{1,0,0,0}{0,1,0,0}{0,0,1,0}{0,0,0,1}"
ChannelCount="1"
AmplifierClass="D"
DSP="Yes"
Latency="2.5"
CoolingType="Passive">
<AmplifierChannel
Name="LFHF"
ChannelIndex="1"
Mode="SingleEnded"
OutputPower="900"
LoadImpedance="4"
MinLoadImpedance="4"
FrequencyRangeMin="45"
FrequencyRangeMax="18000"
LinkedOutput="InternalAmpOut1"
LinkedSpeaker="AcousticSource"/>
</Amplifier>
```
## DMX Mode Collect

### General
Expand Down
Loading
Loading