===== Sound & Audio =====

This page reflects the state of sound support in %%FreeBSD%% 10.0-RELEASE to 14.0-CURRENT. It documents things of interest to users and developers.

==== History ====

Sound support for %%FreeBSD%% began in 1993, when Jordan K. Hubbard imported version 1.0c of the generic Linux sound driver into %%FreeBSD%%, later known as the %%VoxWare%% sound drivers, written by Hannu Savolainen. This code was made available by Hannu under two different licenses: GPL for Linux and BSD for %%FreeBSD%%/Unix variants.

Several new versions of the %%VoxWare%% drivers were imported (and modified) into the %%FreeBSD%% base system between 1993 and 1997. At this time Amancio Hasty and Jim Lowe did most of the work on sound support in %%FreeBSD%%. The %%VoxWare%% drivers eventually became what we know today as OSS, the [[http://www.opensound.com/|Open Sound System]], maintained by Hannu and his team at 4Front Technologies. OSS has been considered a standard in the Linux world for many years (even if the ALSA project has become the number one choice nowadays, or ALSA has been defacto-replaced with other solutions like %%PulseAudio%% and/or pipewire). The last version to be imported was %%VoxWare%% 3.5-alpha6. By following the history it is evident that the sound API in %%FreeBSD%% has gradually evolved from the %%VoxWare%% standard, which later become the OSS standard.

However, things changed in 1997 as more of the foundation for the sound system we have today was laid out. Luigi Rizzo was maintaining his own set of patches for %%FreeBSD%% and in 1997 his sound code was [[http://docs.freebsd.org/cgi/getmsg.cgi?fetch=8330+0+archive/1997/cvs-sys/19970914.cvs-sys|imported]] by John-Mark Gurney as an alternate sound driver. This driver was a complete rewrite (with the exception of soundcard.h) of the existing code (%%VoxWare%% code + modifications from Amancio). One of the most important features was support for %%PnP%% and %%FreeBSD%% 2.2.6 was the first release where it was part of the %%FreeBSD%% kernel source tree. So, for a period of time we had two sound drivers available in the %%FreeBSD%% kernel source tree:

  * new code in ''%%sys/i386/isa/snd/%%'' by Luigi Rizzo called "pcm" driver
  * old code in ''%%sys/i386/isa/sound/%%'' obtained from %%VoxWare%% and modified for %%FreeBSD%%.

From 1997 to 1998, Luigi's code was maintained outside of the %%FreeBSD%% repository and was imported into %%FreeBSD%% whenever he cut a new release of his code.

In 1999, Cameron Grant rewrote the sound system for %%FreeBSD%% 4.0 (his new driver was referred to as "newpcm" at the time) and later on [[http://docs.freebsd.org/cgi/getmsg.cgi?fetch=1177021+0+archive/1999/cvs-all/19990905.cvs-all|imported]] his work to ''%%sys/dev/pcm%%'' and [[http://docs.freebsd.org/cgi/getmsg.cgi?fetch=593969+0+archive/1999/freebsd-current/19990905.freebsd-current|announced]] the change on the %%FreeBSD%% current mailing list. This superceded Luigi's pcm driver and it was [[http://docs.freebsd.org/cgi/getmsg.cgi?fetch=76641+0+archive/1999/cvs-all/19991003.cvs-all|removed]] from the tree a month later. Cameron's newpcm code used the newbus interface and supported a great deal of hardware. Not long after the import of newpcm, the sound [[http://docs.freebsd.org/cgi/getmsg.cgi?fetch=907682+0+archive/1999/cvs-all/19991121.cvs-all|code]] was [[http://docs.freebsd.org/cgi/getmsg.cgi?fetch=24322+0+archive/1999/cvs-all/19991128.cvs-all|moved]] again. This time it ended up in ''%%sys/dev/sound%%'', which also is the current location of all code belonging to the %%FreeBSD%% sound system. In the following years many things changed in the sound area. The amount of drivers for different hardware chips increased dramatically (especially for PCI and USB devices) and many improvements were made to the sound infrastructure, much thanks to Cameron Grant and Orion Hodson. Cameron [[http://lists.freebsd.org/pipermail/freebsd-announce/2005-March/000984.html|passed away]] in 2005, a major loss for the %%FreeBSD%% community.

Ariff Abdullah took over the maintainership of the pcm code in %%FreeBSD%% in 2005 and other individuals are taking care of the sound device drivers. Since then we've seen some dramatic changes in sound support including the volume per-channel adjustments, low-latency audio, multi-channel, locking removal, virtual channels, a high-quality resampler, a sync of the API to be compatible with OSSv4, as well as several rounds of device driver restructuring.

==== Features ====
  * Multi-channel audio
  * Mixing
  * Equalization
  * Volume per-channel
  * Bit-perfect modes
  * Low latency I/O, as well as latency profiles
  * Virtual channels, for recording from multiple sources with mixing
  * High-quality resampling, featuring either linear interpolation, a couple of different kinds of bandlimited SINC interpolation, or zero order hold
  * OSSv4 compatibility
  * Statistics
  * Runtime setting via sysctl

----

===== Documentation =====

==== FreeBSD Handbook ====
The //Multimedia// chatper includes [[https://docs.freebsd.org/en/books/handbook/multimedia/#sound-setup|Setting Up the Sound Card]]. This section includes advice on configuring audio devices, including Bluetooth.

==== Manual Pages ====
[[https://man.freebsd.org/cgi/man.cgi?query=sound&sektion=4&manpath=FreeBSD|sound(4)]] should be updated whenever a new feature is added – a first stop for information. The page describes all [[https://docs.freebsd.org/en/books/handbook/config/#configtuning-sysctl|sysctl]] audio parameters.

pcm(4) and snd(4) redirect to sound(4).

[[https://man.freebsd.org/cgi/man.cgi?query=sysctl&sektion=8&manpath=FreeBSD|sysctl(8)]] can help to learn about runtime configuration of sound:
  * the subtree of ''%%hw.snd%%'' represents the sound system
  * each subtree of ''%%dev.pcm%%'' represents a device.

Individual drivers:
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_ad1816&sektion=4&manpath=FreeBSD|snd_ad1816(4)]] – Analog Devices AD1816 ISA bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_als4000&sektion=4&manpath=FreeBSD|snd_als4000(4)]] – Avance Logic ALS4000 PCI bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_atiixp&sektion=4&manpath=FreeBSD|snd_atiixp(4)]] – ATI IXP bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_cmi&sektion=4&manpath=FreeBSD|snd_cmi(4)]] – CMedia CMI8338/CMI8738 PCI bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_cs4281&sektion=4&manpath=FreeBSD|snd_cs4281(4)]] – Crystal Semiconductor CS4281 PCI bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_csa&sektion=4&manpath=FreeBSD|snd_csa(4)]] – Crystal Semiconductor CS461x/462x/4280 PCI bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_ds1&sektion=4&manpath=FreeBSD|snd_ds1(4)]] – Yamaha DS-1 PCI     bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_emu10k1&sektion=4&manpath=FreeBSD|snd_emu10k1(4)]] – %%SoundBlaster%% Live! and Audigy PCI bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_emu10kx&sektion=4&manpath=FreeBSD|snd_emu10kx(4)]] – Creative %%SoundBlaster%% Live!        and Audigy sound cards device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_envy24&sektion=4&manpath=FreeBSD|snd_envy24(4)]] – VIA Envy24 and compatible bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_envy24ht&sektion=4&manpath=FreeBSD|snd_envy24ht(4)]] – VIA Envy24HT and compatible bridge        device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_es137x&sektion=4&manpath=FreeBSD|snd_es137x(4)]] – Ensoniq %%AudioPCI%% ES137x bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_ess&sektion=4&manpath=FreeBSD|snd_ess(4)]] – Ensoniq     ESS ISA %%PnP%%/non-%%PnP%% bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_fm801&sektion=4&manpath=FreeBSD|snd_fm801(4)]] – Forte Media FM801 bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_gusc&sektion=4&manpath=FreeBSD|snd_gusc(4)]] – Gravis %%UltraSound%% ISA bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_hda&sektion=4&manpath=FreeBSD|snd_hda(4)]] – Intel High Definition Audio bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_hdspe&sektion=4&manpath=FreeBSD|snd_hdspe(4)]] – RME HDSPe bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_ich&sektion=4&manpath=FreeBSD|snd_ich(4)]] – Intel ICH AC'97 and compatible bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_maestro&sektion=4&manpath=FreeBSD|snd_maestro(4)]] – ESS Maestro bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_maestro3&sektion=4&manpath=FreeBSD|snd_maestro3(4)]] – ESS Maestro3/Allegro-1 bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_mss&sektion=4&manpath=FreeBSD|snd_mss(4)]] – Microsoft Sound     System ISA %%PnP%%/non-%%PnP%% bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_neomagic&sektion=4&manpath=FreeBSD|snd_neomagic(4)]] – %%NeoMagic%% 256AV/ZX bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_sbc&sektion=4&manpath=FreeBSD|snd_sbc(4)]] – Creative Sound Blaster ISA and compatible bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_solo&sektion=4&manpath=FreeBSD|snd_solo(4)]] – ESS Solo-1/1E PCI bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_spicds&sektion=4&manpath=FreeBSD|snd_spicds(4)]] – I2S SPI audio codec driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_t4dwave&sektion=4&manpath=FreeBSD|snd_t4dwave(4)]] – Trident 4DWave bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_uaudio&sektion=4&manpath=FreeBSD|snd_uaudio(4)]] – USB audio and MIDI device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_via8233&sektion=4&manpath=FreeBSD|snd_via8233(4)]] – VIA Technologies VT8233 bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_via82c686&sektion=4&manpath=FreeBSD|snd_via82c686(4)]] – VIA Technologies 82C686A bridge device driver
  * [[https://man.freebsd.org/cgi/man.cgi?query=snd_vibes&sektion=4&manpath=FreeBSD|snd_vibes(4)]] – S3 %%SonicVibes%% bridge device driver

Not documented: ''%%snd_ai2s(4)%%'', ''%%snd_audiocs(4)%%'', ''%%snd_aureal(4)%%'', ''%%snd_csapcm(4)%%'' and ''%%snd_davbus(4)%%''.

----

===== Use Cases =====

==== Mixer ====

%%FreeBSD%% 14.0-CURRENT includes a [[https://man.freebsd.org/cgi/man.cgi?query=mixer&sektion=3&manpath=FreeBSD+14.0-current|mixer(3)]] library and a rewritten [[https://man.freebsd.org/cgi/man.cgi?query=mixer&sektion=8&manpath=FreeBSD+14.0-current|mixer(8)]]
utility. See [[https://margiolis.net/w/mixer_improvements/|Improvements on FreeBSD's sound mixer]] (Christos Margiolis, 2022-02-25).

Utilities to set/display sound card mixer values built on the %%FreeBSD%% Sound System:
  * CLI (built-in): [[https://man.freebsd.org/cgi/man.cgi?query=mixer&sektion=8&manpath=FreeBSD|mixer(8)]]
  * TUI (ncurses): [[https://www.freshports.org/audio/mixertui/|audio/mixertui]]
  * GUI (QT): [[https://www.freshports.org/audio/dsbmixer/|audio/dsbmixer]]

The ports collection also includes utilities such as [[https://www.freshports.org/audio/gtk-mixer/|GTK-Mixer]], which can set the default device.

The default device can be set at the command line. For example, prior to %%FreeBSD%% 14.0-CURRENT:

<code>
% cat /dev/sndstat
Installed devices:
pcm0: <Realtek ALC662 rev3 (Analog 2.0+HP/2.0)> (play/rec)
pcm1: <USB audio> (play/rec) default
No devices installed from userspace.

% sysctl hw.snd.default_unit=0
hw.snd.default_unit: 1 -> 0
</code>

– and with %%FreeBSD%% 14.0-CURRENT:

<code>
% mixer -a | grep ^pcm
pcm0:mixer: <Realtek ALC662 rev3 (Analog 2.0+HP/2.0)> on hdaa0 kld snd_hda (play/rec)
pcm1:mixer: <USB audio> at ? kld snd_uaudio (play/rec) (default)

% mixer -d0
default_unit: 1 -> 0
pcm1:mixer: <USB audio> at ? kld snd_uaudio (play/rec)
    vol       = 0.70:0.70     pbk
    pcm       = 0.75:0.75     pbk
</code>

==== Video conferencing (via browser) ====

=== OSS (simple) ===

Firefox 81 and greater support OSS. Audio devices can be selected at runtime.

=== sndio (intermediate) ===

The sndio audio framework was originally developed for %%OpenBSD%%.

[[https://www.freshports.org/www/chromium/|www/chromium]] uses sndio by default.

[[https://www.freshports.org/www/firefox/|www/firefox]] does not require sndio. [[https://github.com/mozilla/cubeb|cubeb]], Mozilla's cross-platform audio library, is patched on %%FreeBSD%% to make native use of OSS.

sndio integration for userspace programs.

By default, the PCM sound system in %%FreeBSD%% will create OSS(v4) compatible clones of the basename (ie. /dev/dsp is accessible via /dev/dspN[.N]). This works well for OSS-compatible userspace programs. By default sndio doesn't require a daemon, and just maps OSS /dev/dspN* devices to sndio rsnd/N devices that can be chosen at start-time via the environment variable AUDIODEVICE.

sndio 1.7.0 and greater allow different playback and recording devices through the environment variables AUDIOPLAYDEVICE and AUDIORECDEVICE.

=== sndio (using daemon) ===

In more complex cases you might use the sndio daemon:

<code>
$ sndiod
</code>

To make this permanent:

<code>
# sysrc -f /etc/rc.conf sndiod_enable="YES"
# service sndiod start
</code>

If "Audio device got stuck" occurs, it may help to set a flag then restart sndiod. See [[https://man.freebsd.org/cgi/man.cgi?query=sndiod&sektion=8&manpath=FreeBSD-Ports|sndiod(8)]] to understand the ''%%-a%%'' flag before doing this:

<code>
# sysrc -f /etc/rc.conf sndiod_flags="-a on"
</code>

This assumes that you have your soundcard(s) or snd_uaudio in your kernel configuration, like it is included in the GENERIC kernel configuration file.

=== virtual_oss (advanced) ===
It is not uncommon to need one device for loudspeakers and a different device for a microphone. More complicated setups include mixing three–five sources into a single audio stream that features effects, microphone, game/video audio, and/or music.

%%FreeBSDs%% in-kernel mixing allows [[https://www.freshports.org/audio/virtual_oss/|audio/virtual_oss]] to tell the kernel which devices to mix, to create a sndio-compatible composite device.

The following example assumes output of /dev/sndstat that is similar to this:

<code>
Installed devices:
pcm0: <Conexant CX20590 (Analog 2.0+HP/2.0)> (play/rec)
pcm1: <Conexant CX20590 (Ext-Rear Analog)> (play/rec) default
pcm2: <USB audio> (rec)
</code>

For reference, this lists the primary audio card as pcm1 and the secondary audio card as pcm2.
These can optionally be configured via nids as is the case with the [[Laptops/Thinkpad_T420|ThinkPad T420]] dock.

First, we install virtual_oss:

<code>
# pkg install audio/virtual_oss
</code>

Then edit the file which can start virtual_oss with the system:

<code>
less /usr/local/etc/rc.d/virtual_oss
</code>

This file can be a little complex, so to ease understanding, here is a key scheme:

<code>
-T /dev/sndstat \ # Register this device in /dev/sndstat
-C 2 -c 2 \ # Make sure we're only working with two channels
-S \ # Automatically resample using Project Z
-r 48000 \ # Use a supported sample rate
-b 24 \ # Use a supported sample depth
-s 1024 \ # Set the size of the buffer
-O /dev/dsp1 \ # Set pcm1 as the master device and playback device (default device for output)
-R /dev/dsp2 \ # Set pcm2 as the recording device (device for input)
-d dsp \ # Ensure that access via sndiod and the sndio library works
-t vdsp.ctl # Optional control device for this virtual OSS instance
</code>

You may also need to adjust the sample rate and depth of the various devices, if your devices don't support the values used in the above example. This can be done by checking /var/run/dmesg.boot or /var/log/messages, or by looking through sysctl OIDs in the dev.pcm namespace.

Resampling using [[https://people.freebsd.org/~ariff/z_comparison/|Project Z]] uses the high-quality resampler mentioned elsewhere on this page.

After this, run the following commands to enable and start virtual_oss:

<code>
# service virtual_oss enable
# service virtual_oss start
</code>

The audio device can also be changed run-time without having to restart virtual_oss, give that the virtual_oss instance installed a control device:

<code>
# virtual_oss_cmd /dev/vdsp.ctl -f /dev/dsp0
# virtual_oss_cmd /dev/vdsp.ctl -f /dev/dsp3
</code>

Optionally we also need to enable sndiod and start it (this step is only necessary if sndiod is used):

<code>
# service sndiod enable
# service sndiod start
</code>

With this, these settings will persist across reboots.

Finally, to check that the device is installed correctly, check /dev/sndstat again:

<code>
$ cat /dev/sndstat
Installed devices:
pcm0: <Conexant CX20590 (Analog 2.0+HP/2.0)> (play/rec)
pcm1: <Conexant CX20590 (Ext-Rear Analog)> (play/rec) default
pcm2: <USB audio> (rec)
Installed devices from userspace:
dsp: <Virtual OSS> (play/rec)
</code>

With the dsp device registered as installed from userspace, Firefox and Chromium should correctly identify the audio source(s) that are mixed in the kernel, both output and input, if available) and work with video conferencing.

It should be noted that this is, at present, somewhat incompatible with the simple sndiod setup noted above, as this involves removing and adding various devices - so the two setups should not be used in conjunction.

Your browser may need to have some setting(s) adjusted to pick up on sndio, rather than preferring pulse if that's installed. In Firefox this can be done by adding/changing the media.cubeb.backend OID in the Firefox about:config. Alternatively, %%PulseAudio%% can be removed if it's not needed.

Note: To use virtual_oss you could also edit ''%%/etc/rc.conf.d/virtual_oss%%'', an example

<code>
virtual_oss_enable="YES"
virtual_oss_dsp="-T /dev/sndstat -S -i 8 -C 18 -c 18 -r 48000 -b 32 -s 512 -f /dev/dsp0 -c 2 -d dsp -c 18 -d vdsp -t vdsp.ctl"
</code>

=== Redirecting full duplex audio from a remote machine (advanced) ===

You need to install virtual_oss and HpsJam. Then use virtual_oss(8) to create a fake /dev/dsp audio device, like shown below.

<code>
echo virtual_oss -i 8 -B -S -Q 0 \
        -T /dev/sndstat \
        -c 4 -r 48000 -b 32 -s 4ms -f /dev/null \
        -b 32 -c 2 -m 0,0,1,1 -d dsp \
        -b 32 -c 2 -m 2,2,3,3 -d dsp.jack \
        -M x,0,2,0,0,0 \
        -M x,1,3,0,0,0 \
        -M x,2,0,0,0,0 \
        -M x,3,1,0,0,0 \
        -t vdsp.ctl | su
</code>

Then start a %%HpsJAM%% server instance, like shown below.

<code>
echo HpsJam --server --peers 44 --ncpu 4 --cli-port 222 --port 700 --daemon --rtprio 8 | su
</code>

Then start jackd as a regular user, like shown below.

<code>
rtprio 8 jackd -d oss -d /dev/dsp.jack -r 48000 -p 256 &
</code>

Then start HpsJam as a regular user, either via the terminal or X.org:

<code>
HpsJam --mute-peer-audio --connect <your_server_ip:700>
</code>

On another machine use the HpsJam software to connect to the same HpsJam server instance.
Multiple devices may connect to your server instance of HpsJam.
This allows you to easily move from one device to another.
Then you can basically use any audio application on the remote machine at very low latency.
Also remember to add your regular user to the "realtime" group and load the mac_priority.ko .

=== Chrome linux-binary ===

[[https://forums.freebsd.org/threads/linuxulator-how-to-run-google-chrome-linux-binary-on-freebsd.77559/|[Linuxulator  How to run Google Chrome (linux-binary) on FreeBSD]]: sound, webcam, microphone, hardware acceleration all properly work.

==== FreeBSD in Audio Studio ====

Fosdem 2019 talk and slides: [[https://archive.fosdem.org/2019/schedule/event/freebsd_in_audio_studio/|FreeBSD in Audio Studio]], "%%FreeBSD%% is usually not the first choice for music art, but it has quite a lot to offer".

==== Audio profile ====

Audio profiles can be handled in userspace by:
  * [[https://man.freebsd.org/mixer/8|mixer(8)]] via -s option
  * [[https://www.freshports.org/audio/mixertui|<audio/mixertui>]] via -P/-p options and P/p keys, [[https://gitlab.com/alfix/mixertui/-/issues/4|example]]

----

===== Bridge Device Drivers =====

==== How it works ====
TODO A few words on what the bridge device driver are and what they do.

==== Driver Matrix ====

^ Driver ^ License ^ Type ^ Arch ^ Maintainer ^
| [[https://man.freebsd.org/snd_ad1816/4|snd_ad1816(4)]] | BSD | isa |  |  |
| snd_ai2s(4) | BSD | macio | powerpc | [[marcotrillo@gmail.com|Marco Trillo]], [[nwhitehorn@FreeBSD.org|Nathan Whitehorn]] |
| [[https://man.freebsd.org/snd_als4000/4|snd_als4000(4)]] | BSD | pci |  |  |
| [[https://man.freebsd.org/snd_atiixp/4|snd_atiixp(4)]] | BSD | pci |  | [[ariff@FreeBSD.org|Ariff Abdullah]] |
| snd_audiocs(4) | BSD | sbus | sparc64 |  |
| snd_aureal(4) | BSD | pci |  |  |
| [[https://man.freebsd.org/snd_cmi/4|snd_cmi(4)]] | BSD | pci |  |  |
| [[https://man.freebsd.org/snd_cs4281/4|snd_cs4281(4)]] | BSD | pci |  |  |
| [[https://man.freebsd.org/snd_csa/4|snd_csa(4)]] | BSD | pci |  |  |
| snd_csapcm(4) | BSD | pci |  |  |
| snd_davbus(4) | BSD | macio | powerpc | [[marcotrillo@gmail.com|Marco Trillo]], [[nwhitehorn@FreeBSD.org|Nathan Whitehorn]] |
| [[https://man.freebsd.org/snd_atiixp/4|snd_atiixp(4)]] | BSD? | pci |  |  |
| [[https://man.freebsd.org/snd_emu10k1/4|snd_emu10k1(4)]] | BSD | pci |  |  |
| [[https://man.freebsd.org/snd_emu10kx/4|snd_emu10kx(4)]] | BSD | pci |  | [[yuriy.tsibizov@gfk.ru|Yuriy Tsibizov]] |
| [[https://man.freebsd.org/snd_envy24/4|snd_envy24(4)]] | BSD | pci |  | [[kosio.dimitrov@gmail.com|Konstantin Dimitrov]] |
| [[https://man.freebsd.org/snd_envy24ht/4|snd_envy24ht(4)]] | BSD | pci |  | [[kosio.dimitrov@gmail.com|Konstantin Dimitrov]] |
| [[https://man.freebsd.org/snd_es137x/4|snd_es137x(4)]] | BSD | pci |  |  |
| [[https://man.freebsd.org/snd_ess/4|snd_ess(4)]] | BSD | isa |  |  |
| [[https://man.freebsd.org/nd_fm801/4|snd_fm801(4)]] | BSD | pci |  |  |
| [[https://man.freebsd.org/snd_gusc/4|snd_gusc(4)]] | BSD | isa |  |  |
| [[https://man.freebsd.org/snd_hda/4|snd_hda(4)]] | BSD | pci |  | [[mav@FreeBSD.org|Alexander Motin]] |
| [[https://man.freebsd.org/snd_hdspe/4|snd_hdspe(4)]] | BSD | pci |  | [[br@bsdpad.com|Ruslan Bukin]] |
| [[https://man.freebsd.org/snd_ich/4|snd_ich(4)]] | BSD | pci |  |  |
| [[https://man.freebsd.org/snd_maestro/4|snd_maestro(4)]] | BSD | pci |  |  |
| [[https://man.freebsd.org/snd_maestro3/4|snd_maestro3(4)]] | BSD | pci |  | Untested |
| [[https://man.freebsd.org/snd_mss/4|snd_mss(4)]] | BSD | isa |  |  |
| [[https://man.freebsd.org/snd_neomagic/4|snd_neomagic(4)]] | BSD | pci |  |  |
| [[https://man.freebsd.org/snd_sb16/4|snd_sb16(4)]] | BSD | isa |  |  |
| [[https://man.freebsd.org/snd_sb8/4|snd_sb8(4)]] | BSD | isa |  |  |
| [[https://man.freebsd.org/snd_sbc/4|snd_sbc(4)]] | BSD | isa |  |  |
| [[https://man.freebsd.org/snd_solo/4|snd_solo(4)]] | BSD | pci |  |  |
| [[https://man.freebsd.org/snd_spicds/4|snd_spicds(4)]] | BSD | pci |  | [[kosio.dimitrov@gmail.com|Konstantin Dimitrov]] |
| [[https://man.freebsd.org/snd_t4dwave/4|snd_t4dwave(4)]] | BSD | pci |  |  |
| [[https://man.freebsd.org/snd_via8233/4|snd_via8233(4)]] | BSD | pci |  |  |
| [[https://man.freebsd.org/snd_via82c686/4|snd_via82c686(4)]] | BSD | pci |  |  |
| [[https://man.freebsd.org/snd_uaudio/4|snd_uaudio(4)]] | BSD | usb |  |  |

==== snd_emu10kx ====
This driver now has the possibility to do multichannel recording. This is not for official use, it is only to be able to play around and develop this further until the generic parts of the soundsystem gain the possibility to handle multichannel streams.

=== Optional multichannel recording ===

(32 channels on Live!, 64 channels on Audigy)

All channels are 16bit/48000Hz/mono, format is fixed. Half of them are copied from sound output, another half can be used to record any data from DSP. What should be recorded is hardcoded in DSP code. In this version it records dummy data, but can be used to record all DSP inputs, for example.

Because there are no support of more-than-stereo sound streams multichannell stream is presented as one 32(64)*48000 Hz 16bit mono stream.

=== Channel map ===

SB Live! (4.0/5.1):

^ offset (words) ^ substream ^
| 0x00 | Front L |
| 0x01 | Front R |
| 0x02 | Digital Front L |
| 0x03 | Digital Front R |
| 0x04 | Digital Center |
| 0x05 | Digital Sub |
| 0x06 | Headphones L |
| 0x07 | Headphones R |
| 0x08 | Rear L |
| 0x09 | Rear R |
| 0x0A | ADC (multi-rate recording) L |
| 0x0B | ADC (multi-rate recording) R |
| 0x0C | unused |
| 0x0D | unused |
| 0x0E | unused |
| 0x0F | unused |
| 0x10 | Analog Center (Live! 5.1) / dummy (Live! 4.0) |
| 0x11 | Analog Sub (Live! 5.1) / dummy (Live! 4.0) |
| 0x12..-0x1F | dummy |

Audigy / Audigy 2 / Audigy 2 Value / Audigy 4:

^ offset (words) ^ substream ^
| 0x00 | Digital Front L |
| 0x01 | Digital Front R |
| 0x02 | Digital Center |
| 0x03 | Digital Sub |
| 0x04 | Digital Side L (7.1 cards) / Headphones L (5.1 cards) |
| 0x05 | Digital Side R (7.1 cards) / Headphones R (5.1 cards) |
| 0x06 | Digital Rear L |
| 0x07 | Digital Rear R |
| 0x08 | Front L |
| 0x09 | Front R |
| 0x0A | Center |
| 0x0B | Sub |
| 0x0C | Side L |
| 0x0D | Side R |
| 0x0E | Rear L |
| 0x0F | Rear R |
| 0x10 | output to AC97 input L (muted) |
| 0x11 | output to AC97 input R (muted) |
| 0x12 | unused |
| 0x13 | unused |
| 0x14 | unused |
| 0x15 | unused |
| 0x16 | ADC (multi-rate recording) L |
| 0x17 | ADC (multi-rate recording) R |
| 0x18 | unused |
| 0x19 | unused |
| 0x1A | unused |
| 0x1B | unused |
| 0x1C | unused |
| 0x1D | unused |
| 0x1E | unused |
| 0x1F | unused |
| 0x20..0x3F | dummy |

==== snd_envy24* ====
Envy24-based cards are the only consumer soundcards to far, that can offer true quality. They are 'bit-perfect' (no resampling) and use high-quality I2S codecs. That is why most of them -- even not professional grade ones -- have quality and features of professional boards.

[[kosio.dimitrov@gmail.com|Konstantin Dimitrov]] is the only person that is working on the Envy24 support under %%FreeBSD%% and his free time for that is very limited, so it will be extremely slow and when you look at [[https://web.archive.org/web/20090209195200/http://envy24.svobodno.com/|envy24.svobodno.com]], in the table, you will see how much work should be done (and the table is far from being full). For example there is no code at all for DITs (Digital Interface Transceivers) and if someone write module for DITs, like 'spicds' module, it can be reused by many audio drivers, for example Creative. At least on their new boards they use the same DIT ICs like the ones on Envy24-based boards, so the work exceeds far beyond dealing with Envy24 chips. Any help by owners of Envy24 based cards is more than welcome.

From an user point of view the behavior of snd_envy24(4) and snd_envy24ht(4) (and snd_spicds(4%%))%% is stable enough, however they are highly experimental drivers and need a serious clean-up.

Currently Konstantin is working on adding support for all chips from the VT172x family and more hardware designs. Compared to extending the existing features, this is a huge amount of work. Every Envy24-based card has an unique hardware design. For this reason adding support for an Envy24-based card requires as a first step to reverse engineer the card hardware design. This step takes a huge part of the time to support a card.

The Envy24HT (VT1724) code initially intended for use with the Envy24HT-based card "Terratec Aureon 7.1 Space" actually proved itself to work with all other VT172x chips -- Envy24PT (VT1720), Envy24MT (VT1720T), Envy24HT-S (VT1721), Envy24GT (VT1722) and Envy24DT (VT1723 aka Tremor) -- with minor or no Envy24-related changes at all. This will affect the future of snd_envy24ht(4) and it may be renamed to "snd_vt172x(4)".

Support for cards that use I2C-to-GPIO expanders wired between the control line of the codec and the Envy24 chip is upcomming. This will affect snd_envy24(4). At the moment snd_envy24(4) supports only 3 cards. The work Konstantin is doing ATM may result in support for all VT1712-based cards made by Terratec and M-Audio. Probably then snd_envy24(4) will support about 10 cards then.

snd_envy24ht(4) already has support for more than 10 cards, including all cards made by Terratec and M-Audio that are based on VT172x. Support for cards that are made by the third major manufacturer of Envy24-based cards -- ESI and their consumer division Audiotrak -- is lacking because their cards are hard to find outside Korea and Japan. Konstantin thinks they made the best Envy24-based cards out there. So if you are willing to spend such a card, feel free to him/us.

The next update to snd_envy24ht(4) will maybe support the "Philips PSC724 Ultimate Edge", "Hercules Fortissimo4" and the very new "Audiotrak Prodigy 7.1 %%HiFi%%". They all are VT172x-based cards which use the WM8766+WM8776 chips and share the same hardware design.

All of this work to support all chips from the VT172x family and all possible hardware designs takes a huge amount of work and only covers the analog playback. Other features like recording, support for all hardware mixers, MIDI and all other features the envy24 chips provide are not implemented. Adding one of those features after each other -- at least for those chips where Konstantin collected the datasheets -- should be easy. It is not that time consuming, but Konstantin can not spend time for them. Anyone interested in some of those features is encouraged to have a look at the datasheets [[https://web.archive.org/web/20090209195200/http://envy24.svobodno.com/|envy24.svobodno.com]] and to send some patches.

----

===== Development =====

==== Implementation ====

  * Code: https://cgit.freebsd.org/src/tree/sys/dev/sound
  * Header: https://cgit.freebsd.org/src/tree/sys/sys/soundcard.h
  * Mirror: https://github.com/freebsd/freebsd/tree/master/sys/dev/sound

==== Open Tasks and Projects ====

  * Add Multichannel support to sound drivers. Multichannel support is already present in the sound system, so implementing it in the drivers should be trivial.
  * Find out if there are things to port from OSS.
  * <del>Contact GPL license holders and ask for permission to re-license to BSD, alternatively port the missing stuff from OSS</del> Done for 9.1.
  * Add OSSv4 ioctls: [[RyanBeasley/ioctlref#todo|missing]], [[RyanBeasley/ioctlref#hmpf|undocumented-missing]] and [[RyanBeasley/ioctlref#stub2|stubs]]
  * Add missing driver manuals

==== Getting started your projects ====

The sound system is OSSv4 compatible so you can use its API to interface to the kernel and hardware:

  * [[http://www.opensound.com|The Open Sound System (OSS)]]
    * [[http://manuals.opensound.com/developer/|OSS API Documentation]]
    * [[http://manuals.opensound.com/sources/|OSS Internals]]
    * [[http://developer.opensound.com/sources/|OSS Source Code Repository]]
  * %%FreeBSD%% implementation:
    * [[RyanBeasley/ioctlref|IOCTL Reference]], from [[RyanBeasley]]
    * [[RyanBeasley/Notes/snd_locking|Locking]] in the Sound System, from [[RyanBeasley]]

Moreover the sound system is settable via [[https://man.freebsd.org/sysctl/3|sysctl(3)]], the audio objects are documented in [[https://man.freebsd.org/sound/4|sound(4)]], briefly:

  * the subtree of ''%%hw.snd%%'' represents the sound system
  * each child (and its subtree) of ''%%dev.pcm%%'' represents a device

==== Write new Driver ====

New driver resources:

  * The %%FreeBSD%% Architecture Handbook: [[https://www.freebsd.org/doc/en/books/arch-handbook/oss.html|Sound Subsystem]]
  * %%FreeBSD%% Kernel Sound Device Code Reference Manual: [[http://www.leidinger.net/FreeBSD/src_docs/dev_sound.pdf|Doxygen PDF]], from [[AlexanderLeidinger]]
  * [[http://people.freebsd.org/~ariff/|Patches and docs]], from [[AriffAbdullah]]
  * [[http://people.freebsd.org/~cg/template.c|Sound Driver Template]], from Cameron Grant
    * The [[https://man.freebsd.org/device/9|device(9)]] manual page
    * The [[https://man.freebsd.org/driver/9|driver(9)]] manual page
    * The [[https://man.freebsd.org/devclass/9|devclass(9)]] manual page
  * [[https://www.sofproject.org/|Sound Open Firmware]]
  * [[https://kernelnomicon.org/texts/sbc-audio.html|Audio Subsystem on Single Board Computers]], from [[OleksandrTymoshenko]]

----

===== Problems =====

==== Troubleshooting ====

  * New laptop, no sound in spite of driver attaching (freebsd-hackers mailing list):
    * [[https://lists.freebsd.org/pipermail/freebsd-hackers/2018-April/052737.html|April emails]]
    * [[https://lists.freebsd.org/pipermail/freebsd-hackers/2018-May/052753.html|May emails]]
  * Mailing list for [[https://lists.freebsd.org/mailman/listinfo/freebsd-multimedia|multimendia]] and audio support.
  * %%FreeBSD%% has a web based forum, the [[https://forums.freebsd.org/forums/multimedia-gaming.19/|Multimedia subforum]] is a good place to discuss sound issues.

==== Open Problem Reports ====

Everyone is encouraged to look at the following reports and fix things, if possible. If a report appears odd, or if you think that the problem has been fixed, add a comment to the report.

=== Critical problems ===

  * No problems at the moment

=== Serious problems ===

  * [[https://bugs.freebsd.org/80040|usb/80040]] - [sound] [hang] Use of sound mixer causes system freeze with uaudio driver
  * [[https://bugs.freebsd.org/94279|kern/94279]] - [sound] [snd_neomagic] snd_neomagic crashes on %%FreeBSD%% 5.4 and 6.0
  * [[https://bugs.freebsd.org/97535|kern/97535]] - [sound] [snd_mss] doesn't work in 6.0-RELEASE and above for Crystal soundcards
  * [[https://bugs.freebsd.org/104874|kern/104874]] - [sound] [snd_emu10k1] kldload snd_emu10k1 hangs system
  * [[https://bugs.freebsd.org/107516|kern/107516]] - [sound] [snd_emu10k1] - skips, clicks and lag after a day of heavy usage
  * [[https://bugs.freebsd.org/114760|kern/114760]] - [sound] [snd_cmi] snd_cmi driver causing sporadic system hangs
  * [[https://bugs.freebsd.org/119759|kern/119759]] - [sound] [snd_emu10k1] [regression] Can not record anything with emu10k1 on 7.0-PRERELEASE (Invalid argument)
  * [[https://bugs.freebsd.org/124319|kern/124319]] - [sound] [snd_emu10k1] [regression] Cannot record from second card when two cards are in system
  * [[https://bugs.freebsd.org/132848|kern/132848]] - [sound] [snd_emu10kx] driver problem with card init, snd_emu10k1 inits card correctly

=== Non-critical problems ===

  * [[https://bugs.freebsd.org/23546|kern/23546]] - [sound] [snd_csa] [patch] csa DMA-interrupt problem
  * [[https://bugs.freebsd.org/62077|bin/62077]] - [sound] [patch] Make it possible to abbreviate mixer(8) device names
  * [[https://bugs.freebsd.org/72995|kern/72995]] - [sound] Intel ICH2 (82801BA) - sound nearly inaudible
  * [[https://bugs.freebsd.org/75137|conf/75137]] - [sound] add snd_* modules support to /etc/rc.d/mixer
  * [[https://bugs.freebsd.org/87782|kern/87782]] - [sound] snd_t4dwave and pcm0:record:0: record interrupt timeout, channel dead
  * [[https://bugs.freebsd.org/98496|kern/98496]] - [sound] [snd_ich] some functions don't work in my sound kernel module
  * [[https://bugs.freebsd.org/100859|kern/100859]] - [sound] [snd_ich] snd_ich broken on GIGABYTE 915 system
  * [[https://bugs.freebsd.org/115300|kern/115300]] - [sound] [snd_hda] [regression] snd_hda(4) fails to attach on -CURRENT
  * [[https://bugs.freebsd.org/120780|kern/120780]] - [sound] [snd_hda] snd_hda doesn't work on Dell Latitutude D530
  * [[https://bugs.freebsd.org/120857|kern/120857]] - [sound] [snd_emu10k1] snd_emu10k1 driver issues a warning on unload
  * [[https://bugs.freebsd.org/121962|kern/121962]] - [sound] [snd_emu10k1] [panic] Kernel panics with device polling and snd_emu10k1.ko enabled and network load
  * [[https://bugs.freebsd.org/125756|kern/125756]] - [sound] [patch] cannot detect soft-modem on HDA bus
  * [[https://bugs.freebsd.org/129604|kern/129604]] - [sound] Sound stops with error: pcm0:virtual:dsp0.vp0: play interrupt timeout, channel dead
  * [[https://bugs.freebsd.org/132511|kern/132511]] - [sound] [snd_hda] Probing ALC888 codec on ASRock %%K10N78%%-1394 fails
  * [[https://bugs.freebsd.org/133503|powerpc/133503]] - [sound] Sound stutter after switching ttys
  * [[https://bugs.freebsd.org/134767|kern/134767]] - [sound] [snd_hda] [regression] Sigmatel STAC9205X no sound under RELENG_7_2_0_RELEASE

==== Reporting Bugs ====

If you have found a bug, make sure that you report it. There are two preferred ways to report bugs and problems concerning the %%FreeBSD%% sound system:
  - Use the [[https://bugs.freebsd.org/bugzilla/enter_bug.cgi|web interface]] to send bug report, it gets archived in the %%FreeBSD%% bug database.
  - Send it directly to the [[https://lists.freebsd.org/mailman/listinfo/freebsd-multimedia|FreeBSD multimedia mailing list]].

The %%FreeBSD%% sound system can spit out quite a lot of debug information if you know how to access it.  This is a list of things that you probably should include in a good bug report.

What version of %%FreeBSD%% are we running:

<code>
% uname -a
FreeBSD foo.bar.com 13.0-CURRENT FreeBSD 13.0-CURRENT #0 r360723: Thu May  7 04:33:35 UTC 2020     root@foo.bar.com:/usr/obj/usr/src/amd64.amd64/sys/GENERIC  amd64
</code>

Status of the sound module:

<code>
% cat /dev/sndstat
Installed devices:
pcm0: <AudioPCI ES1371-A> at io 0x2040 irq 16 kld snd_es137x [MPSAFE] (2p:1v/1r:1v channels duplex default)
</code>

Mixer values:

<code>
% mixer
Mixer vol      is currently set to  75:75
Mixer pcm      is currently set to  75:75
Mixer line     is currently set to  75:75
Mixer mic      is currently set to   0:0
Mixer cd       is currently set to  75:75
Mixer rec      is currently set to   0:0
Mixer igain    is currently set to   0:0
Mixer line1    is currently set to  75:75
Mixer phin     is currently set to   0:0
Mixer video    is currently set to  75:75
Recording source: mic
</code>

The hw.snd sysctl tree:

<code>
% sysctl hw.snd
hw.snd.feeder_rate_quality: 1
hw.snd.feeder_rate_round: 25
hw.snd.feeder_rate_max: 2016000
hw.snd.feeder_rate_min: 1
hw.snd.feeder_rate_polyphase_max: 183040
hw.snd.feeder_rate_presets: 100:8:0.85 100:36:0.92 100:164:0.97
hw.snd.feeder_eq_exact_rate: 0
hw.snd.feeder_eq_presets: PEQ:16000,0,2500,62,0,2500:-9,9,1,0:44100,48000,88200,96000,176400,192000
hw.snd.vpc_reset: 0
hw.snd.vpc_0db: 45
hw.snd.vpc_autoreset: 1
hw.snd.latency_profile: 1
hw.snd.latency: 5
hw.snd.report_soft_matrix: 1
hw.snd.report_soft_formats: 1
hw.snd.compat_linux_mmap: 0
hw.snd.vpc_mixer_bypass: 1
hw.snd.verbose: 1
hw.snd.maxautovchans: 16
hw.snd.default_unit: 0
hw.snd.version: 2009061500/i386
hw.snd.default_auto: 0
</code>

The dev.pcm sysctl tree:

<code>
$ sysctl dev.pcm
dev.pcm.0.%desc: AudioPCI ES1371-A
dev.pcm.0.%driver: pcm
dev.pcm.0.%location: slot=2 function=0 handle=\_SB_.PCI0.P2P0.S3F0
dev.pcm.0.%pnpinfo: vendor=0x1274 device=0x1371 subvendor=0x1274 subdevice=0x1371 class=0x040100
dev.pcm.0.%parent: pci2
dev.pcm.0.play.vchans: 1
dev.pcm.0.play.vchanmode: fixed
dev.pcm.0.play.vchanrate: 48000
dev.pcm.0.play.vchanformat: s16le:2.0
dev.pcm.0.rec.vchans: 1
dev.pcm.0.rec.vchanmode: fixed
dev.pcm.0.rec.vchanrate: 48000
dev.pcm.0.rec.vchanformat: s16le:2.0
dev.pcm.0.buffersize: 4096
dev.pcm.0.bitperfect: 0
dev.pcm.0.latency_timer: 64
dev.pcm.0.polling: 0
dev.pcm.0.wake: 0
</code>

Verbose boot. First, reboot your machine. When the startup menu appear, choose option number 5 to boot with verbose messages turned on. When the machine has booted, use the grep utility to find startup messages related to the sound system:

<code>
% dmesg | grep 'pcm[0-9]'
pcm0: <AudioPCI ES1371-A> port 0x2040-0x207f irq 16 at device 2.0 on pci2
pcm0: Reserved 0x40 bytes for rid 0x10 type 4 at 0x2040
pcm0: <Cirrus Logic CS4297A AC97 Codec (id = 0x43525913)>
pcm0: Codec features 6 bit master volume, no 3D Stereo Enhancement
pcm0: ac97 codec dac ready count: 0
pcm0: Mixer "vol":
pcm0: Mixer "pcm":
pcm0: Mixer "line":
pcm0: Mixer "mic":
pcm0: Mixer "cd":
pcm0: Mixer "rec":
pcm0: Mixer "igain":
pcm0: Mixer "line1":
pcm0: Mixer "phin":
pcm0: Mixer "video":
pcm0: [MPSAFE]
pcm0: [ITHREAD]
pcm0: clone manager: deadline=750ms flags=0x8000001e
pcm0: sndbuf_setmap 1f3c000, 1000; 0xc473c000 -> 1f3c000
pcm0: sndbuf_setmap 1f3e000, 1000; 0xc473e000 -> 1f3e000
pcm0: sndbuf_setmap 1f40000, 1000; 0xc4740000 -> 1f40000
pcm0: <Playback: DAC1,DAC2 / Record: ADC>
</code>

----

{{tag>HowTo Project Docs}}