From 7edc7e4274f627ad91f0b6630ebd42e4633e2040 Mon Sep 17 00:00:00 2001 Message-Id: <7edc7e4274f627ad91f0b6630ebd42e4633e2040.1715609441.git.mdw@distorted.org.uk> From: Mark Wooding Date: Sat, 18 Apr 2009 14:26:04 +0100 Subject: [PATCH] Documentation + comments re recent disorder-playrtp changes. Organization: Straylight/Edgeware From: Richard Kettlewell --- clients/playrtp.c | 35 ++++++++++++++++++++++++++++++++++- doc/disorder-playrtp.1.in | 8 ++++++++ 2 files changed, 42 insertions(+), 1 deletion(-) diff --git a/clients/playrtp.c b/clients/playrtp.c index 90199c4..4e27ebf 100644 --- a/clients/playrtp.c +++ b/clients/playrtp.c @@ -566,7 +566,40 @@ static size_t playrtp_callback(void *buffer, } /* Advance timestamp */ next_timestamp += samples; - /* If we're getting behind then try to drop just silent packets */ + /* If we're getting behind then try to drop just silent packets + * + * In theory this shouldn't be necessary. The server is supposed to send + * packets at the right rate and compares the number of samples sent with the + * time in order to ensure this. + * + * However, various things could throw this off: + * + * - the server's clock could advance at the wrong rate. This would cause it + * to mis-estimate the right number of samples to have sent and + * inappropriately throttle or speed up. + * + * - playback could happen at the wrong rate. If the playback host's sound + * card has a slightly incorrect clock then eventually it will get out + * of step. + * + * So if we play back slightly slower than the server sends for either of + * these reasons then eventually our buffer, and the socket's buffer, will + * fill, and the kernel will start dropping packets. The result is audible + * and not very nice. + * + * Therefore if we're getting behind, we pre-emptively drop silent packets, + * since a change in the duration of a silence is less noticeable than a + * dropped packet from the middle of continuous music. + * + * (If things go wrong the other way then eventually we run out of packets to + * play and are forced to play silence. This doesn't seem to happen in + * practice but if it does then in the same way we can artificially extend + * silent packets to compensate.) + * + * Dropped packets are always logged; use 'disorder-playrtp --monitor' to + * track how close to target buffer occupancy we are on a once-a-minute + * basis. + */ if(nsamples > minbuffer && silent) { info("dropping %zu samples (%"PRIu32" > %"PRIu32")", samples, nsamples, minbuffer); diff --git a/doc/disorder-playrtp.1.in b/doc/disorder-playrtp.1.in index 480a935..c92c55a 100644 --- a/doc/disorder-playrtp.1.in +++ b/doc/disorder-playrtp.1.in @@ -98,10 +98,12 @@ Display a usage message. Display version number. .SS "Buffer Control Options" You shouldn't need to use these options. +Their effects are subject to change between version without warning. You should consult the source code for details of their effects. .TP .B \-\-min \fIFRAMES\fR, \fB\-m \fIFRAMES\fR Specifies the buffer low watermark in frames. +This also acts as the target buffer occupancy. .TP .B \-\-max \fIFRAMES\fR, \fB\-x \fIFRAMES\fR Specifies the maximum buffer size in frames. @@ -114,6 +116,12 @@ Specifies socket receive buffer size. The default is not to change the buffer size, i.e. you get whatever the local operating system chooses. The buffer size will not be reduced below the operating system's default. +.TP +.B \-\-monitor\fR, \fB\-M +Periodically report how close to the buffer low watermark the buffer is. +If you have trouble with poor playback quality, enable this option to see if +the buffer is emptying out (or overfilling, though there are measures to +prevent that from happening). .SH "REMOTE CONTROL" The .B \-\-socket -- [mdw]