AlsaProject - User contributions [en]

Test latency.c

2013-09-18T05:45:00Z

Sdaau: /* Quick overview */ - added clarification about "Trying latency ..." line

__FORCETOC__
== test latency.c ==

Within <code>alsa-lib</code>, there is a utility, [http://git.alsa-project.org/?p=alsa-lib.git;a=blob;f=test/latency.c; test/latency.c] ([http://git.alsa-project.org/?p=alsa-lib.git;a=history;f=test/latency.c; history]), which performs a full-duplex test, where recorded (captured) data is played back.

From <code>alsa-lib/test/latency.c</code>:

<small><pre>
* Latency test program
*
* This small demo program can be used for measuring latency between
* capture and playback. This latency is measured from driver (diff when
* playback and capture was started). Scheduler is set to SCHED_RR.
</pre></small>

=== '''Building''' ===

The name of the executable has to be passed explicitly to the <code>make</code> command - via [http://thread.gmane.org/gmane.linux.alsa.devel/6746/focus=6750 Re: problem ragarding execution of Latency.c (alsa-devel)]:

<small><pre>
cd alsa-lib/test
make latency
</pre></small>

=== '''Options''' ===

<small><pre>
$ ./latency -h
Usage: latency [OPTION]... [FILE]...
-h,--help help
-P,--pdevice playback device
-C,--cdevice capture device
-m,--min minimum latency in frames
-M,--max maximum latency in frames
-F,--frames frames to transfer
-f,--format sample format
-c,--channels channels
-r,--rate rate
-B,--buffer buffer size in frames
-E,--period period size in frames
-s,--seconds duration of test in seconds
-b,--block block mode
-p,--poll use poll (wait for event - reduces CPU usage)
-e,--effect apply an effect (bandpass filter sweep)
Recognized sample formats are: S8 U8 S16_LE S16_BE U16_LE U16_BE S24_LE S24_BE U24_LE U24_BE S32_LE S32_BE U32_LE U32_BE FLOAT_LE FLOAT_BE FLOAT64_LE FLOAT64_BE IEC958_SUBFRAME_LE IEC958_SUBFRAME_BE MU_LAW A_LAW IMA_ADPCM MPEG GSM SPECIAL S24_3LE S24_3BE U24_3LE U24_3BE S20_3LE S20_3BE U20_3LE U20_3BE S18_3LE S18_3BE U18_3LE

Tip #1 (usable latency with large periods, non-blocking mode, good CPU usage,
superb xrun prevention):
latency -m 8192 -M 8192 -t 1 -p
Tip #2 (superb latency, non-blocking mode, but heavy CPU usage):
latency -m 128 -M 128
</pre></small>

Notes:
* The option <code>-F,--frames</code> seems not to be handled anywhere in the code, and as such has no effect.
* The "Tip #1" refers to an option <code>-t</code> which doesn't exist - however, it is likely a typo for the option <code>-s</code> for duration in seconds
* The option <code>-s</code> for duration in seconds is an integer, and the lowest it can be set is 1 second; default if not specified is 30 seconds
* Before 2012-08-08, there is a bug where the short options <code>-B</code> and <code>-E</code> are not recognized ("invalid option") - but the long options <code>--buffer</code> and <code>--period</code> still work even then.

=== '''Usage''' ===

When called, the <code>test/latency.c</code> program will attemp to set period/buffer sizes based on the latency entered, starting from <code>-m,--min</code> option (or the default minimum latency = 64 if not specified). If the run succeeds without errors with that setting, the program exits; otherwise, the latency is increased, and the run repeated - if the run is succesful here, then program exits, else the process continues until the <code>-M,--max</code> latency is reached.

Example of successful run on Linux kernel 2.6.38 / ALSA 1.0.24.2 with HDA Intel onboard PCI soundcard:

<small><pre>
$ aplay -l
**** List of PLAYBACK Hardware Devices ****
card 0: Intel [HDA Intel], device 0: ALC269 Analog [ALC269 Analog]
Subdevices: 1/1
Subdevice #0: subdevice #0

$ alsa-lib/test/latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 -p -s 1
!!!Scheduler set to Round Robin with priority 99 FAILED!!!
Playback device is hw:0,0
Capture device is hw:0,0
Parameters are 44100Hz, S16_LE, 2 channels, non-blocking mode
Poll mode: yes
Loop limit is 44100 frames, minimum latency = 128, maximum latency = 128
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : PLAYBACK
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 128
period_size : 64
period_time : 1451
tstamp_mode : NONE
period_step : 1
avail_min : 64
period_event : 0
start_threshold : 2147483647
stop_threshold : 128
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : CAPTURE
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 128
period_size : 64
period_time : 1451
tstamp_mode : NONE
period_step : 1
avail_min : 64
period_event : 0
start_threshold : 2147483647
stop_threshold : 128
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Trying latency 128 frames, 2902.494us, 2.902494ms (344.5312Hz)
Success
Playback:
*** frames = 44288 ***
state : RUNNING
trigger_time: 84416.108859821
tstamp : 84417.110319083
delay : 80
avail : 48
avail_max : 120
Capture:
*** frames = 44160 ***
state : RUNNING
trigger_time: 84416.108859821
tstamp : 84417.110439490
delay : 9
avail : 9
avail_max : 65
Maximum read: 64 frames
Maximum read latency: 1451.247us, 1.451247ms (689.0625Hz)
Hardware sync
Playback time = 84416.108859, Record time = 84416.108859, diff = 0
</pre></small>

The message "<code>Scheduler set to Round Robin with priority 99 FAILED</code>" can be avoided by running the program with <code>sudo</code> (administrative privileges):

<small><pre>
$ sudo alsa-lib/test/latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 -p -s 1
[sudo] password for user:
Scheduler set to Round Robin with priority 99...
...
</pre></small>

The program can also fail, if the streams experience an XRUN; in that case, if <code>-m</code> is set to be equal to <code>-M</code>, the program will immediately exit:

<small><pre>
$ alsa-lib/test/latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 -p -s 1
!!!Scheduler set to Round Robin with priority 99 FAILED!!!
Playback device is hw:0,0
Capture device is hw:0,0
Parameters are 44100Hz, S16_LE, 2 channels, non-blocking mode
Poll mode: yes
Loop limit is 44100 frames, minimum latency = 128, maximum latency = 128
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : PLAYBACK
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 128
period_size : 64
period_time : 1451
tstamp_mode : NONE
period_step : 1
avail_min : 64
period_event : 0
start_threshold : 2147483647
stop_threshold : 128
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : CAPTURE
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 128
period_size : 64
period_time : 1451
tstamp_mode : NONE
period_step : 1
avail_min : 64
period_event : 0
start_threshold : 2147483647
stop_threshold : 128
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Trying latency 128 frames, 2902.494us, 2.902494ms (344.5312Hz)
Failure
Playback:
*** frames = 38464 ***
state : XRUN
trigger_time: 479.798093354
tstamp : 479.798185056
delay : 0
avail : 128
avail_max : 128
Capture:
*** frames = 38400 ***
state : XRUN
trigger_time: 479.798093354
tstamp : 479.798361196
delay : 0
avail : 9
avail_max : 73
Maximum read: 64 frames
Maximum read latency: 1451.247us, 1.451247ms (689.0625Hz)
Hardware sync
</pre></small>

=== '''Quick overview''' ===

In brief, the <code>latency.c</code> program:

* Parses the command line parameters/options, and sets the playback and capture stream properties according to them
* Starts a loop where (among other things) it:
** shows the current latency value, using the <code>showlatency()</code> function - which ultimately prints the "<i>Trying latency %li frames ...</i>" line
*** <small><i>Note:</i> the <code>showlatency(size_t latency)</code> function multiplies the <code>latency</code> input argument by two (<code>latency *= 2;</code>); so if the printout says "<i>Trying latency 128 frames ...</i>", that means that <code>latency</code> parameter is actually 64</small>
** calls [http://www.alsa-project.org/alsa-doc/alsa-lib/group___p_c_m.html#gac6c33091b049985baa6466e8fe93917e snd_pcm_link] on the capture and playback stream file descriptors, to have them "<i>start/stop/prepare in sync</i>"
** calls <code>snd_pcm_format_set_silence</code>, and then
** calls <code>writebuf(phandle, buffer, latency ...)</code> '''''twice'''''
*** <small><i>Note:</i> since the value of the variable <code>latency</code> is twice smaller than what the printout "<i>Trying latency %li frames ...</i>" says - calling <code>writebuf()</code> twice, means that we ultimately achieve the demanded latency, as shown on the printout.</small>
** starts yet another <code>while</code> loop, where:
*** [http://www.alsa-project.org/alsa-doc/alsa-lib/group___p_c_m.html#gad4d53d58b996a7cd9a5cbf1710b90375 snd_pcm_wait] is called, if polling has been specified in the command line arguments;
*** <code>r = readbuf(chandle, buffer, latency, ...)</code> is called on the capture stream
*** <code>writebuf(phandle, buffer, r, ...)</code> is called on the playback stream

See the source code for details of the <code>readbuf()</code> and <code>writebuf()</code> functions - which may involve loops of their own, but ultimately call <code>[http://www.alsa-project.org/alsa-doc/alsa-lib/group___p_c_m.html#ga4c2c7bd26cf221268d59dc3bbeb9c048 snd_pcm_readi]</code> and <code>[http://www.alsa-project.org/alsa-doc/alsa-lib/group___p_c_m.html#gabc748a500743713eafa960c7d104ca6f snd_pcm_writei]</code>, respectively.

=== '''Mailing list notes''' ===

[http://thread.gmane.org/gmane.linux.alsa.devel/17014 latency.c: some feature requests (alsa-devel)] (2004-11-28)
<small><pre>
> It looks like the playback runs 64 frames ahead of the capture. Do you
> think this would be a problem from the application's perspective?
>

That's correct - it's the latency.

-----

>>>>> I also need the capture device interleaved and the playback device
>>>>> noninterleaved. latency.c does not support this at all, it just assumes
>>>>> that all hardware supports interleaved format.
>>>> Use default device (-D default and -P default) which automatically
>>>> uses available parameters.
>>>
>>> This will not work because I need to use hw:0,3 for playback and hw:0,2
>>> for capture.
>>
>> -P plughw:0,3 -C plughw:0,2

-----

>
> [...] One other thing I noticed is that latency.c doesn't mmap.
> This would cause higher latencies compared to testing with JACK,
> correct?

Yes, it's good point. Perhaps, the snd_pcm_mmap_readi/writei functions
should be used to optimize copying.
</pre></small>

[http://thread.gmane.org/gmane.linux.alsa.devel/37367 latency.c and delay related questions (alsa-devel)] (2006-06-20)
<small><pre>
> The current delay with "latency" is equal to a minimum (that depends
> on the sound card) plus *two* times the period time. [...]

Yes, it's correct. Basically, you cannot avoid double buffering, so the
total latency is:

1) one capture period
2) one playback period (actually being played)
3) moved captured period to playback buffer (not counted)

So the latency should be 2 * period plus a hw latency as you noted.
Everything is correct. Of course, you may get better latencies if you run
"busy loop" on not-loaded system and immediately put captured data to
playback stream, but it's not a correct behaviour in *nix.

> * why is snd_pcm_link() mandatory? (no sound otherwise)

It links playback and capture streams so only one start() is called. On
hardware which supports hardware syncing, the DMA operation is started at
same time for both stream.

> * why two buffers of silence and not just one?

You must wait one period to get data from the capture direction and then
you have exactly one period time to put these data to the playback. As I
said, you can get better results with busy-loop but it's bad
implementation (but if you have a spare dedicated machine without other
tasks, it might be an option).

-----

> [...] The linking of capture and playback devices
> explains everything; if I remove linking and use snd_pcm_start() on
> the playback device I get the expected behaviour.
>
> Here is a little drawing (requires fixed font) to illustrate what you
> have said and what I have understood (useless for you but some people
> like me might find it useful).
>
> When capture and playback devices are linked, the following happens:
>
> +-------------------------
> Capture | C0 | C1 | C2 | C3 | ...
> +-------------------------
>
> +-------------------------
> Playback | -- | -- | C0 | C1 | ...
> +-------------------------
>
> Capture and playback start simultaneously and so playback device needs
> something to play. When the first capture is finished, another is
> started. We would like to play the captured audio, but another
> playback has already started. Only after the latter is finished can
> the captured audio be played.
>
> This explains why the playback device needs two buffers of silence.
>
> The total delay is hw_delay + 2 * period
>

Exactly. Well explained.

> When the devices are not linked, we can start the playback device
> after the first buffer has been captured:
>
> +-------------------------
> Capture | C0 | C1 | C2 | C3 | ...
> +-------------------------
>
> +-----------------
> Playback | C0 | C1 | C2 | .
> +-----------------
>
> Starting the playback device and copying data takes some time, so the
> total delay becomes hw_delay + 1 * period + start_delay + copy_delay.
> For large periods, with period > start_delay + copy_delay, this can
> lead to a lower latency, but who would use large periods for low
> latency?
>

Yes, this buffering schema is also possible, but note that the time window
for the data copy must satisfy the system scheduler requirements and
capabilities to get continous playback. In the "stream linked" case this
time window is exactly one period time.
</pre></small>

=== '''Meaning of --buffer and --period''' ===

Given the specific operation of the program outlined above, note that:

* The latency parameter, derived from <code>-m/--min</code> and <code>-M/--max</code> parameters, ultimately translates to the PCM buffer_size
* Specifying <code>--buffer</code> ultimately translates to the PCM period_size, and PCM buffer_size becomes 2x that - so we can consider it as a latency specification alternative to <code>-m/--min</code> and <code>-M/--max</code>
* Specifying <code>--period</code> does override the PCM period_size, leaving the PCM buffer_size untouched; however, the program will typically exit with an error, if the period_size happens to be not equal to buffer_size/2 and smaller than buffer_size/2 (for values >= buffer_size/2, the engine automatically limits period_size to buffer_size/2)

The easiest way to observe that is to patch/add the following <code>printf</code> statements to the <code>setparams_bufsize</code> function:

<small><pre>
int setparams_bufsize(...)
{
int err;
snd_pcm_uframes_t periodsize;

snd_pcm_hw_params_copy(params, tparams);
periodsize = bufsize * 2;
printf(" spbf: in bufsize:%li ; periodsize %li for %s\n", bufsize, periodsize, id); //added
err = snd_pcm_hw_params_set_buffer_size_near(handle, params, &periodsize);
if (err < 0) {
printf("Unable to set buffer size %li for %s: %s\n", bufsize * 2, id, snd_strerror(err));
return err;
}
printf(" ; set_buffer_size_near: %li for %s\n", periodsize, id); //added
if (period_size > 0)
periodsize = period_size;
else
periodsize /= 2;
printf(" ; now periodsize %li for %s\n", periodsize, id); //added
err = snd_pcm_hw_params_set_period_size_near(handle, params, &periodsize, 0);
if (err < 0) {
printf("Unable to set period size %li for %s: %s\n", periodsize, id, snd_strerror(err));
return err;
}
printf(" ; set_period_size_near: %li for %s\n", periodsize, id); //added
return 0;
}
</pre></small>

With this change, we can now observe the buffer/period size calculations:

<small><pre>
$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 64 -M 64 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max'
Loop limit is 44100 frames, minimum latency = 64, maximum latency = 64
spbf: in bufsize:32 ; periodsize 64 for playback
; set_buffer_size_near: 64 for playback
; now periodsize 32 for playback
; set_period_size_near: 32 for playback
spbf: in bufsize:32 ; periodsize 64 for capture
; set_buffer_size_near: 64 for capture
; now periodsize 32 for capture
; set_period_size_near: 32 for capture
stream : PLAYBACK
buffer_size : 64
period_size : 32
silence_size : 0
stream : CAPTURE
buffer_size : 64
period_size : 32
silence_size : 0
Trying latency 64 frames, 1451.247us, 1.451247ms (689.0625Hz)
state : XRUN
state : XRUN
Maximum read: 32 frames
Maximum read latency: 725.624us, 0.725624ms (1378.1250Hz)

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max'
Loop limit is 44100 frames, minimum latency = 128, maximum latency = 128
spbf: in bufsize:64 ; periodsize 128 for playback
; set_buffer_size_near: 128 for playback
; now periodsize 64 for playback
; set_period_size_near: 64 for playback
spbf: in bufsize:64 ; periodsize 128 for capture
; set_buffer_size_near: 128 for capture
; now periodsize 64 for capture
; set_period_size_near: 64 for capture
stream : PLAYBACK
buffer_size : 128
period_size : 64
silence_size : 0
stream : CAPTURE
buffer_size : 128
period_size : 64
silence_size : 0
Trying latency 128 frames, 2902.494us, 2.902494ms (344.5312Hz)
state : XRUN
state : XRUN
Maximum read: 64 frames
Maximum read latency: 1451.247us, 1.451247ms (689.0625Hz)

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 256 -M 256 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max'
Loop limit is 44100 frames, minimum latency = 256, maximum latency = 256
spbf: in bufsize:128 ; periodsize 256 for playback
; set_buffer_size_near: 256 for playback
; now periodsize 128 for playback
; set_period_size_near: 128 for playback
spbf: in bufsize:128 ; periodsize 256 for capture
; set_buffer_size_near: 256 for capture
; now periodsize 128 for capture
; set_period_size_near: 128 for capture
stream : PLAYBACK
buffer_size : 256
period_size : 128
silence_size : 0
stream : CAPTURE
buffer_size : 256
period_size : 128
silence_size : 0
Trying latency 256 frames, 5804.989us, 5.804989ms (172.2656Hz)
state : RUNNING
state : RUNNING
Maximum read: 128 frames
Maximum read latency: 2902.494us, 2.902494ms (344.5312Hz)

# so, we have:
# -m 64 -M 64 -> buffer_size : 64 -> Trying latency 64 frames
# -m 128 -M 128 -> buffer_size : 128 -> Trying latency 128 frames
# -m 256 -M 256 -> buffer_size : 256 -> Trying latency 256 frames

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 --buffer 128 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max'
Loop limit is 44100 frames, minimum latency = 64, maximum latency = 4096
spbf: in bufsize:128 ; periodsize 256 for playback
; set_buffer_size_near: 256 for playback
; now periodsize 128 for playback
; set_period_size_near: 128 for playback
spbf: in bufsize:128 ; periodsize 256 for capture
; set_buffer_size_near: 256 for capture
; now periodsize 128 for capture
; set_period_size_near: 128 for capture
stream : PLAYBACK
buffer_size : 256
period_size : 128
silence_size : 0
stream : CAPTURE
buffer_size : 256
period_size : 128
silence_size : 0
Trying latency 256 frames, 5804.989us, 5.804989ms (172.2656Hz)
state : RUNNING
state : RUNNING
Maximum read: 128 frames
Maximum read latency: 2902.494us, 2.902494ms (344.5312Hz)

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 --buffer 256 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max'
Loop limit is 44100 frames, minimum latency = 64, maximum latency = 4096
spbf: in bufsize:256 ; periodsize 512 for playback
; set_buffer_size_near: 512 for playback
; now periodsize 256 for playback
; set_period_size_near: 256 for playback
spbf: in bufsize:256 ; periodsize 512 for capture
; set_buffer_size_near: 512 for capture
; now periodsize 256 for capture
; set_period_size_near: 256 for capture
stream : PLAYBACK
buffer_size : 512
period_size : 256
silence_size : 0
stream : CAPTURE
buffer_size : 512
period_size : 256
silence_size : 0
Trying latency 512 frames, 11609.977us, 11.609977ms (86.1328Hz)
state : RUNNING
state : RUNNING
Maximum read: 256 frames
Maximum read latency: 5804.989us, 5.804989ms (172.2656Hz)

# so, we have:
# --buffer 128 -> buffer_size : 256 -> Trying latency 256 frames
# --buffer 256 -> buffer_size : 512 -> Trying latency 512 frames

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 --period 64 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max\|support'
Loop limit is 44100 frames, minimum latency = 128, maximum latency = 128
spbf: in bufsize:64 ; periodsize 128 for playback
; set_buffer_size_near: 128 for playback
; now periodsize 64 for playback
; set_period_size_near: 64 for playback
spbf: in bufsize:64 ; periodsize 128 for capture
; set_buffer_size_near: 128 for capture
; now periodsize 64 for capture
; set_period_size_near: 64 for capture
stream : PLAYBACK
buffer_size : 128
period_size : 64
silence_size : 0
stream : CAPTURE
buffer_size : 128
period_size : 64
silence_size : 0
Trying latency 128 frames, 2902.494us, 2.902494ms (344.5312Hz)
state : XRUN
state : XRUN
Maximum read: 64 frames
Maximum read latency: 1451.247us, 1.451247ms (689.0625Hz)

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 --period 128 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max\|support'
Loop limit is 44100 frames, minimum latency = 128, maximum latency = 128
spbf: in bufsize:64 ; periodsize 128 for playback
; set_buffer_size_near: 128 for playback
; now periodsize 128 for playback
; set_period_size_near: 64 for playback
spbf: in bufsize:64 ; periodsize 128 for capture
; set_buffer_size_near: 128 for capture
; now periodsize 128 for capture
; set_period_size_near: 64 for capture
stream : PLAYBACK
buffer_size : 128
period_size : 64
silence_size : 0
stream : CAPTURE
buffer_size : 128
period_size : 64
silence_size : 0
Trying latency 128 frames, 2902.494us, 2.902494ms (344.5312Hz)
state : XRUN
state : XRUN
Maximum read: 64 frames
Maximum read latency: 1451.247us, 1.451247ms (689.0625Hz)

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 --period 32 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max\|support'
Loop limit is 44100 frames, minimum latency = 128, maximum latency = 128
spbf: in bufsize:64 ; periodsize 128 for playback
; set_buffer_size_near: 128 for playback
; now periodsize 32 for playback
; set_period_size_near: 32 for playback
spbf: in bufsize:64 ; periodsize 128 for capture
; set_buffer_size_near: 128 for capture
; now periodsize 32 for capture
; set_period_size_near: 32 for capture
playback device does not support 2 periods per buffer

# so, we have - for buffer_size/latency=128 (spec'd by -m 128 -M 128):
# --period 64 -> period_size : 64 -> Trying latency 128 frames
# --period 128 -> period_size : 64 -> Trying latency 128 frames
# --period 32 -> period_size : 32 -> (error buffer_size != 2*period_size)
</pre></small>

Note that the "device does not support 2 periods per buffer" message comes from a revision to <code>latency.c</code> from 2011-04-20; earlier versions will exit, but not print a message.

=== '''Algorithm locking''' ===

Note that it is also possible to "lock" the program, especially if automatic latency increase is allowed by specifying different <code>-m/--min</code> and <code>-M/--max</code> options, and the very first run fails with an XRUN (which can happen often for small PCM period/buffer sizes).

For instance, under Linux kernel 2.6.38 / ALSA 1.0.24.2, HDA Intel can typically lock with <code>-m 64 -M 128</code> or <code>-m 64 -M 128</code>:

<small><pre>
$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 64 -M 128 -p -s 1
!!!Scheduler set to Round Robin with priority 99 FAILED!!!
Playback device is hw:0,0
Capture device is hw:0,0
Parameters are 44100Hz, S16_LE, 2 channels, non-blocking mode
Poll mode: yes
Loop limit is 44100 frames, minimum latency = 64, maximum latency = 128
spbf: in bufsize:32 ; periodsize 64 for playback
; set_buffer_size_near: 64 for playback
; now periodsize 32 for playback
; set_period_size_near: 32 for playback
spbf: in bufsize:32 ; periodsize 64 for capture
; set_buffer_size_near: 64 for capture
; now periodsize 32 for capture
; set_period_size_near: 32 for capture
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : PLAYBACK
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 64
period_size : 32
period_time : 725
tstamp_mode : NONE
period_step : 1
avail_min : 32
period_event : 0
start_threshold : 2147483647
stop_threshold : 64
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : CAPTURE
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 64
period_size : 32
period_time : 725
tstamp_mode : NONE
period_step : 1
avail_min : 32
period_event : 0
start_threshold : 2147483647
stop_threshold : 64
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Trying latency 64 frames, 1451.247us, 1.451247ms (689.0625Hz)
Failure
Playback:
*** frames = 64 ***
state : XRUN
trigger_time: 7448.736132319
tstamp : 7448.736189100
delay : 0
avail : 81
avail_max : 81
Capture:
*** frames = 32 ***
state : XRUN
trigger_time: 7448.736132319
tstamp : 7448.736301335
delay : 0
avail : 1
avail_max : 33
Maximum read: 32 frames
Maximum read latency: 725.624us, 0.725624ms (1378.1250Hz)
Hardware sync
spbf: in bufsize:36 ; periodsize 72 for playback
; set_buffer_size_near: 64 for playback
; now periodsize 32 for playback
; set_period_size_near: 32 for playback
spbf: in bufsize:36 ; periodsize 72 for capture
; set_buffer_size_near: 64 for capture
; now periodsize 32 for capture
; set_period_size_near: 32 for capture
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : PLAYBACK
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 64
period_size : 32
period_time : 725
tstamp_mode : NONE
period_step : 1
avail_min : 32
period_event : 0
start_threshold : 2147483647
stop_threshold : 64
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : CAPTURE
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 64
period_size : 32
period_time : 725
tstamp_mode : NONE
period_step : 1
avail_min : 32
period_event : 0
start_threshold : 2147483647
stop_threshold : 64
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Trying latency 72 frames, 1632.653us, 1.632653ms (612.5000Hz)
^C
</pre></small>

So, first the application is "Trying latency 64 frames", experiences an XRUN there, and then repeats the process, this time "Trying latency 72 frames". At this point, the application locks, and Ctrl-C needs to issued in the terminal to stop the application. Note that - in both cases - the engine decides on PCM buffer_size: 64, and period_size: 32 frames; regardless of what is specified as input latency.

Note that if we piped the output to <code>grep</code> also in the above example, similarly to previous examples - it is very likely that we would not observe the "Trying latency 72 frames ..." line.

A quick debug would be to first run the program through <code>strace</code>:

<small><pre>
$ strace ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 64 -M 128 -p -s 1
...
ioctl(4, 0x400c4150, 0xbfc7f6c8) = -1 EAGAIN (Resource temporarily unavailable)
ioctl(4, 0x400c4150, 0xbfc7f6c8) = -1 EAGAIN (Resource temporarily unavailable)
ioctl(4, 0x400c4150, 0xbfc7f6c8) = -1 EAGAIN (Resource temporarily unavailable)
ioctl(4, 0x400c4150, 0xbfc7f6c8) = -1 EAGAIN (Resource temporarily unavailable)
^C--- SIGINT (Interrupt) @ 0 (0) ---
</pre></small>

... which tells us that the program gets stuck on an <code>ioctl</code> system call, repeatedly trying to complete it (and again, Ctrl-C needs to issued in the terminal to stop the application).

To see more precisely where this problem occurs, we can run the program in the <code>gdb</code> debugger; wait for it to lock - and when it does, we can issue Ctrl-C to break into the program, and then issue <code>bt</code> to obtain a backtrace.

It should be noted here that <code>alsa-lib/test/latency</code> is actually a shell script, which loads the libraries built from the specific <code>alsa-lib/</code> source folder; however, for <code>gdb</code>, we need the actual executable, which is typically in <code>alsa-lib/test/.libs/lt-latency</code> <i>or</i> <code>alsa-lib/test/.libs/latency</code> (not sure why this name can vary; the <code>lt-</code> prefix is likely due to <code>ltmain.sh (GNU libtool)</code>).

So, the <code>gdb</code> session would look like this:

<small><pre>
$ gdb --args alsa-lib/test/.libs/latency -P hw:0,0 -C hw:0,0 -r 44100 -m 64 -M 128 -p -s 1
GNU gdb (GDB) 7.3.50.20110806-cvs
...
Reading symbols from /path/to/alsa-lib/test/.libs/latency...done.
(gdb) r
...
...
Trying latency 72 frames, 1632.653us, 1.632653ms (612.5000Hz)
^C
Program received signal SIGINT, Interrupt.
0x0012e416 in __kernel_vsyscall ()
(gdb) bt
#0 0x0012e416 in __kernel_vsyscall ()
#1 0x002c97c9 in ioctl () from /lib/i386-linux-gnu/libc.so.6
#2 0x00182890 in ?? () from /usr/lib/libasound.so.2
#3 0x00171ac4 in snd_pcm_writei () from /usr/lib/libasound.so.2
#4 0x0804a23b in writebuf (handle=0x8056ed8, buf=0x804e0b8 "", len=8, frames=0xbffff1bc) at latency.c:383
#5 0x0804ab8d in main (argc=14, argv=0xbffff294) at latency.c:639
</pre></small>

... which confirms that the failing <code>ioctl</code> is due to a <code>snd_pcm_writei</code> call.

Test latency.c

2013-09-12T20:02:02Z

Sdaau: added quick overview section

__FORCETOC__
== test latency.c ==

Within <code>alsa-lib</code>, there is a utility, [http://git.alsa-project.org/?p=alsa-lib.git;a=blob;f=test/latency.c; test/latency.c] ([http://git.alsa-project.org/?p=alsa-lib.git;a=history;f=test/latency.c; history]), which performs a full-duplex test, where recorded (captured) data is played back.

From <code>alsa-lib/test/latency.c</code>:

<small><pre>
* Latency test program
*
* This small demo program can be used for measuring latency between
* capture and playback. This latency is measured from driver (diff when
* playback and capture was started). Scheduler is set to SCHED_RR.
</pre></small>

=== '''Building''' ===

The name of the executable has to be passed explicitly to the <code>make</code> command - via [http://thread.gmane.org/gmane.linux.alsa.devel/6746/focus=6750 Re: problem ragarding execution of Latency.c (alsa-devel)]:

<small><pre>
cd alsa-lib/test
make latency
</pre></small>

=== '''Options''' ===

<small><pre>
$ ./latency -h
Usage: latency [OPTION]... [FILE]...
-h,--help help
-P,--pdevice playback device
-C,--cdevice capture device
-m,--min minimum latency in frames
-M,--max maximum latency in frames
-F,--frames frames to transfer
-f,--format sample format
-c,--channels channels
-r,--rate rate
-B,--buffer buffer size in frames
-E,--period period size in frames
-s,--seconds duration of test in seconds
-b,--block block mode
-p,--poll use poll (wait for event - reduces CPU usage)
-e,--effect apply an effect (bandpass filter sweep)
Recognized sample formats are: S8 U8 S16_LE S16_BE U16_LE U16_BE S24_LE S24_BE U24_LE U24_BE S32_LE S32_BE U32_LE U32_BE FLOAT_LE FLOAT_BE FLOAT64_LE FLOAT64_BE IEC958_SUBFRAME_LE IEC958_SUBFRAME_BE MU_LAW A_LAW IMA_ADPCM MPEG GSM SPECIAL S24_3LE S24_3BE U24_3LE U24_3BE S20_3LE S20_3BE U20_3LE U20_3BE S18_3LE S18_3BE U18_3LE

Tip #1 (usable latency with large periods, non-blocking mode, good CPU usage,
superb xrun prevention):
latency -m 8192 -M 8192 -t 1 -p
Tip #2 (superb latency, non-blocking mode, but heavy CPU usage):
latency -m 128 -M 128
</pre></small>

Notes:
* The option <code>-F,--frames</code> seems not to be handled anywhere in the code, and as such has no effect.
* The "Tip #1" refers to an option <code>-t</code> which doesn't exist - however, it is likely a typo for the option <code>-s</code> for duration in seconds
* The option <code>-s</code> for duration in seconds is an integer, and the lowest it can be set is 1 second; default if not specified is 30 seconds
* Before 2012-08-08, there is a bug where the short options <code>-B</code> and <code>-E</code> are not recognized ("invalid option") - but the long options <code>--buffer</code> and <code>--period</code> still work even then.

=== '''Usage''' ===

When called, the <code>test/latency.c</code> program will attemp to set period/buffer sizes based on the latency entered, starting from <code>-m,--min</code> option (or the default minimum latency = 64 if not specified). If the run succeeds without errors with that setting, the program exits; otherwise, the latency is increased, and the run repeated - if the run is succesful here, then program exits, else the process continues until the <code>-M,--max</code> latency is reached.

Example of successful run on Linux kernel 2.6.38 / ALSA 1.0.24.2 with HDA Intel onboard PCI soundcard:

<small><pre>
$ aplay -l
**** List of PLAYBACK Hardware Devices ****
card 0: Intel [HDA Intel], device 0: ALC269 Analog [ALC269 Analog]
Subdevices: 1/1
Subdevice #0: subdevice #0

$ alsa-lib/test/latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 -p -s 1
!!!Scheduler set to Round Robin with priority 99 FAILED!!!
Playback device is hw:0,0
Capture device is hw:0,0
Parameters are 44100Hz, S16_LE, 2 channels, non-blocking mode
Poll mode: yes
Loop limit is 44100 frames, minimum latency = 128, maximum latency = 128
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : PLAYBACK
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 128
period_size : 64
period_time : 1451
tstamp_mode : NONE
period_step : 1
avail_min : 64
period_event : 0
start_threshold : 2147483647
stop_threshold : 128
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : CAPTURE
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 128
period_size : 64
period_time : 1451
tstamp_mode : NONE
period_step : 1
avail_min : 64
period_event : 0
start_threshold : 2147483647
stop_threshold : 128
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Trying latency 128 frames, 2902.494us, 2.902494ms (344.5312Hz)
Success
Playback:
*** frames = 44288 ***
state : RUNNING
trigger_time: 84416.108859821
tstamp : 84417.110319083
delay : 80
avail : 48
avail_max : 120
Capture:
*** frames = 44160 ***
state : RUNNING
trigger_time: 84416.108859821
tstamp : 84417.110439490
delay : 9
avail : 9
avail_max : 65
Maximum read: 64 frames
Maximum read latency: 1451.247us, 1.451247ms (689.0625Hz)
Hardware sync
Playback time = 84416.108859, Record time = 84416.108859, diff = 0
</pre></small>

The message "<code>Scheduler set to Round Robin with priority 99 FAILED</code>" can be avoided by running the program with <code>sudo</code> (administrative privileges):

<small><pre>
$ sudo alsa-lib/test/latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 -p -s 1
[sudo] password for user:
Scheduler set to Round Robin with priority 99...
...
</pre></small>

The program can also fail, if the streams experience an XRUN; in that case, if <code>-m</code> is set to be equal to <code>-M</code>, the program will immediately exit:

<small><pre>
$ alsa-lib/test/latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 -p -s 1
!!!Scheduler set to Round Robin with priority 99 FAILED!!!
Playback device is hw:0,0
Capture device is hw:0,0
Parameters are 44100Hz, S16_LE, 2 channels, non-blocking mode
Poll mode: yes
Loop limit is 44100 frames, minimum latency = 128, maximum latency = 128
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : PLAYBACK
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 128
period_size : 64
period_time : 1451
tstamp_mode : NONE
period_step : 1
avail_min : 64
period_event : 0
start_threshold : 2147483647
stop_threshold : 128
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : CAPTURE
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 128
period_size : 64
period_time : 1451
tstamp_mode : NONE
period_step : 1
avail_min : 64
period_event : 0
start_threshold : 2147483647
stop_threshold : 128
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Trying latency 128 frames, 2902.494us, 2.902494ms (344.5312Hz)
Failure
Playback:
*** frames = 38464 ***
state : XRUN
trigger_time: 479.798093354
tstamp : 479.798185056
delay : 0
avail : 128
avail_max : 128
Capture:
*** frames = 38400 ***
state : XRUN
trigger_time: 479.798093354
tstamp : 479.798361196
delay : 0
avail : 9
avail_max : 73
Maximum read: 64 frames
Maximum read latency: 1451.247us, 1.451247ms (689.0625Hz)
Hardware sync
</pre></small>

=== '''Quick overview''' ===

In brief, the <code>latency.c</code> program:

* Parses the command line parameters/options, and sets the playback and capture stream properties according to them
* Starts a loop where (among other things) it:
** shows the current latency value, using the <code>showlatency()</code> function - which ultimately prints the "<i>Trying latency %li frames ...</i>" line
** calls [http://www.alsa-project.org/alsa-doc/alsa-lib/group___p_c_m.html#gac6c33091b049985baa6466e8fe93917e snd_pcm_link] on the capture and playback stream file descriptors, to have them "<i>start/stop/prepare in sync</i>"
** calls <code>snd_pcm_format_set_silence</code>, and then
** calls <code>writebuf(phandle, buffer, latency ...)</code> '''''twice'''''
** starts yet another <code>while</code> loop, where:
*** [http://www.alsa-project.org/alsa-doc/alsa-lib/group___p_c_m.html#gad4d53d58b996a7cd9a5cbf1710b90375 snd_pcm_wait] is called, if polling has been specified in the command line arguments;
*** <code>r = readbuf(chandle, buffer, latency, ...)</code> is called on the capture stream
*** <code>writebuf(phandle, buffer, r, ...)</code> is called on the playback stream

See the source code for details of the <code>readbuf()</code> and <code>writebuf()</code> functions - which may involve loops of their own, but ultimately call <code>[http://www.alsa-project.org/alsa-doc/alsa-lib/group___p_c_m.html#ga4c2c7bd26cf221268d59dc3bbeb9c048 snd_pcm_readi]</code> and <code>[http://www.alsa-project.org/alsa-doc/alsa-lib/group___p_c_m.html#gabc748a500743713eafa960c7d104ca6f snd_pcm_writei]</code>, respectively.

=== '''Mailing list notes''' ===

[http://thread.gmane.org/gmane.linux.alsa.devel/17014 latency.c: some feature requests (alsa-devel)] (2004-11-28)
<small><pre>
> It looks like the playback runs 64 frames ahead of the capture. Do you
> think this would be a problem from the application's perspective?
>

That's correct - it's the latency.

-----

>>>>> I also need the capture device interleaved and the playback device
>>>>> noninterleaved. latency.c does not support this at all, it just assumes
>>>>> that all hardware supports interleaved format.
>>>> Use default device (-D default and -P default) which automatically
>>>> uses available parameters.
>>>
>>> This will not work because I need to use hw:0,3 for playback and hw:0,2
>>> for capture.
>>
>> -P plughw:0,3 -C plughw:0,2

-----

>
> [...] One other thing I noticed is that latency.c doesn't mmap.
> This would cause higher latencies compared to testing with JACK,
> correct?

Yes, it's good point. Perhaps, the snd_pcm_mmap_readi/writei functions
should be used to optimize copying.
</pre></small>

[http://thread.gmane.org/gmane.linux.alsa.devel/37367 latency.c and delay related questions (alsa-devel)] (2006-06-20)
<small><pre>
> The current delay with "latency" is equal to a minimum (that depends
> on the sound card) plus *two* times the period time. [...]

Yes, it's correct. Basically, you cannot avoid double buffering, so the
total latency is:

1) one capture period
2) one playback period (actually being played)
3) moved captured period to playback buffer (not counted)

So the latency should be 2 * period plus a hw latency as you noted.
Everything is correct. Of course, you may get better latencies if you run
"busy loop" on not-loaded system and immediately put captured data to
playback stream, but it's not a correct behaviour in *nix.

> * why is snd_pcm_link() mandatory? (no sound otherwise)

It links playback and capture streams so only one start() is called. On
hardware which supports hardware syncing, the DMA operation is started at
same time for both stream.

> * why two buffers of silence and not just one?

You must wait one period to get data from the capture direction and then
you have exactly one period time to put these data to the playback. As I
said, you can get better results with busy-loop but it's bad
implementation (but if you have a spare dedicated machine without other
tasks, it might be an option).

-----

> [...] The linking of capture and playback devices
> explains everything; if I remove linking and use snd_pcm_start() on
> the playback device I get the expected behaviour.
>
> Here is a little drawing (requires fixed font) to illustrate what you
> have said and what I have understood (useless for you but some people
> like me might find it useful).
>
> When capture and playback devices are linked, the following happens:
>
> +-------------------------
> Capture | C0 | C1 | C2 | C3 | ...
> +-------------------------
>
> +-------------------------
> Playback | -- | -- | C0 | C1 | ...
> +-------------------------
>
> Capture and playback start simultaneously and so playback device needs
> something to play. When the first capture is finished, another is
> started. We would like to play the captured audio, but another
> playback has already started. Only after the latter is finished can
> the captured audio be played.
>
> This explains why the playback device needs two buffers of silence.
>
> The total delay is hw_delay + 2 * period
>

Exactly. Well explained.

> When the devices are not linked, we can start the playback device
> after the first buffer has been captured:
>
> +-------------------------
> Capture | C0 | C1 | C2 | C3 | ...
> +-------------------------
>
> +-----------------
> Playback | C0 | C1 | C2 | .
> +-----------------
>
> Starting the playback device and copying data takes some time, so the
> total delay becomes hw_delay + 1 * period + start_delay + copy_delay.
> For large periods, with period > start_delay + copy_delay, this can
> lead to a lower latency, but who would use large periods for low
> latency?
>

Yes, this buffering schema is also possible, but note that the time window
for the data copy must satisfy the system scheduler requirements and
capabilities to get continous playback. In the "stream linked" case this
time window is exactly one period time.
</pre></small>

=== '''Meaning of --buffer and --period''' ===

Given the specific operation of the program outlined above, note that:

* The latency parameter, derived from <code>-m/--min</code> and <code>-M/--max</code> parameters, ultimately translates to the PCM buffer_size
* Specifying <code>--buffer</code> ultimately translates to the PCM period_size, and PCM buffer_size becomes 2x that - so we can consider it as a latency specification alternative to <code>-m/--min</code> and <code>-M/--max</code>
* Specifying <code>--period</code> does override the PCM period_size, leaving the PCM buffer_size untouched; however, the program will typically exit with an error, if the period_size happens to be not equal to buffer_size/2 and smaller than buffer_size/2 (for values >= buffer_size/2, the engine automatically limits period_size to buffer_size/2)

The easiest way to observe that is to patch/add the following <code>printf</code> statements to the <code>setparams_bufsize</code> function:

<small><pre>
int setparams_bufsize(...)
{
int err;
snd_pcm_uframes_t periodsize;

snd_pcm_hw_params_copy(params, tparams);
periodsize = bufsize * 2;
printf(" spbf: in bufsize:%li ; periodsize %li for %s\n", bufsize, periodsize, id); //added
err = snd_pcm_hw_params_set_buffer_size_near(handle, params, &periodsize);
if (err < 0) {
printf("Unable to set buffer size %li for %s: %s\n", bufsize * 2, id, snd_strerror(err));
return err;
}
printf(" ; set_buffer_size_near: %li for %s\n", periodsize, id); //added
if (period_size > 0)
periodsize = period_size;
else
periodsize /= 2;
printf(" ; now periodsize %li for %s\n", periodsize, id); //added
err = snd_pcm_hw_params_set_period_size_near(handle, params, &periodsize, 0);
if (err < 0) {
printf("Unable to set period size %li for %s: %s\n", periodsize, id, snd_strerror(err));
return err;
}
printf(" ; set_period_size_near: %li for %s\n", periodsize, id); //added
return 0;
}
</pre></small>

With this change, we can now observe the buffer/period size calculations:

<small><pre>
$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 64 -M 64 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max'
Loop limit is 44100 frames, minimum latency = 64, maximum latency = 64
spbf: in bufsize:32 ; periodsize 64 for playback
; set_buffer_size_near: 64 for playback
; now periodsize 32 for playback
; set_period_size_near: 32 for playback
spbf: in bufsize:32 ; periodsize 64 for capture
; set_buffer_size_near: 64 for capture
; now periodsize 32 for capture
; set_period_size_near: 32 for capture
stream : PLAYBACK
buffer_size : 64
period_size : 32
silence_size : 0
stream : CAPTURE
buffer_size : 64
period_size : 32
silence_size : 0
Trying latency 64 frames, 1451.247us, 1.451247ms (689.0625Hz)
state : XRUN
state : XRUN
Maximum read: 32 frames
Maximum read latency: 725.624us, 0.725624ms (1378.1250Hz)

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max'
Loop limit is 44100 frames, minimum latency = 128, maximum latency = 128
spbf: in bufsize:64 ; periodsize 128 for playback
; set_buffer_size_near: 128 for playback
; now periodsize 64 for playback
; set_period_size_near: 64 for playback
spbf: in bufsize:64 ; periodsize 128 for capture
; set_buffer_size_near: 128 for capture
; now periodsize 64 for capture
; set_period_size_near: 64 for capture
stream : PLAYBACK
buffer_size : 128
period_size : 64
silence_size : 0
stream : CAPTURE
buffer_size : 128
period_size : 64
silence_size : 0
Trying latency 128 frames, 2902.494us, 2.902494ms (344.5312Hz)
state : XRUN
state : XRUN
Maximum read: 64 frames
Maximum read latency: 1451.247us, 1.451247ms (689.0625Hz)

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 256 -M 256 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max'
Loop limit is 44100 frames, minimum latency = 256, maximum latency = 256
spbf: in bufsize:128 ; periodsize 256 for playback
; set_buffer_size_near: 256 for playback
; now periodsize 128 for playback
; set_period_size_near: 128 for playback
spbf: in bufsize:128 ; periodsize 256 for capture
; set_buffer_size_near: 256 for capture
; now periodsize 128 for capture
; set_period_size_near: 128 for capture
stream : PLAYBACK
buffer_size : 256
period_size : 128
silence_size : 0
stream : CAPTURE
buffer_size : 256
period_size : 128
silence_size : 0
Trying latency 256 frames, 5804.989us, 5.804989ms (172.2656Hz)
state : RUNNING
state : RUNNING
Maximum read: 128 frames
Maximum read latency: 2902.494us, 2.902494ms (344.5312Hz)

# so, we have:
# -m 64 -M 64 -> buffer_size : 64 -> Trying latency 64 frames
# -m 128 -M 128 -> buffer_size : 128 -> Trying latency 128 frames
# -m 256 -M 256 -> buffer_size : 256 -> Trying latency 256 frames

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 --buffer 128 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max'
Loop limit is 44100 frames, minimum latency = 64, maximum latency = 4096
spbf: in bufsize:128 ; periodsize 256 for playback
; set_buffer_size_near: 256 for playback
; now periodsize 128 for playback
; set_period_size_near: 128 for playback
spbf: in bufsize:128 ; periodsize 256 for capture
; set_buffer_size_near: 256 for capture
; now periodsize 128 for capture
; set_period_size_near: 128 for capture
stream : PLAYBACK
buffer_size : 256
period_size : 128
silence_size : 0
stream : CAPTURE
buffer_size : 256
period_size : 128
silence_size : 0
Trying latency 256 frames, 5804.989us, 5.804989ms (172.2656Hz)
state : RUNNING
state : RUNNING
Maximum read: 128 frames
Maximum read latency: 2902.494us, 2.902494ms (344.5312Hz)

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 --buffer 256 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max'
Loop limit is 44100 frames, minimum latency = 64, maximum latency = 4096
spbf: in bufsize:256 ; periodsize 512 for playback
; set_buffer_size_near: 512 for playback
; now periodsize 256 for playback
; set_period_size_near: 256 for playback
spbf: in bufsize:256 ; periodsize 512 for capture
; set_buffer_size_near: 512 for capture
; now periodsize 256 for capture
; set_period_size_near: 256 for capture
stream : PLAYBACK
buffer_size : 512
period_size : 256
silence_size : 0
stream : CAPTURE
buffer_size : 512
period_size : 256
silence_size : 0
Trying latency 512 frames, 11609.977us, 11.609977ms (86.1328Hz)
state : RUNNING
state : RUNNING
Maximum read: 256 frames
Maximum read latency: 5804.989us, 5.804989ms (172.2656Hz)

# so, we have:
# --buffer 128 -> buffer_size : 256 -> Trying latency 256 frames
# --buffer 256 -> buffer_size : 512 -> Trying latency 512 frames

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 --period 64 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max\|support'
Loop limit is 44100 frames, minimum latency = 128, maximum latency = 128
spbf: in bufsize:64 ; periodsize 128 for playback
; set_buffer_size_near: 128 for playback
; now periodsize 64 for playback
; set_period_size_near: 64 for playback
spbf: in bufsize:64 ; periodsize 128 for capture
; set_buffer_size_near: 128 for capture
; now periodsize 64 for capture
; set_period_size_near: 64 for capture
stream : PLAYBACK
buffer_size : 128
period_size : 64
silence_size : 0
stream : CAPTURE
buffer_size : 128
period_size : 64
silence_size : 0
Trying latency 128 frames, 2902.494us, 2.902494ms (344.5312Hz)
state : XRUN
state : XRUN
Maximum read: 64 frames
Maximum read latency: 1451.247us, 1.451247ms (689.0625Hz)

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 --period 128 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max\|support'
Loop limit is 44100 frames, minimum latency = 128, maximum latency = 128
spbf: in bufsize:64 ; periodsize 128 for playback
; set_buffer_size_near: 128 for playback
; now periodsize 128 for playback
; set_period_size_near: 64 for playback
spbf: in bufsize:64 ; periodsize 128 for capture
; set_buffer_size_near: 128 for capture
; now periodsize 128 for capture
; set_period_size_near: 64 for capture
stream : PLAYBACK
buffer_size : 128
period_size : 64
silence_size : 0
stream : CAPTURE
buffer_size : 128
period_size : 64
silence_size : 0
Trying latency 128 frames, 2902.494us, 2.902494ms (344.5312Hz)
state : XRUN
state : XRUN
Maximum read: 64 frames
Maximum read latency: 1451.247us, 1.451247ms (689.0625Hz)

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 --period 32 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max\|support'
Loop limit is 44100 frames, minimum latency = 128, maximum latency = 128
spbf: in bufsize:64 ; periodsize 128 for playback
; set_buffer_size_near: 128 for playback
; now periodsize 32 for playback
; set_period_size_near: 32 for playback
spbf: in bufsize:64 ; periodsize 128 for capture
; set_buffer_size_near: 128 for capture
; now periodsize 32 for capture
; set_period_size_near: 32 for capture
playback device does not support 2 periods per buffer

# so, we have - for buffer_size/latency=128 (spec'd by -m 128 -M 128):
# --period 64 -> period_size : 64 -> Trying latency 128 frames
# --period 128 -> period_size : 64 -> Trying latency 128 frames
# --period 32 -> period_size : 32 -> (error buffer_size != 2*period_size)
</pre></small>

Note that the "device does not support 2 periods per buffer" message comes from a revision to <code>latency.c</code> from 2011-04-20; earlier versions will exit, but not print a message.

=== '''Algorithm locking''' ===

Note that it is also possible to "lock" the program, especially if automatic latency increase is allowed by specifying different <code>-m/--min</code> and <code>-M/--max</code> options, and the very first run fails with an XRUN (which can happen often for small PCM period/buffer sizes).

For instance, under Linux kernel 2.6.38 / ALSA 1.0.24.2, HDA Intel can typically lock with <code>-m 64 -M 128</code> or <code>-m 64 -M 128</code>:

<small><pre>
$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 64 -M 128 -p -s 1
!!!Scheduler set to Round Robin with priority 99 FAILED!!!
Playback device is hw:0,0
Capture device is hw:0,0
Parameters are 44100Hz, S16_LE, 2 channels, non-blocking mode
Poll mode: yes
Loop limit is 44100 frames, minimum latency = 64, maximum latency = 128
spbf: in bufsize:32 ; periodsize 64 for playback
; set_buffer_size_near: 64 for playback
; now periodsize 32 for playback
; set_period_size_near: 32 for playback
spbf: in bufsize:32 ; periodsize 64 for capture
; set_buffer_size_near: 64 for capture
; now periodsize 32 for capture
; set_period_size_near: 32 for capture
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : PLAYBACK
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 64
period_size : 32
period_time : 725
tstamp_mode : NONE
period_step : 1
avail_min : 32
period_event : 0
start_threshold : 2147483647
stop_threshold : 64
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : CAPTURE
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 64
period_size : 32
period_time : 725
tstamp_mode : NONE
period_step : 1
avail_min : 32
period_event : 0
start_threshold : 2147483647
stop_threshold : 64
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Trying latency 64 frames, 1451.247us, 1.451247ms (689.0625Hz)
Failure
Playback:
*** frames = 64 ***
state : XRUN
trigger_time: 7448.736132319
tstamp : 7448.736189100
delay : 0
avail : 81
avail_max : 81
Capture:
*** frames = 32 ***
state : XRUN
trigger_time: 7448.736132319
tstamp : 7448.736301335
delay : 0
avail : 1
avail_max : 33
Maximum read: 32 frames
Maximum read latency: 725.624us, 0.725624ms (1378.1250Hz)
Hardware sync
spbf: in bufsize:36 ; periodsize 72 for playback
; set_buffer_size_near: 64 for playback
; now periodsize 32 for playback
; set_period_size_near: 32 for playback
spbf: in bufsize:36 ; periodsize 72 for capture
; set_buffer_size_near: 64 for capture
; now periodsize 32 for capture
; set_period_size_near: 32 for capture
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : PLAYBACK
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 64
period_size : 32
period_time : 725
tstamp_mode : NONE
period_step : 1
avail_min : 32
period_event : 0
start_threshold : 2147483647
stop_threshold : 64
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : CAPTURE
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 64
period_size : 32
period_time : 725
tstamp_mode : NONE
period_step : 1
avail_min : 32
period_event : 0
start_threshold : 2147483647
stop_threshold : 64
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Trying latency 72 frames, 1632.653us, 1.632653ms (612.5000Hz)
^C
</pre></small>

So, first the application is "Trying latency 64 frames", experiences an XRUN there, and then repeats the process, this time "Trying latency 72 frames". At this point, the application locks, and Ctrl-C needs to issued in the terminal to stop the application. Note that - in both cases - the engine decides on PCM buffer_size: 64, and period_size: 32 frames; regardless of what is specified as input latency.

Note that if we piped the output to <code>grep</code> also in the above example, similarly to previous examples - it is very likely that we would not observe the "Trying latency 72 frames ..." line.

A quick debug would be to first run the program through <code>strace</code>:

<small><pre>
$ strace ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 64 -M 128 -p -s 1
...
ioctl(4, 0x400c4150, 0xbfc7f6c8) = -1 EAGAIN (Resource temporarily unavailable)
ioctl(4, 0x400c4150, 0xbfc7f6c8) = -1 EAGAIN (Resource temporarily unavailable)
ioctl(4, 0x400c4150, 0xbfc7f6c8) = -1 EAGAIN (Resource temporarily unavailable)
ioctl(4, 0x400c4150, 0xbfc7f6c8) = -1 EAGAIN (Resource temporarily unavailable)
^C--- SIGINT (Interrupt) @ 0 (0) ---
</pre></small>

... which tells us that the program gets stuck on an <code>ioctl</code> system call, repeatedly trying to complete it (and again, Ctrl-C needs to issued in the terminal to stop the application).

To see more precisely where this problem occurs, we can run the program in the <code>gdb</code> debugger; wait for it to lock - and when it does, we can issue Ctrl-C to break into the program, and then issue <code>bt</code> to obtain a backtrace.

It should be noted here that <code>alsa-lib/test/latency</code> is actually a shell script, which loads the libraries built from the specific <code>alsa-lib/</code> source folder; however, for <code>gdb</code>, we need the actual executable, which is typically in <code>alsa-lib/test/.libs/lt-latency</code> <i>or</i> <code>alsa-lib/test/.libs/latency</code> (not sure why this name can vary; the <code>lt-</code> prefix is likely due to <code>ltmain.sh (GNU libtool)</code>).

So, the <code>gdb</code> session would look like this:

<small><pre>
$ gdb --args alsa-lib/test/.libs/latency -P hw:0,0 -C hw:0,0 -r 44100 -m 64 -M 128 -p -s 1
GNU gdb (GDB) 7.3.50.20110806-cvs
...
Reading symbols from /path/to/alsa-lib/test/.libs/latency...done.
(gdb) r
...
...
Trying latency 72 frames, 1632.653us, 1.632653ms (612.5000Hz)
^C
Program received signal SIGINT, Interrupt.
0x0012e416 in __kernel_vsyscall ()
(gdb) bt
#0 0x0012e416 in __kernel_vsyscall ()
#1 0x002c97c9 in ioctl () from /lib/i386-linux-gnu/libc.so.6
#2 0x00182890 in ?? () from /usr/lib/libasound.so.2
#3 0x00171ac4 in snd_pcm_writei () from /usr/lib/libasound.so.2
#4 0x0804a23b in writebuf (handle=0x8056ed8, buf=0x804e0b8 "", len=8, frames=0xbffff1bc) at latency.c:383
#5 0x0804ab8d in main (argc=14, argv=0xbffff294) at latency.c:639
</pre></small>

... which confirms that the failing <code>ioctl</code> is due to a <code>snd_pcm_writei</code> call.

Test latency.c

2013-08-18T11:06:52Z

Sdaau: inited page

__FORCETOC__
== test latency.c ==

Within <code>alsa-lib</code>, there is a utility, [http://git.alsa-project.org/?p=alsa-lib.git;a=blob;f=test/latency.c; test/latency.c] ([http://git.alsa-project.org/?p=alsa-lib.git;a=history;f=test/latency.c; history]), which performs a full-duplex test, where recorded (captured) data is played back.

From <code>alsa-lib/test/latency.c</code>:

<small><pre>
* Latency test program
*
* This small demo program can be used for measuring latency between
* capture and playback. This latency is measured from driver (diff when
* playback and capture was started). Scheduler is set to SCHED_RR.
</pre></small>

=== '''Building''' ===

The name of the executable has to be passed explicitly to the <code>make</code> command - via [http://thread.gmane.org/gmane.linux.alsa.devel/6746/focus=6750 Re: problem ragarding execution of Latency.c (alsa-devel)]:

<small><pre>
cd alsa-lib/test
make latency
</pre></small>

=== '''Options''' ===

<small><pre>
$ ./latency -h
Usage: latency [OPTION]... [FILE]...
-h,--help help
-P,--pdevice playback device
-C,--cdevice capture device
-m,--min minimum latency in frames
-M,--max maximum latency in frames
-F,--frames frames to transfer
-f,--format sample format
-c,--channels channels
-r,--rate rate
-B,--buffer buffer size in frames
-E,--period period size in frames
-s,--seconds duration of test in seconds
-b,--block block mode
-p,--poll use poll (wait for event - reduces CPU usage)
-e,--effect apply an effect (bandpass filter sweep)
Recognized sample formats are: S8 U8 S16_LE S16_BE U16_LE U16_BE S24_LE S24_BE U24_LE U24_BE S32_LE S32_BE U32_LE U32_BE FLOAT_LE FLOAT_BE FLOAT64_LE FLOAT64_BE IEC958_SUBFRAME_LE IEC958_SUBFRAME_BE MU_LAW A_LAW IMA_ADPCM MPEG GSM SPECIAL S24_3LE S24_3BE U24_3LE U24_3BE S20_3LE S20_3BE U20_3LE U20_3BE S18_3LE S18_3BE U18_3LE

Tip #1 (usable latency with large periods, non-blocking mode, good CPU usage,
superb xrun prevention):
latency -m 8192 -M 8192 -t 1 -p
Tip #2 (superb latency, non-blocking mode, but heavy CPU usage):
latency -m 128 -M 128
</pre></small>

Notes:
* The option <code>-F,--frames</code> seems not to be handled anywhere in the code, and as such has no effect.
* The "Tip #1" refers to an option <code>-t</code> which doesn't exist - however, it is likely a typo for the option <code>-s</code> for duration in seconds
* The option <code>-s</code> for duration in seconds is an integer, and the lowest it can be set is 1 second; default if not specified is 30 seconds
* Before 2012-08-08, there is a bug where the short options <code>-B</code> and <code>-E</code> are not recognized ("invalid option") - but the long options <code>--buffer</code> and <code>--period</code> still work even then.

=== '''Usage''' ===

When called, the <code>test/latency.c</code> program will attemp to set period/buffer sizes based on the latency entered, starting from <code>-m,--min</code> option (or the default minimum latency = 64 if not specified). If the run succeeds without errors with that setting, the program exits; otherwise, the latency is increased, and the run repeated - if the run is succesful here, then program exits, else the process continues until the <code>-M,--max</code> latency is reached.

Example of successful run on Linux kernel 2.6.38 / ALSA 1.0.24.2 with HDA Intel onboard PCI soundcard:

<small><pre>
$ aplay -l
**** List of PLAYBACK Hardware Devices ****
card 0: Intel [HDA Intel], device 0: ALC269 Analog [ALC269 Analog]
Subdevices: 1/1
Subdevice #0: subdevice #0

$ alsa-lib/test/latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 -p -s 1
!!!Scheduler set to Round Robin with priority 99 FAILED!!!
Playback device is hw:0,0
Capture device is hw:0,0
Parameters are 44100Hz, S16_LE, 2 channels, non-blocking mode
Poll mode: yes
Loop limit is 44100 frames, minimum latency = 128, maximum latency = 128
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : PLAYBACK
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 128
period_size : 64
period_time : 1451
tstamp_mode : NONE
period_step : 1
avail_min : 64
period_event : 0
start_threshold : 2147483647
stop_threshold : 128
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : CAPTURE
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 128
period_size : 64
period_time : 1451
tstamp_mode : NONE
period_step : 1
avail_min : 64
period_event : 0
start_threshold : 2147483647
stop_threshold : 128
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Trying latency 128 frames, 2902.494us, 2.902494ms (344.5312Hz)
Success
Playback:
*** frames = 44288 ***
state : RUNNING
trigger_time: 84416.108859821
tstamp : 84417.110319083
delay : 80
avail : 48
avail_max : 120
Capture:
*** frames = 44160 ***
state : RUNNING
trigger_time: 84416.108859821
tstamp : 84417.110439490
delay : 9
avail : 9
avail_max : 65
Maximum read: 64 frames
Maximum read latency: 1451.247us, 1.451247ms (689.0625Hz)
Hardware sync
Playback time = 84416.108859, Record time = 84416.108859, diff = 0
</pre></small>

The message "<code>Scheduler set to Round Robin with priority 99 FAILED</code>" can be avoided by running the program with <code>sudo</code> (administrative privileges):

<small><pre>
$ sudo alsa-lib/test/latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 -p -s 1
[sudo] password for user:
Scheduler set to Round Robin with priority 99...
...
</pre></small>

The program can also fail, if the streams experience an XRUN; in that case, if <code>-m</code> is set to be equal to <code>-M</code>, the program will immediately exit:

<small><pre>
$ alsa-lib/test/latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 -p -s 1
!!!Scheduler set to Round Robin with priority 99 FAILED!!!
Playback device is hw:0,0
Capture device is hw:0,0
Parameters are 44100Hz, S16_LE, 2 channels, non-blocking mode
Poll mode: yes
Loop limit is 44100 frames, minimum latency = 128, maximum latency = 128
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : PLAYBACK
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 128
period_size : 64
period_time : 1451
tstamp_mode : NONE
period_step : 1
avail_min : 64
period_event : 0
start_threshold : 2147483647
stop_threshold : 128
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : CAPTURE
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 128
period_size : 64
period_time : 1451
tstamp_mode : NONE
period_step : 1
avail_min : 64
period_event : 0
start_threshold : 2147483647
stop_threshold : 128
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Trying latency 128 frames, 2902.494us, 2.902494ms (344.5312Hz)
Failure
Playback:
*** frames = 38464 ***
state : XRUN
trigger_time: 479.798093354
tstamp : 479.798185056
delay : 0
avail : 128
avail_max : 128
Capture:
*** frames = 38400 ***
state : XRUN
trigger_time: 479.798093354
tstamp : 479.798361196
delay : 0
avail : 9
avail_max : 73
Maximum read: 64 frames
Maximum read latency: 1451.247us, 1.451247ms (689.0625Hz)
Hardware sync
</pre></small>

=== '''Mailing list notes''' ===

[http://thread.gmane.org/gmane.linux.alsa.devel/17014 latency.c: some feature requests (alsa-devel)] (2004-11-28)
<small><pre>
> It looks like the playback runs 64 frames ahead of the capture. Do you
> think this would be a problem from the application's perspective?
>

That's correct - it's the latency.

-----

>>>>> I also need the capture device interleaved and the playback device
>>>>> noninterleaved. latency.c does not support this at all, it just assumes
>>>>> that all hardware supports interleaved format.
>>>> Use default device (-D default and -P default) which automatically
>>>> uses available parameters.
>>>
>>> This will not work because I need to use hw:0,3 for playback and hw:0,2
>>> for capture.
>>
>> -P plughw:0,3 -C plughw:0,2

-----

>
> [...] One other thing I noticed is that latency.c doesn't mmap.
> This would cause higher latencies compared to testing with JACK,
> correct?

Yes, it's good point. Perhaps, the snd_pcm_mmap_readi/writei functions
should be used to optimize copying.
</pre></small>

[http://thread.gmane.org/gmane.linux.alsa.devel/37367 latency.c and delay related questions (alsa-devel)] (2006-06-20)
<small><pre>
> The current delay with "latency" is equal to a minimum (that depends
> on the sound card) plus *two* times the period time. [...]

Yes, it's correct. Basically, you cannot avoid double buffering, so the
total latency is:

1) one capture period
2) one playback period (actually being played)
3) moved captured period to playback buffer (not counted)

So the latency should be 2 * period plus a hw latency as you noted.
Everything is correct. Of course, you may get better latencies if you run
"busy loop" on not-loaded system and immediately put captured data to
playback stream, but it's not a correct behaviour in *nix.

> * why is snd_pcm_link() mandatory? (no sound otherwise)

It links playback and capture streams so only one start() is called. On
hardware which supports hardware syncing, the DMA operation is started at
same time for both stream.

> * why two buffers of silence and not just one?

You must wait one period to get data from the capture direction and then
you have exactly one period time to put these data to the playback. As I
said, you can get better results with busy-loop but it's bad
implementation (but if you have a spare dedicated machine without other
tasks, it might be an option).

-----

> [...] The linking of capture and playback devices
> explains everything; if I remove linking and use snd_pcm_start() on
> the playback device I get the expected behaviour.
>
> Here is a little drawing (requires fixed font) to illustrate what you
> have said and what I have understood (useless for you but some people
> like me might find it useful).
>
> When capture and playback devices are linked, the following happens:
>
> +-------------------------
> Capture | C0 | C1 | C2 | C3 | ...
> +-------------------------
>
> +-------------------------
> Playback | -- | -- | C0 | C1 | ...
> +-------------------------
>
> Capture and playback start simultaneously and so playback device needs
> something to play. When the first capture is finished, another is
> started. We would like to play the captured audio, but another
> playback has already started. Only after the latter is finished can
> the captured audio be played.
>
> This explains why the playback device needs two buffers of silence.
>
> The total delay is hw_delay + 2 * period
>

Exactly. Well explained.

> When the devices are not linked, we can start the playback device
> after the first buffer has been captured:
>
> +-------------------------
> Capture | C0 | C1 | C2 | C3 | ...
> +-------------------------
>
> +-----------------
> Playback | C0 | C1 | C2 | .
> +-----------------
>
> Starting the playback device and copying data takes some time, so the
> total delay becomes hw_delay + 1 * period + start_delay + copy_delay.
> For large periods, with period > start_delay + copy_delay, this can
> lead to a lower latency, but who would use large periods for low
> latency?
>

Yes, this buffering schema is also possible, but note that the time window
for the data copy must satisfy the system scheduler requirements and
capabilities to get continous playback. In the "stream linked" case this
time window is exactly one period time.
</pre></small>

=== '''Meaning of --buffer and --period''' ===

Given the specific operation of the program outlined above, note that:

* The latency parameter, derived from <code>-m/--min</code> and <code>-M/--max</code> parameters, ultimately translates to the PCM buffer_size
* Specifying <code>--buffer</code> ultimately translates to the PCM period_size, and PCM buffer_size becomes 2x that - so we can consider it as a latency specification alternative to <code>-m/--min</code> and <code>-M/--max</code>
* Specifying <code>--period</code> does override the PCM period_size, leaving the PCM buffer_size untouched; however, the program will typically exit with an error, if the period_size happens to be not equal to buffer_size/2 and smaller than buffer_size/2 (for values >= buffer_size/2, the engine automatically limits period_size to buffer_size/2)

The easiest way to observe that is to patch/add the following <code>printf</code> statements to the <code>setparams_bufsize</code> function:

<small><pre>
int setparams_bufsize(...)
{
int err;
snd_pcm_uframes_t periodsize;

snd_pcm_hw_params_copy(params, tparams);
periodsize = bufsize * 2;
printf(" spbf: in bufsize:%li ; periodsize %li for %s\n", bufsize, periodsize, id); //added
err = snd_pcm_hw_params_set_buffer_size_near(handle, params, &periodsize);
if (err < 0) {
printf("Unable to set buffer size %li for %s: %s\n", bufsize * 2, id, snd_strerror(err));
return err;
}
printf(" ; set_buffer_size_near: %li for %s\n", periodsize, id); //added
if (period_size > 0)
periodsize = period_size;
else
periodsize /= 2;
printf(" ; now periodsize %li for %s\n", periodsize, id); //added
err = snd_pcm_hw_params_set_period_size_near(handle, params, &periodsize, 0);
if (err < 0) {
printf("Unable to set period size %li for %s: %s\n", periodsize, id, snd_strerror(err));
return err;
}
printf(" ; set_period_size_near: %li for %s\n", periodsize, id); //added
return 0;
}
</pre></small>

With this change, we can now observe the buffer/period size calculations:

<small><pre>
$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 64 -M 64 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max'
Loop limit is 44100 frames, minimum latency = 64, maximum latency = 64
spbf: in bufsize:32 ; periodsize 64 for playback
; set_buffer_size_near: 64 for playback
; now periodsize 32 for playback
; set_period_size_near: 32 for playback
spbf: in bufsize:32 ; periodsize 64 for capture
; set_buffer_size_near: 64 for capture
; now periodsize 32 for capture
; set_period_size_near: 32 for capture
stream : PLAYBACK
buffer_size : 64
period_size : 32
silence_size : 0
stream : CAPTURE
buffer_size : 64
period_size : 32
silence_size : 0
Trying latency 64 frames, 1451.247us, 1.451247ms (689.0625Hz)
state : XRUN
state : XRUN
Maximum read: 32 frames
Maximum read latency: 725.624us, 0.725624ms (1378.1250Hz)

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max'
Loop limit is 44100 frames, minimum latency = 128, maximum latency = 128
spbf: in bufsize:64 ; periodsize 128 for playback
; set_buffer_size_near: 128 for playback
; now periodsize 64 for playback
; set_period_size_near: 64 for playback
spbf: in bufsize:64 ; periodsize 128 for capture
; set_buffer_size_near: 128 for capture
; now periodsize 64 for capture
; set_period_size_near: 64 for capture
stream : PLAYBACK
buffer_size : 128
period_size : 64
silence_size : 0
stream : CAPTURE
buffer_size : 128
period_size : 64
silence_size : 0
Trying latency 128 frames, 2902.494us, 2.902494ms (344.5312Hz)
state : XRUN
state : XRUN
Maximum read: 64 frames
Maximum read latency: 1451.247us, 1.451247ms (689.0625Hz)

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 256 -M 256 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max'
Loop limit is 44100 frames, minimum latency = 256, maximum latency = 256
spbf: in bufsize:128 ; periodsize 256 for playback
; set_buffer_size_near: 256 for playback
; now periodsize 128 for playback
; set_period_size_near: 128 for playback
spbf: in bufsize:128 ; periodsize 256 for capture
; set_buffer_size_near: 256 for capture
; now periodsize 128 for capture
; set_period_size_near: 128 for capture
stream : PLAYBACK
buffer_size : 256
period_size : 128
silence_size : 0
stream : CAPTURE
buffer_size : 256
period_size : 128
silence_size : 0
Trying latency 256 frames, 5804.989us, 5.804989ms (172.2656Hz)
state : RUNNING
state : RUNNING
Maximum read: 128 frames
Maximum read latency: 2902.494us, 2.902494ms (344.5312Hz)

# so, we have:
# -m 64 -M 64 -> buffer_size : 64 -> Trying latency 64 frames
# -m 128 -M 128 -> buffer_size : 128 -> Trying latency 128 frames
# -m 256 -M 256 -> buffer_size : 256 -> Trying latency 256 frames

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 --buffer 128 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max'
Loop limit is 44100 frames, minimum latency = 64, maximum latency = 4096
spbf: in bufsize:128 ; periodsize 256 for playback
; set_buffer_size_near: 256 for playback
; now periodsize 128 for playback
; set_period_size_near: 128 for playback
spbf: in bufsize:128 ; periodsize 256 for capture
; set_buffer_size_near: 256 for capture
; now periodsize 128 for capture
; set_period_size_near: 128 for capture
stream : PLAYBACK
buffer_size : 256
period_size : 128
silence_size : 0
stream : CAPTURE
buffer_size : 256
period_size : 128
silence_size : 0
Trying latency 256 frames, 5804.989us, 5.804989ms (172.2656Hz)
state : RUNNING
state : RUNNING
Maximum read: 128 frames
Maximum read latency: 2902.494us, 2.902494ms (344.5312Hz)

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 --buffer 256 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max'
Loop limit is 44100 frames, minimum latency = 64, maximum latency = 4096
spbf: in bufsize:256 ; periodsize 512 for playback
; set_buffer_size_near: 512 for playback
; now periodsize 256 for playback
; set_period_size_near: 256 for playback
spbf: in bufsize:256 ; periodsize 512 for capture
; set_buffer_size_near: 512 for capture
; now periodsize 256 for capture
; set_period_size_near: 256 for capture
stream : PLAYBACK
buffer_size : 512
period_size : 256
silence_size : 0
stream : CAPTURE
buffer_size : 512
period_size : 256
silence_size : 0
Trying latency 512 frames, 11609.977us, 11.609977ms (86.1328Hz)
state : RUNNING
state : RUNNING
Maximum read: 256 frames
Maximum read latency: 5804.989us, 5.804989ms (172.2656Hz)

# so, we have:
# --buffer 128 -> buffer_size : 256 -> Trying latency 256 frames
# --buffer 256 -> buffer_size : 512 -> Trying latency 512 frames

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 --period 64 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max\|support'
Loop limit is 44100 frames, minimum latency = 128, maximum latency = 128
spbf: in bufsize:64 ; periodsize 128 for playback
; set_buffer_size_near: 128 for playback
; now periodsize 64 for playback
; set_period_size_near: 64 for playback
spbf: in bufsize:64 ; periodsize 128 for capture
; set_buffer_size_near: 128 for capture
; now periodsize 64 for capture
; set_period_size_near: 64 for capture
stream : PLAYBACK
buffer_size : 128
period_size : 64
silence_size : 0
stream : CAPTURE
buffer_size : 128
period_size : 64
silence_size : 0
Trying latency 128 frames, 2902.494us, 2.902494ms (344.5312Hz)
state : XRUN
state : XRUN
Maximum read: 64 frames
Maximum read latency: 1451.247us, 1.451247ms (689.0625Hz)

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 --period 128 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max\|support'
Loop limit is 44100 frames, minimum latency = 128, maximum latency = 128
spbf: in bufsize:64 ; periodsize 128 for playback
; set_buffer_size_near: 128 for playback
; now periodsize 128 for playback
; set_period_size_near: 64 for playback
spbf: in bufsize:64 ; periodsize 128 for capture
; set_buffer_size_near: 128 for capture
; now periodsize 128 for capture
; set_period_size_near: 64 for capture
stream : PLAYBACK
buffer_size : 128
period_size : 64
silence_size : 0
stream : CAPTURE
buffer_size : 128
period_size : 64
silence_size : 0
Trying latency 128 frames, 2902.494us, 2.902494ms (344.5312Hz)
state : XRUN
state : XRUN
Maximum read: 64 frames
Maximum read latency: 1451.247us, 1.451247ms (689.0625Hz)

$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 128 -M 128 --period 32 -p -s 1 | grep 'size\|Trying\|limit\|state\|stream\|Max\|support'
Loop limit is 44100 frames, minimum latency = 128, maximum latency = 128
spbf: in bufsize:64 ; periodsize 128 for playback
; set_buffer_size_near: 128 for playback
; now periodsize 32 for playback
; set_period_size_near: 32 for playback
spbf: in bufsize:64 ; periodsize 128 for capture
; set_buffer_size_near: 128 for capture
; now periodsize 32 for capture
; set_period_size_near: 32 for capture
playback device does not support 2 periods per buffer

# so, we have - for buffer_size/latency=128 (spec'd by -m 128 -M 128):
# --period 64 -> period_size : 64 -> Trying latency 128 frames
# --period 128 -> period_size : 64 -> Trying latency 128 frames
# --period 32 -> period_size : 32 -> (error buffer_size != 2*period_size)
</pre></small>

Note that the "device does not support 2 periods per buffer" message comes from a revision to <code>latency.c</code> from 2011-04-20; earlier versions will exit, but not print a message.

=== '''Algorithm locking''' ===

Note that it is also possible to "lock" the program, especially if automatic latency increase is allowed by specifying different <code>-m/--min</code> and <code>-M/--max</code> options, and the very first run fails with an XRUN (which can happen often for small PCM period/buffer sizes).

For instance, under Linux kernel 2.6.38 / ALSA 1.0.24.2, HDA Intel can typically lock with <code>-m 64 -M 128</code> or <code>-m 64 -M 128</code>:

<small><pre>
$ ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 64 -M 128 -p -s 1
!!!Scheduler set to Round Robin with priority 99 FAILED!!!
Playback device is hw:0,0
Capture device is hw:0,0
Parameters are 44100Hz, S16_LE, 2 channels, non-blocking mode
Poll mode: yes
Loop limit is 44100 frames, minimum latency = 64, maximum latency = 128
spbf: in bufsize:32 ; periodsize 64 for playback
; set_buffer_size_near: 64 for playback
; now periodsize 32 for playback
; set_period_size_near: 32 for playback
spbf: in bufsize:32 ; periodsize 64 for capture
; set_buffer_size_near: 64 for capture
; now periodsize 32 for capture
; set_period_size_near: 32 for capture
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : PLAYBACK
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 64
period_size : 32
period_time : 725
tstamp_mode : NONE
period_step : 1
avail_min : 32
period_event : 0
start_threshold : 2147483647
stop_threshold : 64
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : CAPTURE
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 64
period_size : 32
period_time : 725
tstamp_mode : NONE
period_step : 1
avail_min : 32
period_event : 0
start_threshold : 2147483647
stop_threshold : 64
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Trying latency 64 frames, 1451.247us, 1.451247ms (689.0625Hz)
Failure
Playback:
*** frames = 64 ***
state : XRUN
trigger_time: 7448.736132319
tstamp : 7448.736189100
delay : 0
avail : 81
avail_max : 81
Capture:
*** frames = 32 ***
state : XRUN
trigger_time: 7448.736132319
tstamp : 7448.736301335
delay : 0
avail : 1
avail_max : 33
Maximum read: 32 frames
Maximum read latency: 725.624us, 0.725624ms (1378.1250Hz)
Hardware sync
spbf: in bufsize:36 ; periodsize 72 for playback
; set_buffer_size_near: 64 for playback
; now periodsize 32 for playback
; set_period_size_near: 32 for playback
spbf: in bufsize:36 ; periodsize 72 for capture
; set_buffer_size_near: 64 for capture
; now periodsize 32 for capture
; set_period_size_near: 32 for capture
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : PLAYBACK
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 64
period_size : 32
period_time : 725
tstamp_mode : NONE
period_step : 1
avail_min : 32
period_event : 0
start_threshold : 2147483647
stop_threshold : 64
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Hardware PCM card 0 'HDA Intel' device 0 subdevice 0
Its setup is:
stream : CAPTURE
access : RW_INTERLEAVED
format : S16_LE
subformat : STD
channels : 2
rate : 44100
exact rate : 44100 (44100/1)
msbits : 16
buffer_size : 64
period_size : 32
period_time : 725
tstamp_mode : NONE
period_step : 1
avail_min : 32
period_event : 0
start_threshold : 2147483647
stop_threshold : 64
silence_threshold: 0
silence_size : 0
boundary : 1073741824
appl_ptr : 0
hw_ptr : 0
Trying latency 72 frames, 1632.653us, 1.632653ms (612.5000Hz)
^C
</pre></small>

So, first the application is "Trying latency 64 frames", experiences an XRUN there, and then repeats the process, this time "Trying latency 72 frames". At this point, the application locks, and Ctrl-C needs to issued in the terminal to stop the application. Note that - in both cases - the engine decides on PCM buffer_size: 64, and period_size: 32 frames; regardless of what is specified as input latency.

Note that if we piped the output to <code>grep</code> also in the above example, similarly to previous examples - it is very likely that we would not observe the "Trying latency 72 frames ..." line.

A quick debug would be to first run the program through <code>strace</code>:

<small><pre>
$ strace ./latency -P hw:0,0 -C hw:0,0 -r 44100 -m 64 -M 128 -p -s 1
...
ioctl(4, 0x400c4150, 0xbfc7f6c8) = -1 EAGAIN (Resource temporarily unavailable)
ioctl(4, 0x400c4150, 0xbfc7f6c8) = -1 EAGAIN (Resource temporarily unavailable)
ioctl(4, 0x400c4150, 0xbfc7f6c8) = -1 EAGAIN (Resource temporarily unavailable)
ioctl(4, 0x400c4150, 0xbfc7f6c8) = -1 EAGAIN (Resource temporarily unavailable)
^C--- SIGINT (Interrupt) @ 0 (0) ---
</pre></small>

... which tells us that the program gets stuck on an <code>ioctl</code> system call, repeatedly trying to complete it (and again, Ctrl-C needs to issued in the terminal to stop the application).

To see more precisely where this problem occurs, we can run the program in the <code>gdb</code> debugger; wait for it to lock - and when it does, we can issue Ctrl-C to break into the program, and then issue <code>bt</code> to obtain a backtrace.

It should be noted here that <code>alsa-lib/test/latency</code> is actually a shell script, which loads the libraries built from the specific <code>alsa-lib/</code> source folder; however, for <code>gdb</code>, we need the actual executable, which is typically in <code>alsa-lib/test/.libs/lt-latency</code> <i>or</i> <code>alsa-lib/test/.libs/latency</code> (not sure why this name can vary; the <code>lt-</code> prefix is likely due to <code>ltmain.sh (GNU libtool)</code>).

So, the <code>gdb</code> session would look like this:

<small><pre>
$ gdb --args alsa-lib/test/.libs/latency -P hw:0,0 -C hw:0,0 -r 44100 -m 64 -M 128 -p -s 1
GNU gdb (GDB) 7.3.50.20110806-cvs
...
Reading symbols from /path/to/alsa-lib/test/.libs/latency...done.
(gdb) r
...
...
Trying latency 72 frames, 1632.653us, 1.632653ms (612.5000Hz)
^C
Program received signal SIGINT, Interrupt.
0x0012e416 in __kernel_vsyscall ()
(gdb) bt
#0 0x0012e416 in __kernel_vsyscall ()
#1 0x002c97c9 in ioctl () from /lib/i386-linux-gnu/libc.so.6
#2 0x00182890 in ?? () from /usr/lib/libasound.so.2
#3 0x00171ac4 in snd_pcm_writei () from /usr/lib/libasound.so.2
#4 0x0804a23b in writebuf (handle=0x8056ed8, buf=0x804e0b8 "", len=8, frames=0xbffff1bc) at latency.c:383
#5 0x0804ab8d in main (argc=14, argv=0xbffff294) at latency.c:639
</pre></small>

... which confirms that the failing <code>ioctl</code> is due to a <code>snd_pcm_writei</code> call.

File:Minivosc-pavucontrol.png

2012-04-23T07:54:13Z

Sdaau: Minivosc with `pavucontrol` volume applet from `pulseaudio`; ( image processed with: pngquant 256 minivosc-pavucontrol_orig.png ; pngcrush -rem gAMA -rem cHRM -rem iCCP -force -bkgd 255 255 255 minivosc-pavucontrol_orig-fs8.png minivosc-pavucontrol.png )

Minivosc with `pavucontrol` volume applet from `pulseaudio`; ( image processed with: pngquant 256 minivosc-pavucontrol_orig.png ; pngcrush -rem gAMA -rem cHRM -rem iCCP -force -bkgd 255 255 255 minivosc-pavucontrol_orig-fs8.png minivosc-pavucontrol.png )

File:Minivosc-gnome-volume.png

2012-04-23T07:45:03Z

Sdaau: gnome-volume-control in Ubuntu 11.04 with minivosc - with and without pulseaudio

gnome-volume-control in Ubuntu 11.04 with minivosc - with and without pulseaudio

User:Sdaau/Monobook.js

2010-11-05T02:21:12Z

Sdaau: New page: // Install InstaView document.write('<script type="text/javascript" src="http://www.alsa-project.org/main/index.php/User:Sdaau/instaview.js&action=raw&ctype=text/javascript&dontcountme=s">...

// Install InstaView
document.write('<script type="text/javascript" src="http://www.alsa-project.org/main/index.php/User:Sdaau/instaview.js&action=raw&ctype=text/javascript&dontcountme=s"></script>');

InstaView.conf.user.name = 'Sdaau';

/* This is to keep track of who is using InstaView: [[User:Pilaf/instaview.js]] */

/************ OLD STUFF *************

// Live Preview customization,
// edit this to your own liking.

wpUserName = 'Pilaf'; // User name to display in signatures
wpShowImages = true; // Enable downloading and displaying of images

// Include Live Preview...
document.write('<script type="text/javascript" src="http://en.wikipedia.org/w/index.php?title=User:Pilaf/livepreview.js&action=raw&ctype=text/javascript&dontcountme=s"></script>');

// Now set everything up
window.onload = Main;

function Main()
{
LivePreviewInstall();
// You may include here other "extensions"
}

*/

User:Sdaau/monobook.js

2010-11-05T02:11:46Z

Sdaau:

User:Sdaau/monobook.css

2010-11-05T02:10:30Z

Sdaau: New page: #content { background: red !important; }

#content { background: red !important; }

User:Sdaau/instaview.js

2010-11-05T02:07:24Z

Sdaau: added instaview.js

// Last update: Cacycle 22:26, 22 November 2008 (UTC)
// <nowiki>

// Script to embed InstaView in MediaWiki's edit page
addOnloadHook(function(){
if (document.getElementById('editpage-copywarn')) {
var oldPreview = document.getElementById('wpPreview');
var newPreview = document.createElement('input');
newPreview.setAttribute('type', 'button');
newPreview.setAttribute('style', 'font-style: italic');
newPreview.setAttribute('value', 'InstaView');
newPreview.setAttribute('id', 'InstaView');
newPreview.setAttribute('name', 'InstaView');
newPreview.setAttribute('onclick', "InstaView.dump('wpTextbox1', 'InstaViewDump')");
oldPreview.parentNode.insertBefore(newPreview, oldPreview);
oldPreview.parentNode.innerHTML += '<div style="margin: 5px 0 5px 0; padding: 5px; border: 2px solid orange;" id="InstaViewDump"></div>';
oldPreview.value = 'Classic Preview';
}
});

/*
* InstaView - a Mediawiki to HTML converter in JavaScript
* Version 0.6.1
* Copyright (C) Pedro Fayolle 2005-2006
* http://en.wikipedia.org/wiki/User:Pilaf
* Distributed under the BSD license
*
* Changelog:
*
* 0.6.1
* - Fixed problem caused by \r characters
* - Improved inline formatting parser
*
* 0.6
* - Changed name to InstaView
* - Some major code reorganizations and factored out some common functions
* - Handled conversion of relative links (i.e. [[/foo]])
* - Fixed misrendering of adjacent definition list items
* - Fixed bug in table headings handling
* - Changed date format in signatures to reflect Mediawiki's
* - Fixed handling of [[:Image:...]]
* - Updated MD5 function (hopefully it will work with UTF-8)
* - Fixed bug in handling of links inside images
*
* To do:
* - Better support for <math>
* - Full support for <nowiki>
* - Parser-based (as opposed to RegExp-based) inline wikicode handling (make it one-pass and bullet-proof)
* - Support for templates (through AJAX)
* - Support for coloured links (AJAX)
*/

var InstaView = {}

// options
InstaView.conf =
{
user: {},

wiki: {
lang: 'en',
interwiki: 'ab|aa|af|ak|sq|als|am|ang|ar|an|arc|hy|roa-rup|as|ast|av|ay|az|bm|ba|eu|be|bn|bh|bi|bs|br|bg|my|ca|ch|ce|chr|chy|ny|zh|zh-tw|zh-cn|cho|cv|kw|co|cr|hr|cs|da|dv|nl|dz|en|eo|et|ee|fo|fj|fi|fr|fy|ff|gl|ka|de|got|el|kl|gn|gu|ht|ha|haw|he|hz|hi|ho|hu|is|io|ig|id|ia|ie|iu|ik|ga|it|ja|jv|kn|kr|csb|ks|kk|km|ki|rw|rn|tlh|kv|kg|ko|kj|ku|ky|lo|la|lv|li|ln|lt|jbo|nds|lg|lb|mk|mg|ms|ml|mt|gv|mi|minnan|mr|mh|zh-min-nan|mo|mn|mus|nah|na|nv|ne|se|no|nn|oc|or|om|pi|fa|pl|pt|pa|ps|qu|ro|rm|ru|sm|sg|sa|sc|gd|sr|sh|st|tn|sn|scn|simple|sd|si|sk|sl|so|st|es|su|sw|ss|sv|tl|ty|tg|ta|tt|te|th|bo|ti|tpi|to|tokipona|ts|tum|tr|tk|tw|uk|ur|ug|uz|ve|vi|vo|wa|cy|wo|xh|ii|yi|yo|za|zu',
default_thumb_width: 180
},

paths: {
articles: '/wiki/',
math: '/math/',
images: '',
images_fallback: 'http://upload.wikimedia.org/wikipedia/commons/',
magnify_icon: 'skins/common/images/magnify-clip.png'
},

locale: {
user: 'User',
image: 'Image',
category: 'Category',
months: ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec']
}
}

// options with default values or backreferences
with (InstaView.conf) {
user.name = user.name || 'Wikipedian'
user.signature = '[['+locale.user+':'+user.name+'|'+user.name+']]'
paths.images = 'http://upload.wikimedia.org/wikipedia/' + wiki.lang + '/'
}

// define constants
InstaView.BLOCK_IMAGE = new RegExp('^\\[\\['+InstaView.conf.locale.image+':.*?\\|.*?(?:frame|thumbnail|thumb|none|right|left|center)', 'i');

InstaView.dump = function(from, to)
{
if (typeof from == 'string') from = document.getElementById(from)
if (typeof to == 'string') to = document.getElementById(to)
to.innerHTML = this.convert(from.value)
}

InstaView.convert = function(wiki)
{
var ll = (typeof wiki == 'string')? wiki.replace(/\r/g,'').split(/\n/): wiki, // lines of wikicode
o='', // output
p=0, // para flag
$r // result of passing a regexp to $()

// some shorthands
function remain() { return ll.length }
function sh() { return ll.shift() } // shift
function ps(s) { o+=s } // push

function f() // similar to C's printf, uses ? as placeholders, ?? to escape question marks
{
var i=1,a=arguments,f=a[0],o='',c,p
for (;i<a.length; i++) if ((p=f.indexOf('?'))+1) {
// allow character escaping
i -= c=f.charAt(p+1)=='?'?1:0
o += f.substring(0,p)+(c?'?':a[i])
f=f.substr(p+1+c)
} else break;
return o+f
}

function html_entities(s) { return s.replace(/&/g,"&").replace(/</g,"<").replace(/>/g,">") }

function max(a,b) { return (a>b)?a:b }
function min(a,b) { return (a<b)?a:b }

// return the first non matching character position between two strings
function str_imatch(a, b)
{
for (var i=0, l=min(a.length, b.length); i<l; i++) if (a.charAt(i)!=b.charAt(i)) break
return i
}

// compare current line against a string or regexp
// if passed a string it will compare only the first string.length characters
// if passed a regexp the result is stored in $r
function $(c) { return (typeof c == 'string') ? (ll[0].substr(0,c.length)==c) : ($r = ll[0].match(c)) }

function $$(c) { return ll[0]==c } // compare current line against a string
function _(p) { return ll[0].charAt(p) } // return char at pos p

function endl(s) { ps(s); sh() }

function parse_list()
{
var prev='';

while (remain() && $(/^([*#:;]+)(.*)$/)) {

var l_match = $r

sh()

var ipos = str_imatch(prev, l_match[1])

// close uncontinued lists
for (var i=prev.length-1; i >= ipos; i--) {

var pi = prev.charAt(i)

if (pi=='*') ps('</ul>')
else if (pi=='#') ps('</ol>')
// close a dl only if the new item is not a dl item (:, ; or empty)
else switch (l_match[1].charAt(i)) { case'':case'*':case'#': ps('</dl>') }
}

// open new lists
for (var i=ipos; i<l_match[1].length; i++) {

var li = l_match[1].charAt(i)

if (li=='*') ps('<ul>')
else if (li=='#') ps('<ol>')
// open a new dl only if the prev item is not a dl item (:, ; or empty)
else switch(prev.charAt(i)) { case'':case'*':case'#': ps('<dl>') }
}

switch (l_match[1].charAt(l_match[1].length-1)) {

case '*': case '#':
ps('<li>' + parse_inline_nowiki(l_match[2])); break

case ';':
ps('<dt>')

var dt_match

// handle ;dt :dd format
if (dt_match = l_match[2].match(/(.*?) (:.*?)$/)) {

ps(parse_inline_nowiki(dt_match[1]))
ll.unshift(dt_match[2])

} else ps(parse_inline_nowiki(l_match[2]))

break

case ':':
ps('<dd>' + parse_inline_nowiki(l_match[2]))
}

prev=l_match[1]
}

// close remaining lists
for (var i=prev.length-1; i>=0; i--)
ps(f('</?>', (prev.charAt(i)=='*')? 'ul': ((prev.charAt(i)=='#')? 'ol': 'dl')))
}

function parse_table()
{
endl(f('<table?>', $(/^\{\|( .*)$/)? $r[1]: ''))

for (;remain();) if ($('|')) switch (_(1)) {
case '}': endl('</table>'); return
case '-': endl(f('<tr ?>', $(/\|-*(.*)/)[1])); break
default: parse_table_data()
}
else if ($('!')) parse_table_data()
else sh()
}

function parse_table_data()
{
var td_line, match_i

// 1: "|+", '|' or '+'
// 2: ??
// 3: attributes ??
// TODO: finish commenting this regexp
var td_match = sh().match(/^(\|\+|\||!)((?:([^[|]*?)\|(?!\|))?(.*))$/)

if (td_match[1] == '|+') ps('<caption');
else ps('<t' + ((td_match[1]=='|')?'d':'h'))

if (typeof td_match[3] != 'undefined') {

ps(' ' + td_match[3])
match_i = 4

} else match_i = 2

ps('>')

if (td_match[1] != '|+') {

// use || or !! as a cell separator depending on context
// NOTE: when split() is passed a regexp make sure to use non-capturing brackets
td_line = td_match[match_i].split((td_match[1] == '|')? '||': /(?:\|\||!!)/)

ps(parse_inline_nowiki(td_line.shift()))

while (td_line.length) ll.unshift(td_match[1] + td_line.pop())

} else ps(td_match[match_i])

var tc = 0, td = []

for (;remain(); td.push(sh()))
if ($('|')) {
if (!tc) break // we're at the outer-most level (no nested tables), skip to td parse
else if (_(1)=='}') tc--
}
else if (!tc && $('!')) break
else if ($('{|')) tc++

if (td.length) ps(InstaView.convert(td))
}

function parse_pre()
{
ps('<pre>')
do endl(parse_inline_nowiki(ll[0].substring(1)) + "\n"); while (remain() && $(' '))
ps('</pre>')
}

function parse_block_image()
{
ps(parse_image(sh()))
}

function parse_image(str)
{
// get what's in between "[[Image:" and "]]"
var tag = str.substring(InstaView.conf.locale.image.length + 3, str.length - 2);

var width;
var attr = [], filename, caption = '';
var thumb=0, frame=0, center=0;
var align='';

if (tag.match(/\|/)) {
// manage nested links
var nesting = 0;
var last_attr;
for (var i = tag.length-1; i > 0; i--) {
if (tag.charAt(i) == '|' && !nesting) {
last_attr = tag.substr(i+1);
tag = tag.substring(0, i);
break;
} else switch (tag.substr(i-1, 2)) {
case ']]':
nesting++;
i--;
break;
case '[[':
nesting--;
i--;
}
}

attr = tag.split(/\s*\|\s*/);
attr.push(last_attr);
filename = attr.shift();

var w_match;

for (;attr.length; attr.shift())
if (w_match = attr[0].match(/^(\d*)px$/)) width = w_match[1]
else switch(attr[0]) {
case 'thumb':
case 'thumbnail':
thumb=true;
case 'frame':
frame=true;
break;
case 'none':
case 'right':
case 'left':
center=false;
align=attr[0];
break;
case 'center':
center=true;
align='none';
break;
default:
if (attr.length == 1) caption = attr[0];
}

} else filename = tag;

var o='';

if (frame) {

if (align=='') align = 'right';

o += f("<div class='thumb t?'>", align);

if (thumb) {
if (!width) width = InstaView.conf.wiki.default_thumb_width;

o += f("<div style='width:?px;'>?", 2+width*1, make_image(filename, caption, width)) +
f("<div class='thumbcaption'><div class='magnify' style='float:right'><a href='?' class='internal' title='Enlarge'><img src='?'></a></div>?</div>",
InstaView.conf.paths.articles + InstaView.conf.locale.image + ':' + filename,
InstaView.conf.paths.magnify_icon,
parse_inline_nowiki(caption)
)
} else {
o += '<div>' + make_image(filename, caption) + f("<div class='thumbcaption'>?</div>", parse_inline_nowiki(caption))
}

o += '</div></div>';

} else if (align != '') {
o += f("<div class='float?'><span>?</span></div>", align, make_image(filename, caption, width));
} else {
return make_image(filename, caption, width);
}

return center? f("<div class='center'>?</div>", o): o;
}

function parse_inline_nowiki(str)
{
var start, lastend=0
var substart=0, nestlev=0, open, close, subloop;
var html='';

while (-1 != (start = str.indexOf('<nowiki>', substart))) {
html += parse_inline_wiki(str.substring(lastend, start));
start += 8;
substart = start;
subloop = true;
do {
open = str.indexOf('<nowiki>', substart);
close = str.indexOf('</nowiki>', substart);
if (close<=open || open==-1) {
if (close==-1) {
return html + html_entities(str.substr(start));
}
substart = close+9;
if (nestlev) {
nestlev--;
} else {
lastend = substart;
html += html_entities(str.substring(start, lastend-9));
subloop = false;
}
} else {
substart = open+8;
nestlev++;
}
} while (subloop)
}

return html + parse_inline_wiki(str.substr(lastend));
}

function make_image(filename, caption, width)
{
// uppercase first letter in file name
filename = filename.charAt(0).toUpperCase() + filename.substr(1);
// replace spaces with underscores
filename = filename.replace(/ /g, '_');

caption = strip_inline_wiki(caption);

var md5 = hex_md5(filename);

var source = md5.charAt(0) + '/' + md5.substr(0,2) + '/' + filename;

if (width) width = "width='" + width + "px'";

var img = f("<img onerror=\"this.onerror=null;this.src='?'\" src='?' ? ?>", InstaView.conf.paths.images_fallback + source, InstaView.conf.paths.images + source, (caption!='')? "alt='" + caption + "'" : '', width);

return f("<a class='image' ? href='?'>?</a>", (caption!='')? "title='" + caption + "'" : '', InstaView.conf.paths.articles + InstaView.conf.locale.image + ':' + filename, img);
}

function parse_inline_images(str)
{
var start, substart=0, nestlev=0;
var loop, close, open, wiki, html;

while (-1 != (start=str.indexOf('[[', substart))) {
if(str.substr(start+2).match(RegExp('^' + InstaView.conf.locale.image + ':','i'))) {
loop=true;
substart=start;
do {
substart+=2;
close=str.indexOf(']]',substart);
open=str.indexOf('[[',substart);
if (close<=open||open==-1) {
if (close==-1) return str;
substart=close;
if (nestlev) {
nestlev--;
} else {
wiki=str.substring(start,close+2);
html=parse_image(wiki);
str=str.replace(wiki,html);
substart=start+html.length;
loop=false;
}
} else {
substart=open;
nestlev++;
}
} while (loop)

} else break;
}

return str;
}

// the output of this function doesn't respect the FILO structure of HTML
// but since most browsers can handle it I'll save myself the hassle
function parse_inline_formatting(str)
{
var em,st,i,li,o='';
while ((i=str.indexOf("''",li))+1) {
o += str.substring(li,i);
li=i+2;
if (str.charAt(i+2)=="'") {
li++;
st=!st;
o+=st?'<strong>':'</strong>';
} else {
em=!em;
o+=em?'<em>':'</em>';
}
}
return o+str.substr(li);
}

function parse_inline_wiki(str)
{
var aux_match;

str = parse_inline_images(str);
str = parse_inline_formatting(str);

// math
while (aux_match = str.match(/<(?:)math>(.*?)<\/math>/i)) {
var math_md5 = hex_md5(aux_match[1]);
str = str.replace(aux_match[0], f("<img src='?.png'>", InstaView.conf.paths.math+math_md5));
}

// Build a Mediawiki-formatted date string
var date = new Date;
var minutes = date.getUTCMinutes();
if (minutes < 10) minutes = '0' + minutes;
var date = f("?:?, ? ? ? (UTC)", date.getUTCHours(), minutes, date.getUTCDate(), InstaView.conf.locale.months[date.getUTCMonth()], date.getUTCFullYear());

// text formatting
return str.
// signatures
replace(/~{5}(?!~)/g, date).
replace(/~{4}(?!~)/g, InstaView.conf.user.name+' '+date).
replace(/~{3}(?!~)/g, InstaView.conf.user.name).

// [[:Category:...]], [[:Image:...]], etc...
replace(RegExp('\\[\\[:((?:'+InstaView.conf.locale.category+'|'+InstaView.conf.locale.image+'|'+InstaView.conf.wiki.interwiki+'):.*?)\\]\\]','gi'), "<a href='"+InstaView.conf.paths.articles+"$1'>$1</a>").
replace(RegExp('\\[\\[(?:'+InstaView.conf.locale.category+'|'+InstaView.conf.wiki.interwiki+'):.*?\\]\\]','gi'),'').

// [[/Relative links]]
replace(/\[\[(\/[^|]*?)\]\]/g, f("<a href='?$1'>$1</a>", location)).

// [[/Replaced|Relative links]]
replace(/\[\[(\/.*?)\|(.+?)\]\]/g, f("<a href='?$1'>$2</a>", location)).

// [[Common links]]
replace(/\[\[([^|]*?)\]\](\w*)/g, f("<a href='?$1'>$1$2</a>", InstaView.conf.paths.articles)).

// [[Replaced|Links]]
replace(/\[\[(.*?)\|([^\]]+?)\]\](\w*)/g, f("<a href='?$1'>$2$3</a>", InstaView.conf.paths.articles)).

// [[Stripped:Namespace|Namespace]]
replace(/\[\[([^\]]*?:)?(.*?)( *$.*?$)?\|\]\]/g, f("<a href='?$1$2$3'>$2</a>", InstaView.conf.paths.articles)).

// External links
replace(/\[(https?|news|ftp|mailto|gopher|irc):(\/*)([^\]]*?) (.*?)\]/g, "<a href='$1:$2$3'>$4</a>").
replace(/\[http:\/\/(.*?)\]/g, "<a href='http://$1'>[#]</a>").
replace(/\[(news|ftp|mailto|gopher|irc):(\/*)(.*?)\]/g, "<a href='$1:$2$3'>$1:$2$3</a>").
replace(/(^| )(https?|news|ftp|mailto|gopher|irc):(\/*)([^ $]*)/g, "$1<a href='$2:$3$4'>$2:$3$4</a>").

replace('__NOTOC__','').
replace('__NOEDITSECTION__','');
}

function strip_inline_wiki(str)
{
return str
.replace(/\[\[[^\]]*\|(.*?)\]\]/g,'$1')
.replace(/\[\[(.*?)\]\]/g,'$1')
.replace(/''(.*?)''/g,'$1');
}

// begin parsing
for (;remain();) if ($(/^(={1,6})(.*)\1(.*)$/)) {
p=0
endl(f('<h?>?</h?>?', $r[1].length, parse_inline_nowiki($r[2]), $r[1].length, $r[3]))

} else if ($(/^[*#:;]/)) {
p=0
parse_list()

} else if ($(' ')) {
p=0
parse_pre()

} else if ($('{|')) {
p=0
parse_table()

} else if ($(/^----+$/)) {
p=0
endl('<hr>')

} else if ($(InstaView.BLOCK_IMAGE)) {
p=0
parse_block_image()

} else {

// handle paragraphs
if ($$('')) {
if (p = (remain()>1 && ll[1]==(''))) endl('<p><br>')
} else {
if(!p) {
ps('<p>')
p=1
}
ps(parse_inline_nowiki(ll[0]) + ' ')
}

sh();
}

return o
}

/*
* A JavaScript implementation of the RSA Data Security, Inc. MD5 Message
* Digest Algorithm, as defined in RFC 1321.
* Version 2.2-alpha Copyright (C) Paul Johnston 1999 - 2005
* Other contributors: Greg Holt, Andrew Kepert, Ydnar, Lostinet
* Distributed under the BSD License
* See http://pajhome.org.uk/crypt/md5 for more info.
*/

/*
* Configurable variables. You may need to tweak these to be compatible with
* the server-side, but the defaults work in most cases.
*/
var hexcase = 0; /* hex output format. 0 - lowercase; 1 - uppercase */
var b64pad = ""; /* base-64 pad character. "=" for strict RFC compliance */

/*
* These are the functions you'll usually want to call
* They take string arguments and return either hex or base-64 encoded strings
*/
function hex_md5(s) { return rstr2hex(rstr_md5(str2rstr_utf8(s))); }
function b64_md5(s) { return rstr2b64(rstr_md5(str2rstr_utf8(s))); }
function any_md5(s, e) { return rstr2any(rstr_md5(str2rstr_utf8(s)), e); }
function hex_hmac_md5(k, d)
{ return rstr2hex(rstr_hmac_md5(str2rstr_utf8(k), str2rstr_utf8(d))); }
function b64_hmac_md5(k, d)
{ return rstr2b64(rstr_hmac_md5(str2rstr_utf8(k), str2rstr_utf8(d))); }
function any_hmac_md5(k, d, e)
{ return rstr2any(rstr_hmac_md5(str2rstr_utf8(k), str2rstr_utf8(d)), e); }

/*
* Calculate the MD5 of a raw string
*/
function rstr_md5(s)
{
return binl2rstr(binl_md5(rstr2binl(s), s.length * 8));
}

/*
* Calculate the HMAC-MD5, of a key and some data (raw strings)
*/
function rstr_hmac_md5(key, data)
{
var bkey = rstr2binl(key);
if(bkey.length > 16) bkey = binl_md5(bkey, key.length * 8);

var ipad = Array(16), opad = Array(16);
for(var i = 0; i < 16; i++)
{
ipad[i] = bkey[i] ^ 0x36363636;
opad[i] = bkey[i] ^ 0x5C5C5C5C;
}

var hash = binl_md5(ipad.concat(rstr2binl(data)), 512 + data.length * 8);
return binl2rstr(binl_md5(opad.concat(hash), 512 + 128));
}

/*
* Convert a raw string to a hex string
*/
function rstr2hex(input)
{
var hex_tab = hexcase ? "0123456789ABCDEF" : "0123456789abcdef";
var output = "";
var x;
for(var i = 0; i < input.length; i++)
{
x = input.charCodeAt(i);
output += hex_tab.charAt((x >>> 4) & 0x0F)
+ hex_tab.charAt( x & 0x0F);
}
return output;
}

/*
* Convert a raw string to a base-64 string
*/
function rstr2b64(input)
{
var tab = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
var output = "";
var len = input.length;
for(var i = 0; i < len; i += 3)
{
var triplet = (input.charCodeAt(i) << 16)
| (i + 1 < len ? input.charCodeAt(i+1) << 8 : 0)
| (i + 2 < len ? input.charCodeAt(i+2) : 0);
for(var j = 0; j < 4; j++)
{
if(i * 8 + j * 6 > input.length * 8) output += b64pad;
else output += tab.charAt((triplet >>> 6*(3-j)) & 0x3F);
}
}
return output;
}

/*
* Convert a raw string to an arbitrary string encoding
*/
function rstr2any(input, encoding)
{
var divisor = encoding.length;
var remainders = Array();
var i, q, x, quotient;

/* Convert to an array of 16-bit big-endian values, forming the dividend */
var dividend = Array(input.length / 2);
for(i = 0; i < dividend.length; i++)
{
dividend[i] = (input.charCodeAt(i * 2) << 8) | input.charCodeAt(i * 2 + 1);
}

/*
* Repeatedly perform a long division. The binary array forms the dividend,
* the length of the encoding is the divisor. Once computed, the quotient
* forms the dividend for the next step. We stop when the dividend is zero.
* All remainders are stored for later use.
*/
while(dividend.length > 0)
{
quotient = Array();
x = 0;
for(i = 0; i < dividend.length; i++)
{
x = (x << 16) + dividend[i];
q = Math.floor(x / divisor);
x -= q * divisor;
if(quotient.length > 0 || q > 0)
quotient[quotient.length] = q;
}
remainders[remainders.length] = x;
dividend = quotient;
}

/* Convert the remainders to the output string */
var output = "";
for(i = remainders.length - 1; i >= 0; i--)
output += encoding.charAt(remainders[i]);

return output;
}

/*
* Encode a string as utf-8.
* For efficiency, this assumes the input is valid utf-16.
*/
function str2rstr_utf8(input)
{
var output = "";
var i = -1;
var x, y;

while(++i < input.length)
{
/* Decode utf-16 surrogate pairs */
x = input.charCodeAt(i);
y = i + 1 < input.length ? input.charCodeAt(i + 1) : 0;
if(0xD800 <= x && x <= 0xDBFF && 0xDC00 <= y && y <= 0xDFFF)
{
x = 0x10000 + ((x & 0x03FF) << 10) + (y & 0x03FF);
i++;
}

/* Encode output as utf-8 */
if(x <= 0x7F)
output += String.fromCharCode(x);
else if(x <= 0x7FF)
output += String.fromCharCode(0xC0 | ((x >>> 6 ) & 0x1F),
0x80 | ( x & 0x3F));
else if(x <= 0xFFFF)
output += String.fromCharCode(0xE0 | ((x >>> 12) & 0x0F),
0x80 | ((x >>> 6 ) & 0x3F),
0x80 | ( x & 0x3F));
else if(x <= 0x1FFFFF)
output += String.fromCharCode(0xF0 | ((x >>> 18) & 0x07),
0x80 | ((x >>> 12) & 0x3F),
0x80 | ((x >>> 6 ) & 0x3F),
0x80 | ( x & 0x3F));
}
return output;
}

/*
* Encode a string as utf-16
*/
function str2rstr_utf16le(input)
{
var output = "";
for(var i = 0; i < input.length; i++)
output += String.fromCharCode( input.charCodeAt(i) & 0xFF,
(input.charCodeAt(i) >>> 8) & 0xFF);
return output;
}

function str2rstr_utf16be(input)
{
var output = "";
for(var i = 0; i < input.length; i++)
output += String.fromCharCode((input.charCodeAt(i) >>> 8) & 0xFF,
input.charCodeAt(i) & 0xFF);
return output;
}

/*
* Convert a raw string to an array of little-endian words
* Characters >255 have their high-byte silently ignored.
*/
function rstr2binl(input)
{
var output = Array(input.length >> 2);
for(var i = 0; i < output.length; i++)
output[i] = 0;
for(var i = 0; i < input.length * 8; i += 8)
output[i>>5] |= (input.charCodeAt(i / 8) & 0xFF) << (i%32);
return output;
}

/*
* Convert an array of little-endian words to a string
*/
function binl2rstr(input)
{
var output = "";
for(var i = 0; i < input.length * 32; i += 8)
output += String.fromCharCode((input[i>>5] >>> (i % 32)) & 0xFF);
return output;
}

/*
* Calculate the MD5 of an array of little-endian words, and a bit length.
*/
function binl_md5(x, len)
{
/* append padding */
x[len >> 5] |= 0x80 << ((len) % 32);
x[(((len + 64) >>> 9) << 4) + 14] = len;

var a = 1732584193;
var b = -271733879;
var c = -1732584194;
var d = 271733878;

for(var i = 0; i < x.length; i += 16)
{
var olda = a;
var oldb = b;
var oldc = c;
var oldd = d;

a = md5_ff(a, b, c, d, x[i+ 0], 7 , -680876936);
d = md5_ff(d, a, b, c, x[i+ 1], 12, -389564586);
c = md5_ff(c, d, a, b, x[i+ 2], 17, 606105819);
b = md5_ff(b, c, d, a, x[i+ 3], 22, -1044525330);
a = md5_ff(a, b, c, d, x[i+ 4], 7 , -176418897);
d = md5_ff(d, a, b, c, x[i+ 5], 12, 1200080426);
c = md5_ff(c, d, a, b, x[i+ 6], 17, -1473231341);
b = md5_ff(b, c, d, a, x[i+ 7], 22, -45705983);
a = md5_ff(a, b, c, d, x[i+ 8], 7 , 1770035416);
d = md5_ff(d, a, b, c, x[i+ 9], 12, -1958414417);
c = md5_ff(c, d, a, b, x[i+10], 17, -42063);
b = md5_ff(b, c, d, a, x[i+11], 22, -1990404162);
a = md5_ff(a, b, c, d, x[i+12], 7 , 1804603682);
d = md5_ff(d, a, b, c, x[i+13], 12, -40341101);
c = md5_ff(c, d, a, b, x[i+14], 17, -1502002290);
b = md5_ff(b, c, d, a, x[i+15], 22, 1236535329);

a = md5_gg(a, b, c, d, x[i+ 1], 5 , -165796510);
d = md5_gg(d, a, b, c, x[i+ 6], 9 , -1069501632);
c = md5_gg(c, d, a, b, x[i+11], 14, 643717713);
b = md5_gg(b, c, d, a, x[i+ 0], 20, -373897302);
a = md5_gg(a, b, c, d, x[i+ 5], 5 , -701558691);
d = md5_gg(d, a, b, c, x[i+10], 9 , 38016083);
c = md5_gg(c, d, a, b, x[i+15], 14, -660478335);
b = md5_gg(b, c, d, a, x[i+ 4], 20, -405537848);
a = md5_gg(a, b, c, d, x[i+ 9], 5 , 568446438);
d = md5_gg(d, a, b, c, x[i+14], 9 , -1019803690);
c = md5_gg(c, d, a, b, x[i+ 3], 14, -187363961);
b = md5_gg(b, c, d, a, x[i+ 8], 20, 1163531501);
a = md5_gg(a, b, c, d, x[i+13], 5 , -1444681467);
d = md5_gg(d, a, b, c, x[i+ 2], 9 , -51403784);
c = md5_gg(c, d, a, b, x[i+ 7], 14, 1735328473);
b = md5_gg(b, c, d, a, x[i+12], 20, -1926607734);

a = md5_hh(a, b, c, d, x[i+ 5], 4 , -378558);
d = md5_hh(d, a, b, c, x[i+ 8], 11, -2022574463);
c = md5_hh(c, d, a, b, x[i+11], 16, 1839030562);
b = md5_hh(b, c, d, a, x[i+14], 23, -35309556);
a = md5_hh(a, b, c, d, x[i+ 1], 4 , -1530992060);
d = md5_hh(d, a, b, c, x[i+ 4], 11, 1272893353);
c = md5_hh(c, d, a, b, x[i+ 7], 16, -155497632);
b = md5_hh(b, c, d, a, x[i+10], 23, -1094730640);
a = md5_hh(a, b, c, d, x[i+13], 4 , 681279174);
d = md5_hh(d, a, b, c, x[i+ 0], 11, -358537222);
c = md5_hh(c, d, a, b, x[i+ 3], 16, -722521979);
b = md5_hh(b, c, d, a, x[i+ 6], 23, 76029189);
a = md5_hh(a, b, c, d, x[i+ 9], 4 , -640364487);
d = md5_hh(d, a, b, c, x[i+12], 11, -421815835);
c = md5_hh(c, d, a, b, x[i+15], 16, 530742520);
b = md5_hh(b, c, d, a, x[i+ 2], 23, -995338651);

a = md5_ii(a, b, c, d, x[i+ 0], 6 , -198630844);
d = md5_ii(d, a, b, c, x[i+ 7], 10, 1126891415);
c = md5_ii(c, d, a, b, x[i+14], 15, -1416354905);
b = md5_ii(b, c, d, a, x[i+ 5], 21, -57434055);
a = md5_ii(a, b, c, d, x[i+12], 6 , 1700485571);
d = md5_ii(d, a, b, c, x[i+ 3], 10, -1894986606);
c = md5_ii(c, d, a, b, x[i+10], 15, -1051523);
b = md5_ii(b, c, d, a, x[i+ 1], 21, -2054922799);
a = md5_ii(a, b, c, d, x[i+ 8], 6 , 1873313359);
d = md5_ii(d, a, b, c, x[i+15], 10, -30611744);
c = md5_ii(c, d, a, b, x[i+ 6], 15, -1560198380);
b = md5_ii(b, c, d, a, x[i+13], 21, 1309151649);
a = md5_ii(a, b, c, d, x[i+ 4], 6 , -145523070);
d = md5_ii(d, a, b, c, x[i+11], 10, -1120210379);
c = md5_ii(c, d, a, b, x[i+ 2], 15, 718787259);
b = md5_ii(b, c, d, a, x[i+ 9], 21, -343485551);

a = safe_add(a, olda);
b = safe_add(b, oldb);
c = safe_add(c, oldc);
d = safe_add(d, oldd);
}
return Array(a, b, c, d);
}

/*
* These functions implement the four basic operations the algorithm uses.
*/
function md5_cmn(q, a, b, x, s, t)
{
return safe_add(bit_rol(safe_add(safe_add(a, q), safe_add(x, t)), s),b);
}
function md5_ff(a, b, c, d, x, s, t)
{
return md5_cmn((b & c) | ((~b) & d), a, b, x, s, t);
}
function md5_gg(a, b, c, d, x, s, t)
{
return md5_cmn((b & d) | (c & (~d)), a, b, x, s, t);
}
function md5_hh(a, b, c, d, x, s, t)
{
return md5_cmn(b ^ c ^ d, a, b, x, s, t);
}
function md5_ii(a, b, c, d, x, s, t)
{
return md5_cmn(c ^ (b | (~d)), a, b, x, s, t);
}

/*
* Add integers, wrapping at 2^32. This uses 16-bit operations internally
* to work around bugs in some JS interpreters.
*/
function safe_add(x, y)
{
var lsw = (x & 0xFFFF) + (y & 0xFFFF);
var msw = (x >> 16) + (y >> 16) + (lsw >> 16);
return (msw << 16) | (lsw & 0xFFFF);
}

/*
* Bitwise rotate a 32-bit number to the left.
*/
function bit_rol(num, cnt)
{
return (num << cnt) | (num >>> (32 - cnt));
}

// </nowiki>

User:Sdaau/monobook.js

2010-11-05T01:57:40Z

Sdaau: tried adding LivePreview - instaview

// Install InstaView
document.write('<script type="text/javascript" src="http://en.wikipedia.org/w/index.php?title=User:Pilaf/instaview.js&action=raw&ctype=text/javascript&dontcountme=s"></script>');

InstaView.conf.user.name = 'Sdaau';

/* This is to keep track of who is using InstaView: [[User:Pilaf/instaview.js]] */

/************ OLD STUFF *************

// Live Preview customization,
// edit this to your own liking.

wpUserName = 'Pilaf'; // User name to display in signatures
wpShowImages = true; // Enable downloading and displaying of images

// Include Live Preview...
document.write('<script type="text/javascript" src="http://en.wikipedia.org/w/index.php?title=User:Pilaf/livepreview.js&action=raw&ctype=text/javascript&dontcountme=s"></script>');

// Now set everything up
window.onload = Main;

function Main()
{
LivePreviewInstall();
// You may include here other "extensions"
}

*/

FramesPeriods

2010-11-04T23:27:20Z

Sdaau: /* Additional example */ - added mailing list quote

A frame is equivalent of one sample being played, irrespective of the number of channels or the number of bits. e.g.
* 1 frame of a Stereo 48khz 16bit PCM stream is 4 bytes.
* 1 frame of a 5.1 48khz 16bit PCM stream is 12 bytes.

A period is the number of frames in between each hardware interrupt. The poll() will return once a period.

The buffer is a ring buffer. The buffer size always has to be greater than one period size. Commonly this is 2*period size, but some hardware can do 8 periods per buffer. It is also possible for the buffer size to not be an integer multiple of the period size.

Now, if the hardware has been set to 48000Hz , 2 periods, of 1024 frames each, making a buffer size of 2048 frames. The hardware will interrupt 2 times per buffer. ALSA will endeavor to keep the buffer as full as possible. Once the first period of samples has been played, the third period of samples is transfered into the space the first one occupied while the second period of samples is being played. (normal ring buffer behaviour).

 

== Additional example ==

Here is an alternative example for the above discussion.

Say we want to work with a stereo, 16-bit, 44.1 KHz stream, ''one-way'' (meaning, ''either'' in playback ''or'' in capture direction). Then we have:
* 'stereo' = '''number of channels''': 2
* 1 '''analog sample''' is represented with 16 bits = 2 bytes
* 1 '''frame''' represents 1 analog sample from all channels; here we have 2 channels, and so:
** 1 frame = (num_channels) * (1 sample in bytes) = (2 channels) * (2 bytes (16 bits) per sample) = 4 bytes (32 bits)
* To sustain 2x 44.1 KHz '''analog rate''' - the system must be capable of '''data transfer rate''', in Bytes/sec:
** Bps_rate = (num_channels) * (1 sample in bytes) * (analog_rate) = (1 frame) * (analog_rate) = ( 2 channels ) * (2 bytes/sample) * (44100 samples/sec) = 2*2*44100 = 176400 Bytes/sec ([http://latex.codecogs.com/png.latex?\begin{array}{ccc}&space;Bps\_rate&space;&=&space;(analog\_rate)&space;&\cdot&space;(num\_channels)&space;\cdot&space;(1\&space;\text{sample&space;(as&space;bytes)})&space;\\&space;&=&space;(analog\_rate)&space;&\cdot&space;(1\&space;\text{frame})&space;\\&space;&=&space;(44100\&space;\frac{\text{samples}}{\text{sec}})&space;&\cdot&space;(&space;2\&space;\text{channels}&space;)&space;\cdot&space;(2\&space;\frac{\text{bytes}}{\text{sample}})&space;\\&space;&=&space;(44100\&space;\frac{\text{frames}}{\text{sec}})&space;&\cdot&space;(4\&space;\frac{\text{bytes}}{\text{frame}})&space;\\&space;&=&space;176400\&space;\frac{\text{bytes}}{\text{sec}}&space;\end{array} link to formula img])

[[Image:alsa_bps_formula.png|frame|center|Alsa Bps formula]]

Now, if ALSA would interrupt each second, asking for bytes - we'd need to have 176400 bytes ready for it (at end of each second), in order to sustain analog 16-bit stereo @ 44.1Khz.
* If it would interrupt each half a second, correspondingly for the same stream we'd need 176400/2 = 88200 bytes ready, at each interrupt;
* if the interrupt hits each 100 ms, we'd need to have 176400*(0.1/1) = 17640 bytes ready, at each interrupt.

We can control when this PCM interrupt is generated, by setting a ''period size'', which is set in ''frames''.
* Thus, if we set 16-bit stereo @ 44.1Khz, and the period_size to 4410 frames => (<small>for 16-bit stereo @ 44.1Khz, 1 frame equals 4 bytes - so 4410 frames equal 4410*4 = 17640 bytes</small>) => an interrupt will be generated each 17640 bytes - that is, each 100 ms.
* Correspondingly, buffer_size should be at least 2*period_size = 2*4410 = 8820 frames (or 8820*4 = 35280 bytes).

It seems ([http://mirror.leaseweb.com/kernel/people/tiwai/docs/writing-an-alsa-driver.pdf writing-an-alsa-driver.pdf]), however, that it is the ALSA runtime that decides on the actual ''buffer_size'' and ''period_size'', depending on: the requested number of channels, and their respective properties (rate and sampling resolution) - as well as the parameters set in the ''snd_pcm_hardware'' structure (in the driver).

Also, the following quote may be relevant, from "[http://mailman.alsa-project.org/pipermail/alsa-devel/2007-April/000474.html (alsa-devel) Questions about writing a new ALSA driver for a very limitted device]":
<pre>
> > The "frame" represents the unit, 1 frame = # channels x sample_bytes.
> > In your case, 1 frame corresponds to 2 channels x 16 bits = 4 bytes.
> >
> > The periods is the number of periods in a ring-buffer. In OSS, called
> > as "fragments".
> >
> > So,
> > - buffer_size = period_size * periods
> > - period_bytes = period_size * bytes_per_frame
> > - bytes_per_frame = channels * bytes_per_sample
> >
>
> I still don't understand what 'period_size' and a 'period' is?

The "period" defines the frequency to update the status, usually via
the invokation of interrupts. The "period_size" defines the frame
sizes corresponding to the "period time". This term corresponds to
the "fragment size" on OSS. On major sound hardwares, a ring-buffer
is divided to several parts and an irq is issued on each boundary.
The period_size defines the size of this chunk.

On some hardwares, the irq is controlled on the basis of a timer. In
this case, the period is defined as the timer frequency to invoke an
irq.
</pre>

----
[https://bugtrack.alsa-project.org/wiki/wikka.php?wakka=FramesPeriods original] created 2006-09-24 by [[User:JamesCourtierDutton]]

[[Category:Development]] [[Category:MigratedFromDev]]

FramesPeriods

2010-11-04T22:29:48Z

Sdaau: added additional example section

A frame is equivalent of one sample being played, irrespective of the number of channels or the number of bits. e.g.
* 1 frame of a Stereo 48khz 16bit PCM stream is 4 bytes.
* 1 frame of a 5.1 48khz 16bit PCM stream is 12 bytes.

A period is the number of frames in between each hardware interrupt. The poll() will return once a period.

The buffer is a ring buffer. The buffer size always has to be greater than one period size. Commonly this is 2*period size, but some hardware can do 8 periods per buffer. It is also possible for the buffer size to not be an integer multiple of the period size.

Now, if the hardware has been set to 48000Hz , 2 periods, of 1024 frames each, making a buffer size of 2048 frames. The hardware will interrupt 2 times per buffer. ALSA will endeavor to keep the buffer as full as possible. Once the first period of samples has been played, the third period of samples is transfered into the space the first one occupied while the second period of samples is being played. (normal ring buffer behaviour).

 

== Additional example ==

Here is an alternative example for the above discussion.

Say we want to work with a stereo, 16-bit, 44.1 KHz stream, ''one-way'' (meaning, ''either'' in playback ''or'' in capture direction). Then we have:
* 'stereo' = '''number of channels''': 2
* 1 '''analog sample''' is represented with 16 bits = 2 bytes
* 1 '''frame''' represents 1 analog sample from all channels; here we have 2 channels, and so:
** 1 frame = (num_channels) * (1 sample in bytes) = (2 channels) * (2 bytes (16 bits) per sample) = 4 bytes (32 bits)
* To sustain 2x 44.1 KHz '''analog rate''' - the system must be capable of '''data transfer rate''', in Bytes/sec:
** Bps_rate = (num_channels) * (1 sample in bytes) * (analog_rate) = (1 frame) * (analog_rate) = ( 2 channels ) * (2 bytes/sample) * (44100 samples/sec) = 2*2*44100 = 176400 Bytes/sec ([http://latex.codecogs.com/png.latex?\begin{array}{ccc}&space;Bps\_rate&space;&=&space;(analog\_rate)&space;&\cdot&space;(num\_channels)&space;\cdot&space;(1\&space;\text{sample&space;(as&space;bytes)})&space;\\&space;&=&space;(analog\_rate)&space;&\cdot&space;(1\&space;\text{frame})&space;\\&space;&=&space;(44100\&space;\frac{\text{samples}}{\text{sec}})&space;&\cdot&space;(&space;2\&space;\text{channels}&space;)&space;\cdot&space;(2\&space;\frac{\text{bytes}}{\text{sample}})&space;\\&space;&=&space;(44100\&space;\frac{\text{frames}}{\text{sec}})&space;&\cdot&space;(4\&space;\frac{\text{bytes}}{\text{frame}})&space;\\&space;&=&space;176400\&space;\frac{\text{bytes}}{\text{sec}}&space;\end{array} link to formula img])

[[Image:alsa_bps_formula.png|frame|center|Alsa Bps formula]]

Now, if ALSA would interrupt each second, asking for bytes - we'd need to have 176400 bytes ready for it (at end of each second), in order to sustain analog 16-bit stereo @ 44.1Khz.
* If it would interrupt each half a second, correspondingly for the same stream we'd need 176400/2 = 88200 bytes ready, at each interrupt;
* if the interrupt hits each 100 ms, we'd need to have 176400*(0.1/1) = 17640 bytes ready, at each interrupt.

We can control when this PCM interrupt is generated, by setting a ''period size'', which is set in ''frames''.
* Thus, if we set 16-bit stereo @ 44.1Khz, and the period_size to 4410 frames => (<small>for 16-bit stereo @ 44.1Khz, 1 frame equals 4 bytes - so 4410 frames equal 4410*4 = 17640 bytes</small>) => an interrupt will be generated each 17640 bytes - that is, each 100 ms.
* Correspondingly, buffer_size should be at least 2*period_size = 2*4410 = 8820 frames (or 8820*4 = 35280 bytes).

It seems ([http://mirror.leaseweb.com/kernel/people/tiwai/docs/writing-an-alsa-driver.pdf writing-an-alsa-driver.pdf]), however, that it is the ALSA runtime that decides on the actual ''buffer_size'' and ''period_size'', depending on: the requested number of channels, and their respective properties (rate and sampling resolution) - as well as the parameters set in the ''snd_pcm_hardware'' structure (in the driver).

----
[https://bugtrack.alsa-project.org/wiki/wikka.php?wakka=FramesPeriods original] created 2006-09-24 by [[User:JamesCourtierDutton]]

[[Category:Development]] [[Category:MigratedFromDev]]

File:Alsa bps formula.png

2010-11-04T22:16:19Z

Sdaau: Alsa bps formula

Alsa bps formula

Tutorials and Presentations

2010-09-10T07:10:55Z

Sdaau: /* Developer tutorials */ - added a link to MInivosc page

== Developer tutorials ==

*[http://www.suse.de/~mana/alsa090_howto.html ALSA 0.9.0 HOWTO] - Dr Matthias Nagorni has writen a comprehensive tutorial for audio application developers.
*[http://equalarea.com/paul/alsa-audio.html Howto use the ALSA API] - Paul Davis has also written a brief explanation.
*[http://www.alsa-project.org/~frank/alsa-sequencer/ ALSA Sequencer (draft)] - Frank van de Pol's draft on programming the alsa sequencer.
*[http://www.alsa-project.org/~iwai/OSS-Emulation.html Kernel OSS-Emulation] - Takashi Iwai has written some notes on how ALSA handles OSS applications.
*[http://www.salleurl.edu/~is04069/Modders/Docs/alsadoc.html Programming ALSA (Espanol)] - David Garcia Garzon has written Spanish docs and tutorials
*[http://ben-collins.blogspot.com/2010/04/writing-alsa-driver.html Basic Alsa Driver Tutorial] - Ben Collins has written a very basic tutorial on the minimum alsa kernel driver
*[[Minivosc]] - Smilen Dimitrov has written a driver tutorial for a '''mini'''mal '''v'''irtual '''osc'''illator driver (based on some of the resources above)

=== Presentations: ===

*The [http://lad.linuxaudio.org/events/2003_zkm/index.html LAD Meeting @ZKM 2003] in Karlsruhe, April 2003 provided two presentations (among many) from the core ALSA developers Jaroslav and Takashi. You can view slides and listen to .ogg recordings of the presentations.

File:Minivosc-comp07-ant.png

2010-08-10T09:58:14Z

Sdaau:

File:Minivosc-comp03-ant.png

2010-08-10T09:57:06Z

Sdaau:

File:Minivosc-comp03.png

2010-08-10T09:55:37Z

Sdaau:

File:Minivosc-comp02.png

2010-08-10T09:54:58Z

Sdaau:

File:Minivosc-comp01.png

2010-08-10T09:54:16Z

Sdaau:

File:Minivosc buffer viz.png

2010-08-10T09:52:59Z

Sdaau:

File:Snd-driver-context.png

2010-08-10T09:52:08Z

Sdaau: