diff --git a/README.md b/README.md index 8b16052..1192940 100644 --- a/README.md +++ b/README.md @@ -1,235 +1,291 @@ -FORK INFORMATION ---------- -This branch is very close to morituri's master one (internal morituri references are still unchanged). As a starting point, I've just merged the following commits: -- [#79](https://github.com/thomasvs/morituri/issues/79) -- [#92](https://github.com/thomasvs/morituri/issues/92) -- [#109](https://github.com/thomasvs/morituri/issues/109) -- [#133](https://github.com/thomasvs/morituri/issues/133) (with custom `.travis.yml`) -- [#137](https://github.com/thomasvs/morituri/issues/137) -- [#139](https://github.com/thomasvs/morituri/issues/139) -- [#140](https://github.com/thomasvs/morituri/issues/140) -- [#141](https://github.com/thomasvs/morituri/issues/141) +# Whipper + [![License: GPLv3+](https://img.shields.io/badge/license-GPLv3+-blue.svg)](https://github.com/JoeLametta/whipper/blob/readme-rewrite/COPYING) [![Build Status](https://travis-ci.org/JoeLametta/whipper.svg?branch=master)](https://travis-ci.org/JoeLametta/whipper) [![Current version number](https://img.shields.io/badge/version-0.3.0-red.svg)](https://github.com/JoeLametta/whipper) [![IRC](https://img.shields.io/badge/irc-%23whipper%40freenode-008000.svg)](https://webchat.freenode.net/?channels=%23whipper) [![GitHub Stars](https://img.shields.io/github/stars/JoeLametta/whipper.svg)](https://github.com/JoeLametta/whipper/stargazers) [![GitHub Issues](https://img.shields.io/github/issues/JoeLametta/whipper.svg)](https://github.com/JoeLametta/whipper/issues) -And changed the default logger to [morituri-yamllogger](https://github.com/JoeLametta/morituri-yamllogger)'s one. +Whipper is a Python 2 CD-DA ripper, fork of the morituri project (_CDDA ripper for *nix systems aiming for accuracy over speed_). It improves morituri which development seems to have halted merging old ignored pull requests, improving it with bugfixes and new features. -In order to track whipper's current development it's better to check its commit history (README *needs* to be updated). +Whipper is developed and tested _only_ on Linux distributions but _should_ work fine on other *nix OSes too. -**WARNING:** As whipper is still under heavy development sometimes I will force push (`--force-with-lease`) to the non master branches. +In order to track whipper's current development it's advised to check its commit history (README **isn't** still complete). -BACKWARD INCOMPATIBLE CHANGES ---------- -* Whipper has adopted new config/cache/state file paths +## Table of content +- [Rationale](#rationale) +- [Features](#features) +- [Release history](#release-history) +- [Installation](#installation) + 1. [Required dependencies](#required-dependencies) + 2. [Fetching the source code](#fetching-the-source-code) + 3. [Building the bundled dependencies](#building-the-bundled-dependencies) + 4. [Finalizing the installation](#finalizing-the-installation) +- [Usage](#usage) +- [Getting started](#getting-started) +- [Configuration file documentation](#configuration-file-documentation) +- [Backward incompatible changes](#backward-incompatible-changes) +- [Running uninstalled](#running-uninstalled) +- [Logger plugins](#logger-plugins) +- [License](#license) +- [Contributing](#contributing) + - [Bug reports & feature requests](#bug-reports--feature-requests) + - [Developing](#developing) +- [Credits](#credits) +- [Links](#links) + +## Rationale +For a detailed description, see morituri's wiki page: [The Art of the Rip]( +https://web.archive.org/web/20160528213242/https://thomas.apestaart.org/thomas/trac/wiki/DAD/Rip). + +## Features +* Detects correct sample read offset and ability to defeat cache of drives +* Performs Test & Copy rips +* Verifies rip accuracy using the [AccurateRip database](http://www.accuraterip.com/) +* Uses [MusicBrainz](https://musicbrainz.org/doc/About) for metadata lookup +* Supports reading the [pre-emphasis](http://wiki.hydrogenaud.io/index.php?title=Pre-emphasis) flag embedded into some CDs (and correctly tags the resulting rip) +* Detects and rips non digitally silent [Hidden Track One Audio](http://wiki.hydrogenaud.io/index.php?title=HTOA) (HTOA) +* Provides batch ripping capabilities +* Provides templates for file and directory naming +* Supports lossless encoding +* Allows retagging of already completed rips +* Allows extensibility through external logger plugins + +## Release history + +- 0.3.0 - SoX is now used for peak detection. Migration to setuptools +- 0.2.4 - First tagged release after morituri fork (includes "new config/cache/state file paths" backward incompatible change) + +## Installation +With the exception of an [AUR package for Arch Linux](https://aur.archlinux.org/packages/whipper-git), whipper isn't currently available in a prepackaged form so, in order to use it, it must be built from its source code. + +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: +- [cdparanoia](https://www.xiph.org/paranoia/), for the actual ripping +- [cdrdao](http://cdrdao.sourceforge.net/), for session, TOC, pre-gap, and ISRC extraction +- [GStreamer](https://gstreamer.freedesktop.org/) and its python bindings, for encoding (it's going to be removed soon™) + - `gstreamer0.10-base-plugins` >= **0.10.22** for appsink + - `gstreamer0.10-good-plugins` for wav encoding (it depends on the Linux distro used) +-[python-musicbrainzngs](https://github.com/alastair/python-musicbrainzngs), for metadata lookup +- `python-setuptools`, for installation, plugins support +- [python-cddb](http://cddb-py.sourceforge.net/), for showing but not using metadata if disc not available in the MusicBrainz DB +- [pycdio](https://pypi.python.org/pypi/pycdio/) (to avoid bugs please use `pycdio` **0.20** & `libcdio` >= **0.90** or, with previous `libcdio` versions, `pycdio` **0.17**), for drive identification + - Required for drive offset and caching behavior to be stored in the configuration file +- [libsndfile](http://www.mega-nerd.com/libsndfile/), for reading wav files +- [flac](https://xiph.org/flac/), for reading flac files +- [sox](http://sox.sourceforge.net/), for track peak detection + +### 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`) + +```bash +git clone -b master --single-branch https://github.com/JoeLametta/whipper.git +cd whipper +# fetch bundled python dependencies +git submodule init +git submodule update +``` + +### 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` + +```bash +cd src +make +sudo make install +cd .. +``` + +### Finalizing the installation +Install whipper: `python2 setup.py install` + +## 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 whipper command. + +~~Check the man page (`whipper(1)`) for more information.~~ (currently not available as whipper's documentation is planned to be migrated to [Sphinx](http://www.sphinx-doc.org)). + +## Getting started +The simplest way to get started making accurate rips is: + +1. Pick a relatively popular CD that has a good change of being in the AccurateRip database +2. Analyze the drive's caching behavior + + `whipper drive analyze` + +3. Find the drive's offset. + + Consult the [AccurateRip's CD Drive Offset database](http://www.accuraterip.com/driveoffsets.htm) for your drive. Drive information can be retrieved with `whipper drive list`. + + `whipper offset find -o OFFSET` + + 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 = 42` in `whipper.conf`. + + Offsets confirmed with `whipper offset find` are automatically written to the configuration file. + +4. Rip the disc by running + + `whipper cd rip` + +## Configuration file documentation +The configuration file is stored according to the [XDG Base Directory Specification]( +http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) +when possible. + +It lives in `$XDG_CONFIG_HOME/whipper/whipper.conf` (or `$HOME/.config/whipper/whipper.conf`). + +The configuration file follows python's [ConfigParser](https://docs.python.org/2/library/configparser.html) syntax. + +The possible sections are: + +- Main section: `[main]` + - `path_filter_fat`: whether to filter path components for FAT file systems + - `path_filter_special`: whether to filter path components for special characters + +- Drive section: `[drive:IDENTIFIER]`, one for each configured drive. All these values are probed by whipper and should not be edited by hand. + - `defeats_cache`: whether this drive can defeat the audio cache + - `read_offset`: the read offset of the drive + +- Rip command section: `[rip.COMMAND.SUBCOMMAND]`. Can be used to change the command options default values. + +Example section to configure `whipper cd rip` defaults: + +``` +[rip.cd.rip] +unknown = True +output_directory = ~/My Music +track_template = new/%%A/%%y - %%d/%%t - %%n +disc_template = %(track_template)s +profile = flac +``` + +Note: to get a literal `%` character it must be doubled. + +## Backward incompatible changes +* Whipper executable name changed: from `rip` to `whipper` +* Whipper has adopted new config/cache/state file paths ([PR #42](https://github.com/JoeLametta/whipper/pull/42)) * Now always follows XDG specifications + * Paths used when XDG environment variables are available: * `$XDG_CONFIG_HOME/whipper` * `$XDG_CACHE_HOME/whipper` * `$XDG_DATA_HOME/whipper` + * Paths used when XDG environment variables are **NOT** available: * `$HOME/.config/whipper` * `$HOME/.cache/whipper` * `$HOME/.local/share/whipper` + * Configuration file information: * `.moriturirc`, `morituri.conf` aren't used anymore - * `$XDG_CONFIG_HOME/whipper/whipper.conf` (OR `$HOME/.config/whipper/whipper.conf`) + + * When XDG environment variables are available it's located in: + * `$XDG_CONFIG_HOME/whipper/whipper.conf` + + * When XDG environment variables are **NOT** available it's located in: + * `$HOME/.config/whipper/whipper.conf` + * Plugins folder path: - * `$XDG_DATA_HOME/whipper/plugins` (OR `$HOME/.local/share/whipper/plugins`) + * When XDG environment variables are available it's located in: + * `$XDG_DATA_HOME/whipper/plugins` -WHIPPER [![Build Status](https://travis-ci.org/JoeLametta/whipper.svg?branch=master)](https://travis-ci.org/JoeLametta/whipper) ---------- -whipper is a fork of the morituri project (CDDA ripper for *nix systems aiming for accuracy over speed). + * When XDG environment variables are **NOT** available it's located in: + * `$HOME/.local/share/whipper/plugins` -It improves morituri which development seems to have halted/slowed down merging old pull requests and improving it with bugfixes and new functions. - -If possible, I'll try to upstream the progress done here but, in the future, this may not be possible because of different project choices. - -RATIONALE ---------- -For a more detailed rationale, see morituri's wiki page ['The Art of the Rip']( -http://thomas.apestaart.org/thomas/trac/wiki/DAD/Rip). - -FEATURES --------- -* support for MusicBrainz for metadata lookup -* support for AccurateRip (V1) verification -* detects sample read offset and ability to defeat cache of drives -* performs test and copy rip -* detects and rips Hidden Track One Audio (only if not digitally silent) -* templates for file and directory naming -* support for lossless encoding and lossy encoding or re-encoding of images -* tagging using GStreamer, including embedding MusicBrainz id's -* retagging of images -* plugins for logging -* for now, only a command line client (rip) is shipped - -REQUIREMENTS ------------- -- cdparanoia, for the actual ripping -- cdrdao, for session, TOC, pregap, and ISRC extraction -- GStreamer and its python bindings, for encoding (it's going to be removed soon™) - - gstreamer0.10-base-plugins >= 0.10.22 for appsink - - gstreamer0.10-good-plugins for wav encoding (it depends on the Linux distro used) -- python musicbrainzngs, for metadata lookup -- python-setuptools, for plugin support -- python-cddb, for showing but not using disc info if not in MusicBrainz -- pycdio, for drive identification - - Required for drive offset and caching behavior to be stored in the config file -- libsndfile, for reading wav files -- flac, for reading flac files -- sox, for track peak detection - -GETTING WHIPPER ----------------- -If you are building from a source tarball or checkout, you can choose to -use whipper installed or uninstalled. - -- getting: - - Change to a directory where you want to put the whipper source code - (For example, `$HOME/dev/ext` or `$HOME/prefix/src`) - - source: download tarball, unpack, and change to its directory - - checkout: - - git clone -b master --single-branch https://github.com/JoeLametta/whipper.git - cd whipper - git submodule init - git submodule update - export PYTHON=$(which python2) - -- building bundled dependencies - -This is only needed if you do not have the 'accuraterip-checksum' package installed on -your system. whipper packages this for your convenience: - -You can edit the install path in `config.mk`. - - cd src - make - sudo make install - cd .. - -- installation - - python2 setup.py install - -RUNNING WHIPPER ----------------- -whipper currently only has a command-line interface called 'rip' - -rip is self-documenting. -`rip -h` gives you the basic instructions. - -rip implements a tree of commands; for example, the top-level 'changelog' -command has a number of sub-commands. - -Positioning of arguments is important; - - rip cd -d (device) rip - -is correct, while - - rip cd rip -d (device) - -is not, because the `-d` argument applies to the rip command. - -Check the man page (rip(1)) for more information. - - -RUNNING UNINSTALLED -------------------- +## Running uninstalled To make it easier for developers, you can run whipper straight from the source checkout: - ./autogen.sh - make - misc/morituri-uninstalled +```bash +python2 setup.py develop +whipper -h +``` -GETTING STARTED ---------------- -The simplest way to get started making accurate rips is: +## Logger plugins +Whipper supports using external logger plugins to write rip `.log` files. -- pick a relatively popular CD that has a good change of being in the - AccurateRip database -- find the drive's offset by running +List available plugins with `whipper cd rip -h`. Specify a logger to rip with by passing `-L loggername`: - rip offset find +```bash +whipper cd rip -L what +``` -- wait for it to complete; this might take a while -- optionally, confirm this offset with two more discs -- analyze the drive's caching behaviour +### Official loggers - rip drive analyze +* [morituri-yamlloger](https://github.com/JoeLametta/morituri-yamllogger) - default whipper logger, yaml format +* [morituri-eaclogger](https://github.com/JoeLametta/morituri-eaclogger) - eac-like logger attempting to maintain strict compatability with EAC +* [morituri-whatlogger](https://github.com/RecursiveForest/morituri-whatlogger) - eac-like logger containing the informational enhancements of the yamllogger, for use on [What.CD](https://what.cd) -- rip the disc by running one of +## License - rip cd rip # uses the offset from configuration file - rip cd rip --offset (the number you got before) # manually specified offset +Licensed under the [GNU GPLv3 license](http://www.gnu.org/licenses/gpl-3.0). -FILING BUGS ------------ -whipper's bugs are tracked using the repository issue section provided by GitHub. +``` +Copyright (C) 2009 Thomas Vander Stichele +Copyright (C) 2016 JoeLametta -morituri's bug tracker is at [http://thomas.apestaart.org/morituri/trac/]( -http://thomas.apestaart.org/morituri/trac/). -When filing bugs, please run the failing command with the environment variable -`RIP_DEBUG` set; for example: +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. - RIP_DEBUG=5 rip offset find > morituri.log 2>&1 - gzip morituri.log +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 + +### Bug reports & feature requests + +Please use the [issue tracker](https://github.com/JoeLametta/whipper/issues) to report any bugs or file feature requests. + +When filing bug reports, please run the failing command with the environment variable `RIP_DEBUG` set. For example: + +```bash +RIP_DEBUG=5 whipper offset find > whipper.log 2>&1 +gzip whipper.log +``` And attach the gzipped log file to your bug report. -KNOWN ISSUES ------------- -- no GUI yet -- only AccurateRip V1 CRCs are computed and checked against the online database -- `rip offset find` fails to delete the temporary .wav files it creates if an error occurs while ripping -- whipper only checks for the pre-emphasis flag in the TOC - - To improve the accuracy of the detection, the sub-channel data should be scanned too -- cd-text isn't read from the CD (useful when the CD informations are not available in the MusicBrainz DB) +### Developing -GOALS ------ -- quality over speed -- support one-command automatic ripping -- support offline ripping (doing metadata lookup and log rewriting later) - - separate the info/result about the rip from the metadata/file generation/... +Pull requests are welcome. -CONFIGURATION FILE ------------------- -The configuration file is stored according to [XDG Base Directory Specification]( -http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) -when possible. +**WARNING:** As whipper is still under heavy development sometimes I will force push (`--force-with-lease`) to the non master branches. -It lives in `$XDG_CONFIG_HOME/whipper/whipper.conf` (or `$HOME/.config/whipper/whipper.conf`) +## Credits -The configuration file follows python's ConfigParser syntax. +Thanks to: -The possible sections are: +- [Thomas Vander Stichele](https://github.com/thomasvs) +- [Joe Lametta](https://github.com/JoeLametta) +- [Merlijn Wajer](https://github.com/MerlijnWajer) +- [Samantha Baldwin](https://github.com/RecursiveForest) -- main section: [main] - - `path_filter_fat`: whether to filter path components for FAT file systems - - `path_filter_special`: whether to filter path components for special - characters - -- drive section: [drive:IDENTIFIER], one for each configured drive - All these values are probed by whipper and should not be edited by hand. - - `defeats_cache`: whether this drive can defeat the audio cache - - `read_offset`: the read offset of the drive - -- rip command section: [rip.COMMAND.SUBCOMMAND] - Can be used to change the command options default values. - -Example section to configure "rip cd rip" defaults: - - [rip.cd.rip] - unknown = True - output_directory = ~/My Music - track_template = new/%%A/%%y - %%d/%%t - %%n - disc_template = %(track_template)s - profile = flac - -Note: to get a literal '%' character it must be doubled. - -CONTRIBUTING ------------- -- Please send pull requests through GitHub. +## Links +You can find us and talk about the project on IRC: [freenode](https://webchat.freenode.net/?channels=%23whipper), **#whipper** channel. +- [What.CD thread (official)](https://what.cd/forums.php?action=viewthread&threadid=163034) +- [Reddit thread (unofficial)](https://www.reddit.com/r/linux/comments/53hyw1/github_joelamettawhipper_for_those_about_to_rip_a/) +- [Arch Linux whipper AUR package](https://aur.archlinux.org/packages/whipper-git/) +- [Unattended ripping using whipper (script by Thomas McWork)](https://github.com/thomas-mc-work/most-possible-unattended-rip) diff --git a/setup.py b/setup.py index 5d6c7ba..e34d508 100644 --- a/setup.py +++ b/setup.py @@ -10,7 +10,7 @@ setup( packages=find_packages(), entry_points = { 'console_scripts': [ - 'rip = morituri.rip.main:main' + 'whipper = morituri.rip.main:main' ] } )