IdEst
	ID3 Editing and Scripting Tool	Sergey Poznyakoff

• Main
• Downloads
• Documentation

10.4 Batch

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.

10.4.1 How to Write New Batch Modules

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 the usual 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 #f.

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

10.4.2 Existing Batch Modules

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

10.4.2.1 help: List and Describe Available Batches

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

10.4.2.2 setlyrics

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:

-f file

--file file

Read text from file (default: stdin).

-l name

--lang name

Set language in which the lyrics is written, i.e. the value of the ‘lang’ qualifier (default: ‘eng’).

-c text

--content text

Set content description.

-h

--help

Show a short help summary

10.4.2.3 setpic: Attach a Picture

The ‘setpic’ module reads a picture from a supplied file and attaches it to the argument files. It supports the following options:

-f file

--file file

Read picture from file. This option is required.

-d text

--description text

Set the value of ‘condesc’ qualifier.

-m type

--mime-type type

Set MIME type. By default it is deduced from the picture file suffix.

-p num

--pic-type num

Set picture type (a decimal number). Default is ‘0’.

-h

--help

Show a short help summary

For example:

$ idest --batch setpic --file cover.png \
        --description='Album Cover' file.mp3