TYPESET_AUDIO_DIR(1p)

👑 TYPESET_AUDIO_DIR(1p) 👑

okay bestie, so this is typeset_audio_dir — it lives in the User Contributed Perl Documentation, section 1p. She's a whole icon and she's about to make your music folders look gorgeous. buckle up. 🎀

---

✨ 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         (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 .
  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 audios with lyrics
  typeset_audio_dir -ynTL -P long -B All

  # Likewise, but the name is based on the album; ignore comments
  typeset_audio_dir -yTn -P short -B All_short

  # Likewise, but produce both long and short listings.  The short one serves
  # as a table-of-contents for the long one
  typeset_audio_dir -ynTL -P short,long -B All

like, look at her go. five whole vibes, one tiny script. 💅

---

🌈 DESCRIPTION 🌈

She scans the directory (or directories, plural, she's flexible) you hand her on the command line, and uses MP3::Tag to pull info about the audio files. Wanna process non-MP3 files? that's valid, but you'll need extra modules (peep MP3::Tag for that) and you have to pass the -r FILENAME_FILTER option. no exceptions bestie.

Then she produces one or more TeX files (how many depends on the -B option) stuffed with commands that typeset human-readable listings. Non-directories sitting on the command line? ignored, not her problem. (She can also be used to process non-audio files, if MP3::Tag can extract the title/etc info from them. slay.)

With -B, the file *_list.tex contains all the data about the audio files — and when -P gets both "short,long", another similar file *_list_long.tex gets written too. The file *_titles.tex contains a 0th approximation to the possible "title" of the collection (one based on the -N option plus a short summary of toplevel directories). The file *_common.tex contains macros common to the following files. The remaining files define different environments to typeset the listing (including two TeX files with "content" as needed): a "normal" listing (for A4/Letter, *_text.tex), two flavors of a "compressed" listing (for jewel case insert, *_cdbooklet.tex and *_cdcover.tex), and a back insert for the jewel case (*_backcover.tex). ✨

The whole intent here? support so many different layouts of directories with audio files, with as little tinkering with command-line options as humanly possible. So typeset_audio_dir tries to do as much as she can by guestimates. And simultaneously, you should be able to tune the script to handle whatever layout you actually have. main character energy, honestly.

The script emits headers for several levels of "grouping". The "toplevel" group header is emited once for every "toplevel" directory (with audio files), and further headers are emited based on changes in descriptors of the audio files during the 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 6 TeX files:

  basename_text.tex
  basename_cdcover.tex
  basename_cdbooklet.tex
  basename_backcover.tex
  basename_list.tex
  basename_titles.tex
  basename_common.tex

not me counting that list and getting seven 🙈 anyway. The last file contains the common macros needed for typesetting. The previous two files contain 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. yes girl, customize your little heart out.

The *_titles.tex file is of mixed nature: it reflects the content of audio files, and is supposed to be human-editable. It will be overwritten unless it is Read-Only; so if you hand-edit it, make it Read-Only. Similar overwrite logic is applied to *_common.tex file too.

🫶 heads up bestie: hand-edit *_titles.tex or *_common.tex and forget the Read-Only bit, and she will steamroll your work. protect your art.

• -P "plan" — a shortcut to setting hairy options; currently, two values of "plan" are supported:

  short   =>    -1 ""  -2 ""   -t -1e100 -a -1e100 -c
  long    =>    -1 ""  -2 "@l" -t  1e100 -a  1e100

for generation of short/long listings. In the short listing, records correspond to the album names. In the long listing, records correspond to individual files, and album names serve as second-level headings.

• -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. she's not gonna let your dates ramble, ngl.
• -Y — Emit the whole date information if present. no compression, all the tea. 🍵
• -T — Emit duration information.
• -n — Enable emit track number. Environment variable TYPESET_AUDIO_TRACK may contain the format to interpolate for typesetting (defaults to "%{mA}%{n1}"). For example, set TYPESET_AUDIO_TRACK to "%{n1}" to use "pure" track number instead of combination of media/disk number and 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 empty value is the default; in this case the header is based on the name of the directory (with some normalization: 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. (put "" in and she simply will not. iconic.)

• -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 of 2 is not very intuitive. It is recommended to explicitly set this option to the value you feel appropriate (1e100 would play role of infinity — so any change will generate a new second-level heading). fr fr, set it yourself, don't trust the default to read your mind.

• -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(). lowkey a lifesaver on those shells.
• -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" for output, names of directories, and files .top_heading correspondingly. Use 0 instead of an encoding to do byte-oriented read/write.
• -c — 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.

If the content of this field is contained at end of the title, nothing is added, just this part is typeset differently.

• -L — Mark files with embedded (un)syncronized lyrics and pictures. Put the explanation of used symbols at the end of the listing. 🎤🖼️
• -N COLLECTION_NAME — (defaults to "COLLECTION") the name of the collection to insert into the file *_title.tex. The interaction with encoding may be less than intuitive; you may want to check/edit this file for corrections.
• -F FONT_ENCODING_SYMBOL — (defaults to "T2A"): the name of "LaTeX" font encoding. If your installation is broken and "T2A" is not available, you may try "T1" or "OT1". See "PROBLEMS when TYPESETTING".
• -r FILENAME_FILTER — sets the regular expression for filenames to look for (the default is "(?i:\.mp3$)").

---

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

Example: suppose your section heading is based on directory names. Suppose the directory tree to process contains a directory Mixed/2009. If you want names of subdirectories of this directory to become section headings, make file Mixed/2009/.top_heading which contains 0. If the same holds for other subdirectories of Mixed, instead of creation of such file in all year-subdirectories, one can make file Mixed/.top_heading which contains "-1".

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

✨ TYPESETTING ✨

Okay bestie, listen up 💅 running this script is only gonna generate the TeX files you need — it will not typeset them for you. And fr fr, they will look so much better if you first go in and edit the files to suit your needs. No cap.

Recall how you typeset TeX documents (we're assuming PDF target here, obviously):

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

(ngl a LOT of temporary files are gonna spawn from this too 🫠 you can totally break it into multiple commands on && if that's easier on your brain.)

Some of the files (like ..._cdcover.tex, iykyk) fit way better in landscape orientation, so for those you need:

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

And with ..._cdbooklet.tex? For the absolute best result, you better rearrange pages for booklet 2up 2-pages-per-side printing, like this:

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

(all on one line, or give 3 separate commands, breaking on &&; more details on running dvips are put in the beginning of the TeX file 🎀). If you can easily print a .ps file, you can just skip that last step entirely, slay. (The option -dAutoRotatePages=/None interferes with viewing; you may omit it unless you do "extra flipping of even pages", as shown below 👇.)

Note that this assumes that when you send files to the printer you request duplexing with "binding on the short side of paper". If your printer can survive manual duplexing, do it as usual: print first the even pages in opposite order, reload paper, then print odd pages. (You need to understand which orientation you must put the paper back in when reloading — there are 4 variants, and only one is correct 😭 good luck bestie.)

For "real" duplex printers, see below 💖

---

🚨 PROBLEMS when TYPESETTING 🚨

incomplete installations

! Font T2A/cmr/m/n/10.95=larm1095 at 10.95pt not loadable:
  Metric (TFM) file not found.

For the best multilanguage coverage I could find, by default the generated LaTeX files use T2A-encoded-fonts with extra Latin characters provided by textcomp. Apparently, some TeX installations omit T2A encoding tables 🙈. You may want to change T2A to, like, T1 by using option -F T1.

In a booklet, page 1 is at end, the rest is a mess

The landscape option of geometry package should rotate the page 90 degrees. Depending on the way it's configured, the direction of rotation varies 🤷. If the .pdf file obtained with -dAutoRotatePages=/None option has top of page on the left, you may need to invert the direction of shifting: instead of 2:0(0,-6cm)+1(0,6cm) you should use 2:0(0,6cm)+1(0,-6cm).

Duplexing with "bind on the long side of paper"

By default, most duplex printers are configured to "bind on the long side of paper", so to avoid manual setup of binding options, you may want to flip even pages in the generated file. To do this, add an extra ps2ps step at the end of pipeline, like:

... psbook | pstops "2:0(0,-6cm)+1(0,6cm)" | pstops "2:0,1U(1w,1h)" > document.ps

A4-sized paper vs. Letter-sized paper

Some TeX/PS installations do not have correctly set-up site configuration files, so they don't know what the usual paper size on your printer is 💀. Fortunately, all steps of the typesetting pipeline allow a manual reconfiguration. Unfortunately, command options for the required reconfigurations are subtly different for different steps. It's giving chaos honestly.

For example, if your TeX/PS-utils think that your paper size is letter, while what you actually print to is a4, you need to do the following (depending on which configuration files are broken, you might be able to omit some modifications):

1. Add a4paper to the \usepackage[...,...]{geometry} options (the comma-separated list in brackets) in TeX files which use geometry.
2. Add -t a4 as a dvips option.
3. Add -pa4 as a pstops option. (If it breaks rotation, omit it, sigh! 😮‍💨)
4. Add -sPAPERSIZE=a4 as a ps2pdf option.

Example commandline working with some of the complications:

dvips -t landscape -f < All_cdbooklet-a4.dvi | psbook | pstops -pa4 "2:0(0,-6cm)+1(0,6cm)" | pstops -pa4 "2:0,1U(1w,1h)" > Output-even_flipped-a4.ps
  && ps2pdf -sPAPERSIZE=a4 -dAutoRotatePages=/None Output-even_flipped-a4

Likewise, quite often one needs to add -pletter to ps2ps commandlines for correct printing to letter-size paper. You can check the resulting PDF file in a viewer: the status line should show the correct paper size (e.g., 8.5in x 11in is Letter), even pages should be flipped (for binding "on the long side"), and the wireframes on different pages should be positioned exactly at same positions. For visual verification, choose "fit-to-page" scaling, and quickly switch pages back-and-forth by keyboard or by the "Next page" button 🦋.

Warnings from dvips

Note also that if your TeX/dvips installation is completely correct, you can remove -t landscape from your dvips command line; not removing it would produce a warning: both both landscape and papersize specified: ignoring landscape.

Systematic duplexing offset

Some printers can't reliably match positions on the front and back side when printing; there's little one can do about it 😔. However, if your printer adds some consistent misplacement of front and back sides, one can put workarounds in for it.

For example, when "binding on the short side", the common error is that (in landscape orientation) the backside is offset horizontally w.r.t. the frontside. So like, if the offset is 3.4mm to the left, one can shift the image on the page by half of this — 0.17cm to the left: replace 2:0(0,-6cm)+1(0,6cm) by 2:0(0,-6.17cm)+1(0,5.83cm).

With "binding on the long side", the typical error is vertical offset. To work around it, one needs to shift vertically (again, by half the amount) after flipping even pages. To shift 0.17cm up, add an extra step pstops "(0.17cm,0)" to the pipeline after the 2:0,1U(1w,1h) step (untested 👀).

---

🌸 HINTS 🌸

The default font sizes and density of type are chosen to optimize printing of a DL-DVD collection of short high quality audio (of song-like duration: about 100 subheadings, and 2000 audio files). You may improve the visual quality if you tune the typesetting to your particular needs ✨.

The most commonly changed settings are on top of the generated files. These are fonts and degrees of vertical squeeze of paragraphs for the principal title, titles of sections (1st level) and subsections (2nd level), and of actual records emitted for each audio file, as well as the number of columns. Slightly further in the file are settings for gaps to left around section headings, and for fine-tuning of squeezing.

Do not forget that if you can't describe a complicated layout by command-line options, you still have the 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. Periodt 💅

You can also redefine \preSection * \postSection 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. (Of the more tricky stuff, mention \squeezeContunuationLines and \parskip, which regulate the density of lines — without changing the line font; note that setting \parskip is a part of the action of \squeezeContunuationLines. \columnsep regulates the horizontal separation of columns. One can also fine-tune the vertical position of the start of the first page; for backcover, also tune up \CDbackMargin and \CDbackTopMargin. The definition(s) of \squeezeContunuationLines are commented out (by %) in non-*_common.tex files; you may uncomment it, and tune it up separately for each TeX file.)

One can combine two (or more) lists (e.g., one with the short style, and one with the long style) into one output file; the generated files ..._cdbooklet.tex and ..._text.tex already have a necessary template (disabled) at the end. (Moreover, with -P "short,long", this is done automatically 👑.)

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

\input{another_list}

to All_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 \SectionFont etc, \COLUMNS, type of squeeze to suit your needs — the point is that they should not be necessarily the same for the second list. It's giving customization, we love to see it 💖)

---

🔥 WORKFLOW 🔥

The module is quite flexible; here is one of the possible workflows (suitable if all you need is -P <short> and -P <long>:

Put all the "toplevel" directories as subdirectories of the current directory (well, this is not really necessary!). And put the heading to use for each directory into a file .top_heading. You may need to specify the encoding used in this file into the options (do similar to -e h:cp1252). That's it bestie, go off 🌈

---

And that's a wrap, gorgeous 🎀 this page came from the user-contributed Perl documentation, running under perl v5.36.0, dated 2022-12-30. Drink some water, fix your paper size, and go make something iconic. Bye bestie 💜✨