Mark up control properties, port groups, and add documentation for plugins and ports.

git-svn-id: http://svn.drobilla.net/lad/trunk/plugins/mdala.lv2@4118 a436a847-0d15-0410-975c-d299462d15a1

1 files changed, 33 insertions, 4 deletions

diff --git a/mdala.lv2/Dither.ttl b/mdala.lv2/Dither.ttl
index 89a8b27..7f6faf2 100644
--- a/mdala.lv2/Dither.ttl
+++ b/mdala.lv2/Dither.ttl
@@ -2,6 +2,8 @@
 @prefix lv2: <http://lv2plug.in/ns/lv2core#> .
 @prefix mdala: <http://drobilla.net/plugins/mdala/> .
 @prefix pg: <http://lv2plug.in/ns/ext/port-groups#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
 
 mdala:Dither
 	a lv2:Plugin ,
@@ -13,6 +15,17 @@ mdala:Dither
 	lv2:pluginProperty lv2:hardRTCapable ;
 	pg:mainInput mdala:mainIn ;
 	pg:mainOutput mdala:mainOut ;
+	rdfs:comment """When a waveform is rounded to the nearest 16 (or whatever)-bit value this causes distortion. Dither allows you to exchange this rough sounding signal-dependant distortion for a smooth background hiss.
+
+Some sort of dither should always be used when reducing the word length of digital audio, such as from 24-bit to 16-bit. In many cases the background noise in a recording will act as dither, but dither will still be required on fades and on very clean recordings such as purely synthetic sources.
+
+Noise shaping makes the background hiss of dither sound quieter, but adds more high-frequency noise than 'ordinary' dither. This high frequency noise can be a problem if a recording is later processed in any way (including gain changes) especially if noise shaping is applied a second time.
+
+If you are producing an absolutely final master at 16 bits or less, use noise shaped dither. In all other situations use a non-noise-shaped dither such as high-pass-triangular. When mastering for MP3 or other compressed formats be aware that noise shaping may take some of the encoder's 'attention' away from the real signal at high frequencies.
+
+No gain changes should be applied after this plug-in. Make sure any master output fader is set to 0.0 dB in the host application.
+
+Very technical note This plug-in follows Steinberg's convention that a signal level of 1.0 corresponds to a 16-bit output of 32768. If your host application does not allow this exact gain setting the effectiveness of dither may be reduced (check for harmonic distortion of a 1 kHz sine wave using a spectrum analyser).""" ;
 	lv2:port [
 		a lv2:InputPort ,
 			lv2:ControlPort ;
@@ -30,7 +43,20 @@ mdala:Dither
 		lv2:symbol "dither" ;
 		lv2:default 0.88 ;
 		lv2:minimum 0.0 ;
-		lv2:maximum 1.0
+		lv2:maximum 1.0 ;
+		lv2:scalePoint [
+			rdfs:label "Truncation" ;
+			rdf:value 0.0
+		] , [
+			rdfs:label "Triangular PDF dither" ;
+			rdf:value 0.25
+		] , [
+			rdfs:label "High-pass Triangular PDF dither" ;
+			rdf:value 0.5
+		] , [
+			rdfs:label "Second-order noise-shaped dither" ;
+			rdf:value 0.75
+		]
 	] , [
 		a lv2:InputPort ,
 			lv2:ControlPort ;
@@ -39,7 +65,8 @@ mdala:Dither
 		lv2:symbol "dith_amp" ;
 		lv2:default 0.5 ;
 		lv2:minimum 0.0 ;
-		lv2:maximum 1.0
+		lv2:maximum 1.0 ;
+		rdfs:comment """Dither amplitude - can be turned down to reduce background hiss at the expense of dither level "pumping" caused by the input signal type and level"""
 	] , [
 		a lv2:InputPort ,
 			lv2:ControlPort ;
@@ -48,7 +75,8 @@ mdala:Dither
 		lv2:symbol "dc_trim" ;
 		lv2:default 0.5 ;
 		lv2:minimum 0.0 ;
-		lv2:maximum 1.0
+		lv2:maximum 1.0 ;
+		rdfs:comment "Fine tune DC offset - can help get best dither sound for silent or very quiet inputs"
 	] , [
 		a lv2:InputPort ,
 			lv2:ControlPort ;
@@ -57,7 +85,8 @@ mdala:Dither
 		lv2:symbol "zoom" ;
 		lv2:default 0 ;
 		lv2:minimum 0.0 ;
-		lv2:maximum 1.0
+		lv2:maximum 1.0 ;
+		rdfs:comment """Allows the signal to be faded into the noise floor at a clearly audible level so dither settings can be "auditioned".  Note that some (perceptual) properties of dither will change when listened to in this way"""
 	] , [
 		a lv2:InputPort ,
 			lv2:AudioPort ;