chiark / gitweb /
Add documentation and administrivia about `disorder-gstdecode'.
authorMark Wooding <mdw@distorted.org.uk>
Tue, 15 Dec 2015 19:15:23 +0000 (19:15 +0000)
committerMark Wooding <mdw@distorted.org.uk>
Sat, 16 Jan 2016 01:15:28 +0000 (01:15 +0000)
CHANGES.html
README
debian/rules
doc/Makefile.am
doc/disorder-gstdecode.8.in [new file with mode: 0644]

index 4fbc197..e8532f4 100644 (file)
@@ -67,6 +67,42 @@ href="README.upgrades.html">README.upgrades</a> before upgrading.</p>
 
   </div>
 
+  <h3>GStreamer support</h3>
+
+  <div class=section>
+
+    <p>If it's detected at <tt>configure</tt> time, a new decoder
+    program <tt>disorder-gstdecode</tt> is built.  It uses the GStreamer
+    library for audio decoding and sample-rate conversion, among other
+    features.
+
+    <p>The decoder has a number of options for controlling the sample-rate and
+    audio format conversion, allowing various tradeoffs between quality and
+    processor time.  (High-quality conversion can consume more processor time
+    than decoding, so this is potentially useful on very a small device such as
+    a Raspberry Pi.</p>
+
+    <p>The GStreamer decoder can also use ReplayGain information stored in
+    audio files' metadata to adjust playback volume, so that tracks with very
+    wide dynamic range don't sound really quiet in comparison.  This
+    information can be added using tools such as <tt>mp3gain</tt>,
+    <tt>vorbisgain</tt>, or <tt>metaflac</tt>.  This is turned on by default if
+    you use the decoder; you can choose between per-album or per-track
+    settings, or turn it off entirely, using command-line options.</p> 
+
+    <p>The GStreamer decoder is not used by default, but it can be enabled
+    easily enough by dropping something like the following into the server
+    configuration file:
+      <pre>
+        player
+        player *.flac execraw /usr/sbin/disorder-gstdecode -ralbum -f-8.0
+        player *.mp2 execraw /usr/sbin/disorder-gstdecode -ralbum -f-8.0
+        player *.mp3 execraw /usr/sbin/disorder-gstdecode -ralbum -f-8.0
+        player *.ogg execraw /usr/sbin/disorder-gstdecode -ralbum -f-8.0
+        player *.wav execraw /usr/sbin/disorder-gstdecode -ralbum -f-8.0
+      </pre>
+    </p>
+
   <h3>General</h3>
 
   <div class=section>
diff --git a/README b/README
index 71176aa..af88631 100644 (file)
--- a/README
+++ b/README
@@ -267,7 +267,7 @@ Copyright
 DisOrder - select and play digital audio files
 Copyright (C) 2003-2013 Richard Kettlewell
 Portions copyright (C) 2007 Ross Younger
-Portions copyright (C) 2007 Mark Wooding
+Portions copyright (C) 2007, 2013, 2016 Mark Wooding
 Portions extracted from MPG321, http://mpg321.sourceforge.net/
   Copyright (C) 2001 Joe Drew
   Copyright (C) 2000-2001 Robert Leslie
index c2c2df6..9a7c28a 100755 (executable)
@@ -274,14 +274,16 @@ pkg-disorder-gstdecode: build
          fi;\
        done
        $(MKDIR) debian/disorder-gstdecode/usr/sbin
-       : $(MKDIR) debian/disorder-gstdecode/usr/share/man/man1
+       $(MKDIR) debian/disorder-gstdecode/usr/share/man/man8
        $(INSTALL_PROGRAM) server/disorder-gstdecode \
                debian/disorder-gstdecode/usr/sbin/disorder-gstdecode
        strip --remove-section=.comment debian/disorder-gstdecode/usr/sbin/disorder-gstdecode
+       $(INSTALL_DATA) doc/disorder-gstdecode.8 \
+               debian/disorder-gstdecode/usr/share/man/man8/disorder-gstdecode.8
        dpkg-shlibdeps -Tdebian/substvars.disorder-gstdecode \
                debian/disorder-gstdecode/usr/sbin/*
        $(INSTALL_DATA) CHANGES.html debian/disorder-gstdecode/usr/share/doc/disorder-gstdecode/CHANGES.html
-       gzip -9f debian/disorder-gstdecode/usr/share/man/man*/*
+       gzip -9f debian/disorder-gstdecode/usr/share/man/man*/*
        cd debian/disorder-gstdecode && \
                find -name DEBIAN -prune -o -type f -print \
                        | sed 's/^\.\///' \
index b3d8926..3919135 100644 (file)
@@ -24,14 +24,15 @@ man_MANS=disorderd.8 disorder.1 disorder.3 disorder_config.5 disorder-dump.8 \
        disorder-playrtp.1 disorder-normalize.8 disorder-decode.8 \
        disorder-stats.8 disorder-dbupgrade.8 disorder_templates.5 \
        disorder_actions.5 disorder_options.5 disorder.cgi.8 \
-       disorder_preferences.5 disorder-choose.8
+       disorder_preferences.5 disorder-choose.8 disorder-gstdecode.8
 
 SEDFILES=disorder.1 disorderd.8 disorder_config.5 \
        disorder-dump.8 disorder_protocol.5 disorder-deadlock.8 \
        disorder-rescan.8 disobedience.1 disorderfm.1 disorder-playrtp.1 \
        disorder-decode.8 disorder-stats.8 disorder-dbupgrade.8 \
        disorder_options.5 disorder.cgi.8 disorder_templates.5 \
-       disorder_actions.5 disorder_preferences.5 disorder-choose.8
+       disorder_actions.5 disorder_preferences.5 disorder-choose.8 \
+       disorder-gstdecode.8
 
 include ${top_srcdir}/scripts/sedfiles.make
 
@@ -42,7 +43,8 @@ disorderfm.1.html disorder-speaker.8.html disorder-playrtp.1.html     \
 disorder-normalize.8.html disorder-decode.8.html disorder-stats.8.html \
 disorder-dbupgrade.8.html disorder_templates.5.html                    \
 disorder_actions.5.html disorder_options.5.html disorder.cgi.8.html    \
-disorder_preferences.5.html disorder-choose.8.html
+disorder_preferences.5.html disorder-choose.8.html                     \
+disorder-gstdecode.8.html
 
 $(wordlist 2,9999,$(HTMLMAN)): disorderd.8.html
 disorderd.8.html: $(man_MANS)
@@ -55,7 +57,8 @@ disorderfm.1.tmpl disorder-speaker.8.tmpl disorder-playrtp.1.tmpl     \
 disorder-normalize.8.tmpl disorder-decode.8.tmpl disorder-stats.8.tmpl \
 disorder-dbupgrade.8.tmpl disorder_templates.5.tmpl                    \
 disorder_actions.5.tmpl disorder_options.5.tmpl disorder.cgi.8.tmpl    \
-disorder_preferences.5.tmpl disorder-choose.8.tmpl
+disorder_preferences.5.tmpl disorder-choose.8.tmpl                     \
+disorder-gstdecode.8.tmpl
 
 $(wordlist 2,9999,$(TMPLMAN)): disorderd.8.tmpl
 disorderd.8.tmpl: $(man_MANS)
@@ -101,7 +104,7 @@ EXTRA_DIST=disorderd.8.in disorder.1.in disorder_config.5.in \
           disorder_actions.5.head disorder_templates.5.head \
           disorder_actions.5.tail disorder_templates.5.tail \
           disorder_options.5.in disorder.cgi.8.in disorder_preferences.5.in \
-          disorder-choose.8.in
+          disorder-choose.8.in disorder-gstdecode.8.in
 
 CLEANFILES=$(SEDFILES) $(HTMLMAN) $(TMPLMAN) \
        disorder_actions.5.in disorder_templates.5.in
diff --git a/doc/disorder-gstdecode.8.in b/doc/disorder-gstdecode.8.in
new file mode 100644 (file)
index 0000000..16fb458
--- /dev/null
@@ -0,0 +1,110 @@
+.\" -*-nroff-*-
+.\"
+.\" Copyright (C) 2007, 2008 Richard Kettlewell
+.\" Copyright (C) 2016 Mark Wooding
+.\"
+.\" This program is free software: you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation, either version 3 of the License, or
+.\" (at your option) any later version.
+.\" 
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\" 
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
+.\"
+.TH disorder-gstdecode 8
+.SH NAME
+disorder-gstdecode \- DisOrder audio decoder using GStreamer
+.SH SYNOPSIS
+.B disorder\-gstdecode
+.RB [ -c
+.IR CONFIGFILE ]
+.RB [ -d
+.IR DITHER ]
+.RB [ -f
+.IR GAIN ]
+.br
+\h'8n'\c
+.RB [ -n
+.IR SHAPE ]
+.RB [ -q
+.IR QUALITY ]
+.RB [ -r
+.IR MODE ]
+.I PATH
+.SH DESCRIPTION
+.B disorder\-gstdecode
+converts encoded audio files into DisOrder's "raw" format.
+It uses the GStreamer library for conversion,
+and can decode any kind of audio file
+for which the necessary GStreamer plugins are available.
+.PP
+It is suitable for use as an
+.B execraw
+player.
+.PP
+It is not intended to be used from the command line,
+but command-line options can usefully be provided
+in DisOrder's configuration file.
+.SH OPTIONS
+.TP
+.B \-\-help\fR, \fB\-h
+Display a usage message.
+.TP
+.B \-\-version\fR, \fB\-V
+Display version number.
+.TP
+.B \-\-config \fICONFIGFILE\fR, \fB\-c \fICONFIGFILE
+Set the configuration file.
+.TP
+.B \-\-dither \fITYPE\fR, \fB\-d \fIDITHER
+Set the dither type used during audio format conversion.
+This can be \fBnone\fR,
+\fBrpdf\fR for rectangular dithering,
+\fBtpdf\fR for triangular dithering, or
+\fBtpdf-hf\fR for high-frequency triangular dithering.
+Maybe the GStreamer documentation will explain what these mean.
+The default is to leave the decision
+to GStreamer's \fBaudioconvert\fR plugin.
+.TP
+.B \-\-fallback-gain \fIGAIN\fR, \fB\-f \fIGAIN
+Set the gain to be applied to tracks
+which don't have ReplayGain information.
+This is in decibels, and will usually be negative.
+The default is zero, which is probably wrong.
+.TP
+.B \-\-noise-shape \fITYPE\fR, \fB-n \fITYPE
+Set the noise shaping type used during audio format conversion.
+This can be \fBnone\fR,
+\fBerror-feedback\fR,
+\fBsimple\fR for 2-pole noise shaping,
+\fBmedium\fR for 5-pole noise shaping, or
+\fBhigh\fR for 8-pole noise shaping.
+Maybe the GStreamer documentation will explain what these mean.
+The default is to leave the decision
+to GStreamer's \fBaudioconvert\fR plugin.
+.TP
+.B \-\-quality \fIQUALITY\fR, \fB\-q \fIQUALITY
+Set the quality level to be used for resampling.
+This should be an integer between
+0 (poor, but fast) and
+10 (good, but slow).
+See the GStreamer documentation for more information.
+The default is to leave the decision
+to GStreamer's \fBaudioresample\fR plugin.
+.TP
+.B \-\-replay-gain \fIMODE\fR, \fB\-r \fIMODE
+Set the ReplayGain mode.
+This can be \fBoff\fR to not bother with ReplayGain at all,
+\fBtrack\fR to use the per-track gain setting, or
+\fBalbum\fR to use the per-album gain setting
+(so that the volume level sounds consistent
+when playing an entire album).
+The default is \fBalbum\fR.
+.SH "SEE ALSO"
+.BR disorderd (8),
+.BR disorder_config (5)