kaworu / tagutil

scriptable music files tags tool and editor

Tagutil - CLI music files tags editor

tagutil(1) is a CLI tool to edit music file's tag. It aims to provide both an easy-to-script interface and ease of use interactively. Unlike most other tag tools out there, it fully support Vorbis Comments for both ogg/vorbis files and FLAC. Vorbis Comments are sexy, because you can set tags with any key/value without much restrictions (you can even have more than one value for a key).

Installation

Required Dependencies:

• pkg-config (build dep)
• cmake >= 2.6 (build dep)
• libyaml

Optionals Dependencies:

Optionals dependencies are detected by cmake. If you want to override the detection you can define WITHOUT_$LIB to avoid tagutil to link against $LIB.

• JSON: jansson JSON output format.
• FLAC: libFLAC If you want the flac files to be handled by libFLAC.
• OGGVORBIS: libvorbis If you want the ogg/vorbis files to be handled by libvorbis.
• TAGLIB: TagLib (>=1.5) Generic backend. Can handle a lot of different file type, but only a limited set of tags (artist, title, album, tracknumber, date, genre and comment).
• ID3V1: A stock ID3v1.1 TAG backend. ID3v1 is only used by very old mp3 files and has a lot of limitation including: limited set of tags, limited length (30 characters at the most), genre has to be part of the ID3v1 list (this backend support the Winamp extended list though) etc.

Building:

type make, it'll create the build/ directory and call cmake and make to configure and build tagutil. Or if you want to gives some arguments to cmake do (for example):

mkdir build && cd build
cmake -DWITHOUT_TAGLIB=yes ../src
make

Installation:

From Source:

build tagutil, then cd build && make install. You might need root access to call make install.

From Arch Linux:

A package is provided in the AUR. Use your favorite AUR helper to install it or download the AUR tarball and run makepkg -si to build and install the package.

Usage

reading tags

Use the print action. Since it is the default action, you can omit it from the command line:

% tagutil fearless.flac
# fearless.flac
---
- album: Meddle
- artist: Pink Floyd
- date: 1971
- title: Fearless
- tracknumber: 03
- genre: Progressive Rock

editing tags

There are commands for basic editing stuff like clear, add and set. If you need to do something more complex, the edit action let you use your favourite $EDITOR.

renaming files

One powerful feature of tagutil is the rename action. It rename the music files after inferring the new name from a rename pattern. In the rename pattern, %{name} is replaced by the name tag. You can also use the simpler form %name if the tag is only composed of alphanumeric characters. Example:

% tagutil -p rename:"[%date] %artist/%tracknumber - %title" fearless.flac
rename `fearless.flac' to `[1971] Pink Floyd/03 - Fearless.flac'? [y/n]

scripting

tagutil can easily be scripted. Basic scripts can use the editing actions while more complex scripts can use print, parse the output, do some modifications and then use load. There are two examples in the scripts/ directory:

• scripts/tagutil-track: this simple Perl script will take a tag name and some files as arguments, and will set 01 for the first file, 02 for the second and so on. Useful to set the track number of an album.
• scripts/tagutil-trim: this Ruby script is a bit more complex and is an example using YAML parsing. What is does is very simple though, it just trim every tags of leading and trailing white space(s).

full --help

% tagutil -h
tagutil v3.0

usage: tagutil [OPTION]... [ACTION:ARG]... [FILE]...
Modify or display music file's tag.

Options:
  -h     show this help
  -p     create destination directories if needed (used by rename)
  -F fmt use the fmt format for print, edit and load actions (see Formats)
  -Y     answer yes to all questions
  -N     answer no  to all questions

Actions:
  print            print tags (default action)
  backend          print the backend used (see Backend)
  clear:TAG        clear all tag TAG. If TAG is empty, all tags are cleared
  add:TAG=VALUE    add a TAG=VALUE pair
  set:TAG=VALUE    set TAG to VALUE
  edit             prompt for editing
  load:PATH        load PATH yaml tag file
  rename:PATTERN   rename to PATTERN

Formats:
         yml: YAML - YAML Ain't Markup Language
        json: JSON - JavaScript Object Notation

Backends:
     libFLAC: Free Lossless Audio Codec (FLAC) files format
   libvorbis: Ogg/Vorbis files format
      TagLib: various file format but limited set of tags

Test

% gem install bundler
% make test

LICENSE

It is a BSD 2-Clause license, see LICENSE.

tagutil's Issues

target for lexer and parser binary

There are already main() methods, but they're never compiled. It would be nice if they would be compiled if I_WANT_PARSER_BIN or so and then added as target for CMake.

segfault on print action.

Just trying to print tags from some mp3 and flac files gives me segmentation fault.
Using 3.0.1, happens with TagLib and libFLAC backends, cannot test libvorbis ATM.

Backtrace on TagLib:

#0  t_fttaglib_read (opaque=<optimized out>) at /.../tagutil/t_fttaglib.c:112
#1  0x0000000000406aa7 in t_tune_tags (tune=tune@entry=0x616210) at /../tagutil/t_tune.c:97
#2  0x0000000000405285 in t_action_print (self=<optimized out>, tune=0x616210) at /.../tagutil/t_action.c:429
#3  0x0000000000404b9a in main (argc=1, argv=0x7fffffffe380) at /.../tagutil/tagutil.c:139

Backtrace on libFLAC:

#0  0x0000000000405297 in t_action_print (self=<optimized out>, tune=0x616210) at /.../tagutil/t_action.c:433
#1  0x0000000000404b9a in main (argc=1, argv=0x7fffffffe380) at /.../tagutil/tagutil.c:139

Possibly important fact: It appears to work fine on -DCMAKE_BUILD_TYPE=Debug. I've compiled with -DCMAKE_BUILD_TYPE=RelWithDebInfo to get backtraces.

check the whole project using scan-build

Feature Request: Lyrics Tag, Extensible print

motivation:
I wish to use tagutil to preview music tags in my file manager. It would be great if we could format the output of print as such:

$ tagutil print 'track artist lyrics' 01-i-want-wind-to-blow.mp3
#no header for a single file
track: 01
artist: The Microphones
lyrics: The thunder clouds broke up
           The rain dried up
           The lightning let up
           The clacking shutters just shut up

also, IMO, I think print should not have "unnecessary" characters (e.g., - proceeding tags and ---) and only have relevant information to make it easy to be used in other contexts (preferably with calling grep/awk).

Support for id3v2 tags

Are they already supported?

ID3v1 & ID3v2 stock support

Better handling of backends error messages

stop with bool / stdbool.h

use sys/sbuf, get ride of t_strbuffer, import the lib for portability

/usr/src/sys/kern/subr_sbuf.c & /usr/include/sys/sbuf.h

Support for cover

Not sure if I missed the obvious, but I can't find a way to add cover tags.

Issue on macOS

Hi,

There are some compatibility issues on macOS that prevent me for putting it in homebrew right now, but I've figured out some workarounds.

Before sending a proper pull request, I wanted to show the quick and dirty fix and see how we can improve it if of course you mind adding support for macOS.

diff --git a/src/t_editor.c b/src/t_editor.c
index 4524fa1..55d3263 100644
--- a/src/t_editor.c
+++ b/src/t_editor.c
@@ -97,8 +97,13 @@ t_edit(struct t_tune *tune)
 	if (stat(tmp, &after) != 0)
 		goto out;
 
+#if defined(__APPLE__)
+	int modified = (after.st_mtimespec.tv_sec  > before.st_mtimespec.tv_sec ||
+		        after.st_mtimespec.tv_nsec > before.st_mtimespec.tv_nsec);
+#else
 	int modified = (after.st_mtim.tv_sec  > before.st_mtim.tv_sec ||
 		        after.st_mtim.tv_nsec > before.st_mtim.tv_nsec);
+#endif
 
 	/* we perform the load iff the file has been modified by the edit
 	   process and that process exited with success */
diff --git a/src/t_ftoggvorbis.c b/src/t_ftoggvorbis.c
index b3ad6b3..7447cf5 100644
--- a/src/t_ftoggvorbis.c
+++ b/src/t_ftoggvorbis.c
@@ -15,6 +15,10 @@
 #include "t_config.h"
 #include "t_backend.h"
 
+#if defined(__APPLE__)
+#define eaccess access
+#endif
+
 
 static const char libid[] = "libvorbis";
 
diff --git a/src/t_toolkit.h b/src/t_toolkit.h
index ee6567f..566b49b 100644
--- a/src/t_toolkit.h
+++ b/src/t_toolkit.h
@@ -7,16 +7,7 @@
  *
  */
 
-#ifdef FLAC_CLASH_WORKAROUND
-/*
- * FLAC's assert header conflict with the standard. It has been fixed in libFLAC
- * 1.3 (by requiring prefixing) but not all OS / distro have updated yet (Ubuntu
- * 13.04 for example).
- */
-#include </usr/include/assert.h>
-#else
 #include <assert.h>
-#endif
 
 #include <ctype.h>
 #include <err.h>

Use Aruba?

See https://github.com/cucumber/aruba

prevent building without any backend

developer README

remove all that xfopen / xfclose stuff.

taglib comment writing

taglib comment is set to blank at t_fttaglib.c#L217. I have changed "" to t->val and it worked fine. Is that intentional?

OSX CI

now that #32 is merged we should be able to build and run under OSX. Add it to the Travis-CI build matrix. Maybe migrate to GitHub actions on the way.

honor $TMPDIR

segfault on action parsing

tagutil setfoo
tagutil: zsh: segmentation fault (core dumped) tagutil setfoo

get ride of t_error

check if case insensitive handling is right

Fix scripts

add version command

expected:

$ tagutil version
3.1

ensure proper handling of multiple tag with the same name

• rename
• filter
• edit
• show
• etc.

ensure UTF-8 ?

Have an alternate emit / parsing format

YAML is bound to be represented as UTF-8 and for the sake of clean design an alternate format should be implemented. At the moment YAML should be the default and primary though.

use sysexits.h for return codes.

Update doc

update the manual and README.

check if T_SAVE_IF_DIRTY is really needed before T_FILTER

ogg write support through libvorbis

Trouble Building ("CMakeFiles/tagutil.dir/tagutil.c.d: No such file or directory")

When I try building tagutil, I keep running into this error:

make[3]: Entering directory '/tmp/guix-build-tagutil-3.1.drv-0/source/build'
[  4%] Building C object CMakeFiles/tagutil.dir/tagutil.c.o
cc1: error: too many filenames given; type ‘cc1 --help’ for usage
cc1: fatal error: CMakeFiles/tagutil.dir/tagutil.c.d: No such file or directory
compilation terminated.
make[3]: *** [CMakeFiles/tagutil.dir/build.make:76: CMakeFiles/tagutil.dir/tagutil.c.o] Error 1
make[3]: Leaving directory '/tmp/guix-build-tagutil-3.1.drv-0/source/build'
make[2]: *** [CMakeFiles/Makefile2:83: CMakeFiles/tagutil.dir/all] Error 2
make[2]: Leaving directory '/tmp/guix-build-tagutil-3.1.drv-0/source/build'
make[1]: *** [Makefile:136: all] Error 2
make[1]: Leaving directory '/tmp/guix-build-tagutil-3.1.drv-0/source/build'
make: *** [Makefile:6: release] Error 2
error: in phase 'build': uncaught exception:
%exception #<&invoke-error program: "make" arguments: ("-j" "8") exit-status: 2 term-signal: #f stop-signal: #f>

As far as I can tell – though –, I'm running the right commands (as the GitHub instructed):

test -d build || mkdir build
cd build && cmake -DCMAKE_BUILD_TYPE=RELEASE ../src && make

So I can't tell what I'm doing wrong; the version of cmake I'm using is 3.24.2.

And full output can be found here: https://pastebin.com/NAHgxpc1.

Thanks for any help!

document genre with TagLib

setting to a number will be translated into a genre (1 → "Classic Rock"). Document it in the manual and find the TagLib table in its documentation.

handle optional argument for actions

both clear and load have default behaviour. For example for clear, both calls should be equivalent (currently only the later is supported):

% tagutil clear foo.mp3
% tagutil clear: foo.mp3

remove all that restrict stuff.