Introduction

I've ripped over two thousand CDs with abcde and along the way have fixed bugs, had a go at some workflow enhancements and introduced new features.

This is a fork of abcde. At the time of forking, abcde version 2.9.3 was the most recent download and was released on February 5th 2019. The starting point for this GitHub repository was 2.9.4-DEV with the last upstream commit dated 2021-02-14.

Now up to version 2.13.2 released on 7th November, 2026. I've been actively maintaining this fork of abcde since 5th June, 2024.

My goals are to:

• maintain abcde as a great automated or interactive audio CD encoder (aka "ripper")
• streamline the workflow and automation
• tag the audio tracks with as much information from the read process as possible (CD Table Of Contents (TOC), CUE sheets, CD-TEXT: complete CD metadata)
• implement/facilitate changes that are standards compliant
  • metadata standards for flac and other output formats, eg tags
  • CDDB and CUE file formats
  • defacto standards implemented by music players and catalogues, eg Musicbrainz tags
• provide ongoing maintenance so that abcde continues to work in the future

I mostly focus on flac but am considerate to not break existing functions such as reading once and encoding to multiple output formats in one pass.

Whole disk flac archives are now a format of focus due to their ability to capture an entire album, artwork and other metadata in a single file. More music players are now able to handle them correctly. Whole disk flacs can achieve the goal: One disc = one file

Please take a moment and tell us about your audio CD ripping experience and environment in the abcde user poll

Submitting issues and pull requests

Your feedback is very welcome. Please open an issue and I will read it. Let me know about your environment (operating system name and version, abcde version, abcde config file, abcde command line, the details of the audio CD that you are testing with (Discogs links are my preference).

I will look at pull requests respectfully but please submit code that you have run real live tests by ripping CDs. It is also helpful to provide URL references to standards or discussions when the pull request changes files on disk (eg metadata formats, music player compatibility)

All changes committed to this repository are tested before I commit them so I encourage you to run the latest code and provide feedback.

Features of this fork

Enhancements

• Read hidden track one audio tracks, if they exist
• Rip one track CDs (a bug in older versions prevented ripping discs with only 1 track)
• Greatly improved handling of CD sets:
  • The -W option is expanded to optionally add the total number of discs in the set. These details are recorded in the FLAC metadata tags DISCNUMBER and DISCTOTAL
  • Create playlist defaults to append instead of erase when the disc number is greater than 1
• Greatly improved handling of FLACs:
  • Add the MUSICBRAINZ MBIDs as tags
  • comments added on the command line with the -w option are designated as USERCOMMENTS and added to every track
  • CDDB extended data (EXTD) are passed through to FLAC COMMENT tags and added to every track
  • CDDB extended track data (EXTTn) is passed through to FLAC COMMENT tags for the relevant track
    • see https://gnudb.org/gnudbformat.php for Gnudb xmcd file format
  • Configurable FLAC ALBUMARTIST="Various Artists" metadata tag for multi-artist CDs
  • Enhanced whole disk flac archives with hidden track one audio and cue sheet with track titles
• Improved handling of cover art:
  • Album art selection and handling improvements
  • Define a default local album art directory/file location. If the album artwork download fails or the user chooses to overide the downloaded art, abcde will look for ALBUMARTDIR/ALBUMARTFILE before asking the user to manually enter the filename
  • Cover art is now available for use in multiple output formats (eg flac and mp3) in the same pass
• Created munge helper functions:
  • munge_fs-safe: remove characters that are not Windows and Linux file-system safe or sane
  • munge_Startcase: capitalise the first letter of every word
  • munge_unicodetoascii: transliterate Unicode to ASCII
  • munge_collapsewhitespace: replace multiple spaces with a single space
  • munge_simplify_punctuation: helper function to standardise unicode and ascii punctuation like apostrophe's and ellipsis
  • mungecddb: this is a pre-processor for looked up CDDB entries to apply local standards, such as capitalisation, removing excess spaces, line endings and punctuation
  • Add new config examples to use munge helper functions
• Generate a MusicBrainz URL that can be used to submit CD Table of Contents (TOC) if they are not found during the lookup
• Interactive interface improvements
  • show release year in cddb entry display
  • provide help option in cddb entry selection
    • explain how to diff (show the differences between two CDDB entries)
    • provide option to re-list available entries
• Archive mode
  • aims to preserve on disc metadata and details from the encoding process
  • writes the raw CD TOC data to the output directory
  • if cd-text has been looked for and found, it is written to the output directory
  • planned features include:
    • comprehensive on-disc metadata collection
    • directory listings of Enhanced CD
    • save data sessions to iso format

Bug fixes, patches and pull requests

• applied many patches from GitHub issues and pull requests
• applied many patches from bug reports: https://abcde.einval.com/bugzilla/query.cgi
• applied many patches from the mailing list: https://lists.einval.com/cgi-bin/mailman/listinfo/abcde-users

Todo

• Move these Todo items from here to GitHub enhancement Issues
• Improve CDDB selection dialogue:
  • improve the diff display: show cddb entry number and source (ie musicbrainz, cddb, cd-text, local) in the header
  • highlight CDDB entries with extended info and provide a way to view it (ie -s 'genre,year,ext')
  • make the CDDB entry choice prompt for locally cached (line ~2618) the same as in do_cddbedit (line ~3031)
  • add q quit immediately and x exit cleanly options
• Create a completion report a la rubyrip that shows if any tracks have read errors (adding the -l option to cdparanoia logs the progress bar that can be used for analysis and reporting)
• Review playlist generation
  • add a new playlist option: s sort. Keep the existing playlist, append the new tracks, sort numerically, replace the existing playlist with the new sorted playlist. This new option will permit ripping discs in sets in any order and in parallel. Currently discs in sets need to be ripped sequentially for the generated playlist to make sense.
  • or just make a new playlist every time from the files in the directory sorted numerically - this makes most sense and represents current on-disk truth

Known issues

• See Issues with the bug label

Installation Instructions

• The latest package or source code can be found here: https://github.com/poddmo/abcde/releases/latest
• See the Testing section below for configuration file and command line examples

Debian-based systems

• These instructions are for Debian, Ubuntu, Mint, Pop OS, Raspberry Pi OS and other Debian or Ubuntu-derived Linux distributions:
  • https://en.wikipedia.org/wiki/Category:Debian-based_distributions
  • https://en.wikipedia.org/wiki/Category:Ubuntu_derivatives

Package Installation

Install the distribution version of abcde first to pull in the recommended dependencies and be set up for converting to flac and mp3:

sudo apt install abcde bsd-mailx- ffmpeg flac eject eyed3 glyrc imagemagick mkcue

Then install my latest updated version from the github repo with all the bug fixes, workflow and metadata improvements:

wget https://github.com/poddmo/abcde/releases/download/2.13.2/abcde_2.13.2-1_all.deb
sudo dpkg -i abcde_2.13.2-1_all.deb

Build the package from source

Download the source, extract it, create a package from it and then install the fresh package:

wget -O abcde_2.13.2.tar.gz https://github.com/poddmo/abcde/archive/refs/tags/2.13.2.tar.gz
tar zxf abcde_2.13.2.tar.gz
cd abcde-2.13.2
dpkg-buildpackage -us -uc --build=binary
cd ..
sudo dpkg -i abcde_2.13.2-1_all.deb

Arch Linux

An AUR is available: https://aur.archlinux.org/packages/abcde-poddmo-git

Red Hat-based Distributions

Sorry we don't have a package or specific instructions yet. If you're handy at building rpm packages, a pull request would be greatly appreciated by this Debian-derived bloke. The easiest way to get started is usually to install abcde from your distribution and then replace abcde, abcde-musicbrainz-tool and abcde.1 with the latest version from this repository.

NixOS

There is a Nix flake, package, and NixOS module. See the NixOS README for details. Please review, test and comment.

Install from source

wget -O abcde_2.13.2.tar.gz https://github.com/poddmo/abcde/archive/refs/tags/2.13.2.tar.gz
tar zxf abcde_2.13.2.tar.gz
cd abcde-2.13.2
chmod 755 abcde abcde-musicbrainz-tool cddb-tool
sudo cp abcde abcde-musicbrainz-tool cddb-tool /usr/local/bin
sudo cp abcde.1 cddb-tool.1 /usr/local/share/man/man1/

There will be dependencies that you will need to satisfy so I suggest to begin trying to rip a CD and install those that make themselves known. For reference, these are the dependency details from the Debian package configuration:

Depends: cd-discid, wget, cdparanoia | icedax, vorbis-tools (>= 1.0beta4-1) | lame | flac | speex | musepack-tools | opus-tools, libmusicbrainz-discid-perl, libwebservice-musicbrainz-perl (>= 1.0.4-1.1), sensible-utils
Recommends: vorbis-tools, libdigest-sha-perl, bsd-mailx, glyrc, imagemagick
Suggests: eject, distmp3, id3 (>= 0.12), id3v2, eyed3 (<< 0.7~), normalize-audio, vorbisgain, mkcue, mp3gain, atomicparsley

You can also run it from the source directory:

wget -O abcde_2.13.2.tar.gz https://github.com/poddmo/abcde/archive/refs/tags/2.13.2.tar.gz
tar zxf abcde_2.13.2.tar.gz
cd abcde-2.13.2
./abcde -V -G

NixOS

A Nix flake is provided. See nixos/readme-nixos.md for install instructions, the NixOS module and package usage.

Configuration

• Configuration is a process you will refine over time as you rip more CDs and play the files on a variety of music players
• I recommend to get started, just put a disc in your optical drive and type:

abcde -V -G -o flac -d /dev/sr0

This will rip a CD to flac and retrieve the cover art. Then you'll start to get an idea of what to set in the configuration file

• I don't recommend using the system-wide configuration file: /etc/abcde.conf
• Use the default per-user configuration: $HOME/.abcde.conf or specify your own configuration file location with the -c command line option
• Use the system config file as a starting template:

cp /etc/abcde.conf $HOME/.abcde.conf

and look at my configuration file below.

Example Command lines

(1) abcde -V -G -o flac -d /dev/sr0
(2) abcde -V -G -o flac,mp3 -d /dev/sr0
(3) abcde -V -G -o flac -d /dev/sr0 -W 1,2
(4) abcde -V -o flac -d /dev/sr1 -W 2,2

• Line 1: Verbose rip (-V), download albumart (-G), output to FLAC (-o flac) from CDROM drive (-d /dev/sr0)
• Line 2: Verbose rip (-V), download albumart (-G), output to FLAC and MP3 (-o flac,mp3) from CDROM drive (-d /dev/sr0)
• Line 3: The CD in my first optical drive (-d /dev/sr0) is the first disc of a set (-W 1,2)
• Line 4: I only try to download albumart for the first disc in a set. Disc 2 of 2 (-W 2,2) is in my second optical drive (-d /dev/sr1)

Configuration file example

This is my $HOME/.abcde.conf. The FLACOPTS will only work with flac 1.5.0 or later.

export LC_ALL=en_AU.UTF-8
ACTIONS=cddb,cue,read,encode,tag,move,clean
READHIDDENTRACK=y
MAXPROCS=2                              # Run a few encoders simultaneously
PADTRACKS=y                             # Makes track numbers 01 02 not 1 2
EXTRAVERBOSE=0                          # Useful for debugging
COMMENT="ABCDE=${VERSION}"              # Place a comment...'
EJECTCD=y                               # Please eject cd when finished :-)
DIFFOPTS=-y
PAGEROPTS="-fM"
ALBUMARTFILE='cover.jpg'
ALBUMARTDIR="${HOME}/Music"
OVERRIDEALBUMARTDOWNLOAD=y
ANYASCIIBIN="$HOME/bin/anyascii"
ARCHIVEMODE=y
LOWDISK=n
CDDBMETHOD=musicbrainz,cdtext,cddb
CDDBCOPYLOCAL="y"
CDDBLOCALDIR="$HOME/.cddb"
CDDBLOCALRECURSIVE="y"
CDDBUSELOCAL="y"
CDDBURL="http://gnudb.gnudb.org/~cddb/cddb.cgi"
[email protected]
NOSUBMIT=n
HELLOINFO="abcde-${VERSION}@poddmo.noreply.github.com"
HTTPGETOPTS="-q -nv --timeout=30 --tries=2 -e timestamping=off -O -"
FLACENCODERSYNTAX=flac
FLAC=flac
FLACOPTS='-s -8pV -j3'
FLACTAGSTARTCASE=y
FLACTAGALBUMARTISTTAGNAME="ALBUMARTIST"
FLACTAGALBUMARTISTVALUE="Various Artists"
AACENCODERSYNTAX=ffmpeg
FFMPEGENCOPTS="-c:a aac -b:a 192k"
OUTPUTTYPE="flac"
CDROMREADERSYNTAX=cdparanoia
CDPARANOIA=cdparanoia
CDPARANOIAOPTS="-L --never-skip=2"
CDDISCID=cd-discid
MKCUE=abcde.mkcue
CUEREADERSYNTAX=abcde.mkcue
OUTPUTDIR="$HOME/Music"
OUTPUTFORMAT='${ARTISTFILE}/${ALBUMFILE}/${TRACKNUM}.${TRACKFILE}'
VAOUTPUTFORMAT='Various-${ALBUMFILE}/${TRACKNUM}.${ARTISTFILE}-${TRACKFILE}'
ONETRACKOUTPUTFORMAT='${ARTISTFILE}/${ARTISTFILE}-${ALBUMFILE}${DISCNUMBER:+$(printf -- "-Disc-%02d\\n" "$DISCNUMBER")}'
VAONETRACKOUTPUTFORMAT='Various-${ALBUMFILE}/Various-${ALBUMFILE}${DISCNUMBER:+$(printf -- "-Disc-%02d\\n" "$DISCNUMBER")}'
PLAYLISTFORMAT='${ARTISTFILE}/${ALBUMFILE}/${ARTISTFILE} - ${ALBUMFILE}.m3u'
VAPLAYLISTFORMAT='Various-${ALBUMFILE}/${ALBUMFILE}.m3u'
DOSPLAYLIST=n
IDENTIFY='magick identify'
CONVERT='magick convert'
DISPLAYCMD='magick display'
DISPLAYCMDOPTS="-resize 900x900 -title abcde_album_art"
CONVERTOPTS="-resize 1200x1200>"
ALBUMARTALWAYSCONVERT="y"
munge_simplify_punctuation ()
{
        # list of targeted punctuation:
        # RIGHT SINGLE QUOTATION MARK, HORIZONTAL ELLIPSIS,
        # HYPHEN, EN DASH
        sed -e "s/\xe2\x80\x99/\'/g" \
            -e "s/\xe2\x80\x9c/\"/g" \
            -e "s/\xe2\x80\x9d/\"/g" \
            -e "s/\xe2\x80\xa6/.../g" \
            -e "s/\xe2\x80\x90/-/g" \
            -e "s/\xe2\x80\x93/-/g" \
            -e 's/\r//g'
}
mungefilename ()
{
        echo "$@" | \
                munge_unicodetoascii | \
                munge_fs-safe | \
                munge_collapsewhitespace | \
                sed -e 's/\.*$//'
}
mungecddb ()
{
        echo "$@" | \
                munge_collapsewhitespace | \
                munge_simplify_punctuation | \
                munge_Startcase
}