IdEst – ID3 Editing and Scripting Tool (split by section):   Section:   Chapter:FastBack: Scripting   Up: Scripting   FastForward: Backups   Contents: Table of ContentsIndex: Concept Index

10.3 Format

Formats are advanced scripting feature which allows for extending idest output by writing an appropriate script in Scheme. A format is invoked using the --format (-H) command line option. The format name is given as argument to that option. Similarly to the --source option, the --format option stops further argument processing and passes the rest of arguments to the format module, which is supposed to remove its option arguments and leave only input file names. For example:

$ idest --format=framelist -Q -l *.mp3

This example invokes idest with the ‘framelist’ format (see framelist). The -Q and -l flags are format options.

10.3.1 How to Write Format Modules

The source for format module name must be saved in the file named name.scm located in the subdirectory idest/format somewhere in the Guile load path. It must begin with the following clause:

(define-module (idest format name))

The module must define and export the ‘idest-main’ function, whose calling convention and return type is the same as that in the usual idest scripts (see idest-main). For example, the following is a simplified version of the ‘framelist’ module (see framelist):

(define-module (idest format framelist))

(define frame-list '())

(define-public (idest-main name frames)
  (for-each
    (lambda (elt)
      (cond
       ((member (car elt) frame-list)
        (display (car elt))
        (newline))))
    frames))

If the module needs to process command line arguments, it may not do so in the main code, as the usual idest modules do. Instead, it should export a special function, ‘idest-init’, defined as:

(define-public (idest-init)
  ...)

This function analyzes the command line, removes the consumed modules options and returns. For example:

(define-public (idest-init)
  (let ((cmd (command-line)))
    (cond
     ((< (length cmd) 3)
      (error "usage: idest --format=framelist
             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)))))))

The module should also export the symbol ‘description’, which should contain a string with a concise description of the module. This description will be shown in the --format=help output (see help format). For example:

(define-public description
  "display a list of frames defined in each file")

10.3.2 Existing Formats

Idest is shipped with a set of predefined formats. These formats are found in the scheme/idest/format subdirectory of the source tree. They are installed into the version-site-dir’/format directory (see version-site-dir).

10.3.2.1 help: List and Describe Available Formats

The ‘help’ format searches the load path for available format 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
framelist: display a list of frames defined in each file
lyrics: display lyrics (the USLT content), if present
pic: show attached picture (APIC frame) or save it on disk
shortlist: display title, artist name and year

If ‘help’ is used with the --which (-w) option, the format includes the directory where the module is found:

$ idest --format=help --which
framelist (/usr/share/idest/format): display a list of frames
defined in each file
...

10.3.2.2 framelist: Display List of Frames Present in Each File

The ‘framelist’ format displays a list of ID3 frames present in each input file, e.g.:

$ idest --format=framelist file.mp3
TIT2
TRCK
COMM
TENC
COMM

The following command line options are understood:

-F
--full

Display all qualifiers. For example:

$ idest --format=framelist --full file.mp3
TIT2 descr="Title/songname/content description"
TRCK descr="Track number/position in set"
COMM descr="Comments" lang="eng" condesc=""
TENC descr="Encoded by"
COMM descr="Comments" lang="cat" condesc=""
-f flist
--frames flist

Display only frames from flist, which is a list of frame names, separated by commas.

-Q
--qualified

Display frames in qualified form:

$ idest --format=framelist --qualified file.mp3
TIT2
TRCK
COMM:eng:
TENC
COMM:cat:
-l
--single-line

Fit output on single-line, e.g.:

$ idest --format=framelist --single-line file.mp3
TIT2,TRCK,COMM,TENC,COMM
-h
--help

Show a short help summary

10.3.2.3 lyrics: Display Lyrics

The ‘lyrics’ format displays the lyrics (as found in the ‘USLT’ frame). The text is preceded by the song title from the ‘TIT2’ frame, e.g.:

$ idest --format lyrics file.mp3
How doth the little

How doth the little crocodile
Improve his shining tail,
And pour the waters of the Nile
On every golden scale!

How cheerfully he seems to grin,
How neatly spreads his claws,
And welcomse little fishes in
With gently smiling jaws!

If the environment variable PAGER is set, its value is used to paginate the output.

This module supports the following command line options:

-l name
--lang name

Select ‘USLT’ frames with name as the value of their ‘lang’ qualifier.

-c text
--content text

Select ‘USLT’ frames with text as the value of their ‘condesc’ qualifier.

-h
--help

Show a short help summary

10.3.2.4 pic: Display Attached Pictures

The ‘pic’ format displays or stores on disk attached pictures. It supports the following options:

-v prog
--viewer prog

Use prog to view images (default: xv).

-d text
--description text

Look for pictures with this descriptive text.

-m type
--mime-type type

Look for pictures with this MIME type.

-s
--store

Store pictures on disk, instead of displaying them. The picture names are created by expanding the file name template, given with the following option:

-f template
--file template

Set the template for output file names (implies –store). The template can contain the following meta-characters:

CharExpands to
~DInput file directory part
~NInput file base name
~CContent description
~TMime type without the ‘image/’ prefix
~PPicture type
~IPID of the idest process

The default template is ‘/tmp/~I-~N.~T’.

-h
--help

Show a short help summary

10.3.2.5 shortlist: Display Short Information

The ‘shortlist’ format module is similar to the ‘shortlist.scm’ example program, discussed in shortlist example. It does not take any command line options – everything after the format name is treated as file names:

$ idest --format=shortlist *.mp3
dnr.mp3: Diamonds & Rust by Joan Baez, 1975
ams.mp3: Amsterdam, by Jacques Brel, 1968

IdEst – ID3 Editing and Scripting Tool (split by section):   Section:   Chapter:FastBack: Scripting   Up: existing formats   FastForward: Backups   Contents: Table of ContentsIndex: Concept Index