README
^^^^^^

This directory contains the audio subsystem support for NuttX. The contents of this
directory are only built if CONFIG_AUDIO is defined in the NuttX configuration file.

Contents
^^^^^^^^
- Files in this directory
- Related Header Files
- Related directories

Files in this directory
^^^^^^^^^^^^^^^^^^^^^^^

This directory holds the NuttX audio subsystem upper-half. The upper-half provides
a common interface for applications to interface with and also defines a bind
layer for specific lower-half audio device drivers.

audio.c - The upper-half driver that binds to a lower-half driver from the
drivers/audio subdirectory. For each attached audio device, there
will be an instance of this upper-half driver bound to the
instance of the lower half driver context.
pcm_decode.c - Routines to decode PCM / WAV type data.
README - This file!

Portions of the audio system interface have application interfaces. Those
portions reside in the nuttx/libc/audio directory where the will be built for
access by both OS driver logic and user application logic. Those relevant
files in nuttx/libc/audio include:

buffer.c - Routines to manage creattion and destruction of audio pipeline buffers
(apb) used in the audio subsystem. Audio pipeline buffers are passed
between user applications and the audio drivers to deliver audio
content for playback (or possibly recording in the future).

Related Header Files
^^^^^^^^^^^^^^^^^^^^

include/nuttx/audio/audio.h -- Top level include file defining the audio interface
include/nuttx/audio/vs1053.h -- Specific driver initialization prototypes

Configuration Settings
^^^^^^^^^^^^^^^^^^^^^^

General Audio Settings
----------------------

CONFIG_AUDIO
Enables overall support for audio subsystem
CONFIG_AUDIO_MULTI_SESSION
Enables support for the audio subsystem to track multiple open sessions
with lower-level audio devices.
CONFIG_AUDIO_LARGE_BUFFERS
Specifies that buffer size variables should be 32-bit vs. the normal 16-bit
size. This allows buffers to be larger than 64K bytes on systems with
an abundance of RAM.
CONFIG_AUDIO_NUM_BUFFERS
Sets the number of audio buffers to use for audio operations. If the
configuration has set CONFIG_AUDIO_DRIVER_SPECIFIC_BUFFERS, and an audio
device does not support the operation, then this becomes the default number
of buffers to use.
CONFIG_AUDIO_BUFFER_SIZE
Sets the size of the audio buffers to use for audio operations. If the
configuration has set CONFIG_AUDIO_DRIVER_SPECIFIC_BUFFERS, and an audio
device does not support the operation, then this becomes the default size
of buffers to use.
CONFIG_AUDIO_DRIVER_SPECIFIC_BUFFERS
Enables support for lower-level audio drivers to specify the number and size
of buffers that should be allocated for best performance while interacting
with that driver.
CONFIG_AUDIO_CUSTOM_DEV_PATH
Specifies that all audio devices should be registered in the filesystem at
a location other than the standard /dev/audio directory.
CONFIG_AUDIO_DEV_ROOT
Specifies that all audio devices should be registered in the /dev directory.
Saves a tiny bit of code and RAM space since an additional directory isn't needed,
but at the expense of execution speed when searching for audio devices since all
entries in /dev must be opened and tested if they provide audio support.
Available only if CONFIG_AUDIO_CUSTOM_DEV_PATH is selected.
CONFIG_AUDIO_DEV_PATH
Specifies a custom directory where audio devices will be registered.
Available if CONFIG_AUDIO_CUSTOM_DEV_PATH is selected and CONFIG_AUDIO_DEV_ROOT
is not selected.


Audio Format Support Selections
-------------------------------

CONFIG_AUDIO_FORMAT_AC3
Specifies that AC3 support should be enabled if available by a lower-half driver.
CONFIG_AUDIO_FORMAT_DTS
Specifies that DTS support should be enabled if available by a lower-half driver.
CONFIG_AUDIO_FORMAT_PCM
Specifies that PCM support should be enabled if available by a lower-half driver.
CONFIG_AUDIO_FORMAT_MP3
Specifies that MP3 support should be enabled if available by a lower-half driver.
CONFIG_AUDIO_FORMAT_MIDI
Specifies that MIDI support should be enabled if available by a lower-half driver.
CONFIG_AUDIO_FORMAT_WMA
Specifies that WMA support should be enabled if available by a lower-half driver.
CONFIG_AUDIO_FORMAT_OGG_VORBIS
Specifies that Ogg Vorbis support should be enabled if available by a lower-half driver.


Audio feature exclusion Selections
----------------------------------

CONFIG_AUDIO_EXCLUDE_VOLUME
Disables support in all libraries and drivers for setting the playback volume. In
this case, the device volume will depend on the default level defined by the
lower-level driver, typically via a config setting.
CONFIG_AUDIO_EXCLUDE_BALANCE
Disables support in all libraries and drivers for setting the playback balance.
Also, the volume support must not be excluded for balance to work or make sense.
CONFIG_AUDIO_EXCLUDE_TONE
Disables support for setting bass and treble.
CONFIG_AUDIO_EXCLUDE_PAUSE_RESUME
Disables support in all libraries and drivers for pausing and resuming playback.
CONFIG_AUDIO_EXCLUDE_STOP
Disables support in all libraries and drivers for stopping an audio playback
once it has started. Typically selected if only short notification audio sounds
are needed (vs. media playing type applications).

Related Subdirectories
^^^^^^^^^^^^^^^^^^^^^^

drivers/audio -- Contains the lower-level device specific drivers.
apps/system/nxplayer -- User-mode audio subsystem interface library.