burncd/burncd.1

.\" burncd.1
.\" Copyright 2018-2019 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 August 29, 2019
.Dt BURNCD 1
.Os
.Sh NAME
.Nm burncd
.Nd burn audio files to a blank CD
.Sh SYNOPSIS
.Nm
.Op Fl dhnvV
.Op Fl e Ar format ...
.Op Fl f Ar format ...
.Op Fl o Ar path
.Op Fl z Ar device
.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 and Sun/NeXT audio files which will be automatically detected from the
current directory.
.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
.Xr flac 1
files.
Lossy audio formats will always be the least prefered.
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
.El
.Ss AUDIO FILES
Audio files will be detected from the current directory 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 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> -offset indent -compact
.It Ev CDRECORD
Path of the
.Xr cdrecord 1
binary.
.It Ev FLAC
Path of the
.Xr flac 1
binary.
.It Ev SOX
Path of the
.Xr sox 1
binary.
.El
.Sh OPTIONS
A summary of the options is included below.
.Bl -tag -width indent
.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 h , -help
Show basic usage and a list of all options.
.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 o , -output Ar path
Configure the output directory path.
Defaults to
.Pa /tmp/CD .
.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/sr1 .
.El
.Sh EXAMPLES
.Bl -tag -width indent
.It Nm
Burn audio files from the current directory to a blank CD.
.It Nm Fl e Cm wav
Exclude all wav audio files from the current directory.
.It Nm Fl f Cm flac
Prefer
.Xr flac 1
audio files from the current directory.
.It Nm Fl o Cm /tmp
Set the output directory path to
.Pa /tmp .
.It Nm Fl z Cm /dev/sr0
Set the CD drive path to
.Pa /dev/sr0 .
.El
.Sh SEE ALSO
.Xr cdrecord 1 ,
.Xr flac 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
.Lk https://notabug.org/orbea/burncd/issues "Issue tracker"