
cdwrite 3.5.1


QUICK START

If you use Slackware Linux or a similar distribution read first
README.Slackware file.  If you use Linux Mint or a similar distribution read
first README.Mint file. In the other case read the following document.

Install cdwrite according to INSTALLATION section below.  After the
installation copy the framed text from the end of FURTHER CONFIGURATION
section below to /etc/sudoers file and run cdwrite for the first time.  If
the shell displays the information about lacking programs, install them
using the tips given by the shell or described in BASIC REQUIREMENTS section
below.  For full cdwrite functionality install the programs mentioned in
OPTIONAL REQUIREMENTS section below.  Then run cdwrite for the second time
and use ``Preferences | Display config'' menu to check where cdwrite seeks
for its configuration file -- the same information you will get using the
command ``cdwrite -c''.  Next exit the shell and customize the configuration
file to your needs according to BASIC CONFIGURATION and IMPORTANT VARIABLES
sections below.


INSTALLATION

To install cdwrite globally run the following commands as root:

    ./configure
    make install

It is possible to run configure script with option ``--prefix=PREFIX''.
Default PREFIX is ``/usr/local'', allowed PREFIXES are: ``/usr'' and
``/opt/cdwrite''.

To install it locally copy cdwrite script and the other executables except
for configure to ~/bin directory and copy cdwrite.conf file to ~/.cdwriterc
one.

To uninstall cdwrite run ``make uninstall'' command as root and optionally
remove all local ~/bin executables as well as ~/.cdwriterc files.

If cdwrite prompts you at the start to type your password it means the
configuration of the program is not valid (see BASIC CONFIGURATION and
FURTHER CONFIGURATION sections below).


TESTS WITHOUT INSTALLATION

It is also possible to test cdwrite without installing it globally or
locally.  To achieve that run cdwrite using one of these commands: ./cdwrite
or /path/to/the/shell/cdwrite.  In these cases cdwrite uses respectively
./cdwrite.conf or /path/to/the/shell/cdwrite.conf configuration file.

In the similar way it is possible to test cdwr.* and cdencode scripts found
in the local directory.  To test them you have first run ``./cdwrite.links
--make'' command to prepare required symbolic links.  Then sample command
./cdwr calls ./cdwr.cdparanoia script using the configuration named cdwr.
Before trying that you have to check and update the configuration section of
cdwr.cdparanoia and cdwr.cdda2wav scripts.  The command ``./cdwrite.links
--remove'' removes those symbolic links.  To display the man page without
the installation you have to use the command ``less cdwrite.1''.

You can use cdwrite.links script to remove default cdwrite links made during
the installation.  After the update of the cdwrite.links script you can make
your own links.  It is easier than the modification of the configure script
or Makefile.


BASIC CONFIGURATION

The cdwrite seeks for the configuration file in the following order:

  1 ./.cdwriterc	# the directory containing cdwrite shell
  2 ./cdwrite.conf	# the directory containing cdwrite shell
  3 ~/.cdwriterc
  4 /usr/local/etc/cdwrite.conf
  5 /etc/cdwrite.conf
  6 /opt/cdwrite/etc/cdwrite.conf

Take that into consideration if you installed cdwrite in a few locations.
The first two locations are for the testing purposes only.  The third
location is for the local configuration file.  Three following locations are
for global configuration files.

To configure cdwrite edit /cdwrite.conf file, or ~/.cdwriterc file, or the
other mentioned above configuration file and check all the values,
especially:

  - device,
  - reader,
  - writer,
  - number,
  - driver,
  - dvd_rw,
  - speed,
  - buffers,
  - cd_dir,
  - and dvd_dir.

for the first -- default -- device.

In the case of the plugged device which changes its number from session to
session use the setting such as:

    number="`sudo cdrecord -scanbus | grep 'LITE-ON' | awk '{print $1}'`"

In the above example ``LITE-ON'' is the unique name of the device displayed
by the command ``sudo cdrecord -scanbus''.  The usage of sudo is discussed
below.

You can add up to five devices to the configuration file.  If you use only
one device you can comment the above ten variables for the second and the
third devices, or you can set these variables to the empty values, or just
leave them in peace and do not use them.


FURTHER CONFIGURATION

To use /bin/umount, /usr/bin/mkisofs, /usr/bin/cdrecord, /usr/bin/cdda2wav,
/usr/bin/cdrdao, and /usr/bin/dvd+rw-format with cdwrite you have to use one
of the following methods:

  1 add rec group to the system, register /dev/sr0 device in that group, and
    add yourself to it; cdwrite uses links to /dev/sr0 such as /dev/cdrom
    and /dev/cdrw; if /dev/sr0 device has brw------- rights change them to
    brw-rw---- ones.

  2 or register yourself in cdrom group assuming that /dev/sr0 is in cdrom
    group; use the command such as: ``usermod -G group user''; to check the
    groups you belong use the command ``groups''.

  3 or register umount, mkisofs, cdrecord, cdda2wav, cdrdao, and
    dvd+rw-format in /etc/sudoers file (see: below) and update umount_call,
    mkisofs_call, cdrecord_call, cdda2wav_call, and dvdrw_format_call from
    configuration file to use sudo:

	umount_call="sudo umount"
	mkisofs_call="sudo mkisofs"
	cdrecord_call="sudo cdrecord"
	cdda2wav_call="sudo cdda2wav"
	cdrdao_call="sudo cdrdao"
	dvdrw_format_call="sudo dvd+rw-format"

  4 or set suid bit for umount, mkisofs, cdrecord, cdda2wav, cdrdao, and
    dvd+rw-format using the commands such as: ``chmod u+s /path/file'',

  5 or set suid bit for cdwrite,

  6 or register cdwrite in /etc/sudoers and put an alias in ~/.bashrc:

	alias cdwrite='sudo /usr/local/bin/cdwrite'

In the last case growisofs refuses to work because it can not be called with
sudo.

The first method is safe but it violates default system configuration and is
the most complicated one -- the last two methods are the worst, possibly
dangerous, and not recommended.  The third method is the most flexible and
depends on the settings stored in /etc/sudoers file (see: below).

The cdwrite uses by default the third method and requires the appropriate
/etc/sudoers file.  Simple working /etc/sudoers file for default cdwrite
configuration is the following:

    #-------------------------------------------------------------------
    root	ALL = (ALL) ALL

    %users	ALL = NOPASSWD: /bin/mount, /bin/umount

    %users	ALL = NOPASSWD: /usr/bin/mkisofs, /usr/bin/cdrecord, \
				/usr/bin/cdda2wav, /usr/bin/cdrdao, \
    				/usr/bin/dvd+rw-format

    %users	ALL = NOPASSWD: /bin/kill
    #-------------------------------------------------------------------

The above example assumes you are a member of the group users.


BASIC REQUIREMENTS

The cdwrite shell uses the dialog program to display dialog boxes.  If your
Linux distribution repositories do not include dialog you will find it here:
http://invisible-island.net/dialog/.

The other requirements include:

  - cdda2wav, cdrecord, mkisofs, and isoinfo from cdrtools package (in some
    Linux distributions cdda2wav is a part of icedax package, cdrecord is a
    part of wodim package, and mkisofs and isoinfo are a part of genisoimage
    package),

  - normalize or normalize-audio from normalize or normalize-audio package,

  - cdda-player from libcdio or libcdio-utils package,

  - growisofs and dvd+rw-mediainfo from dvd+rw-tools package,

  - oggenc from vorbis-tools package,

  - and also cdparanoia, cdrdao, lame, mp3gain, mplayer, perl, and gawk
    packages.


OPTIONAL REQUIREMENTS

Optional requirements allow to use CDDB data and ID3 tags:

  - CDDB_get Perl module package is required for communication with CDDB
    servers (see: http://search.cpan.org/).

    To install it use the commands:

      tar xzf CDDB_get-2.28.tar.gz
      cd CDDB_get-2.28
      perl Makefile.PL
      make
      make install

  - mutagen package to set ID3 tags using UTF-8 encoding (see:
    https://bitbucket.org/lazka/mutagen/).

  or:

  - id3lib library (in some Linuxes called libid3) and id3v2 package are
    required for mass ID3 tagging of MP3 files (see:
    http://id3lib.sourceforge.net/ for the library and
    http://id3v2.sourceforge.net/ for the program).

The mutagen package is necessary if you would like to set ID3 tags in MP3
files using UTF-8 encoding.


IMPORTANT VARIABLES

Some /usr/local/etc/cdwrite.conf or ~/.cdwriterc files settings deserve the
special attention:

  - driver (default: generic-mmc-raw),
  - speed (default: 12),
  - mp3_normalization (default: mp3gain),
  - cd_player (default: mplayer),
  - mplayer_speed (default: 1),
  - mplayer_cache (default: 4096),
  - filename_convention (default: Windows),
  - and debug (default: off).

The default driver ``generic-mmc-raw'' works in most cases better than
``generic-mmc'' one because it allows to write CD-TEXT and indexes on audio
CDs with most devices.

The default speed is set to moderate value 12x because devices using high
speeds often refuse to blank CD-RW and DVD-RW media.

The default MP3 files normalization program is ``mp3gain'' because it
normalizes MP3 files without decoding and encoding them so it preserve the
original quality and ID3 tags.  The alternative program ``normalize-mp3''
decodes and encodes MP3 files in order to normalize them and moreover it
does not recognize already normalized files so a lot of consecutive
normalizations is possible causing a severe deterioration of the sound.

The default CD player is ``mplayer'' because it works with all devices.  The
cdda-player plays audio CD tracks without the gaps and allows to jump from
track to track without the breaks in comparison with mplayer but with some
devices the sound played by cdda-player is not audible.  It is worth to run
cdda-player manually to test it.  If it plays audio CDs the best option is
to set ``cd_player'' variable to ``cdda-player''.  Before testing
cdda-player increase the CD device volume to 100% using alsamixer or the
other mixer.

The default mplayer speed is set to 1x because it is enough to read audio CD
and the drive working with the low speed produces less noise.

The default mplayer cache is set to ``4096'' because without the cache some
drives can not play audio CD tracks smoothly.  It is worth to lower the
cache size to ``32''.  If mplayer plays audio CD tracks smoothly with the
minimal cache the gaps between the tracks will be a few seconds shorter.

Linux allows to use almost all characters in the names of directories and
files.  Forbidden is / which means new directory.  It is also impossible to
name directory or file . or .. because they mean the current directory and
the above the current directory.  The name ... is allowed as well as the
names including the other special characters.  Windows is more restrictive
and does not accept more characters: " : / \ | * ? < and >.  Mentioned above
``filename_convention'' variable accepts two settings: ``Linux'' or
``Windows''.  In the first it replaces ``/'' with `` - ''.  For example the
first track on Pink Floyd's ``Dark Side of the Moon'' has the title in CDDB:
``Speak To Me/Breathe''.  It is impossible to encode it to the file named
``01 Speak To Me/Breathe.mp3'' so cdwrite in ``Linux'' setting changes it to
``01 Speak To Me - Breathe.mp3''.  For Windows compatibility it is necessary
to replace or remove colons, question marks and other forbidden characters.
The cdwrite does it in ``Windows'' setting.  The cdwrite default setting for
``filename_convention'' variable is ``Windows''.

The variable ``debug'' has two settings: ``on'' or ``off''.  In the first
case cdwrite displays the information without breaks allowing to follow it
as it comes while in the second case it resets the terminal before
displaying the new information.  The cdwrite default setting for ``debug''
variable is ``off''.


Copyright (C) 2005-2015 Cezary M. Kruk <c.kruk@bigfoot.com>

