Whipper

Whipper is a Python 3 (3.6+) CD-DA ripper based on the morituri project (CDDA ripper for *nix systems aiming for accuracy over speed). It started just as a fork of morituri - which development seems to have halted - merging old ignored pull requests, improving it with bugfixes and new features. Nowadays whipper's codebase diverges significantly from morituri's one.

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
  1. Required dependencies
  2. Optional dependencies
  3. Fetching the source code
  4. Finalizing the build
• Usage
• Getting started
• Configuration file documentation
• Running uninstalled
• Logger plugins
  • Official logger plugins
• License
• Contributing
  • Developer Certificate of Origin (DCO)
    • DCO Sign-Off Methods
  • 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 whipperteam/whipper

Please note that, right now, Docker Hub only builds whipper images for the amd64 architecture: if you intend to use them on a different one, you'll need to build the images locally (as explained below).

Building the Docker image locally is required in order to make it work on Arch Linux (and its derivatives) because of a group permission issue (for more details see issue #499).

To build the Docker image locally just issue the following command (it relies on the Dockerfile included in whipper's repository):

optical_gid=$(getent group optical | cut -d: -f3) uid=$(id -u) docker build --build-arg optical_gid --build-arg uid -t whipperteam/whipper .

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

alias whipper="docker run -ti --rm --device=/dev/cdrom \
    --mount type=bind,source=${HOME}/.config/whipper,target=/home/worker/.config/whipper \
    --mount type=bind,source=${PWD}/output,target=/output \
    whipperteam/whipper"

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

Essentially, what this does is to map the /home/worker/.config/whipper and ${PWD}/output (or whatever other directory you specified) on your host system to locations inside the Docker container where the files can be written and read. These directories need to exist on your system before you can run the container:

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

Please note that the example alias written above only provides access to a single disc drive: if you've got many you will need to customise it in order to use all of them in whipper's Docker container.

Finally, you can test the correct installation as such:

whipper -v
whipper drive list

Package

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

NOTE: if installing whipper from an unofficial repository please 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 versions ≥ 10.2+0.94+2
  • The package named libcdio-utils, available on older Debian and Ubuntu versions, is affected by a bug: it doesn't include the cd-paranoia binary (needed by whipper). Starting with Debian bullseye (11) and Ubuntu focal (20.04), a separatecd-paranoia package is available which provides the aforementioned binary. For more details on this issue, please check the relevant bug reports: #888053 (Debian), #889803 (Debian) and #1750264 (Ubuntu).
• cdrdao, for session, TOC, pre-gap, and ISRC extraction
• musicbrainzngs, for metadata lookup
• mutagen, for tagging support
• setuptools, for installation, plugins support
• 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 the most recent pycdio version with the corresponding libcdio release or, if stuck on old pycdio versions, 0.20/0.21 with libcdio ≥ 0.90 ≤ 0.94. All other combinations won't probably work.
• discid, for calculating Musicbrainz disc id.
• ruamel.yaml, for generating well formed YAML report logfiles
• libsndfile, for reading wav files
• flac, for reading flac files
• sox, for track peak detection
• git or mercurial
  • Required either when running whipper without installing it or when building it from its source code (code cloned from a git/mercurial repository).

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

• cd-paranoia
• cdrdao
• libsndfile
• flac
• sox
• git or mercurial
• libdiscid

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

pip3 install -r requirements.txt

Optional dependencies

• Pillow, for compl