wtfplay-live user manual

wtfplay-live is a small Linux distribution highly optimised for audio playback. What does that mean in practice?

The core component of the distribution is wtfplay player. It is a command line driven program and is built purely with having sound quality as top priority.

Since Linux file system navigation requires a learning curve, there is also a small text based UI available. It is called wtfcui and offers simple and intuitive menu driven user interface.

In this manual you can find comprehensive information on how to play music on your PC with wtfplay-live.

The next section covers wtfplay-live in general. It includes essential information about the basic environment, sound interface naming and accessing local disks.

The third section covers wtfplay player. It starts by introducing the features of the player and continues with basic usage. It also describes how to use wtfcui.

The fourth section covers advanced topics such as tweaking the player’s parameters. Please feel encouraged to experiment with parameters. This may bring very rewarding results.

Finally, the last section describes a configuration tool that allows you to define default playback parameters. The tool is called wtfsetup.

The wtfplay-live runs on PC with processors compatible with Intel Core2 Duo. At the moment the following ISO images are available:

In terms of memory, the distribution is extremely light. It requires less than 100MB of RAM for itself. All remaining RAM is used to load your music files. 2GB+ is the recommended RAM size.

The wtfplay-live relies on ALSA (Advanced Linux Sound Architecture, http://alsa-project.org) to play music. ALSA is the default sound subsystem in Linux kernel. wtfplay-live has been created with USB audio in mind. That is why it does not support all devices that are supported by ALSA.

Here are the USB devices that are supported:

Apart from USB devices wtfplay-live supports a small number of PCI devices. Those are:

Unfortunately, the mainline Linux kernel does not support many USB devices in native DSD mode. One reason is that USB audio class specification does not define the DSD format. The short list of supported devices includes:

There is also a set of experimental kernel patches that add support for more USB devices. The set is available at https://github.com/lintweaker/xmos-native-dsd These patches will be tested and gradually included in further releases of wtfplay-live

wtfplay-live supports SATA/PATA disk controllers that work in AHCI mode. This is usually the default setting in SATA controllers that you can find on most motherboards. The IDE Legacy mode should also work without problems.

In most computer motherboards there are also certain SATA ports that are dedicated for RAID configuration. They are usually routed to a special controller that assists the operating system driver in performing RAID operations. This kind of controllers is typically called Fake RAID and is not supported by wtfplay-live.

If your SATA disks are not detected please make sure that your SATA controller operates in AHCI mode. This is usually done in motherboard’s BIOS setup program.

wtfplay-live can access SATA/PATA/USB disks/flash drives with following file systems:

If you have your media files on a hard drive with one of the file systems above, wtfplay-live will be able to read them.

There is one caveat however. wtfplay-live will not access Logical Volume Manager (LVM) partitions or software RAID configurations.

wtfplay-live does not require installation in the traditional meaning. It is a live Linux distribution.

wtfplay-live is provided as hybrid-ISO image. That means you can burn it on optical disk and you can write it on a regular disk (SATA/USB) without modifications. In other words, you can create Live-CD and Live-USB from exactly the same image.

For detailed installation instruction please see the Installation Guide.

During boot wtfplay-live offers a choice of a few Linux kernels. This is done via a small menu. To choose a specific kernel simply highlight it using the arrow keys and press ENTER to boot it.

If the kernel is not selected manually, the default one (first one on the list) will be booted after 5 seconds.

Each kernel may have different impact on overall sound quality. Feel free to experiment and try each of them. The default kernel has been considered the best by majority of early testers, however a group of test participants preferred other (non default) kernels.

After the system is booted you will be logged in automatically as root (system administrator) and a small welcome screen will be displayed. At the bottom of the screen you will see the command prompt:

This means that the system is ready for your commands. At this stage you do not need the boot disk either, and if you wish, you can remove/unplug it from your computer. wtfplay-live runs from RAM and accesses local disks in read-only mode. That means all data on local disks are preserved intact.

wtfplay-live by default uses US English keyboard layout. This may potentially be a problem if you use a keyboard with a different layout. To change keyboard layout a new keyboard map must be loaded into the Linux kernel and you can use 321 command for this:

If the command is run without any parameters it will display the list of the most popular keyboard maps that are available. The maps are displayed as numbered list that is sorted alphabetically.

Below the list you will see the prompt asking you to select the keyboard map. You can choose which map to apply by typing either its number or its name. After confirming with ENTER key the keyboard map will be applied.

The keyboard map configuration will be stored on the persistent storage when possible. In this case the map will be loaded automatically after you restart the system.

Sometimes the keyboard settings cannot be stored, for example because the boot disk is in read-only mode. In this situation wtfplay-live will assume the default layout after rebooting. That means, that every time you boot wtfplay-live you will have to select keyboard map again. In order to accelerate the subsequent keyboard layout selection you can run 321 in non-interactive mode and pass the selected keyboard map number or name as a parameter.

For example, assume that you want to use UK keyboard layout. This map has number 48 on the list. To apply this map directly you can type:

Alternatively you can type the command with the map name:

In both cases above, the keyboard map list will not be displayed.

If your specific keyboard layout is not listed by 321 tool you may want to load it manually with the loadkeys command. First you need to find the map file that you want to load. The map files are located in /usr/share/keymaps directory and the subdirectories. Once you have located the map file all you need to do is to pass it as a parameter to the loadkeys command.

As an example let us use the uk layout again. The map file for this layout is /usr/share/keymaps/i386/qwerty/uk.map.gz. The command to load it is as follows:

Or even shorter than that:

To check what sound devices are available in your system run snd command. It will print a table with all sound devices detected by the OS. The table will look similar to the one below:

In the example above you can see two sound cards. The first card has three devices and they are associated with the HDMI outputs. The second card has just single device that is associated with the analogue output.

In general, the identifier for sound devices has format of hw:N,M, where N is the sound card index and M is the device index within the card. If the device index is omitted (including comma), then 0 is assumed. In other words, the identifiers hw:0 and hw:0,0 are equivalent.

The identifier is important as it is needed to invoke the player as well as the UI.

Volume levels can be adjusted with alsamixer command. It is the very basic tool that is available in most, if not all, Linux distributions.

alsamixer offers a visual interface to adjust hardware mixer controls of sound devices.

alsamixer is controlled from the keyboard. The basic keys are as follows:

The local hard drives, SATA and USB, are available in /media directory. For each of the drives there is a subdirectory there, that is named after the corresponding Linux block device. Inside that subdirectory you will find the contents of your disk/partition.

The above may seem complicated but it is really simple. Let us take a look at few examples:

Whenever you attach a new disk drive to your computer wtfplay-live will automatically mount it (and all partitions that the disk may have) in the /media directory. Similarly, if you remove the disk, then the system will automatically remove corresponding mount directories.

The contents of all disks available in /media directory remains intact at all time. This is because all disks mounted automatically are accessed in read-only mode. Why? This is the no-compromise approach again. There is no need to write anything.

For convenience a small script is provided that displays all disks that are mounted. It is called mnt. The script prints the disk’s directory, the mode and the file system. Here is an example:

The mode can have two values: ro stands for read-only and rw means read-write disk access.

There are two ways to restart wtfplay-live. One is with command:

The other way is by pressing CTRL+ALT+DEL key combination.

To shutdown wtfplay-live you can type either of the following commands:

If wtfplay-live is installed on a memory stick or other writeable medium it can save its configuration there. During the first boot a small partition is created on the boot disk for that purpose.

The following items are stored:

The configuration is stored onto the boot disk during system shutdown. If the boot disk is not attached to the PC at that time the configuration will not be preserved. Similarly, the configuration will not be preserved, if the PC is shut down "brutally", either by pressing (and holding) the power button, or by pulling the power plug.

Currently wtfplay supports only lossless file formats and that list is not long. The supported PCM files are WAV and FLAC with the following parameters:

The player also support DSF files with stereo DSD material. At the moment single-rate DSD (DSD64) and double-rate DSD (DSD128) are officially supported. Support for higher rates DSD (DSD256, DSD512) is experimental. Please see DSD playback section for details.

Note that some files that use the parameters listed here may not play in your system if the player detects that your hardware does not support certain values. In particular, wtfplay does not change the resolution of your material if that causes information loss, for example it does not convert 24bit samples into 16bit samples.

Similarly, the player does not resample your data. If your sound device does not support FS of the media file, then the player aborts the playback.

There is one more constraint and that is the file size. wtfplay will not be able to play any file that cannot be fully loaded into RAM. In other words, the audio data from the file that you want to play must load into RAM.

This may be a tiny potential issue, but it rarely becomes a real problem. Modern PCs are equipped with large amounts of RAM. 4GB is pretty much a standard now.

If you have a really big file and you are are not sure whether your file will play here is a simple rule to follow: your RAM size must be at least twice as large as the WAV file that you want to play and at least four times larger that the FLAC file size that you want to play.

By default wtfplay will use DoP encapsulation to play DSD material. This is the most popular and reliable method of DSD playback across audio devices supporting DSD audio. With DoP encapsulation you will be able to play DSD64 and DSD128 material.

There are two options to play music. The first option is to run the wtfplay from the command line. An alternative is to use UI called wtfcui. Each method will be covered in subsequent sections.

A big effort was made to make wtfcui very compact and fast, however it is not guaranteed that it will not impact on playback quality. For absolutely best results we recommend using the command line.

The UI for wtfplay player is called wtfcui and it will save you some time typing commands. It is designed to be very simple and intuitive.

To start wtfcui you need to know the sound device id that you want to use. The sound devices are called: hw:0, hw:1, hw:2, and so on. Here is the command to start wtfcui with hw:1:

By default wtfcui will use wtfplay player. If you want to change the player to wtfplay-dsd you may add -x wtfplay-dsd parameter as follows:

The are also other command line parameters that can be passed to wtfcui. To see them all run wtfcui --help command.

wtfplaylist utility allows playing from the command line the most recent playlist created with wtfcui.

To use the utility, create the playlist in wtfcui and quit to the command line. The playlist will be preserved. To play the preserved playlist type:

The utility will use the default player and the parameters that have been configured with wtfsetup (See wtfsetup section for details).

It is also possible to manually specify the player and its parameters manually as the arguments. This is shown in the examples below:

The above command will play the current playlist using the wtfplay-dsd player binary.

The above command will play the playlist using the default player binary on the second sound card.

In this example, both, the player and its parameters have been specified.

Before you start tweaking the audio driver’s buffer size, it is important that you become familiar with a few terms and concepts.

The audio driver’s buffer is is maintained by ALSA’s audio driver in the Linux kernel. It is used to transfer the audio data to the audio interface. This is typically done with help of DMA controller. In other words, the hardware uses this buffer directly. The size of this buffer can be changed by software.

The unit that is used to describe the buffer is the frame. The frame is a group of samples for each channel that should be processed/played at the same time.

The audio buffer is divided into a number of periods of the same size. The size of period is defined in frames. At each period boundary the audio driver asks the player for more audio data.

The relation between sample, frame, period and buffer for stereo data is shown in the drawing below:

Let us explain the picture above. It shows the stereo data. We can tell that:

As you may notice the total size (in frames) of the audio buffer that is maintained by the ALSA kernel driver is just a multiplication of period size and period count.

Now we know the terminology and we can now learn how to tweak the audio buffer in wtfplay. You can change two things: the period size in frames and number of periods in audio buffer.

Period size can be set by adding -f N or --frames=N command line parameter, where N is the size of the period in frames. The player requires that the number of frames is a power of two and is greater than 32. The sample values are: 32, 64, 128, 256, 512, 1024, 2048 and so on. Any number entered that is not a power of two will be ignored and the default period size will be used.

The number of periods can be specified by adding -n M or --periods=M command line parameter, where the M is the number of periods. The minimum number of periods is two.

If you do not specify either of the two parameters above wtfplay will use default values that are:

Here are some examples of how to use those parameters. In all of the examples below hw:1 is used as audio device and the file that is played is /media/sda1/MyMusic/track1.flac.

In the example above we just change the period size. The period count remains at its default value.

Here we changed the period count and we keep the default value of period size.

In this example we changed both parameters and we used the short form of parameters for this.

In this example we did exactly the same thing as previously but this time we used long notation to specify the command line parameters.

That example showed that you can mix short and long notation of the parameters. That has exactly the same effect as before.

Why tweak the audio buffer, you may ask? Are the values not universal? Unfortunately, the answer is no. A particular hardware configuration may simply not support certain values. Furthermore, during initial listening tests, we discovered that the same buffer settings impact sound quality differently on different hardware.

The values really depends on your hardware and, more importantly, on your taste, so discover yourself what values are the best for you. We strongly encourage you to do so as the reward can be worth the effort.

wtfplay, as any other Linux processes, runs with a certain priority. In simple terms, the priority tells the Linux kernel scheduler which process to run next. The processes with greater priority will run before processes with lower priority.

The priority of the player can be specified by adding -p N or --rtprio=N command line parameter, where N is the value between 1 and 99 (inclusive). Greater value means higher scheduling priority. The default value of priority is 5.

Here are some examples how to change priority. As previously, we use hw:1 audio device and we play /media/sda1/MyMusic/track1.flac file. We want to change the priority to 6 and we can use two notations to specify that.

Does setting the higher priority means that it is better? The answer to this question is "No". Specifying priority high enough may mean that the player process is more important than some Linux kernel processes, such as audio driver or USB host controller driver. This is not necessarily a desirable situation. Again, this is something that you will need to discover yourself.

If you want to use wtfcui, you can still tweak playback parameters. wtfcui passes some parameters directly to underlying wtfplay. Those parameters are: period size, period count and priority. Run wtfcui --help to see them all.

Here are some examples:

Unfortunately, you cannot change those parameters while wtfcui is running. The current release of wtfcui does not support that. That may change in future releases.

It is usually beneficial to disable the sound cards that are not used to reduce unnecessary CPU activity. Typically this can be done in the computer BIOS setup program, but some PC BIOS do not allow disabling sound cards.

In wtfplay-live sound cards can be disabled by detaching (unbinding) them from their drivers. In other words the sound card driver can be told to completely ignore the hardware.

This can be easily done with snd unbind CARD command, where CARD is the identifier of the sound card. It may be specified as a card index (e.g. 1) or card identifiers like, hw:0 or card0.

For example, to disable the first sound card in the system (hw:0) the command can be called in one of the following ways:

Keep in mind that when the sound cards are disabled using the above method this is not permanent. The cards will be enabled after the system is restarted.

To tell the system to disable the card automatically at the startup use snd unbind auto command and its subcommands. The example below shows how do tell the system to automatically disable hw:0 on startup:

You can verify which cards are set up to be automatically disabled with:

If you want to tell the system to disable the sound cards now, rather than at the reboot you can use:

Clearing the configuration for automatic card disabling can be achieved with:

In the wizard mode the tool interactively guides you through a series of questions allowing you to define new values of parameters. To start wizard mode run the tool without any parameters:

You exit the wizard mode at any time by pressing CTRL+C.

In non-interactive mode, the new values of parameters are defined as a command line parameters. wtfsetup accepts following command line parameters:

You can always run wtfsetup -h to see the usage info.

Here is an example of running wtfsetup in non-interactive mode. We will use the sample values from the table above and we will ask wtfsetup to save the parameters to the boot disk immediately:

When you run wtfsetup for the first time it will use the default values of the parameters, as described in the previous sections. In a subsequent execution wtfsetup will use previously defined values. Let us demonstrate this using the example above. If you run the example and later decide to change priority to 10, you can run wtfsetup like this:

In this case, only the priority value will be updated. All other parameters will remain the same (-x wtfplay -d hw:1 -f 4096 -n 2)

The important thing to remember is that command line options always take precedence over configured default values. Let us assume that we configured hw:1 as a default audio device for the player. If we run player like this:

as you can guess, file.flac will be played on hw:1. If we decide that we want to temporarily play the file on a different audio device, e.g. hw:0, we can always use the command line parameter:

In this case the default output device hw:1 will be ignored and hw:0 will be used instead.

The same principle applies to other player parameters.