diff options
Diffstat (limited to 'ext/pui.lv2')
| -rw-r--r-- | ext/pui.lv2/pui.h | 43 | ||||
| -rw-r--r-- | ext/pui.lv2/pui.ttl | 38 |
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> +""". |