scribbu

Introduction

scribbu is a C++ library & associated command-line tool for working with ID3 tags. It was born when I retired my last Windows machine & could no longer use Winamp to manage my library of digital music. The scribbu library offers classes & methods for reading, editing & writing ID3v1 & ID3v2 tags. The scribbu program provides assorted sub-commands for working with ID3-tagged files (e.g. re-naming files based on their tags), but its real power lies in its embedded Scheme interpreter in which scribbu library features are exported as a Scheme module (on which more below).

What Can You Do With It?

scribbu can be invoked in a few ways:

• with a sub-command & relevant options & arguments; i.e. scribbu SUB-COMMAND OPTION.... scribbu implements the following sub-commands:

• scribbu dump will write the contents of the ID3 tags found in one or more files to stdout
  • scribbu rename will rename one or more files based on the content of their ID3 tags; e.g. scribbu rename -t %A-%T.mp3 *.mp3 will rename all the files matching *.mp3 to <artist>-<title>.mp3 where “artist” and “title” are derived from their ID3 tags (if any).
  • scribbu report will generate a report listing ID3 attributes on one or more files on stdout. CSV & TDF formats are supported currently (on the basis that there are better querying/reporting tools out there already; they can just import the .csv or .tdf & do better than scribbu would)
• scribbu popm will create or update popularimeter & playcount frames. This can be used to keep up the play count, or set a rating.
• scribbu text will create, update, or delete various text frames
  • scribbu genre will update the genre-related fields of ID3v1 and/or -v2 tags
  • scribbu m3u will print M3U entries
  • scribbu encodings will print a list of all the text encodings scribbu supports
  • with a Scheme expression (-e, --expression) or Scheme file (-f, --file). E.g.

    srcibbu -e '(with-track-in <path> (lambda (v2 pth v1) (format #t "~s: ~a\n" pth v1)))'
            

    will list (recursively) the ID3v1 tag for all files in <path>.

  • as part of a script

          #!/usr/local/bin/scribbu \
    		--debug -L /home/sp1ff/share/guile/site -e main -s
    		!#
    		;;; coding: utf-8
    
    		(use-modules (ice-9 format)
    		             (ice-9 getopt-long)
    		             (oop goops)
    		             (scribbu))
    
    		(setlocale LC_ALL "")
    
    		(define (main args)
    		  (let* ((options-spec '((help          (single-char #\h) (value #f))
    		                         (version       (single-char #\v) (value #f))
    								 ...))
    		         (options  (getopt-long args options-spec))
    		         (help     (option-ref options 'help   #f))
    				 ...
            

  • with no arguments at all. In this case, scribbu will drop into a Scheme shell in which the user can evaluate arbitrary Scheme expressions. For instance:

    	    scribbu
    		scribbu 0.7.1
    		Copyright (C) 2017-2024 Michael Herstine <sp1ff@pobox.com>
    
    		You are in the Guile REPL; in your shell, type `info scribbu' for documentation.
    
    		GNU Guile 2.2.0
    		Copyright (C) 1995-2017 Free Software Foundation, Inc.
    
    		Guile comes with ABSOLUTELY NO WARRANTY; for details type `,show w'.
    		This program is free software, and you are welcome to redistribute it
    		under certain conditions; type `,show c' for details.
    
    		Enter `,help' for help.
    		scheme@(guile-user)> (use-modules (scribbu))
    		scheme@(guile-user)> (use-modules (oop goops))
    		scheme@(guile-user)> (define tags (read-tagset "<path>"))
    		scheme@(guile-user)> (length tags)
    		$1 = 1
    		scheme@(guile-user)> (car tags)
    		$2 = (#<<id3v2-tag> 2cd4210> 3)
    		scheme@(guile-user)> (define tag (caar tags))
    		scheme@(guile-user)> (define artists (get-frames tag 'artist-frame))
    		scheme@(guile-user)> (length artists)
    		$5 = 1
    		scheme@(guile-user)> (define A (car artists))
    		scheme@(guile-user)> (slot-ref A 'text)
    		$6 = "The Pogues"
            

Any sub-command can be invoked with --help or -h for more information. Use the --info option to display the Info manual.

Full documentation is distributed with scribbu in Texinfo format. The HTML version is avaiable here.

Downloading

You can find the project at https://github.com/sp1ff/scribbu. You can clone it by typing `git clone https://github.com/sp1ff/scribbu.git`. Releases may be found here and include Autotools distributions as well as binary packages for Arch & Debian.

Prerequisites

scribbu is supported on Linux & MacOS. It depends upon:

• boost.org 1.58 or later
• Gnu Guile 2.2 or later
• libffi
• openssl
• zlib

Installing

scribbu is distributed as an Autotools source distribution, so installation is accomplished via the usual “configure, make, make install” incantations. General instructions may be found in INSTALL.

Begining with scribbu 0.7.1, binary packages for Debian & Arch are also available.

Patches, suggestions & bug reports are welcome.

Development

You can obtain the code by doing git clone https://github.com/sp1ff/scribbu.git:

git clone https://github.com/sp1ff/scribbu.git
cd scribbu
./bootstrap

I like to build in a separate directory (AKA VPATH build):

cd /tmp
mkdir build && cd build
.../scribbu/configure CXXFLAGS="-g -O0"
make check

Status & Roadmap

The MP3 format is showing its age; Fraunhofer IIS announced in 2017 that it was ending its licensing programs for MP3. AAC is now the standard for digital music.

And yet, I have several thousand mp3 files in my personal library. Since both MP3 and AAC are lossy formats, transcoding them to AAC would not lead to good results even if I were inclined to do the work. The original sources of many of the .mp3s have been lost, so re-encoding to AAC is not possible.

Perhaps scribbu will support AAC in the future, but regardless it seems that MP3 & ID3 will be relevant to my musical life for some time. I wrote this tool to help me manage them, and I offer it to anyone else in the same position: if you need to manage ID3-tagged mp3 files, and especially if you enjoy hacking in LISP and/or C++, I hope you find scribbu useful and enjoyable.