// Copyright 2014-2025 Jesper Larsson
//
// This file is part of Klipspringer, <https://klipspringer.avadeaux.net/>
//
// Klipspringer is free software: you can redistribute it and/or modify it under the terms of the
// GNU General Public License as published by the Free Software Foundation, either version 3 of the
// License, or (at your option) any later version.
//
// Klipspringer is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
// even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// General Public License for more details.
//
// You should have received a copy of the GNU General Public License along with Klipspringer. If
// not, see <https://www.gnu.org/licenses/>.

/***************************************************************************************************
<p>Package for accessing <a href="https://www.alsa-project.org/wiki/Main_Page">ALSA</a> PCM audio
functionality directly via the <a
href="https://docs.oracle.com/en/java/javase/17/docs/specs/jni/">Java Native Interface</a>.</p>

<p>There are at least two advantages with going this path instead of relying on the <a
href="https://docs.oracle.com/en/java/javase/17/docs/api/java.desktop/javax/sound/sampled/package-summary.html">standard
Java sound API</a>.First, it can be more efficient if you shuffle a lot of audio data without
manipulating it, since it works primarily with <a
href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/nio/ByteBuffer.html#direct">direct
buffers</a>. Second, it ensures that audio data is sent to and received from ALSA devices without
any intemediary tampering with it in some way. By contrast, the standard Java sound system is
normally compiled to access ALSA devices through the <em>plug</em> module, which performs conversion
of formats and sample rates. (Conversion between various <a
href="https://klipspringer.avadeaux.net/ten-standard-ways-of-representing-binary-numbers/">sample
encoding formats</a> does not require the plug module, but can be handled by {@link
net.avadeaux.klipspringer.codec.PcmBuffer PcmBuffer}.)</p>

<p>Note that this package is only useful for systems with ALSA, which means most Linux systems but
not many others. On systems without Alsa, use {@link net.avadeaux.klipspringer.codec.LinePlayer
LinePlayer} or {@link net.avadeaux.klipspringer.codec.LineTuner LineTuner} as a bridge between
standard Java sound and the Klipspringer codec API.</p>

<p>This is part of the Klipspringer music playing software<br>&#xa9; 2014&#x2013;2025 Jesper
Larsson, released as free software under GPL version 3 or later.<br>
See <a href="https://klipspringer.avadeaux.net">klipspringer.avadeaux.net</a> for more information.
***************************************************************************************************/
package net.avadeaux.klipspringer.alsa;