burncd/burncd.1

.\" burncd.1
.\" Copyright 2018-2020 orbea
.\" All rights reserved.
.\"
.\" Redistribution and use of this script, with or without modification, is
.\" permitted provided that the following conditions are met:
.\"
.\" 1. Redistributions of this script must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED
.\" WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO
.\" EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd September 27, 2020
.Dt BURNCD 1
.Os
.Sh NAME
.Nm burncd
.Nd burn audio files to a blank CD
.Sh SYNOPSIS
.Nm
.Op Fl dhnNvV
.Op Fl c Ar config ...
.Op Fl C Ar binary
.Op Fl e Ar format ...
.Op Fl f Ar format ...
.Op Fl F Ar binary
.Op Fl i Ar path ...
.Op Fl M Ar binary
.Op Fl o Ar path
.Op Fl p Ar playlist ...
.Op Fl S Ar binary
.Op Fl z Ar device
.Op Ar
.Sh DESCRIPTION
burncd is a portable POSIX shell script that uses
.Xr cdrecord 1
to burn audio files to a blank CD.
It currently supports
.Xr flac 1 ,
wav, mp3 and Sun/NeXT audio files which will be automatically detected from the
command line, current directory or playlist.
.Ss AUDIO FORMATS
By default
.Nm
will prefer wav and Sun/NeXT audio formats as
.Xr cdrecord 1
supports these files natively.
It will then select other lossless and lossy audio formats.
Lossy audio formats will always be the least preferred.
If any files exist in multiple audio formats it will use only the first.
.Pp
Currently supported audio formats by
.Nm :
.Pp
.Bl -tag -width <TAB><TAB> -offset indent -compact
.It Cm wav
WAVE
.It Cm au
Sun/NeXT
.It Cm flac
FLAC
.It Cm mp3
MPEG Audio Layer III
.El
.Ss AUDIO FILES
Audio files will be detected from the command line, current directory or
playlist using the sanitized output of
.Xr file 1 .
This avoids issues related to filenames that do not have a correct filename
extension.
.Ss NON-NATIVE CD AUDIO FILES
Audio files must be 44.1 kHz, 16-bit and stereo to be correctly work on blank
audio CDs.
If
.Xr sox 1
is found in the user's $PATH then it will be used to convert any audio files
that are not properly supported.
If
.Xr sox 1
is not found then
.Nm
will exit early when any such files are detected.
.Ss PLAYLISTS
Audio files can be read from plaintext playlist files containing a list of
files separated by newline characters.
Relative paths will be read from the current directory.
If the file or playlist is missing, cannot be read or the playlist is not a
text file a warning will be printed.
Comment lines are not supported.
.Ss CDRECORD PERMISSIONS
Some distributions will install
.Xr cdrecord 1
without suid permissions for security concerns which will require
.Nm
to be run as root.
Alternatively the user can add suid permissions to
.Xr cdrecord 1 .
.Pp
For example the following commands can be used.
.Bd -literal -offset indent
# chown root:somegroup /usr/bin/cdrecord
# chmod 4710 /usr/bin/cdrecord
.Ed
.Pp
The user should then make sure they belong to 'somegroup'.
.Ss ENVIRONMENT VARIABLES
.Nm
supports the following environment variables.
.Pp
.Bl -tag -width <TAB><TAB><TAB> -offset indent -compact
.It Ev XDG_CONFIG_HOME
XDG base directory.
.It Ev XDG_CONFIG_DIRS
List of colon-separated directories.
.El
.Pp
.Ev XDG_CONFIG_HOME
defaults to
.Pa $HOME/.config/burncd/burncd.conf .
.Ev XDG_CONFIG_DIRS
defaults to
.Pa /etc/xdg/burncd/burncd.conf .
.Ss CONFIGURATION FILES
.Nm
looks for configuration files in the following order.
.Pp
.Bl -enum -offset indent -compact
.It
.Pa $XDG_CONFIG_HOME/burncd/burncd.conf
.It
.Pa $HOME/.burncd.conf
.It
.Pa $XDG_CONFIG_DIRS/burncd/burncd.conf
.It
.Pa /etc/burncd.conf
.It
.Pa ./burncd.conf
.El
.Pp
Configuration files are written in plain text.
Comments begin with a #.
Variables are split by whitespace and a =.
All other whitespace is ignored.
Variables can be set to either a file path, a list deliminated with spaces or
enabled with 1.
Any unset variables will be set to the default.
.Pp
.Nm
will ignore any unlisted variables.
.Pp
.Bl -tag -width <TAB><TAB> -offset indent -compact
.It Va CDRECORD
Path of the
.Xr cdrecord 1
binary.
.It Va DEBUG
Enable debug output from external programs.
.It Va DEVICE
Path of the CD drive.
.It Va DRYRUN
Enable a test run without burning to a CD.
.It Va EXCLUDE
Exclude audio formats from being detected.
.It Va FORMAT
Preferred audio formats.
.It Va FLAC
Path of the
.Xr flac 1
binary.
.It Va MPG123
Path of the
.Xr mpg123 1
binary.
.It Va OUTPUT
Path of the output directory.
.It Va SOX
Path of the
.Xr sox 1
binary.
.It Va VERBOSE
Enable verbose logging.
.El
.Pp
When loading configuration files with
.Fl -config ,
variables set in a config file can be overridden by being set again in any
additional config files.
.Sh OPTIONS
A summary of the options is included below.
.Bl -tag -width indent
.It Fl c , -config Ar config ...
Path of the configuration files.
.It Fl C , -cdrecord Ar binary
Path of the
.Xr cdrecord 1
binary.
.It Fl d , -debug
Show the debug output from external programs.
.It Fl e , -exclude Ar format ...
Configure the excluded audio formats.
.It Fl f , -format Ar format ...
Configure the default audio formats.
.It Fl F , -flac Ar binary
Path of the
.Xr flac 1
binary.
.It Fl h , -help
Show basic usage and a list of all options.
.It Fl i , -input Ar path ...
Configure the default directories path.
This is a no-op when reading files from the command line, playlist or standard
input.
.Nm
will search the current directory by default.
.It Fl M , -mpg123 Ar binary
Path of the
.Xr mpg123 1
binary.
.It Fl n , -dry-run
Enable a test run without burning to a CD.
.Nm
will not check for a blank CD under this mode.
.It Fl N , -no-conf
Do not load default configuration files.
.It Fl o , -output Ar path
Configure the output directory path.
Defaults to
.Pa /tmp/CD .
.It Fl p , -playlist Ar playlist ...
Read audio files from a playlist.
.It Fl S , -sox Ar binary
Path of the
.Xr sox 1
binary.
.It Fl v , -verbose
Show the verbose
.Nm
output.
.It Fl V , -version
Show the
.Nm
version number.
.It Fl z , -device Ar device
Configure the CD drive path.
Defaults to
.Pa /dev/sr0 .
.El
.Sh EXAMPLES
.Bl -tag -width indent
.It Nm
Burn audio files from the current directory to a blank CD.
.It Nm Ar
Burn audio files from the command line to a blank CD.
.It Nm Fl c Cm burncd.conf.1 burncd.conf.2
Load the
.Pa burncd.conf.1
and
.Pa burncd.conf.2
configuration files from the command line.
.It Nm Fl C Cm /usr/bin/cdrecord
Use the
.Pa /usr/bin/cdrecord
binary.
.It Nm Fl e Cm wav mp3
Exclude all wav and mp3 audio files.
.It Nm Fl f Cm flac mp3
Prefer
.Xr flac 1
and then mp3 audio files.
.It Nm Fl F Cm /usr/bin/flac
Use the
.Pa /usr/bin/flac
binary.
.It Nm Fl i Cm /tmp/dir1 /tmp/dir2
Set the default directories to
.Pa /tmp/dir1
and
.Pa /tmp/dir2 .
.It Nm Fl M Cm /usr/bin/mpg123
Use the
.Pa /usr/bin/mpg123
binary.
.It Nm Fl o Cm /tmp
Set the output directory path to
.Pa /tmp .
.It Nm Fl p Cm foo bar
Read audio files from plaintext playlists titled
.Pa foo
and
.Pa bar .
.It Nm Fl S Cm /usr/bin/sox
Use the
.Pa /usr/bin/sox
binary.
.It Nm Fl z Cm /dev/sr1
Set the CD drive path to
.Pa /dev/sr1 .
.It Nm Fl
Read audio files from standard input.
.El
.Pp
Example
.Nm
configuration file.
.Bd -literal -offset indent
# Set the cdrecord binary path
CDRECORD = /usr/bin/cdrecord

# Prefer flac and then wav audio formats
FORMAT = flac wav

# Set the output directory
OUTPUT = /tmp

# Enable verbose logging
VERBOSE = 1
.Ed
.Sh SEE ALSO
.Xr cdrecord 1 ,
.Xr flac 1 ,
.Xr mpg123 1 ,
.Xr sox 1
.Sh AUTHORS
.An -nosplit
.Bl -tag -width "orbea Aq orbea@riseup.net " -compact
.It An orbea Aq Mt orbea@riseup.net
.El
.Sh BUGS
Not all mp3 audio files are detected by
.Nm .
.Pp
.Lk https://notabug.org/orbea/burncd/issues "Issue tracker"