View on
Ilya Zakharevich > MP3-Tag-0.9714 > typeset_audio_dir


Annotate this POD


New  8
Open  25
View/Report Bugs


typeset_audio_dir - produce TeX listing of directories with audio files.


  # E.g.: current directory contains 1 subdirectory-per-performer.
  # Inside each directory the structure is
  #   Composer/single*.mp3         (fine-grain output: <title> field)
  # and
  #   Composer/MultiPart/part*.mp3 (fine-grain output: <album> field)
  # Emit year and duration info; use "Quartets" as basename
  typeset_audio_dir -y -T -B Quartets *

  # Likewise, but this directory structure is w.r.t. current directory;
  # Do not emit year and duration, output to STDOUT
  typeset_audio_dir .

  # Use artist as toplevel heading, album as the 2nd level; use track numbers;
  # name is based on title for any depth in directory hierarchy;
  # likewise for generation of 2nd level heading.  Mark pieces with lyrics
  typeset_audio_dir -@ -ynTL -1 "@a" -2 "@l" -t 1000 -a 1000 -B All .

  # Likewise, but the name is based on the album; ignore comments
  typeset_audio_dir    -yTn -c -1 "" -2 "" -t -1e100 -a -1e100 -B All_short .


Scans directory (or directories), using MP3::Tag to obtain information about audio files (currently only MP3s). Produces (one or more) TeX files with the listing.

The intent is to support many different layouts of directories with audio files with as little tinkering with command-line options as possible; thus type_audio_dir tries to do as much as possible by guestimates. Similtaneously, one should be able to tune the script to handle the layout they have.

The script emits headers for several levels of "grouping". The "toplevel" group header is emited once for every "toplevel" directory (with audio files), further headers are emited based on changes in descriptors of the audio files during scan.



gives basename of the output file. Without this option the script will output to STDOUT. With this option, script separates the layout from content, and produces 5 TeX files:


The last file contains the information about audio files encountered. The others files contain frameworks to typeset this information.

The first four files are supposed to be human-editable; they will not be overwritten by a following rerun with the same basename given to the script. By editing these files, one can choose between several encodings, languages, multicolumn output, font size, interline spacing, margins, page size etc.


Emit year (or date) information if present. Very long date descriptors (e.g., when multiple ranges of dates are present) are compressed as much as possible.


Emit the whole date information if present.


Emit duration information.


Enable emit track number. Environment variable TYPESET_AUDIO_TRACK may contain the format to interpolate for typesetting.


Toplevel header format; is interpolate()d by MP3::Tag based on the content of the first audio file encountered during scan of this toplevel directory. The default is based on the name of the directory (with some translation: underscore is converted to space).


Second-level heading format; is interpolate()d by MP3::Tag. Calculated based on the content of each audio file. The heading is emited when the interpolated value changes (subject to option -a).

Empty string disables generation.


Ignore changes to the second-level heading for directories deeper than this inside top-level directory. Defaults to 2. For example, in


if the toplevel directory is Performer, then changes of the second-level header in single*.mp3 would create a new second-level heading. However, similar changes in part*.mp3 will not create a new heading.

NOTE: maybe this default of 2 is not very intuitive. It is recommended to explicitely set this option to the value you feel appropriate (1e100 would play role of infinity).


The title-cutoff depth (w.r.t. toplevel directory). Defaults to 2. In audio files deeper than this the album %l is used as the name; otherwise the title %t of the audio file is used.

Set to -1e100 to always use %l, and to 1e100 to always use %a.


Replace all @ by % in options. Very useful with DOSISH shells to include %-escapes necessary for MP3::Tag's interpolate().


Sets encodings for output files, directory names (when uses to generate headings), and hint files. ENCODINGS is a comma-separated list of directives; each directive is either an encoding name (to use for all targets), or TARGET_LETTERS:encoding. Target letters are o, d, and h for output, names of directories, and files .top_heading correspondingly. Use 0 instead of an encoding to do byte-oriented read/write.


What to use as "comment" for a record (a part which is typeset differently). If not given, the ID3v2 frame TXXX[add-to:file-by-person,l,t,n] is used.

Info read from file system ^

The following files are used to give hints to typeset_audio_dir:


Content of this file is used as a comment field in the output for all files in this directory.


If empty, indicates that when the depth of files modifies the output, it is calculated w.r.t. the subdirectories of the directory of this file (ouph!). If contains a number, it is added to this depth.

Otherwise the content of this file is used as a toplevel heading for this directory.


Running this script will only generate necessary TeX files, but will not typeset them (they will look much better if you first edit the files to suit your needs). Recall how to typeset TeX documents (here we assume PDF target):

  latex document.tex && dvips document.dvi && ps2pdf document

(a lot of temporary files are going to be generated too). Some of the files (e.g., ..._cdcover.tex) assume work better with landscape orientation; one needs

  latex document.tex && dvips -t landscape document.dvi && ps2pdf document

With ..._cdbooklet.tex, for best result, one better should rearrange pages for booklet 2up 2-pages-per-side printing:

  latex document.tex
    && dvips -t landscape -f < document.dvi | psbook | pstops "2:0(0,-6cm)+1(0,6cm)" >
    && ps2pdf document

(more details on running dvips is put in the beginning of this TeX file).


Do not forget that if you can't describe a complicated layout by command-line options, you still have a possibility to run this script many times (once per directory with "handable layout", using -B and other options suitable for this subdirectory). Then you can use LaTeX \input directives to include the generated basename_list.tex files into the toplevel LaTeX file.

You can also redefine \preDir * \posDir to do nothing, and put the necessary code to generate the headers into the top-level file.

Modify the formatting macros to suit your needs.

One can combine two (or more) lists (e.g., with the short style, and the long style) into one output file; the generated files ..._cdbooklet.tex and ..._text.tex already have a necessary template (disabled) at the end. For example, with two lists created in "SYNOPSIS", All_list.tex, and All_short_list.tex, find \iffalse near the end of All_short_cdbooklet.tex and change it to \iftrue; then change the name in the directive


to All_long_list

This will make the "short" cdbooklet become a kind of "table of contents" for the combined "short+long" cdbooklet. (Of course, one can change the values of macros \dirSIZE, \COLUMNS, size of skips and of type [as \scriptsize above] to suit your needs - the point is that they should not be necessarily the same for the second list.)


Put all the "toplevel" directories as subdirectories of the current directory, and put the heading

syntax highlighting: