benya/whipper-gui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Invoke whipper by its name + Readme rewrite (#70)

Browse Source 
* Whipper is now invoked by its name ("whipper") instead of "rip"
* README has been rewritten to provide a better experience and updated information
This commit is contained in:
JoeLametta
2016-11-08 22:31:13 +01:00
committed by GitHub
parent 39aa68909e
commit 2d7692cb22
2 changed files with 251 additions and 195 deletions
Download Patch File Download Diff File Expand all files Collapse all files

444
README.md
View File

@@ -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)

2
setup.py
View File

@@ -10,7 +10,7 @@ setup(
packages=find_packages(),
entry_points = {
'console_scripts': [
'rip = morituri.rip.main:main'
'whipper = morituri.rip.main:main'
]
}
)