Config Mode

Essential reading

Encoder (first paragraph)

backup and restore (one paragraph)


Config mode is for configuring Wax. You are most likely to use Config mode when you first set up your Wax Box.


The notebook in Config mode has four pages. The first is used to set parameters.


  • Auto switch to play mode. This parameter lets you decide whether Wax switches automatically to Play mode when you click the play button.
  • Eject when ripping done. When Wax finishes ripping a CD, it will automatically eject it.
  • Email report of critical error to 3beez. If a critical error occurs while you are using Wax, Wax will email a report to 3beez. The report contains information about the location of the error and the operations that you were performing when the error occurred. We use the information to correct the error. The report contains no personal information, but if you are uncomfortable anyway you can turn off the reporting mechanism here.
  • Compatible export encodings. Select the encodings supported by your portable media player. Note that mp3 is always selected because all PMPs support it. Wax prioritizes encoders from left to right. Thus, if Wax finds multiple versions of the same track, it will copy the one corresponding to the left-most compatible encoding. If Wax does not find a sound file in a compatible encoding, it will select the version corresponding to the left-most encoder (usually flac) and transcode it to the left-most compatible encoding. Note that transcoding from one lossy encoding to another is discouraged. For example, if you ripped a recording using ogg but your PMP supports only mp3, Wax will complete the request by transcoding from ogg to mp3, but the sound quality will be worse than it would be if you ripped to wav or flac instead (because they are lossless) or directly to mp3 (so that losses do not compound). If you plan to rip recordings using a lossy encoder (ogg, m4a, or mp3), try to be sure that your PMP supports the encoding.
  • Gap duration. Recording engineers typically record silence at the end of tracks that are not meant to segue to the next track. Thus, setting segue by default assures that most tracks will play properly whether they were meant to play with a gap or without. If you encounter the rare recording that lacks recorded pauses, you are free to unset segue (which Wax does anyway before and after track groups and at the end of a recording). This control allows you to specify the duration of the pauses that Wax will introduce when segue is not set.


The remaining options are for selecting the encoder to use when ripping and to set parameters associated with the encoder. Not all encoders have parameters. Controls will appear for those that do. In every case, Wax provides an indication of the bit rate for the codec. The bit rate is preceded by “~” when it is possible only to estimate.

The encoders are listed roughly in order of quality (although there is overlap depending on the choice of parameters). Wikipedia is a good place to start for more information about each encoder:

ext name link
wav Waveform Audio File Format
flac Free Lossless Audio Codec
ogg Ogg Vorbis
m4a MPEG-4 Part 14
mp3 MPEG-1/2 Audio Layer III

Note that it is permissible to rip tracks multiple times with different encoders. When playing the corresponding recording, Wax will automatically select a version according to the priority in the table above. You might want to have a lower quality version if you export recordings to a device that does not support the higher quality encoder (see compatible encodings above).

Volume equalization

Wax can equalize the volume automatically as you play a sequence of tracks or works. When you select “track”, Wax attempts to keep the overall volume of each track the same. When you select “work”, Wax attempts to keep the overall volume of each work the same. Track loudness equalization is most useful when you are playing a random selection of tracks. When you are listening to classical music, you probably want work equalization (if anything). If you are listening to symphonic works, for example, you probably want a quiet movement to be quieter than a loud movement (which would not occur with track equalization). However, you may want the overall loudness of the entire symphony to be about the same as the overall loudness of some other symphony (which is what you get with work loudness equalization).

When you rip a CD, Wax measures the loudness of each track. If you select track loudness equalization, Wax will use these measurements to equalize the volume of the tracks. It is also possible to set track trim manually (Volume trim). The work trim can only be set manually.



Properties are metadata that are uniform across all recordings in all genres. They can refer to characteristics such as “sample rate”, which unlike “composer”, for example, is a characteristic shared by all recordings regardless of genre. There are four properties that Wax maintains: Date created, Date played, Times played, and Volume trim. These are the so-called “automatic properties”. Come here to create “user properties” using the Add operation. You will also find controls for renaming or deleting properties. When you delete a property, you will no longer be invited to enter a value for the property for new recordings (on the Props page in Edit mode) and the property will be deleted from every recording in every genre. As usual, Wax assumes that you know what you are doing, so it will not ask for confirmation before performing this operation. Use restore to back up from a mistake.

You can edit user properties on the Props page in Edit mode. View them on the Props page in Play mode, and search for them (Props search) in Select mode.

Completion & Learning


“Completion” refers to the ability of Wax to offer completions for text you enter in any permanent metadata field in Edit mode. Wax obtains values for the possible completions from files whose names match the key of the metadata field. Automatic completion is not available for keys that do not have a matching completions file. To enable automatic completion in such a case, the first step is to create a file with the name of the key. You can perform this task manually, but an easier method is to specify the name of the key and then click the Create button. You can permanently disable completion for a given key by selecting the key in the combobox and then clicking the Delete button. Wax will delete the associated file, so you will lose whatever data it contains. To disable completion temporarily, untick the box on the appropriate line in the table.

“Learning” refers to the ability of Wax to learn additional completions. Whenever you enter an unknown value in a field that has a completions file, Wax will add that value to the completions file when you save the recording. Disable this capability by unticking the box in the Learning column. Some metadata fields, such as codec, resolution, sample rate, and source, do not contain names, so they are unlikely to benefit from learning. The completions file for work contains shortcuts for words that often occur in the name of a work, such as Symphony and Sonata. You are unlikely to benefit by having its completion file learn “Cello Sonata in G minor, Op. 65” because there is probably only one work with this description. Likewise, if you have an “album” key in a pop genre, you are unlikely to benefit by having a completions file that learns “Sgt. Pepper’s Lonely Hearts Club Band”. Enabling Wax to learn such values vitiates the completion functionality by presenting too many choices. If you enable learning, check the file size occasionally to be sure that you have not accumulated too many names. Wax displays a message in the raw metadata panel when it learns a name. To remove a name from a completions file (or to add one manually), click on the corresponding edit button to open the file in a text editor. Read more about completion files in the appendix. In particular, go there to read about alternative spellings.

Completions files are also important for another reason: Wax uses them to assist in extracting names from the raw metadata it obtains from internet sources or from tags in sound files that you import. Wax compares names in the raw metadata with the contents of the completions files. If it finds a match, then it assigns the name to the corresponding metadata field. For example, if Wax sees the name “Wolfgang Amadeus Mozart” in the raw metadata, it will know to put that name in the composer field, if there is one in the genre you selected.


The Genres page is used to create, edit, and delete genres.



To create a genre, start by specifying its name. If you choose a name that is already in use, Wax will display a warning and desensitize the Save button. Leave “Subgenre of” blank if the new genre is not a subgenre. You can use the dropdown menu to select an existing supergenre. If you make the new genre a subgenre of an existing supergenre, Wax will set the primary metadata to be the same as the primary metadata for the parent (which is the essential characteristic of a subgenre). You can still specify whatever secondary metadata you want, though. To create a genre and make it a subgenre of a new supergenre, type the name of the supergenre in the entry. Wax will automatically create the supergenre at the same time it creates the subgenre. Note that Wax provides a dropdown list for specifying the metadata tags to minimize typing. It creates the list by assembling the tags that you used previously in your catalog. If the tag that you want is not among them, you must type it in.


By default, genre and subgenre names appear in alphabetical order in the genre-selection menu. To make them appear in a different order, you can prepend a string ending with a period. Wax will hide the prefix (all characters up to and including the first period) when it displays the menu. For example, if you define a genre “Symphonic” with subgenres “Classical”, “Romantic”, and “Modern”, you might want the subgenre names to appear in chronological order, as they are listed here, rather than alphabetical order, which would reverse “Romantic” and “Modern”. To achieve this result, name them “a.Classical”, “b.Romantic”, and “c.Modern”. The prefixes force the names into the desired order and then discretely disappear when you produce the menu.


A common mistake when attempting to create a new subgenre of a new supergenre, is to try to create the supergenre in a first step by entering its name in the Name entry and then to try to create the subgenre in a second step by entering its name in the Name entry with the name of the newly created supergenre in the “Subgenre of” entry. This two-step procedure will not work. The first step creates a genre, not a supergenre. Wax will then forbid use of that name as a supergenre in the second step. The correct procedure requires only a single step: Specify the name of the subgenre in the Name entry and the name of the supergenre in the “Subgenre of” entry. Wax will create both the supergenre and the subgenre at the same time. Do exactly the same thing when you create the next subgenres of the new supergenre. Wax will see that the supergenre already exists, so it will know that it does not need to create the supergenre again.

It is possible to make the same mistake in connection with the Rename genre operation described below. If you want to rename a genre to a subgenre of a new supergenre, do not start by trying to create the supergenre and then trying to move the genre to the new supergenre. Simply specify the name of the new supergenre in the first field of the new genre name. Wax will know to create the supergenre if it does not already exist.


Metadata keys must be unique. If you violate this edict, Wax will warn you with a message and it will desensitize the Save button to prevent you from saving an invalid genre specification. Note that Wax ignores prefixes when assessing whether names are unique. Thus, 1.Name is the same as Name.

After you specify a name for a metadata key, the button to the right of the entry becomes sensitive. Click on it to specify rules for how the metadata will interface with the non-Wax world.


Extractors are rules that specify how Wax extracts metadata from the raw metadata that it downloads over the Internet.

Name Rule
CONDUCTOR conductor: CONDUCTOR <or> feat. conductor CONDUCTOR
FEAT feat. <text>: FEAT)
TITLE Title: TITLE ( <or> Title: TITLE

Abbreviators are rules that specify how Wax derives the short form of primary metadata from the long form. They do not apply to secondary metadata (which have only a long form), so they do not appear on the panel when the corresponding key is for secondary metadata.

Name Rule
OMIT_ARTICLES Omit “The”, “A”, or “An”
OMIT_FORENAMES Keep only the last name. Keep the last two names if the last name is “II” or “Jr”
OMIT_FORENAMES_R Keep only the last name when the format of the name is “Last, First Second”
OMIT_KEY Omit the key of the work (e.g., “in A major” or “in A-flat Minor”)
OMIT_OPUS Omit the opus number (e.g., “Op. 141”) or a set of opus numbers (e.g., “Op. 141, 142 and 143”). Recognizes alternative catalogs B, BWV, D, HWV, K, KV, L, and S.
OMIT_QUOTE Omit anything in quotes (e.g., “Pastoral”) or parentheses and quotes (e.g., (“Pastoral”))
SYM Abbreviate “Symphony No.” to “Sym”

Use the Tag panel to specify how Wax converts its metadata to standard tags when exporting a track. There are only four tags in use universally, so select the one to which Wax should convert the associated metadata (or none if Wax should not convert it to a tag).

You must specify these rules or Wax will not perform the associated operation.



Edit provides support for four changes to keys. Click the appropriate expander to access the controls for the desired operation.

Throughout the following discussion of the individual edit operations, remember that permanent secondary metadata appear automatically in Edit mode and extended secondary metadata are created manually for specific recordings.

Add/promote key


The action of the Add/promote operation depends on whether the specified key already exists or not.

  • If the specified key is not in use in any recording, Add/promote creates a new permanent secondary metadata key.
  • If the specified key is already an extended secondary metadata key (it appears on the dropdown menu below the horizontal line), the Add/promote operation promotes it to a permanent secondary metadata key. The key will henceforth appear automatically in Edit mode.
  • If the specified key is already a permanent secondary metadata key (it appears on the dropdown menu above the horizontal line), the Add/promote operation makes it primary. The key will henceforth appear in Select mode in a new column. Primary metadata must have a value (so that something will appear in the corresponding column in Select mode), so Wax will create a default value for you. The default value will be in the form *<new key>*. Go to Edit mode to assign an appropriate value.

As soon as you specify a value in the entry, a message will appear telling you what will happen when you click the Add button.

If your objective is to create a new primary metadata key from scratch, specify the new key and click Add to make it permanent secondary, then select it from the dropdown menu and click Add again to promote it to primary.

Promoting a permanent secondary metadata key to primary is permitted in a subgenre, but because all subgenres must have the same primary metadata keys (see note below) Wax will automatically promote the key to primary in any sibling subgenres.

You might want to use Specify rules (below) after adding a key – especially if the key is primary. The newly created key otherwise has no abbreviators or tags selected. If you just created a new primary key, you will probably want to adjust column widths in Select mode.

If you want to create extended secondary metadata, you do not need to edit the genre. Instead, select the recording and enter Edit mode. Use the +Meta button to specify the desired metadatum. Edit the genre only when you want the key to appear automatically in Edit mode.

Specify rules/reorder keys


Specify rules/reorder keys allows you to pop up the configuration panel that you saw when you created a genre (popup) so that you can change the rules that Wax uses to interface to the non-Wax world. Here you can adjust the specification of abbreviators (abbreviators will not appear for secondary metadata because they have only a long form) and tags for the key.

The operation also permits you to reorder keys. To reorder keys, simply drag keys to their new positions. Wax restricts drags to positions within the same metadata type (primary or secondary). Converting metadata to the opposite type is promoting or demoting.

Be sure to save after making changes to either rules or order.

Rename key


To rename a key, start by selecting it using the combobox. There are three groups of keys in the popup menu. The first group is primary metadata, the second permanent secondary metadata, and the third extended secondary metadata. After making your selection, type the desired name for the key in the entry. The Rename button becomes sensitive once you have specified both the “from” key and the “to” key. However, the “to” key must be unique – there cannot be any recordings with both the from key and the to key (in which case changing the from key to the to key would result in a collision with the existing use of the to key). For example, you will not be permitted to change “soloists” to “singers” if both tags are in use in at least one recording. However, a recording that uses only “singers” does not interfere; recordings that use “soloists” will end up using “singers” just like the existing recording that uses “singers”.

Note that you can rename the primary keys in a subgenre, but because all subgenres must have the same primary keys (see note below), Wax will automatically rename the key in any sibling subgenres.

Delete/demote key


Select the key that you want to delete or demote using the combobox. Keys above the first line are for primary metadata; keys in the second section are for permanent secondary metadata; the ones below the second line are for extended secondary metadata. When you “delete” primary metadata, you demote the metadata to permanent secondary. When you “delete” permanent secondary metadata, you demote the key to extended secondary. When you delete extended metadata, Wax deletes the key from all recordings in the genre (along with the corresponding value, of course). N.B.: deleting an extended secondary key deletes actual metadata; deleting a permanent secondary key or a primary metadata key does not.

Note that you can delete a primary key from a subgenre, but because all subgenres must have the same primary keys (see note below), Wax will automatically delete the key from any sibling subgenres.

Rename genre


To rename the genre specified by the comboboxes at the top of the Edit operation, enter the new name here. You can modulate the rename operation depending on how you fill in the entries:

  1. To rename a genre, provide the new name in the first entry and leave the second entry blank.

  2. To rename a genre to a subgenre, fill in both entries. If the supergenre is new, Wax will create it at the same time that it moves the genre. You can make genre a subgenre of an existing supergenre only if the primary metadata match.

  3. To rename a subgenre to a genre, leave the second field blank.

  4. To rename a subgenre, specify both fields. If the supergenre is new, Wax will create it at the same time that it moves the subgenre. You can rename a subgenre to a subgenre of an existing supergenre only if the primary metadata match. Note that the existing supergenre should be the current supergenre if you want to rename a subgenre without changing its supergenre.

  5. To rename a supergenre without affecting the subgenres, provide “All” as the name of the subgenre.


    Users sometimes forget that subgenres all have the same primary metadata. That restriction, which appears several times in the instructions above, is not arbitrary. Remember, when you select a genre with subgenres, Wax presents a pull-right menu with the subgenres listed. The first item in that list, above a horizontal line, is “All”. When you select all, Wax displays a list of recordings in all the subgenres combined. How would you merge the recordings in one table if the subgenres had different keys or even different numbers of keys?

    The final rename genre configuration above is a little obscure. It might help to remember that you specify All as the subgenre to include all the subgenres in the rename operation just as you specify All in Select mode to include all the subgenres in the select operation.


    Wax insists on unique names when you are renaming just as it does when you are creating. As before, it ignores prefixes when assessing whether names are unique. Thus, it is not possible to rename a genre to Name if 1.Name exists.

The Move operation in Select mode covers some of the same ground as Rename genre. Use Move when you also need to map metadata. Move also allows you to move part of a recording into a new recording or to combine multiple recordings into a single recording. You can rename genres using move by creating a new genre, moving metadata into it, and then deleting the original genre, but it is easier to use Rename genre.



To delete a genre, simply specify its name and push the Delete button. But be careful: Deleting a genre deletes any metadata in the genre and the associated sound files. Consider (moving metadata) to another genre before you delete the genre.



To export all the metadata in your catalog to an Excel spreadsheet, simply click the Export button. The file metadata.xlsx will appear in the transfer folder. If the file was already there, clicking the Export button will overwrite it. Primary metadata get a dark gray background, permanent secondary a lighter gray, properties an even lighter gray, and extended secondary no background. To suppress the formatting, put the line

spreadsheet_no_format = True

in the file ~/.wax/waxrc. To restore formatting, delete that line.



The Zones page presents a list of all the Wax players on your network. Use this page to select the player from which you want the sound to emanate. Any player that is already attached to a client will be rendered in grey text and the identity of the client will appear in parenthesis. Normally the name of the client will be “waxbox”, which signifies that the Wax Box is under control of the client running on the same platform. However, there may be unusual circumstances when the client is running on a different platform, in which case the name of that platform will appear. Don’t worry if this discussion doesn’t make sense as these issues are relevant only to advanced configurations.



The Disk page provides information related to the hard disk drives in the Wax Box. The first item provides information about the utilization of the hard disk drives for the sound archive and for the backup of the sound archive. (The usable capacity of these drives is somewhat less than the advertised capacity (1 TB) because some space is consumed by the file system itself.) Below the status bars you will find additional information about the utilization of the sound drive. The estimate of the number of additional recordings that you can store is probably the most useful information presented here. The estimate extrapolates from the average size of recordings already stored in the sound archive. Be aware that the extrapolation is less accurate when your use pattern varies (e.g., by changing the codec you use to rip CDs).

The next item provides information about the utilization of the transfer and export folders (which reside on the main disk along with the operating system). If you need to make room in the transfer folder for a large export operation, use the button below for purging the cache. The button for purging the transfer folder can be used for the same purpose or simply for cleaning up after a large transfer operation.

The next item tells you the date and time of the last backup. Backups run automatically under control of the operating system (late at night), but if you ever want to perform a backup manually, click the Backup button. By default, the system will store up to 7 backups. The number of backups present is indicated after the date in parenthesis. If something ever goes wrong, you can restore the system (the sound archive and the metadata, to be precise) to its state at the time of the given backup. You can click the Restore button repeatedly (as long as additional backups are available) to restore the state of the system to times progressively farther in the past. The restore operation will revert all changes made since that time. To avoid losing changes that you want to keep, perform a backup manually before performing an operation with which you are uncomfortable (e.g., deleting a genre). If something goes wrong, you can revert the system to a point immediately before the operation.


If you have to restore after performing an operation that fails, be sure to perform a backup before attempting the operation again. If the operation fails again, clicking the Restore button will otherwise take you to a point further back in time.


If you ever get the system into a state in which the Wax program will not run, you can perform a restore manually. Connect to the Wax Box in desktop mode and open a terminal window. Execute the command wax-restore. Incidentally, it is also possible to perform a backup manually by executing the command wax-backup.

The next item tells you the date and time of the last updates. Updates also run automatically under control of the operating system. They run at a time chosen randomly between midnight and 0300. The use of a random time avoids inundating the update server with simultaneous update requests from all the Wax Boxes in the field.


The next item on this page is a list of the zombies found in the sound archive. Read about zombies in the section about Edit mode (zombies and phantoms). As we explained there, Wax protects against the creation of zombies, but it is still possible to create them. If zombies are present on the sound drive, you probably did not mean for them to be there. Use the Remove button to remove the corresponding zombie. If the Remove button is insensitive, the corresponding zombie is from a rip that is currently underway. When you finish the rip and save a recording, the directory will no longer be classified as a zombie. Note that for large collections, it can take time to detect zombies. You will see the message “Checking for zombies” during this time.

The final item on this page is a list of phantoms found in the catalog. Read about phantoms in the section about Edit mode (zombies and phantoms). If you forget to rip the disc or import the tracks when you create a recording, the recording is a phantom. Return to Edit mode to correct the oversight or to delete the metadata. Tick the box “Require cover art” if you want Wax to consider recordings lacking only cover art (the tracks are all present) to be considered phantoms as well. Users indifferent to cover art can leave the box unticked to produce a list of recordings with an urgent problem.


The Options menu for Config mode provides two choices. About provides information about the program. Help opens a web browser on the Wax manual. Note that the browser opens behind Wax, so you will not see it if you are using a remote desktop viewer connected in normal mode. Switch to desktop mode to see the browser (use port 5902 instead of 5901).