Whipper

Whipper is a Python 2.7 CD-DA ripper based on the morituri project (CDDA ripper for *nix systems aiming for accuracy over speed). It enhances morituri which development seems to have halted merging old ignored pull requests, improving it with bugfixes and new features.

Whipper is currently developed and tested only on Linux distributions but may work fine on other *nix OSes too.

In order to track whipper's latest changes it's advised to check its commit history (README and CHANGELOG files may not be comprehensive).

Table of content

Rationale
Features
Changelog
Installation
- Docker
- Package
Building
Usage
Getting started
Configuration file documentation
Running uninstalled
Logger plugins
License
Contributing
- Bug reports & feature requests
Credits
Links

Rationale

For a detailed description, see morituri's wiki page: The Art of the Rip.

Features

Detects correct read offset (in samples)
Detects whether ripped media is a CD-R
Has ability to defeat cache of drives
Performs Test & Copy rips
Verifies rip accuracy using the AccurateRip database
Uses MusicBrainz for metadata lookup
Supports reading the pre-emphasis flag embedded into some CDs (and correctly tags the resulting rip). Currently whipper only reports the pre-emphasis flag value stored in the TOC.
Detects and rips non digitally silent Hidden Track One Audio (HTOA)
Provides batch ripping capabilities
Provides templates for file and directory naming
Supports lossless encoding of ripped audio tracks (FLAC)
Allows extensibility through external logger plugins

Changelog

See CHANGELOG.md.

For detailed information, please check the commit history.

Installation

Whipper still isn't available as an official package in every Linux distributions so, in order to use it, it may be necessary to build it from its source code.

Docker

You can easily install whipper without needing to care about the required dependencies by making use of the automatically built images hosted on Docker Hub:

docker pull joelametta/whipper

Alternatively, in case you prefer building Docker images locally, just issue the following command (it relies on the Dockerfile included in whipper's repository):

docker build -t whipper/whipper

It's recommended to create an alias for a convenient usage:

alias whipper="docker run -ti --rm --device=/dev/cdrom \
    -v ~/.config/whipper:/home/worker/.config/whipper \
    -v ${PWD}/output:/output \
    whipper/whipper"

You should put this e.g. into your .bash_aliases. Also keep in mind to substitute the path definitions to something that fits to your needs (e.g. replace … -v ${PWD}/output:/output … with … -v ${HOME}/ripped:/output \ …).

Make sure you create the configuration directory:

mkdir -p ~/.config/whipper ${PWD}/output

Finally you can test the correct installation:

whipper -v
whipper drive list

Package

This is a noncomprehensive summary which shows whipper's packaging status (unofficial repositories are probably not included):

In case you decide to install whipper using an unofficial repository just keep in mind it is your responsibility to verify that the provided content is safe to use.

Building

If you are building from a source tarball or checkout, you can choose to use whipper installed or uninstalled but first install all the required dependencies.

Required dependencies

Whipper relies on the following packages in order to run correctly and provide all the supported features:

cd-paranoia, for the actual ripping
- To avoid bugs it's advised to use cd-paranoia version 10.2+0.94+2-2
- The package named libcdio-utils, available on Debian and Ubuntu, is affected by a bug: it doesn't include the cd-paranoia binary (needed by whipper). For more details see: #888053 (Debian), #1750264 (Ubuntu).
cdrdao, for session, TOC, pre-gap, and ISRC extraction
GObject Introspection, to provide GLib-2.0 methods used by task.py
PyGObject, required by task.py
python-musicbrainzngs, for metadata lookup
python-mutagen, for tagging support
python-setuptools, for installation, plugins support
python-requests, for retrieving AccurateRip database entries
pycdio, for drive identification (required for drive offset and caching behavior to be stored in the configuration file).
- To avoid bugs it's advised to use pycdio 0.20 or 0.21 with libcdio ≥ 0.90 ≤ *0.94 or pycdio 2.0.0 with libcdio 2.0.0. All other combinations won't probably work.
libsndfile, for reading wav files
flac, for reading flac files
sox, for track peak detection

Some dependencies aren't available in the PyPI. They can be probably installed using your distribution's package manager:

PyPI installable dependencies are listed in the requirements.txt file and can be installed issuing the following command:

pip install -r requirements.txt

Fetching the source code

Change to a directory where you want to put whipper source code (for example, $HOME/dev/ext or $HOME/prefix/src)

git clone https://github.com/whipper-team/whipper.git
cd whipper

Building the bundled dependencies

Whipper uses and packages a slightly different version of the accuraterip-checksum tool:

You can edit the install path in config.mk

cd src
make
sudo make install
cd ..

Finalizing the build

Install whipper: python2 setup.py install

Note that, depending on the chosen installation path, this command may require elevated rights.

Usage

Whipper currently only has a command-line interface called whipper which is self-documenting: whipper -h gives you the basic instructions.

Whipper implements a tree of commands: for example, the top-level whipper command has a number of sub-commands.

Positioning of arguments is important:

whipper cd -d (device) rip

is correct, while

whipper cd rip -d (device)

is not, because the -d argument applies to the cd command.

Getting started

The simplest way to get started making accurate rips is:

Pick a relatively popular CD that has a good chance of being in the AccurateRip database
Analyze the drive's caching behavior

whipper drive analyze
Find the drive's offset.

Consult the AccurateRip's CD Drive Offset database for your drive. Drive information can be retrieved with whipper drive list.

whipper offset find -o insert-numeric-value-here

If you omit the -o argument, whipper will try a long, popularity-sorted list of drive offsets.

If you can not confirm your drive offset value but wish to set a default regardless, set read_offset = insert-numeric-value-here in whipper.conf.

Offsets confirmed with whipper offset find are automatically written to the configuration file.

If specifying the offset manually, please note that: if positive it must be written as a number without sign (ex: +102 -> 102), if negative it must include the sign too (ex: -102 -> -102).
Rip the disc by running

whipper cd rip

Configuration file documentation

The configuration file is stored in $XDG_CONFIG_HOME/whipper/whipper.conf, or $HOME/.config/whipper/whipper.conf if $XDG_CONFIG_HOME is undefined.

See XDG Base Directory Specification and ConfigParser.

The configuration file consists of newline-delineated [sections] containing key = value pairs. The sections [main] and [musicbrainz] are special config sections for options not accessible from the command line interface. Sections beginning with drive are written by whipper; certain values should not be edited.

Example configuration demonstrating all [main] and [musicbrainz] options:

[main]
path_filter_fat = True		; replace FAT file system unsafe characters in filenames with _
path_filter_special = False	; replace special characters in filenames with _

[musicbrainz]
server = musicbrainz.org:80	; use MusicBrainz server at host[:port]

[drive:HL-20]
defeats_cache = True		; whether the drive is capable of defeating the audio cache
read_offset = 6			; drive read offset in positive/negative frames (no leading +)
# do not edit the values 'vendor', 'model', and 'release'; they are used by whipper to match the drive

# command line defaults for `whipper cd rip`
[whipper.cd.rip]
unknown = True
output_directory = ~/My Music
track_template = new/%%A/%%y - %%d/%%t - %%n	; note: the format char '%' must be represented '%%'
disc_template =  new/%%A/%%y - %%d/%%A - %%d
# ...

Running uninstalled

To make it easier for developers, you can run whipper straight from the source checkout:

python2 -m whipper -h

Logger plugins

Whipper allows using external logger plugins to customize the template of .log files.

The available plugins can be listed with whipper cd rip -h. Specify a logger to rip with by passing -L loggername:

whipper cd rip -L eac

Whipper searches for logger plugins in the following paths:

$XDG_DATA_HOME/whipper/plugins
Paths returned by the following Python instruction:

[x + '/whipper/plugins' for x in site.getsitepackages()]
If whipper is run in a virtualenv, it will use these alternative instructions (from distutils.sysconfig):
- get_python_lib(plat_specific=False, standard_lib=False, prefix='/usr/local') + '/whipper/plugins'
- get_python_lib(plat_specific=False, standard_lib=False) + '/whipper/plugins'

On a default Debian/Ubuntu installation, the following paths are searched by whipper:

$HOME/.local/share/whipper/plugins
/usr/local/lib/python2.7/dist-packages/whipper/plugins
/usr/lib/python2.7/dist-packages/whipper/plugins

Official logger plugins

I suggest using whipper's default logger unless you've got particular requirements.

whipper-plugin-eaclogger - a plugin for whipper which provides EAC style log reports

License

Licensed under the GNU GPLv3 license.

Copyright (C) 2009 Thomas Vander Stichele
Copyright (C) 2016-2018 The Whipper Team: JoeLametta, Frederik Olesen,
			Samantha Baldwin, Merlijn Wajer, et al.

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, write to the Free Software Foundation,
Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA

Contributing

Make sure you have the latest copy from our git repository. Where possible, please include tests for new or changed functionality. You can run tests with python -m unittest discover from your source checkout.

Bug reports & feature requests

Please use the issue tracker to report any bugs or to file feature requests.

When filing bug reports, please run the failing command with the environment variable WHIPPER_DEBUG set. For example:

WHIPPER_DEBUG=DEBUG WHIPPER_LOGFILE=whipper.log whipper offset find
gzip whipper.log

And attach the gzipped log file to your bug report.

Without WHIPPER_LOGFILE set, logging messages will go to stderr. WHIPPER_DEBUG accepts a string of the default python logging levels.

Credits

Thanks to:

And to all the contributors.

sahwar / whipper Goto Github PK

whipper's Introduction