:toc: :toc-position: preamble :toclevels: 4 ifdef::env-github[] :tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning: endif::[]
= DSBMixer - a tabbed Qt mixer application for FreeBSD
toc::[]
== 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.
image::images/mainwin.png[Main window]
== Installation
=== Building from Source
==== Build Dependencies (Qt5)
==== Build Dependencies (Qt6)
==== Run time Dependencies
==== Getting the Source Code
==== Building and Installing from Source (Qt5)
Then as root run
==== Building and Installing from Source (Qt6)
Then as root run
Add the option -D WITHOUT_DEVD=ON to the first cmake command if you
don't want devd support.
=== Installing via pkg(8)
=== Installing from the FreeBSD Ports
== 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,tray icon>>.
.Main window image::images/mainwin.png[Main window]
[[uniview]] ==== 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.
Decreasing the channel value works accordingly.
[[lrview]] ==== 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.
.Left and Right Channel View image::images/mainwin-lr.png[]
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.
[[tray-icon]] === The Tray Icon
The tray icon indicates the master volume (Vol) of the active device tab. The icon shows four states
Hovering over the tray icon will open a tool tip which shows the current master volume in percent. If not <<lrview, 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 <<uniview,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.
.Tray icon context menu image::images/tray-menu.png[]
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
[[prefs-win]] === 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.
.Changing the default audio device image::images/prefs-default.png[]
.Moving pulseaudio streams to new default device image::images/restart.png[]
==== The Advanced Settings Tab
The Advanced tab allows you to configure various sound settings.
.Advanced sound settings image::images/prefs-advanced.png[]
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.
.Applications Mixer image::images/apps-mixer.png[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
=== Command-line
==== Usage
dsbmixer [-i]
==== Options
-i:: Start DSBMixer as tray icon
== Development
=== Contributing Translations
==== Available Translations
==== Instructions Let's say you want to add French translations, you can proceed as follows:
cd to your-forked-dsbmixer-dir
. Add locale/dsbmixer_fr.ts to the TS_FILES list in CMakeLists.txt.
. In order to create the dsbmixer_fr.ts file, run
+
.Qt5
[source,sh]. Run linguist locale/dsbmixer_fr.ts
. Add the file to the repo: git add locale/dsbmixer_fr.ts
. Commit: git commit -am 'Add French translations.'
. 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:
[[kvantum]] === qt5ct and the Kvantum Theme Engine
==== qt5ct
https://freshports.org/misc/qt5ct[_qt5ct_] is a tool that allows you to
configure themes, fonts, and icons of Qt5 applications.
It can be installed via pkg
or via the FreeBSD ports:
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:
[[session_files]]
.Session Files
[options="header,footer"]
|==================================================
|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
https://www.freshports.org/x11-themes/Kvantum[_Kvantum_] is a SVG-based theme
engine for Qt, KDE and LXQt. Install it via pkg:
or via the FreeBSD ports:
Start qt5ct and choose kvantum under Appeareance -> Style, and
press Ok.
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.
[[qt5-style-plugins]] === Qt5-style-plugins
https://www.freshports.org/x11-themes/qt5-style-plugins/[Qt5-style-plugins]
is a theme engine which allows using GTK-2 themes with Qt5 applications.
Install it via pkg
or via the FreeBSD ports
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:
.Session Files
[options="header,footer"]
|==================================================
|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.