README.adoc

DSBMixer - a tabbed Qt mixer application for FreeBSD

Table of Contents

• About
• Installation
  • Building from Source
    • Build Dependencies (Qt5)
    • Build Dependencies (Qt6)
    • Run time Dependencies
    • Getting the Source Code
    • Building and Installing from Source (Qt5)
    • Building and Installing from Source (Qt6)
  • Installing via pkg(8)
  • Installing from the FreeBSD Ports
• Usage
  • The Main Window
    • Uni-Channel View
    • Left and Right Channel View
    • Adding and Removing Recording Sources
  • The Tray Icon
    • Tray Icon Theme
  • The Preferences Window
    • Default Device Tab
    • The Advanced Settings Tab
  • The Applications Mixer
  • The D-Bus Interface
    • The dsbmixer-dbus Script
      • Examples
  • Command-line
    • Usage
    • Options
• Development
  • Contributing Translations
    • Available Translations
    • Instructions
• Configuring the Look and Behavior of Qt5 Applications
  • qt5ct and the Kvantum Theme Engine
    • qt5ct
    • Kvantum
  • Qt5-style-plugins

About

DSBMixer is a tabbed Qt mixer for FreeBSD. For each installed mixer device, DSBMixer opens a tab. It allows you to configure various sound settings, such as amplification, recording sources, or the default audio device. If built with devd support, tabs are created/removed automatically when a (USB) sound card was added to/removed from the system.

Installation

Building from Source

Build Dependencies (Qt5)

• devel/cmake

• devel/qt5-buildtools

• devel/qt5-core

• devel/qt5-linguisttools

• devel/qt5-qmake

• x11-toolkits/qt5-gui

• x11-toolkits/qt5-widgets

• devel/kf5-knotifications

Build Dependencies (Qt6)

• devel/cmake

• devel/qt6-base

• devel/qt6-tools

• deskutils/kf6-kstatusnotifieritem

Run time Dependencies

• sysutils/dsbwrtsysctl

Getting the Source Code

$ git clone https://github.com/mrclksr/DSBMixer.git
$ git clone https://github.com/mrclksr/dsbcfg.git

Building and Installing from Source (Qt5)

$ cd DSBMixer
$ cmake -S . -B build
$ cmake --build build

Then as root run

# cmake --install build

Building and Installing from Source (Qt6)

$ cd DSBMixer
$ cmake -D USE_QT6=ON -S . -B build
$ cmake --build build

Then as root run

# cmake --install build

Add the option -D WITHOUT_DEVD=ON to the first cmake command if you don’t want devd support.

Installing via pkg(8)

# pkg install dsbmixer

Installing from the FreeBSD Ports

# cd /usr/ports/audio/dsbmixer
# make install distclean

Usage

The Main Window

The main window consists of zero or more tabs, one for each installed sound card. You can switch between tabs by pressing Alt+n (n = 1, 2, …​, 9. n = 0 for the last tab). The master volume (Vol) of the active tab is indicated by the tray icon.

Figure 1. Main window

Uni-Channel View

By default, DSBMixer uses a single slider for each mixer device. Its value is the mean of both channels. If you increase the value by n, each channel is increase by a number ≤ n, such that its value is ≤ 100.

Example 1. Increasing left and right channel values

left channel = 97, right channel = 98. After increasing the value by 3, left channel is 100, and right channel is 100.

Example 2. Increasing left and right channel values

left channel = 42, right channel = 12. After increasing the value by 3, left channel is 45, and right channel is 15

Example 3. Increasing left and right channel values

left channel = 100, right channel = 12. After increasing the value by 3, left channel remains 100, and right channel is 15

Decreasing the channel value works accordingly.

Left and Right Channel View

Open the Preferences window under File → Preferences, and enable Show left and right channel in the View tab, and click Ok.

Figure 2. Left and Right Channel View

This view allows you to separately change the left and right channel. If you check the lock symbol between them, both channel values are equally increased (decreased) if one of them is increased (decreased). That is, their difference is constant.

Adding and Removing Recording Sources

Mixer devices capable of recording are indicated by a microphone icon and a checkbox above the slider. The checkbox lets you add (remove) the mixer device to (from) the set of recording sources.

ℹ️	Usually, you can not remove all recording sources. There must be at least one.

The Tray Icon

The tray icon indicates the master volume (Vol) of the active device tab. The icon shows four states

• muted

• low

• medium

• high

Hovering over the tray icon will open a tool tip which shows the current master volume in percent. If not configured to show the left and right channel separately, the displayed volume is the mean of both channels. The master volume can be increased/decreased by scrolling up/down on the tray icon. If possible, both channel volumes are equally increase/decreased.

Left-clicking on the tray icon will show/hide the main window.

Right-clicking will show the tray icon’s context menu.

Figure 3. Tray icon context menu

If you click on one of the listed devices, it will become the active device. That is, scrolling on the tray icon will change this device’s master volume. The active device is greyed out in the menu. The asterisk (*) marks the default device.

Tray Icon Theme

You can change the icon theme for the tray icon under File → Preferences → View

The Preferences Window

You can open the Preferences by File → Preferences

Default Device Tab

The Default device tab allows you to set the default audio device. This is the device where applications send their audio data to if not configured otherwise. If you press the Test sound button, the command besides is executed. By default, this sends random bytes from /dev/random to the selected sound card which produces some nasty white noise. If you can hear it, press Ok to make the selected sound card the default.

💡	You can change the test command to something that plays an audio file. Clicking on Ok makes this the default test command.

Figure 4. Changing the default audio device

ℹ️	Some audio applications must be restarted to use the new default device.

💡	When the default audio device was changed either through DSBMixer or other means, DSBMixer can restart sound daemons like sndiod and pulseaudio for you. Pulseaudio streams playing on the previous default audio device can be moved to the current one.

Figure 5. Moving pulseaudio streams to new default device

The Advanced Settings Tab

The Advanced tab allows you to configure various sound settings.

Figure 6. Advanced sound settings

Amplification

Lower values mean more amplification, but can produce sound clipping when chosen too low. Higher values mean finer volume control.

Sample rate converter quality

Higher values mean better sample rate conversion, but more memory and CPU usage.

Max. auto VCHANS

Defines the max. number of virtual playback and recording channels that can be created. Virtual channels allow programs to use more playback and recording channels than the physical hardware provides.

Latency (0 low, 10 high)

Higher values mean better sample rate conversion, but more memory and CPU usage.

Bypass mixer

Enable this to allow applications to use their own existing mixer logic to control their own channel volume.

The Applications Mixer

The applications mixer allows you to control the volume of each application currently using the sound system.

Figure 7. Applications Mixer

The D-Bus Interface

DSBMixer registers the D-Bus service org.dsb.dsbmixer. The interface org.dsb.dsbmixer under the path / provides the following methods:

VOID org.dsb.dsbmixer.setVol(UINT32 lvol, UINT32 rvol)

Sets the left and right volume of the master channel.

VOID org.dsb.dsbmixer.incVol(UINT32 amount)

Increases the volume of the master channel by amount.

VOID org.dsb.dsbmixer.decVol(UINT32 amount)

Decreases the volume of the master channel by amount.

VOID org.dsb.dsbmixer.mute(BOOLEAN on)

Mutes the master channel if on is true. Unmutes the master channel if on is false.

VOID org.dsb.dsbmixer.toggleMute()

Toggles the mute state of the master channel.

VOID org.dsb.dsbmixer.toggleAppsWin()

Toggles the visibility of the applications mixer.

The dsbmixer-dbus Script

The shell script dsbmixer-dbus can be used to call the methods above.

Examples

Set the master volume to 10:10

% dsbmixer-dbus setVol 10 10

Toggle the applications mixer window

% dsbmixer-dbus toggleAppsWin

Command-line

Usage

dsbmixer [-i]

Options

-i

Start DSBMixer as tray icon

Development

Contributing Translations

Available Translations

• French (incomplete)

• German

• Swedish (incomplete)

Instructions

Let’s say you want to add French translations, you can proceed as follows:

1. Create a fork of this repo, and clone it:

   % git clone url-of-your-fork

2. Install devel/qt5-linguist

3. cd to your-forked-dsbmixer-dir

4. Add locale/dsbmixer_fr.ts to the TS_FILES list in CMakeLists.txt.

5. In order to create the dsbmixer_fr.ts file, run

   Qt5

   % cd your-fork
   % cmake -S . -B build
   % cmake --build build

   or

   Qt6

   % cd your-fork
   % cmake -D USE_QT6=ON -S . -B build
   % cmake --build build -t dsbmixer_lupdate

6. Run linguist locale/dsbmixer_fr.ts

7. Add the file to the repo: git add locale/dsbmixer_fr.ts

8. Commit: git commit -am 'Add French translations.'

9. Send a pull request.

Configuring the Look and Behavior of Qt5 Applications

If you are not using KDE or GNOME, there are two ways to control the appearance of Qt5 applications:

• qt5ct and the Kvantum theme engine

• Qt5-style-plugins

qt5ct and the Kvantum Theme Engine

qt5ct

qt5ct is a tool that allows you to configure themes, fonts, and icons of Qt5 applications. It can be installed via pkg

# pkg install qt5ct

or via the FreeBSD ports:

# cd /usr/ports/misc/qt5ct
# make install

In order to make Qt5 applications use qt5ct, add the line export QT_QPA_PLATFORMTHEME=qt5ct to one of the following files, depending on how you start your X session:

Table 1. Session Files

X Session Start Method	File
SliM, startx, xinit	~/.xinitrc
GDM, LightDM, LXDM, SDDM	~/.xprofile
WDM, XDM	~/.xsession

Alternatively, you can add the line to your window manager’s startup script, or, if you are using a Bourne shell compatible login shell, to your ~/.profile.

After loggin out and in again, proceed with the next section.

Kvantum

Kvantum is a SVG-based theme engine for Qt, KDE and LXQt. Install it via pkg:

# pkg install Kvantum-qt5

or via the FreeBSD ports:

# cd /usr/ports/x11-themes/Kvantum
# make install distclean

Start qt5ct and choose kvantum under Appeareance → Style, and press Ok.

💡	You can use Kvantum directly without qt5ct by setting QT_STYLE_OVERRIDE=kvantum. Note, however, that the Kvantum Manager lacks the ability to change fonts and the icon theme.

Now you can start kvantummanager to set, install and configure themes.

💡	You can download Kvantum themes from KDE Store. Unpack them, and use the Kvantum Manager to install new themes.

Qt5-style-plugins

Qt5-style-plugins is a theme engine which allows using GTK-2 themes with Qt5 applications. Install it via pkg

# pkg install qt5-style-plugins

or via the FreeBSD ports

# cd /usr/ports/x11-themes/qt5-style-plugins
# make install distclean

In order to make Qt5 applications use qt5-style-plugins, add the line export QT_QPA_PLATFORMTHEME=gtk2 to one of the following files, depending on how you start your X session:

Table 2. Session Files

X Session Start Method	File
SliM, startx, xinit	~/.xinitrc
GDM, LightDM, LXDM, SDDM	~/.xprofile
WDM, XDM	~/.xsession

Alternatively, you can add the line to your window manager’s startup script, or, if you are using a Bourne shell compatible login shell, to your ~/.profile.

After loggin out and in again, your Qt5 applications should look like your GTK applications.