WHAT IS THIS?

        This tool will help you to determine the volume scaling
        factors of your sound card. If your sound card/chip
        manufacturer did not provide you with documentation to which
        attenuation specific volume settings belong this tool can help
        you to measure them.

WHAT YOU NEED?

        a) A sound card where input and output are synchronous

        b) A feedback cable that allows you to feed sound card output
           back into the input

        c) Some time

HOW TO USE IT?

        1) You plug in your feedback cable in the line out and line in
           of your soundcard

        2) You open the low-level ALSA mixer and mute/set to 0
           everything you can mute/set to 0, except what is necessary
           to get a PCM signal out of your machine and back into the
           machine. The slider you want to measure you set the highest
           possible value. The other sliders that are in our pipeline
           you set to some 'sensible' value, in the middle of its
           range somewhere. What does 'sensible' mean?  Something
           where neither clipping happens nor where the signal is too
           faint. In 'alsamixer -c0' those points are usually near 0dB
           or a bit lower. If you are not sure what to pick don't
           despair, our little tool will tell you if you picked a good
           value. 'Inner' sliders should always be kept near to 0dB.

        3) You run our little tool like this:

                make && ./dbmeasure plughw:0 log.csv

        This will now measure a few things and then ask you to lower
        the volume one step. Please comply and press return. It will
        now measure a little bit more, and ask again and so on. When
        you went through all volume levels successfully press C-D
        instead of return.

        If the volume levels mentioned in step 2 were not set up
        correctly the tool will fail and ask you to adjust them a
        little. Then repeat step 3.

        The first argument to the tool is the device to use. It will
        be opened for both capturing and playback. The second argument
        is the filename of a CSV file where the tool will place its
        results. The first column of that file is the numer of the
        volume step we are looking at. Starting with the highest
        one. The last column is the attenuation in dB relative to the
        highest volume level (and hence is always at 0dB on the first
        line). You can then load the CSV output into Gnumeric to draw
        pretty graphs.

        If you want to use the output of this tool in low-level
        drivers, keep in mind that there volume level 0 is usally the
        lowest one, while in our CSV it is the highest. You might
        hence want to invert the order of the CSV file before you make
        use of it.

WHAT DOES IT ACTUALLY DO?

        It's pretty simple. We basically just generate a sine wave @
        440Hz which we output. Then we record that again and deduce
        the amplitude of what we record. Then we ask you to change the
        volume a bit and measure the amplitude again.

        To suppress the noise we play the sine wave for one
        second. And then record the next second adding it to the
        previously recorded second and so on. Dividing the resulting
        summed signal by the number of seconds we did this will give us a
        signal where the noise level is lower on each iteration. This
        works correctly only if record and playback are perfectly in
        sync. As last step we deduce the absolute maximum of our
        summed samples and take that as the volume level for the
        volume setting.

        Before the whole logic properly starts we do a run similar to
        the above but with silence written to the device instead of
        the actual sine signal. We then repeat that as often as the
        resulting sum signal is stronger than -80 dB. This then gives
        us a hint how many seconds/iterations we need to record and
        play the summing game to push the noise level below -80 dB.

        This will only measure the volume dependant attenuation at
        440Hz. This is of course a drastic simplification of the
        actual transfer function.

WHY DO THIS?

        To do more advance volume control in PulseAudio we need the dB
        values for our sound card volume controls. More specifically I
        wanted them for my Thinkpad X60s hardware volume control.

WHO WROTE THIS?

        Lennart Poettering, 2009