path: root/static/freebsd/man4/pcm.4 3.html

<table class="head">
  <tr>
    <td class="head-ltitle">SOUND(4)</td>
    <td class="head-vol">Device Drivers Manual</td>
    <td class="head-rtitle">SOUND(4)</td>
  </tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">sound</code>, <code class="Nm">pcm</code>,
    <code class="Nm">snd</code> &#x2014;
    <span class="Nd"><span class="Ux">FreeBSD</span> PCM audio device
    infrastructure</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp">To compile this driver into the kernel, place the following line
    in your kernel configuration file:</p>
<div class="Bd Pp Bd-indent"><code class="Cd">device sound</code></div>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <code class="Nm">sound</code> driver is the main component of
    the <span class="Ux">FreeBSD</span> sound system. It works in conjunction
    with a bridge device driver on supported devices and provides PCM audio
    record and playback once it attaches. Each bridge device driver supports a
    specific set of audio chipsets and needs to be enabled together with the
    <code class="Nm">sound</code> driver. PCI and ISA PnP audio devices identify
    themselves so users are usually not required to add anything to
    <span class="Pa">/boot/device.hints</span>.</p>
<p class="Pp">Some of the main features of the <code class="Nm">sound</code>
    driver are: multichannel audio, per-application volume control, dynamic
    mixing through virtual sound channels, true full duplex operation, bit
    perfect audio, rate conversion and low latency modes.</p>
<p class="Pp">The <code class="Nm">sound</code> driver is enabled by default,
    along with several bridge device drivers. Those not enabled by default can
    be loaded during runtime with <a class="Xr">kldload(8)</a> or during boot
    via <a class="Xr">loader.conf(5)</a>. The following bridge device drivers
    are available:</p>
<p class="Pp"></p>
<ul class="Bl-bullet Bl-compact">
  <li><a class="Xr">snd_ai2s(4)</a> (enabled by default on powerpc)</li>
  <li><a class="Xr">snd_als4000(4)</a></li>
  <li><a class="Xr">snd_atiixp(4)</a></li>
  <li><a class="Xr">snd_cmi(4)</a> (enabled by default on amd64, i386)</li>
  <li><a class="Xr">snd_cs4281(4)</a></li>
  <li><a class="Xr">snd_csa(4)</a> (enabled by default on amd64, i386)</li>
  <li><a class="Xr">snd_davbus(4)</a> (enabled by default on powerpc)</li>
  <li><a class="Xr">snd_emu10k1(4)</a></li>
  <li><a class="Xr">snd_emu10kx(4)</a> (enabled by default on amd64, i386)</li>
  <li><a class="Xr">snd_envy24(4)</a></li>
  <li><a class="Xr">snd_envy24ht(4)</a></li>
  <li><a class="Xr">snd_es137x(4)</a> (enabled by default on amd64, i386)</li>
  <li><a class="Xr">snd_fm801(4)</a></li>
  <li><a class="Xr">snd_hda(4)</a> (enabled by default on amd64, i386)</li>
  <li><a class="Xr">snd_hdsp(4)</a></li>
  <li><a class="Xr">snd_hdspe(4)</a></li>
  <li><a class="Xr">snd_ich(4)</a> (enabled by default on amd64, i386)</li>
  <li><a class="Xr">snd_maestro3(4)</a></li>
  <li><a class="Xr">snd_neomagic(4)</a></li>
  <li><a class="Xr">snd_solo(4)</a></li>
  <li><a class="Xr">snd_spicds(4)</a></li>
  <li><a class="Xr">snd_uaudio(4)</a> (auto-loaded on device plug)</li>
  <li><a class="Xr">snd_via8233(4)</a> (enabled by default on amd64, i386)</li>
  <li><a class="Xr">snd_via82c686(4)</a></li>
  <li><a class="Xr">snd_vibes(4)</a></li>
</ul>
<p class="Pp">Refer to the manual page for each bridge device driver for driver
    specific settings and information.</p>
<section class="Ss">
<h2 class="Ss" id="Boot_Variables"><a class="permalink" href="#Boot_Variables">Boot
  Variables</a></h2>
<p class="Pp">In general, the module <span class="Pa">snd_foo</span> corresponds
    to <code class="Cd">device snd_foo</code> and can be loaded by the boot
    <a class="Xr">loader(8)</a> via <a class="Xr">loader.conf(5)</a> or from the
    command line using the <a class="Xr">kldload(8)</a> utility. Options which
    can be specified in <span class="Pa">/boot/loader.conf</span> include:</p>
<div class="Bd-indent">
<dl class="Bl-tag">
  <dt id="snd_driver_load"><var class="Va">snd_driver_load</var></dt>
  <dd>(&#x201C;<code class="Li">NO</code>&#x201D;) If set to
      &#x201C;<code class="Li">YES</code>&#x201D;, this option loads all
      available drivers.</dd>
  <dt id="snd_hda_load"><var class="Va">snd_hda_load</var></dt>
  <dd>(&#x201C;<code class="Li">NO</code>&#x201D;) If set to
      &#x201C;<code class="Li">YES</code>&#x201D;, only the Intel High
      Definition Audio bridge device driver and dependent modules will be
      loaded.</dd>
  <dt id="snd_foo_load"><var class="Va">snd_foo_load</var></dt>
  <dd>(&#x201C;<code class="Li">NO</code>&#x201D;) If set to
      &#x201C;<code class="Li">YES</code>&#x201D;, load driver for card/chipset
      foo.</dd>
</dl>
</div>
<p class="Pp">To define default values for the different mixer channels, set the
    channel to the preferred value using hints, e.g.:
    <var class="Va">hint.pcm.0.line</var>=&quot;<code class="Li">0</code>&quot;.
    This will mute the input channel per default.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Multichannel_Audio"><a class="permalink" href="#Multichannel_Audio">Multichannel
  Audio</a></h2>
<p class="Pp">Multichannel audio, popularly referred to as &#x201C;surround
    sound&#x201D; is supported and enabled by default. The
    <span class="Ux">FreeBSD</span> multichannel matrix processor supports up to
    18 interleaved channels, but the limit is currently set to 8 channels (as
    commonly used for 7.1 surround sound). The internal matrix mapping can
    handle reduction, expansion or re-routing of channels. This provides a base
    interface for related multichannel
    <a class="permalink" href="#ioctl"><code class="Fn" id="ioctl">ioctl</code></a>()
    support. Multichannel audio works both with and without VCHANs.</p>
<p class="Pp">Most bridge device drivers are still missing multichannel
    matrixing support, but in most cases this should be trivial to implement.
    Use the <var class="Va">dev.pcm.%d.[play|rec].vchanformat</var>
    <a class="Xr">sysctl(8)</a> to adjust the number of channels used. The
    current multichannel interleaved structure and arrangement was implemented
    by inspecting various popular UNIX applications. There were no single
    standard, so much care has been taken to try to satisfy each possible
    scenario, despite the fact that each application has its own conflicting
    standard.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="EQ"><a class="permalink" href="#EQ">EQ</a></h2>
<p class="Pp">The Parametric Software Equalizer (EQ) enables the use of
    &#x201C;tone&#x201D; controls (bass and treble). Commonly used for ear-candy
    or frequency compensation due to the vast difference in hardware quality. EQ
    is disabled by default, but can be enabled with the
    <var class="Va">hint.pcm.%d.eq</var> tunable.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="VCHANs"><a class="permalink" href="#VCHANs">VCHANs</a></h2>
<p class="Pp">Each device can optionally support more playback and recording
    channels than physical hardware provides by using &#x201C;virtual
    channels&#x201D; or VCHANs. VCHAN options can be configured via the
    <a class="Xr">sysctl(8)</a> interface but can only be manipulated while the
    device is inactive.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="VPC"><a class="permalink" href="#VPC">VPC</a></h2>
<p class="Pp"><span class="Ux">FreeBSD</span> supports independent and
    individual volume controls for each active application, without touching the
    master <code class="Nm">sound</code> volume. This is sometimes referred to
    as Volume Per Channel (VPC). The VPC feature is enabled by default.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Loader_Tunables"><a class="permalink" href="#Loader_Tunables">Loader
  Tunables</a></h2>
<p class="Pp">The following loader tunables are used to set driver configuration
    at the <a class="Xr">loader(8)</a> prompt before booting the kernel, or they
    can be stored in <span class="Pa">/boot/loader.conf</span> in order to
    automatically set them before booting the kernel. It is also possible to use
    <a class="Xr">kenv(1)</a> to change these tunables before loading the
    <code class="Nm">sound</code> driver. The following tunables can not be
    changed during runtime using <a class="Xr">sysctl(8)</a>.</p>
<dl class="Bl-tag">
  <dt id="hint.pcm._d.eq"><var class="Va">hint.pcm.%d.eq</var></dt>
  <dd>Set to 1 or 0 to explicitly enable (1) or disable (0) the equalizer.
      Requires a driver reload if changed. Enabling this will make bass and
      treble controls appear in mixer applications. This tunable is undefined by
      default. Equalizing is disabled by default.</dd>
  <dt id="hint.pcm._d.vpc"><var class="Va">hint.pcm.%d.vpc</var></dt>
  <dd>Set to 1 or 0 to explicitly enable (1) or disable (0) the VPC feature.
      This tunable is undefined by default. VPC is however enabled by
    default.</dd>
</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="Runtime_Configuration"><a class="permalink" href="#Runtime_Configuration">Runtime
  Configuration</a></h2>
<p class="Pp">There are a number of <a class="Xr">sysctl(8)</a> variables
    available which can be modified during runtime. These values can also be
    stored in <span class="Pa">/etc/sysctl.conf</span> in order to automatically
    set them during the boot process. <var class="Va">hw.snd.*</var> are global
    settings and <var class="Va">dev.pcm.*</var> are device specific.</p>
<dl class="Bl-tag">
  <dt id="hw.snd.compat_linux_mmap"><var class="Va">hw.snd.compat_linux_mmap</var></dt>
  <dd>Linux <a class="Xr">mmap(2)</a> compatibility. The following values are
      supported (default is 0):
    <dl class="Bl-tag">
      <dt>-1</dt>
      <dd>Force disabling/denying PROT_EXEC <a class="Xr">mmap(2)</a>
        requests.</dd>
      <dt>0</dt>
      <dd>Auto detect proc/ABI type, allow <a class="Xr">mmap(2)</a> for Linux
          applications, and deny for everything else.</dd>
      <dt>1</dt>
      <dd>Always allow PROT_EXEC page mappings.</dd>
    </dl>
  </dd>
  <dt id="hw.snd.default_auto"><var class="Va">hw.snd.default_auto</var></dt>
  <dd>Automatically assign the default sound unit. The following values are
      supported (default is 1):
    <dl class="Bl-tag">
      <dt>0</dt>
      <dd>Do not assign the default sound unit automatically.</dd>
      <dt>1</dt>
      <dd>Use the best available sound device based on playing and recording
          capabilities of the device.</dd>
      <dt>2</dt>
      <dd>Use the most recently attached device.</dd>
    </dl>
  </dd>
  <dt id="hw.snd.default_unit"><var class="Va">hw.snd.default_unit</var></dt>
  <dd>Default sound card for systems with multiple sound cards. When using
      <a class="Xr">devfs(4)</a>, the default device for
      <span class="Pa">/dev/dsp</span>. Equivalent to a symlink from
      <span class="Pa">/dev/dsp</span> to
      <span class="Pa">/dev/dsp</span><var class="Va">${hw.snd.default_unit}</var>.</dd>
  <dt id="hw.snd.feeder_eq_exact_rate"><var class="Va">hw.snd.feeder_eq_exact_rate</var></dt>
  <dd>Only certain rates are allowed for precise processing. The default
      behavior is however to allow sloppy processing for all rates, even the
      unsupported ones. Enable to toggle this requirement and only allow
      processing for supported rates.</dd>
  <dt id="hw.snd.feeder_rate_max"><var class="Va">hw.snd.feeder_rate_max</var></dt>
  <dd>Maximum allowable sample rate.</dd>
  <dt id="hw.snd.feeder_rate_min"><var class="Va">hw.snd.feeder_rate_min</var></dt>
  <dd>Minimum allowable sample rate.</dd>
  <dt id="hw.snd.feeder_rate_polyphase_max"><var class="Va">hw.snd.feeder_rate_polyphase_max</var></dt>
  <dd>Adjust to set the maximum number of allowed polyphase entries during the
      process of building resampling filters. Disabling polyphase resampling has
      the benefit of reducing memory usage, at the expense of slower and lower
      quality conversion. Only applicable when the SINC interpolator is used.
      Default value is 183040. Set to 0 to disable polyphase resampling.</dd>
  <dt id="hw.snd.feeder_rate_quality"><var class="Va">hw.snd.feeder_rate_quality</var></dt>
  <dd>Sample rate converter quality. Default value is 1, linear interpolation.
      Available options include:
    <dl class="Bl-tag">
      <dt>0</dt>
      <dd>Zero Order Hold, ZOH. Very fast, but with poor quality.</dd>
      <dt>1</dt>
      <dd>Linear interpolation. Fast, quality is subject to personal preference.
          Technically the quality is poor however, due to the lack of
          anti-aliasing filtering.</dd>
      <dt>2</dt>
      <dd>Bandlimited SINC interpolator. Implements polyphase banking to boost
          the conversion speed, at the cost of memory usage, with multiple high
          quality polynomial interpolators to improve the conversion accuracy.
          100% fixed point, 64bit accumulator with 32bit coefficients and high
          precision sample buffering. Quality values are 100dB stopband, 8 taps
          and 85% bandwidth.</dd>
      <dt>3</dt>
      <dd>Continuation of the bandlimited SINC interpolator, with 100dB
          stopband, 36 taps and 90% bandwidth as quality values.</dd>
      <dt>4</dt>
      <dd>Continuation of the bandlimited SINC interprolator, with 100dB
          stopband, 164 taps and 97% bandwidth as quality values.</dd>
    </dl>
  </dd>
  <dt id="hw.snd.feeder_rate_round"><var class="Va">hw.snd.feeder_rate_round</var></dt>
  <dd>Sample rate rounding threshold, to avoid large prime division at the cost
      of accuracy. All requested sample rates will be rounded to the nearest
      threshold value. Possible values range between 0 (disabled) and 500.
      Default is 25.</dd>
  <dt id="hw.snd.latency"><var class="Va">hw.snd.latency</var></dt>
  <dd>Configure the buffering latency. Only affects applications that do not
      explicitly request blocksize / fragments. This tunable provides finer
      granularity than the <var class="Va">hw.snd.latency_profile</var> tunable.
      Possible values range between 0 (lowest latency) and 10 (highest
    latency).</dd>
  <dt id="hw.snd.latency_profile"><var class="Va">hw.snd.latency_profile</var></dt>
  <dd>Define sets of buffering latency conversion tables for the
      <var class="Va">hw.snd.latency</var> tunable. A value of 0 will use a low
      and aggressive latency profile which can result in possible underruns if
      the application cannot keep up with a rapid irq rate, especially during
      high workload. The default value is 1, which is considered a moderate/safe
      latency profile.</dd>
  <dt id="hw.snd.vchans_enable"><var class="Va">hw.snd.vchans_enable</var></dt>
  <dd>Global VCHAN setting to enable (1) or disable (0) VCHANs. This setting can
      be overridden for an individual device by using the
      <var class="Va">dev.pcm.%d.[play|rec].vchans</var> tunables. Default is
      enabled.</dd>
  <dt id="hw.snd.report_soft_formats"><var class="Va">hw.snd.report_soft_formats</var></dt>
  <dd>Controls the internal format conversion if it is available transparently
      to the application software. When disabled or not available, the
      application will only be able to select formats the device natively
      supports.</dd>
  <dt id="hw.snd.report_soft_matrix"><var class="Va">hw.snd.report_soft_matrix</var></dt>
  <dd>Enable seamless channel matrixing even if the hardware does not support
      it. Makes it possible to play multichannel streams even with a simple
      stereo sound card.</dd>
  <dt id="hw.snd.verbose"><var class="Va">hw.snd.verbose</var></dt>
  <dd>Level of verbosity for the <span class="Pa">/dev/sndstat</span> device.
      Higher values include more output and the highest level, four, should be
      used when reporting problems. Other options include:
    <dl class="Bl-tag">
      <dt>0</dt>
      <dd>Installed devices and their allocated bus resources.</dd>
      <dt>1</dt>
      <dd>The number of playback, record, virtual channels, and flags per
          device.</dd>
      <dt>2</dt>
      <dd>Channel information per device including the channel's current format,
          speed, and pseudo device statistics such as buffer overruns and buffer
          underruns.</dd>
      <dt>3</dt>
      <dd>File names and versions of the currently loaded sound modules.</dd>
      <dt>4</dt>
      <dd>Various messages intended for debugging.</dd>
    </dl>
  </dd>
  <dt id="hw.snd.vpc_0db"><var class="Va">hw.snd.vpc_0db</var></dt>
  <dd>Default value for <code class="Nm">sound</code> volume. Increase to give
      more room for attenuation control. Decrease for more amplification, with
      the possible cost of sound clipping.</dd>
  <dt id="hw.snd.vpc_autoreset"><var class="Va">hw.snd.vpc_autoreset</var></dt>
  <dd>When a channel is closed the channel volume will be reset to 0db. This
      means that any changes to the volume will be lost. Enabling this will
      preserve the volume, at the cost of possible confusion when applications
      tries to re-open the same device.</dd>
  <dt id="hw.snd.vpc_mixer_bypass"><var class="Va">hw.snd.vpc_mixer_bypass</var></dt>
  <dd>The recommended way to use the VPC feature is to teach applications to use
      the correct
      <a class="permalink" href="#ioctl~2"><code class="Fn" id="ioctl~2">ioctl</code></a>():
      <code class="Dv">SNDCTL_DSP_GETPLAYVOL</code>,
      <code class="Dv">SNDCTL_DSP_SETPLAYVOL</code>,
      <code class="Dv">SNDCTL_DSP_SETRECVOL</code>,
      <code class="Dv">SNDCTL_DSP_SETRECVOL</code>. This is however not always
      possible. Enable this to allow applications to use their own existing
      mixer logic to control their own channel volume.</dd>
  <dt id="hw.snd.vpc_reset"><var class="Va">hw.snd.vpc_reset</var></dt>
  <dd>Enable to restore all channel volumes back to the default value of
    0db.</dd>
  <dt id="dev.pcm._d.bitperfect"><var class="Va">dev.pcm.%d.bitperfect</var></dt>
  <dd>Enable or disable bitperfect mode. When enabled, channels will skip all
      dsp processing, such as channel matrixing, rate converting and equalizing.
      The pure <code class="Nm">sound</code> stream will be fed directly to the
      hardware. If VCHANs are enabled, the bitperfect mode will use the VCHAN
      format/rate as the definitive format/rate target. The recommended way to
      use bitperfect mode is to disable VCHANs and enable this sysctl. Default
      is disabled.</dd>
  <dt id="dev.pcm._d._play_rec_.vchans"><var class="Va">dev.pcm.%d.[play|rec].vchans</var></dt>
  <dd>Enable (1) or disable (0) VCHANs. Default is enabled.</dd>
  <dt id="dev.pcm._d._play_rec_.vchanformat"><var class="Va">dev.pcm.%d.[play|rec].vchanformat</var></dt>
  <dd>Format for VCHAN mixing. All playback paths will be converted to this
      format before the mixing process begins. By default only 2 channels are
      enabled. Available options include:
    <dl class="Bl-tag">
      <dt>s16le:1.0</dt>
      <dd>Mono.</dd>
      <dt>s16le:2.0</dt>
      <dd>Stereo, 2 channels (left, right).</dd>
      <dt>s16le:2.1</dt>
      <dd>3 channels (left, right, LFE).</dd>
      <dt>s16le:3.0</dt>
      <dd>3 channels (left, right, rear center).</dd>
      <dt>s16le:4.0</dt>
      <dd>Quadraphonic, 4 channels (front/rear left and right).</dd>
      <dt>s16le:4.1</dt>
      <dd>5 channels (4.0 + LFE).</dd>
      <dt>s16le:5.0</dt>
      <dd>5 channels (4.0 + center).</dd>
      <dt>s16le:5.1</dt>
      <dd>6 channels (4.0 + center + LFE).</dd>
      <dt>s16le:6.0</dt>
      <dd>6 channels (4.0 + front/rear center).</dd>
      <dt>s16le:6.1</dt>
      <dd>7 channels (6.0 + LFE).</dd>
      <dt>s16le:7.1</dt>
      <dd>8 channels (4.0 + center + LFE + left and right side).</dd>
    </dl>
  </dd>
  <dt id="dev.pcm._d._play_rec_.vchanmode"><var class="Va">dev.pcm.%d.[play|rec].vchanmode</var></dt>
  <dd>VCHAN format/rate selection. Available options include:
    <dl class="Bl-tag">
      <dt>fixed</dt>
      <dd>Channel mixing is done using fixed format/rate. Advanced operations
          such as digital passthrough will not work. Can be considered as a
          &#x201C;legacy&#x201D; mode. This is the default mode for hardware
          channels which lack support for digital formats.</dd>
      <dt>passthrough</dt>
      <dd>Channel mixing is done using fixed format/rate, but advanced
          operations such as digital passthrough also work. All channels will
          produce sound as usual until a digital format playback is requested.
          When this happens all other channels will be muted and the latest
          incoming digital format will be allowed to pass through undisturbed.
          Multiple concurrent digital streams are supported, but the latest
          stream will take precedence and mute all other streams.</dd>
      <dt>adaptive</dt>
      <dd>Works like the &#x201C;passthrough&#x201D; mode, but is a bit smarter,
          especially for multiple <code class="Nm">sound</code> channels with
          different format/rate. When a new channel is about to start, the
          entire list of virtual channels will be scanned, and the channel with
          the best format/rate (usually the highest/biggest) will be selected.
          This ensures that mixing quality depends on the best channel. The
          downside is that the hardware DMA mode needs to be restarted, which
          may cause annoying pops or clicks.</dd>
    </dl>
  </dd>
  <dt id="dev.pcm._d._play_rec_.vchanrate"><var class="Va">dev.pcm.%d.[play|rec].vchanrate</var></dt>
  <dd>Sample rate speed for VCHAN mixing. All playback paths will be converted
      to this sample rate before the mixing process begins.</dd>
  <dt id="dev.pcm._d.polling"><var class="Va">dev.pcm.%d.polling</var></dt>
  <dd>Experimental polling mode support where the driver operates by querying
      the device state on each tick using a <a class="Xr">callout(9)</a>
      mechanism. Disabled by default and currently only available for a few
      device drivers.</dd>
</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="Statistics"><a class="permalink" href="#Statistics">Statistics</a></h2>
<p class="Pp">Channel statistics are only kept while the device is open. So with
    situations involving overruns and underruns, consider the output while the
    errant application is open and running.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="IOCTL_Support"><a class="permalink" href="#IOCTL_Support">IOCTL
  Support</a></h2>
<p class="Pp">The driver supports most of the OSS
    <code class="Fn">ioctl</code>() functions, and most applications work
    unmodified. A few differences exist, while memory mapped playback is
    supported natively and in Linux emulation, memory mapped recording is not
    due to VM system design. As a consequence, some applications may need to be
    recompiled with a slightly modified audio module. See
    <code class="In">&lt;<a class="In">sys/soundcard.h</a>&gt;</code> for a
    complete list of the supported <code class="Fn">ioctl</code>()
  functions.</p>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
<p class="Pp">The <code class="Nm">sound</code> drivers may create the following
    device nodes:</p>
<p class="Pp"></p>
<dl class="Bl-tag Bl-compact">
  <dt><span class="Pa">/dev/dsp%d</span></dt>
  <dd>Audio device. The number represents the unit number of the device.</dd>
  <dt><span class="Pa">/dev/dsp</span></dt>
  <dd>Alias of <span class="Pa">/dev/dsp${hw.snd.default_unit}</span>. Available
      only if <span class="Pa">hw.snd.basename_clone</span> is set.</dd>
  <dt><span class="Pa">/dev/sndstat</span></dt>
  <dd>Current <code class="Nm">sound</code> status, including all channels and
      drivers.</dd>
</dl>
<p class="Pp">All <code class="Nm">sound</code> devices are listed in
    <span class="Pa">/dev/sndstat</span>. Additional messages are sometimes
    recorded when the device is probed and attached, these messages can be
    viewed with the <a class="Xr">dmesg(8)</a> utility.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
<p class="Pp">Use the sound metadriver to load all <code class="Nm">sound</code>
    bridge device drivers at once (for example if it is unclear which the
    correct driver to use is):</p>
<p class="Pp"></p>
<div class="Bd Bd-indent"><code class="Li">kldload snd_driver</code></div>
<p class="Pp">Load a specific bridge device driver, in this case the Intel High
    Definition Audio driver:</p>
<p class="Pp"></p>
<div class="Bd Bd-indent"><code class="Li">kldload snd_hda</code></div>
<p class="Pp">Check the status of all detected <code class="Nm">sound</code>
    devices:</p>
<p class="Pp"></p>
<div class="Bd Bd-indent"><code class="Li">cat /dev/sndstat</code></div>
<p class="Pp">Change the default sound device, in this case to the second
    device. This is handy if there are multiple <code class="Nm">sound</code>
    devices available:</p>
<p class="Pp"></p>
<div class="Bd Bd-indent"><code class="Li">mixer -d pcm1</code></div>
</section>
<section class="Sh">
<h1 class="Sh" id="DIAGNOSTICS"><a class="permalink" href="#DIAGNOSTICS">DIAGNOSTICS</a></h1>
<dl class="Bl-diag">
  <dt>pcm%d:play:%d:dsp%d.p%d: play interrupt timeout, channel dead</dt>
  <dd>The hardware does not generate interrupts to serve incoming (play) or
      outgoing (record) data.</dd>
  <dt>unsupported subdevice XX</dt>
  <dd>A device node is not created properly.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
  ALSO</a></h1>
<p class="Pp"><a class="Xr">devfs(4)</a>, <a class="Xr">snd_ai2s(4)</a>,
    <a class="Xr">snd_als4000(4)</a>, <a class="Xr">snd_atiixp(4)</a>,
    <a class="Xr">snd_cmi(4)</a>, <a class="Xr">snd_cs4281(4)</a>,
    <a class="Xr">snd_csa(4)</a>, <a class="Xr">snd_davbus(4)</a>,
    <a class="Xr">snd_emu10k1(4)</a>, <a class="Xr">snd_emu10kx(4)</a>,
    <a class="Xr">snd_envy24(4)</a>, <a class="Xr">snd_envy24ht(4)</a>,
    <a class="Xr">snd_es137x(4)</a>, <a class="Xr">snd_fm801(4)</a>,
    <a class="Xr">snd_hda(4)</a>, <a class="Xr">snd_hdsp(4)</a>,
    <a class="Xr">snd_hdspe(4)</a>, <a class="Xr">snd_ich(4)</a>,
    <a class="Xr">snd_maestro3(4)</a>, <a class="Xr">snd_neomagic(4)</a>,
    <a class="Xr">snd_solo(4)</a>, <a class="Xr">snd_spicds(4)</a>,
    <a class="Xr">snd_t4dwave(4)</a>, <a class="Xr">snd_uaudio(4)</a>,
    <a class="Xr">snd_via8233(4)</a>, <a class="Xr">snd_via82c686(4)</a>,
    <a class="Xr">snd_vibes(4)</a>, <a class="Xr">device.hints(5)</a>,
    <a class="Xr">loader.conf(5)</a>, <a class="Xr">dmesg(8)</a>,
    <a class="Xr">kldload(8)</a>, <a class="Xr">mixer(8)</a>,
    <a class="Xr">sysctl(8)</a></p>
<p class="Pp"><cite class="Rs"><span class="RsT">Cookbook formulae for audio EQ
    biquad filter coefficients (Audio-EQ-Cookbook.txt), by Robert
    Bristow-Johnson</span>,
    <a class="RsU" href="https://www.musicdsp.org/en/latest/Filters/197-rbj-audio-eq-cookbook.html">https://www.musicdsp.org/en/latest/Filters/197-rbj-audio-eq-cookbook.html</a>.</cite></p>
<p class="Pp"><cite class="Rs"><span class="RsT">Julius O'Smith's Digital Audio
    Resampling</span>,
    <a class="RsU" href="http://ccrma.stanford.edu/~jos/resample/">http://ccrma.stanford.edu/~jos/resample/</a>.</cite></p>
<p class="Pp"><cite class="Rs"><span class="RsT">Polynomial Interpolators for
    High-Quality Resampling of Oversampled Audio, by Olli Niemitalo</span>,
    <a class="RsU" href="http://yehar.com/blog/wp-content/uploads/2009/08/deip.pdf">http://yehar.com/blog/wp-content/uploads/2009/08/deip.pdf</a>.</cite></p>
<p class="Pp"><cite class="Rs"><span class="RsT">The OSS API</span>,
    <a class="RsU" href="http://www.opensound.com/pguide/oss.pdf">http://www.opensound.com/pguide/oss.pdf</a>.</cite></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">sound</code> device driver first appeared in
    <span class="Ux">FreeBSD 2.2.6</span> as <code class="Nm">pcm</code>,
    written by <span class="An">Luigi Rizzo</span>. It was later rewritten in
    <span class="Ux">FreeBSD 4.0</span> by <span class="An">Cameron
    Grant</span>. The API evolved from the VOXWARE standard which later became
    OSS standard.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp"><span class="An">Luigi Rizzo</span>
    &lt;<a class="Mt" href="mailto:luigi@iet.unipi.it">luigi@iet.unipi.it</a>&gt;
    initially wrote the <code class="Nm">pcm</code> device driver and this
    manual page. <span class="An">Cameron Grant</span>
    &lt;<a class="Mt" href="mailto:gandalf@vilnya.demon.co.uk">gandalf@vilnya.demon.co.uk</a>&gt;
    later revised the device driver for <span class="Ux">FreeBSD 4.0</span>.
    <span class="An">Seigo Tanimura</span>
    &lt;<a class="Mt" href="mailto:tanimura@r.dl.itc.u-tokyo.ac.jp">tanimura@r.dl.itc.u-tokyo.ac.jp</a>&gt;
    revised this manual page. It was then rewritten for <span class="Ux">FreeBSD
    5.2</span>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
<p class="Pp">Some features of your sound card (e.g., global volume control)
    might not be supported on all devices.</p>
<p class="Pp">Some audio devices might refuse to work properly unless the sample
    rate is configured the same for both recording and playback, even if only
    simplex is used. See the
    <var class="Va">dev.pcm.%d.[play|rec].vchanrate</var> sysctls.</p>
</section>
</div>
<table class="foot">
  <tr>
    <td class="foot-date">February 15, 2025</td>
    <td class="foot-os">FreeBSD 15.0</td>
  </tr>
</table>