aboutsummaryrefslogtreecommitdiffstats
path: root/ext/pui.lv2
diff options
context:
space:
mode:
Diffstat (limited to 'ext/pui.lv2')
-rw-r--r--ext/pui.lv2/pui.h43
-rw-r--r--ext/pui.lv2/pui.ttl38
2 files changed, 80 insertions, 1 deletions
diff --git a/ext/pui.lv2/pui.h b/ext/pui.lv2/pui.h
index 6af445b..f6ec303 100644
--- a/ext/pui.lv2/pui.h
+++ b/ext/pui.lv2/pui.h
@@ -55,10 +55,53 @@
/** The full URI for the pui:floatControl PortProtocol. */
#define LV2_PUI_FLOAT_CONTROL_URI "http://lv2plug.in/ns/ext/pui#floatControl"
+/** The full URI for the pui:floatPeakRMS PortProtocol. */
+#define LV2_PUI_FLOAT_PEAK_RMS_URI "http://lv2plug.in/ns/ext/pui#floatPeakRMS"
+
#ifdef __cplusplus
extern "C" {
#endif
+/**
+ A data type that is used to pass peak and RMS values for a period of
+ audio data at an input or output port to an UI, using port_event. See the
+ documentation for pui:floatPeakRMS for details about how and when this
+ should be done.
+*/
+typedef struct _LV2_PUI_Peak_RMS_Data {
+
+ /**
+ The start of the measurement period. This is just a running counter that
+ must not be interpreted as any sort of global frame position. It should
+ only be interpreted relative to the starts of other measurement periods
+ in port_event() calls to the same plugin instance.
+
+ This counter is allowed to overflow, in which case it should just wrap
+ around.
+ */
+ uint32_t period_start;
+
+ /**
+ The size of the measurement period, in the same units as period_start.
+ */
+ uint32_t period_size;
+
+ /**
+ The peak value for the measurement period. This should be the maximal
+ value for abs(sample) over all the samples in the period.
+ */
+ float peak;
+
+ /**
+ The RMS value for the measurement period. This should be the root mean
+ square value of the samples in the period, equivalent to
+ sqrt((pow(sample1, 2) + pow(sample2, 2) + ... + pow(sampleN, 2)) / N)
+ where N is period_size.
+ */
+ float rms;
+
+} LV2_PUI_Peak_RMS_Data;
+
/**
A pointer to a widget or other type of UI.
The actual type is defined by the type of the UI defined in the RDF data.
diff --git a/ext/pui.lv2/pui.ttl b/ext/pui.lv2/pui.ttl
index 425047d..20c9ee8 100644
--- a/ext/pui.lv2/pui.ttl
+++ b/ext/pui.lv2/pui.ttl
@@ -156,7 +156,7 @@ those extensions MUST specify:
<li>What data (if any) should be passed in the LV2_Feature data pointer. </li>
</ol></p>
-<p>For an example, see pui:floatControl.
+<p>For an example, see pui:floatControl or pui:floatPeakRMS.
</p>
<p>PortProtocol is a subclass of lv2:Feature, so UIs use lv2:optionalFeature and
@@ -185,3 +185,39 @@ pui:floatControl a pui:PortProtocol;
NULL.</li>
</ol>
""".
+
+pui:floatPeakRMS a pui:PortProtocol;
+ rdfs:label "Peak and RMS for a period of audio data";
+ lv2:documentation """
+<p>This port protocol defines a way for the host to send continuous peak
+and RMS measurements of the audio signal at a certain port to the UI. The
+intended use is visualisation, e.g. an animated meter widget that shows
+the level of the audio input or output.</p>
+
+<p>A contiguous sequence of audio samples for which a single peak value
+and a single RMS value have been computed is called a <em>measurement
+period</em>.</p>
+
+<p>The rules (see pui:PortProtocol) for this port protocol are:</p>
+<ol>
+<li>This PortProtocol is valid for ports with the type lv2:AudioPort.</li>
+<li>The host SHOULD call port_event() at regular intervals. The measurement
+ periods used for calls to port_event() for the same port SHOULD be
+ contiguous (i.e. the measurement period for one call should begin right
+ after the end of the measurement period for the previous call ends) unless
+ the UI has removed and re-added the port subscription between those calls.
+ However, UIs MUST NOT depend on either the regularity of the calls or the
+ contiguity of the measurement periods; hosts may change the call rate
+ or skip calls for performance or other reasons. Measurement periods for
+ different calls to port_event() for the same port MUST NOT overlap.
+<li>The format of the data in the buffer passed to port_event() is a single
+ LV2_PUI_Peak_RMS_Data object, and the buffer size is
+ sizeof(LV2_PUI_Peak_RMS_Data).</li>
+<li>The UI MUST NOT call write_port() with the ID for this port protocol as
+ the port_protocol parameter.</li>
+<li>The host MUST ignore any write_port() calls with the ID for this port
+ protocol as the port_protocol parameter.</li>
+<li>The data pointer in the LV2_Feature object for this feature should be
+ NULL.</li>
+</ol>
+""".