![[image of the Head of a GNU]](/graphics/gnu-head-sm.jpg)
|
|
IdEst |
ID3 Editing and Scripting Tool |
Sergey Poznyakoff |
IdEst – ID3 Editing and Scripting Tool (split by section): 
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.
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")
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).
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 ...
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:
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=""
Display only frames from flist, which is a list of frame names, separated by commas.
Display frames in qualified form:
$ idest --format=framelist --qualified file.mp3 TIT2 TRCK COMM:eng: TENC COMM:cat:
Fit output on single-line, e.g.:
$ idest --format=framelist --single-line file.mp3 TIT2,TRCK,COMM,TENC,COMM
Show a short help summary
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:
Select ‘USLT’ frames with name as the value of their ‘lang’ qualifier.
Select ‘USLT’ frames with text as the value of their ‘condesc’ qualifier.
Show a short help summary
The ‘pic’ format displays or stores on disk attached pictures. It supports the following options:
Use prog to view images (default: xv).
Look for pictures with this descriptive text.
Look for pictures with this MIME type.
Store pictures on disk, instead of displaying them. The picture names are created by expanding the file name template, given with the following option:
Set the template for output file names (implies –store). The template can contain the following meta-characters:
| Char | Expands to |
|---|---|
| ~D | Input file directory part |
| ~N | Input file base name |
| ~C | Content description |
| ~T | Mime type without the ‘image/’ prefix |
| ~P | Picture type |
| ~I | PID of the idest process |
The default template is ‘/tmp/~I-~N.~T’.
Show a short help summary
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):
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.