#+TITLE: scribbu
#+DESCRIPTION: The extensible tool for tagging your music collection
#+DATE: <2024-10-09 Wed 17:00>
#+AUTHOR: sp1ff
#+EMAIL: sp1ff@pobox.com
#+AUTODATE: t
#+OPTIONS: toc:nil org-md-headline-style:setext *:t ^:nil

* Introduction

scribbu is a C++ library & associated command-line tool for working with [[http://id3.org][ID3]] tags. It was born when I retired my last Windows machine & could no longer use [[https://en.wikipedia.org/wiki/Winamp][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 [[https://www.gnu.org/software/guile/][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.
    #+BEGIN_SRC bash
        srcibbu -e '(with-track-in <path> (lambda (v2 pth v1) (format #t "~s: ~a\n" pth v1)))'
    #+END_SRC

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

  - as part of a script

    #+BEGIN_SRC bash
        #!/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))
				 ...
    #+END_SRC

  - 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:

    #+BEGIN_EXAMPLE
	    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"
    #+END_EXAMPLE

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 [[https://www.unwoundstack.com/doc/scribbu/curr][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 [[https://github.com/sp1ff/scribbu/releases][here]] and include Autotools distributions as well as binary packages for Arch & Debian.

* Prerequisites

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

  - [[https://www.boost.org][boost.org]] 1.58 or later
  - [[https://www.gnu.org/software/guile/][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=:

#+BEGIN_SRC bash
git clone https://github.com/sp1ff/scribbu.git
cd scribbu
./bootstrap
#+END_SRC

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

#+BEGIN_SRC bash
cd /tmp
mkdir build && cd build
.../scribbu/configure CXXFLAGS="-g -O0"
make check
#+END_SRC

* 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.