ID3 Editing and Scripting Tool
Batch modules or batches are
idest module files
located in a set of predefined directories which apply a set of
modifications to the argument files. In other words, batches are
file-modifying counterpart of formats. A batch is invoked using the
--batch (-B) command line option. The batch name
is given as argument to that option. Similarly to the --source
and --format options, the --batch option stops
further argument processing and passes the rest of arguments to the
batch module, which is supposed to remove its option arguments and
leave only the input file names. For example:
$ idest --batch=setpic -f cover.png file.mp3
In this example, ‘setpic’ is the batch module name, ‘-f cover.png’ are its arguments (see setpic), and ‘file.mp3’ is the argument file.
The rules for writing batch modules are similar to those for formats (see format modules) with only few differences.
The source for format module name must be saved in the file named name.scm located in the subdirectory idest/batch somewhere in the Guile load path. It must begin with the following clause:
(define-module (idest batch name))
The module must define and export the ‘idest-main’ function,
whose calling convention is the same as that in
idest scripts (see idest-main). This function
must return the new list of frames. If it returns an empty list,
all existing frames will be deleted. If the function chooses not
to modify any frames, it must return
If the module needs to process command line arguments, it should do so in the function ‘idest-init’, defined as:
(define-public (idest-init) ...)
Finally, the module should export the symbol ‘description’ with a concise description of the module. This description will be shown in the --batch=help output (see help batch).
To illustrate this, here is the code for module ‘delfrm’, which removes the requested frames from all argument files:
(define-module (idest batch delfrm)) (define-public description "remove requested frames from the input files") (define frame-list '()) (define-public (idest-main) (filter (lambda (frame) (not (member (car frame) frame-list))) frames)) (define-public (idest-init) (let ((cmd (command-line))) (cond ((< (length cmd) 3) (error "usage: idest --batch=delfrm FRAME-LIST FILE...") (exit 1)) (else (set! frame-list (string-split (list-ref cmd 1) #\,)) (set-program-arguments (cons (car cmd) (list-tail cmd 2)))))))
Idest is shipped with a set of predefined batch modules. These
modules are found in the scheme/idest/batch subdirectory of
the source tree. They are installed into the
‘version-site-dir’/batch directory (see version-site-dir).
The ‘help’ batch searches the load path for available batch modules and lists them. For each module its name and short description are shown on a separate line. The output is sorted alphabetically by the format name:
$ idest --format=help setlyrics: set song lyrics (USLT frame) from a file setpic: set attached picture from a file
If ‘help’ is used with the --which (-w) option, the format includes the directory where the module is found:
$ idest --format=help --which setlyrics (/usr/share/idest/format): set song lyrics (USLT frame) from a file ...
The ‘setlyrics’ batch reads the text from the specified file (or standard input, if no file is given) and stores it in the ‘USLT’ frame. It supports the following command line options:
Read text from file (default: stdin).
Set language in which the lyrics is written, i.e. the value of the ‘lang’ qualifier (default: ‘eng’).
Set content description.
Show a short help summary
The ‘setpic’ module reads a picture from a supplied file and attaches it to the argument files. It supports the following options:
Read picture from file. This option is required.
Set the value of ‘condesc’ qualifier.
Set MIME type. By default it is deduced from the picture file suffix.
Set picture type (a decimal number). Default is ‘0’.
Show a short help summary
$ idest --batch setpic --file cover.png \ --description='Album Cover' file.mp3
This document was generated on March 11, 2017 using makeinfo.Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.