From c764e832cef2e0828e46762b66ca97cc5541686b Mon Sep 17 00:00:00 2001 Message-Id: From: Mark Wooding Date: Tue, 15 Dec 2015 19:15:23 +0000 Subject: [PATCH] Add documentation and administrivia about `disorder-gstdecode'. Organization: Straylight/Edgeware From: Mark Wooding --- CHANGES.html | 36 ++++++++++++ README | 2 +- debian/rules | 6 +- doc/Makefile.am | 13 +++-- doc/disorder-gstdecode.8.in | 110 ++++++++++++++++++++++++++++++++++++ 5 files changed, 159 insertions(+), 8 deletions(-) create mode 100644 doc/disorder-gstdecode.8.in diff --git a/CHANGES.html b/CHANGES.html index 4fbc197..e8532f4 100644 --- a/CHANGES.html +++ b/CHANGES.html @@ -67,6 +67,42 @@ href="README.upgrades.html">README.upgrades before upgrading.

+

GStreamer support

+ +
+ +

If it's detected at configure time, a new decoder + program disorder-gstdecode is built. It uses the GStreamer + library for audio decoding and sample-rate conversion, among other + features. + +

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.

+ +

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 mp3gain, + vorbisgain, or metaflac. 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.

+ +

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: + 

+        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
+
+

+

General

diff --git a/README b/README index 71176aa..af88631 100644 --- 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 diff --git a/debian/rules b/debian/rules index c2c2df6..9a7c28a 100755 --- a/debian/rules +++ b/debian/rules @@ -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/^\.\///' \ diff --git a/doc/Makefile.am b/doc/Makefile.am index b3d8926..3919135 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -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 index 0000000..16fb458 --- /dev/null +++ b/doc/disorder-gstdecode.8.in @@ -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 . +.\" +.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) -- [mdw]