NAME

typeset_audio_dir - produce TeX listing of directories with audio files.

SYNOPSIS

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

  # Likewise, but this directory structure is w.r.t. current directory;
  # Do not emit year and duration
  typeset_audio_dir .
  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.
  typeset_audio_dir -@ -1 "@a" -2 "@l" -t 1000 -a 1000 -ynT -B All .

DESCRIPTION

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.

OPTIONS

-B

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 4 TeX files:

  basename_text.tex
  basename_cdcover.tex
  basename_cdbooklet.tex
  basename_list.tex

The last file contains the information about audio files encountered.

The first three 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, multicolumn output, font size, interline spacing, margins, page size etc.

-y

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.

-Y

Emit the whole date information if present.

-T

Emit duration information.

-n

Emit track number.

-1

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

-2

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.

-a

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

  Performer/Composer/Collection/part1.mp3
  Performer/Composer/Collection/part2.mp3
  Performer/Composer/single1.mp3
  Performer/Composer/single2.mp3

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

-t

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

-e ENCODINGS

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 correspondingly. Use 0 instead of an encoding to do byte-oriented read/write.

Info read from file system

The following files are used to give hints to typeset_audio_dir:

.content_comment

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

.top_heading

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.

HINTS

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