bitmeter

Langue: en

Version: 313545 (ubuntu - 07/07/09)

Section: 1 (Commandes utilisateur)

NAME

bitmeter - a diagnosis tool for JACK audio software

SYNOPSIS

bitmeter

DESCRIPTION

JACK bitmeter is a diagnosis tool for JACK audio software on Linux (and perhaps other systems which have JACK and GTK+ 2.x). As its name might suggest, the bitmeter operates at the bare metal of JACK's I/O layer, looking at the 32 binary digits in each individual sample.

Think of bitmeter like the cable detector in your toolbox. You cannot use a cable detector to drive screws into wood, or to undo bolts, or measure the length of a copper pipe, but it's the perfect tool for detecting hidden cables in walls before you drill. You will rarely need bitmeter, in fact most JACK users will never use it at all, but having it and never needing it is much better than needing it and not having it.

Using the bitmeter

Each instance of bitmeter has a single JACK input, and is uniquely numbered. Usually you'll want to connect exactly one JACK output to the bitmeter, as the results can otherwise be rather confusing.

In the above diagram one bitmeter has been attached to an ALSA PCM output (in this case sampled from a microphone) and another to the 2nd channel of a running AlsaPlayer. On the command line you can ask a bitmeter to connect itself to an existing output by specifying the full JACK name (such as MyApp: output_4) of the port.

You can "freeze" the display at any time using the labelled button, this doesn't affect the collection of statistics, but it does let you keep an anomaly on the screen long enough to show someone else or get a screenshot. Click once (the button stays pushed in) to freeze, and again to unfreeze. You can also reset the count of irregular samples, which is normally cumulative.

Interpreting the display

There are three main areas to the bitmeter display.


    * Statistics, at the top, including the range of sample values and keeping
      a count of irregular / illegal sample values such as NaN. The statistics
      on the right are cumulative, and should ordinarily read zero.
    * Sign & Mantissa, a row of 24 coloured indicators showing the sign
      (positive or negative) and mantissa of the samples.
    * Adjusted scale, 40 smaller coloured indicators explained later.

The sign and mantissa statistics are show as coloured indicators which map to bits in the samples processed by the bitmeter, with the left most indicator representing the sign bit, and then the mantissa left to right from most significant to least significant. The colour is based on the percentage of samples in which the associated bit was 1 over a period of 100ms or so. Blue indicates that all samples were 0, a light green-blue for up to 33%, green for 33-66% (ie about half), and orange for more than 66%, then finally red if all samples are 1, a possible stuck bit. Gray is used when no samples touched the associated bit.

The "adjusted scale" shows each sample bit on a absolute scale, adjusted for the exponent of the sample, so that internally the bitmeter records a 280- bit binary real. For simplicity only 40 bits are displayed, the 8 left-most bits are the integer part, and the remaining 32 bits after the marker are fractional bits.

The audio range of the adjusted scale is from about 200dB below FS to 40dB above, which would be excessive for audio work but proves useful in diagnosing problems at a lower level.

The sample rate reported by bitmeter is directly from JACK. It's not used to perform any calculations and is purely informative.

Zero

Absolute silence, also seen when no JACK connection has been made. Both sets of coloured indicators are entirely gray, so there were no valid non- zero samples. The smallest / largest sample readings show 'NA'.

Quiet, 16-bit samples

This is from a quiet piece of music recorded through a 16-bit card, the same thing would be seen with a sample from a CD.

The statistics show that the smallest non-zero sample was at about -90dB, an indication that the source data is 16-bit integer PCM. The largest sample was well below full scale.

The sign indicator is green, meaning that samples were more or less evenly distributed between positive & negative. The topmost (leftmost) four bits of the mantissa are green, then a further three are green-blue and the remainder are blue. At this low amplitude only 8 bits of sample accuracy is present in the integer PCM signal.

The adjusted scale shows that all bits below 2-15 were zero, which again indicates 16-bit PCM.

Loud, 16-bit samples

Here the amplitude of the input signal has increased significantly, in fact it's probably clipping slightly. The statistics now show 0dB full scale samples, and the top 14 bits of the mantissa are all green. On the adjusted scale the '1-bit' is green-blue, as we would expect if there were some full-scale samples.

Quiet, 24-bit samples

This is from a quiet passage in a recording made with a 24-bit ADC. You should expect the same thing with 24-bit external AES/EBU or S/PDIF audio, for example from off-board digital effects units.

This time the smallest non-zero sample was about -123dB and the largest sample was more than 40dB below full scale. We can see there is more audio content in this signal than in even the full scale 16-bit example given earlier, because more bits are used in the mantissa.

On the adjusted scale it's clear that this is 24-bit audio because bits zero to eight inclusive are always blue (zero). For 16-bit audio it would be bits zero through sixteen counting from the right.

Loud, 24-bit samples

Here the display has been frozen (the button appears pressed in) when the signal began clipping at 0dB. The adjusted scale correctly suggests that this is also a 24-bit audio input, and one can see that even with the full range of 24-bit audio the last bit of the floating point mantissa is unused.

31-bit white noise

This sample was created using a white noise sample generated with a random number generator equivalent to 31 bits of integer precision. The rightmost two bits of the adjusted scale are blue (zero), indicating 30 bits of precision after the sign bit.

Random samples

In contrast to the previous example, this time the sample values were evenly distributed over a broad range of values in the IEEE floating point representation, yet still random. This produces a very different sound from white noise, and a distinctive pattern in the adjusted scale, as well as this remarkable -758dB minimum non-zero value.

The adjusted scale shows green-blue all the way across 32 bits, a much more even spread than associated with normal signals.

Irregular samples


 Not a number

Some arithmetic operations on floating point numbers have no defined answer in the natural numbers. For example the square root of a negative number. This result has no meaning as a PCM sample value, and should be discarded. You can see the associated irregular sample counter is increasing in this screenshot because NaNs are arriving at the input of the bitmeter.

Infinite

Another class of operations results in answers that are too large to be represented, or are altogether too large to be natural numbers at all. The delicate algorithms used in filters may "explode"
 if exposed to an infinity, ceasing to produce useful output even when the input returns to a more sensible value. Again the appropriate counter is increasing.

Denormal

Samples too small to be represented in an ordinary JACK 32-bit float but not small enough to be zero are denormals. Obviously too small to be significant in playback, denormals are a problem if naive signal processing algorithms attempt to do arithmetic operations on them. Such operations are very slow on denormals and can cause a plug-in or application to exceed its allowable processing time and be kicked from the JACK graph.

JACK applications are expected both to protect themselves against irregular samples and to prevent such samples from being emitted. A suitable test, named JACK demolition in reference to the LADSPA demolition tool, is available from Steve Harris. The above three examples were created using JACK demolition.

Mistake #1

Division by 32767

Although JACK itself works entirely with IEEE floating point values the conversion to and from analog audio uses integers, as do popular audio storage technologies like DAT and Red Book CDs. For correct operation JACK software which uses such integers should use the same conversion ratios as JACK itself. e.g. 16-bit samples should be divided by exactly 32768.

A common mistake is to choose the value 32767 instead. You can't hear this, or see it with ordinary meters, but the bitmeter shows a clear signature for audio processed in this way. The 8th bit of the mantissa (counting the rightmost as the 0th) is orange, indicating that an unusually high percentage of samples have this bit set.

AUTHORS


 Nicholas Lamb <njl195@zepler.org.uk>

This manual page was written by Morten Kjeldgaard <mok0@ubuntu.com> for the Ubuntu project (but may be used by others).