# LV2 Units

Units for LV2 values.

ID | http://lv2plug.in/ns/extensions/units
Version | 5.12
Date | 2020-04-26
Discuss | devel@lists.lv2plug.in (subscribe)

- Index
- History
- API

This is a vocabulary for units typically used for control values in audio processing.

For example, to say that a gain control is in decibels:

    @prefix units: <http://lv2plug.in/ns/extensions/units#> .
    @prefix eg:    <http://example.org/> .

    eg:plugin lv2:port [
        a            lv2:ControlPort , lv2:InputPort ;
        lv2:index    0 ;
        lv2:symbol   "gain" ;
        lv2:name     "Gain" ;
        units:unit   units:db
    ] .

Using the same form, plugins may also specify one-off units inline, to give better display hints to hosts:

    eg:plugin lv2:port [
        a            lv2:ControlPort , lv2:InputPort ;
        lv2:index    0 ;
        lv2:symbol   "frob" ;
        lv2:name     "frob level" ;
        units:unit [
            a            units:Unit ;
            rdfs:label   "frobnication" ;
            units:symbol "fr" ;
            units:render "%f f"
        ]
    ] .

It is also possible to define conversions between various units, which makes it possible for hosts to automatically convert between units where possible. The units defined in this extension include conversion definitions where it makes sense to do so.

## Index

Classes | Properties | Instances
--- | --- | ---
Conversion Unit | conversion factor prefixConversion render symbol to unit | bar beat bpm cent cm coef db degree frame hz inch khz km m mhz midiNote mile min mm ms oct pc s semitone12TET

## Classes

### Conversion

Class

Label | Conversion
In domain of | factor
| to
In range of | conversion
| prefixConversion

A conversion from one unit to another.

Restriction on to
  owl:cardinality 1
  A conversion MUST have exactly 1 units:to property.

### Unit

Class

Label | Unit
In domain of | conversion
| prefixConversion
| render
| symbol
In range of | to
| unit

A unit for a control value.

## Properties

### conversion

Property

Label | conversion
Domain | Unit
Range | Conversion
Type | Object Property

A conversion from this unit to another.

### factor

Property

Label | conversion factor
Domain | Conversion
Type | Datatype Property

The factor to multiply the source value by in order to convert to the target unit.

### prefixConversion

Property

Label | prefix conversion
Sub-property of | conversion
Domain | Unit
Range | Conversion
Type | Object Property

A conversion from this unit to another with the same base but a different prefix.

### render

Property

Label | unit format string
Domain | Unit
Range | xsd:string
Type | Datatype Property

A printf format string for rendering a value (e.g., "%f dB").

### symbol

Property

Label | unit symbol
Domain | Unit
Range | xsd:string
Type | Datatype Property

The abbreviated symbol for this unit (e.g., "dB").

### to

Property

Label | conversion target
Domain | Conversion
Range | Unit
Type | Object Property

The target unit this conversion converts to.

### unit

Property

Label | unit
Range | Unit
Type | Object Property

The unit used by the value of a port or parameter.

## Instances

### bar

Instance

Label | bars
Type | Unit
render | %f bars
symbol | bars

Musical bars or measures.

### beat

Instance

Label | beats
Type | Unit
render | %f beats
symbol | beats

Musical beats.

### bpm

Instance

Label | beats per minute
Type | Unit
prefixConversion |
factor | 0.0166666666
to | hz
render | %f BPM
symbol | BPM

Beats Per Minute (BPM), the standard unit for musical tempo.

### cent

Instance

Label | cents
Type | Unit
conversion |
factor | 0.01
to | semitone12TET
render | %f ct
symbol | ct

Cents (hundredths of semitones).

### cm

Instance

Label | centimetres
Type | Unit
conversion |
factor | 0.3937
to | inch
prefixConversion |
factor | 0.01
to | m
prefixConversion |
factor | 10
to | mm
prefixConversion |
factor | 0.00001
to | km
render | %f cm
symbol | cm

Centimetres (hundredths of metres).

### coef

Instance

Label | coefficient
Type | Unit
conversion |
factor | 100
to | pc
render | * %f
symbol |

A scale coefficient where 1 is unity, or 100 percent.

### db

Instance

Label | decibels
Type | Unit
render | %f dB
symbol | dB

Decibels, a logarithmic relative unit where 0 is unity.

### degree

Instance

Label | degrees
Type | Unit
render | %f deg
symbol | deg

An angle where 360 degrees is one full rotation.

### frame

Instance

Label | audio frames
Type | Unit
render | %f frames
symbol | frames

Audio frames or samples.

### hz

Instance

Label | hertz
Type | Unit
prefixConversion |
factor | 0.001
to | khz
prefixConversion |
factor | 0.000001
to | mhz
render | %f Hz
symbol | Hz

Hertz, or inverse seconds, the SI derived unit for frequency.

### inch

Instance

Label | inches
Type | Unit
conversion |
factor | 0.0254
to | m
render | %f"
symbol | in

An inch, defined as exactly 0.0254 metres.

### khz

Instance

Label | kilohertz
Type | Unit
prefixConversion |
factor | 1000
to | hz
prefixConversion |
factor | 0.001
to | mhz
render | %f kHz
symbol | kHz

Kilohertz (thousands of Hertz).

### km

Instance

Label | kilometres
Type | Unit
conversion |
factor | 0.62138818
to | mile
prefixConversion |
factor | 1000
to | m
prefixConversion |
factor | 100000
to | cm
prefixConversion |
factor | 1000000
to | mm
render | %f km
symbol | km

Kilometres (thousands of metres).

### m

Instance

Label | metres
Type | Unit
conversion |
factor | 39.37
to | inch
prefixConversion |
factor | 100
to | cm
prefixConversion |
factor | 1000
to | mm
prefixConversion |
factor | 0.001
to | km
render | %f m
symbol | m

Metres, the SI base unit for length.

### mhz

Instance

Label | megahertz
Type | Unit
prefixConversion |
factor | 1000000
to | hz
prefixConversion |
factor | 0.001
to | khz
render | %f MHz
symbol | MHz

Megahertz (millions of Hertz).

### midiNote

Instance

Label | MIDI note
Type | Unit
render | MIDI note %d
symbol | note

A MIDI note number.

### mile

Instance

Label | miles
Type | Unit
conversion |
factor | 1609.344
to | m
render | %f mi
symbol | mi

A mile, defined as exactly 1609.344 metres.

### min

Instance

Label | minutes
Type | Unit
conversion |
factor | 60.0
to | s
render | %f mins
symbol | min

Minutes (60s of seconds and 60ths of an hour).

### mm

Instance

Label | millimetres
Type | Unit
conversion |
factor | 0.03937
to | inch
prefixConversion |
factor | 0.001
to | m
prefixConversion |
factor | 0.1
to | cm
prefixConversion |
factor | 0.000001
to | km
render | %f mm
symbol | mm

Millimetres (thousandths of metres).

### ms

Instance

Label | milliseconds
Type | Unit
prefixConversion |
factor | 0.001
to | s
render | %f ms
symbol | ms

Milliseconds (thousandths of seconds).

### oct

Instance

Label | octaves
Type | Unit
conversion |
factor | 12.0
to | semitone12TET
render | %f octaves
symbol | oct

Octaves, relative musical pitch where +1 octave doubles the frequency.

### pc

Instance

Label | percent
Type | Unit
conversion |
factor | 0.01
to | coef
render | %f%%
symbol | %

Percentage, a ratio as a fraction of 100.

### s

Instance

Label | seconds
Type | Unit
conversion |
factor | 0.0166666666
to | min
prefixConversion |
factor | 1000
to | ms
render | %f s
symbol | s

Seconds, the SI base unit for time.

### semitone12TET

Instance

Label | semitones
Type | Unit
conversion |
factor | 0.083333333
to | oct
render | %f semi
symbol | semi

A semitone in the 12-tone equal temperament scale.

## History

Version 5.12 (2019-02-03)
  - Fix outdated port description in documentation.
  - Remove overly restrictive domain from units:unit.
Version 5.10 (2015-04-07)
  - Fix non-existent port type in examples.
  - Add lv2:Parameter to domain of units:unit.
Version 5.8 (2012-10-14)
  - Remove units:name in favour of rdfs:label.
  - Use consistent label style.
Version 5.6 (2012-04-17)
  - Add unit for audio frames.
  - Add header of URI defines.
  - Merge with unified LV2 package.
Version 5.4 (2011-11-21)
  - Make units.ttl a valid OWL 2 DL ontology.
  - Define used but undefined resources (units:name, units:render, units:symbol, units:Conversion, units:conversion, units:prefixConversion, units:to, and units:factor).
  - Update packaging.
  - Improve documentation.
Version 5.2 (2010-10-05)
  - Add build system (for installation).
  - Convert documentation to HTML and use lv2:documentation.
Version 5.0 (2010-10-05)
  - Define used but undefined resources (units:name, units:render, units:symbol, units:Conversion, units:conversion, units:prefixConversion, units:to, and units:factor).
  - Update packaging.
  - Improve documentation.
  - Initial release.