From 1a2aa6b929e5eedee2789fe19acbb4ff56b24703 Mon Sep 17 00:00:00 2001
From: borine <32966433+borine@users.noreply.github.com>
Date: Mon, 16 Sep 2024 14:38:29 +0100
Subject: [PATCH] manual page for a2dpconf utility

---
 doc/Makefile.am       |  4 ++
 doc/a2dpconf.1.rst    | 96 +++++++++++++++++++++++++++++++++++++++++++
 doc/bluealsactl.1.rst |  6 +--
 3 files changed, 103 insertions(+), 3 deletions(-)
 create mode 100644 doc/a2dpconf.1.rst

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 4937bca7c..13eda61b2 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -23,6 +23,10 @@ if ENABLE_RFCOMM
 man1_MANS += bluealsa-rfcomm.1
 endif
 
+if ENABLE_A2DPCONF
+man1_MANS += a2dpconf.1
+endif
+
 if ENABLE_HCITOP
 man1_MANS += hcitop.1
 endif
diff --git a/doc/a2dpconf.1.rst b/doc/a2dpconf.1.rst
new file mode 100644
index 000000000..81e29b3c0
--- /dev/null
+++ b/doc/a2dpconf.1.rst
@@ -0,0 +1,96 @@
+========
+a2dpconf
+========
+
+----------------------------------------
+Decode A2DP codec capability hex strings
+----------------------------------------
+
+:Date: September 2024
+:Manual section: 1
+:Manual group: General Commands Manual
+:Version: $VERSION$
+
+SYNOPSIS
+========
+
+**a2dpconf** [*OPTION*]... <[*CODEC*:]*CONFIG*>...
+
+DESCRIPTION
+===========
+
+**a2dpconf** presents the fields of the given A2DP codec *CONFIG* in a
+human-readable format. *CODEC* is the name of the relevant codec, and *CONFIG*
+is the hexadecimal encoding of the configuration or capabilities binary "blob"
+as reported by tools such as ``bluealsactl(1)`` or the debug output of
+``bluealsad(8)``.
+(see `EXAMPLES`_ below).
+
+OPTIONS
+=======
+
+-h, --help
+    Print this help and exit.
+
+-V, --version
+    Print version and exit.
+
+-x, --auto-detect
+    Try to auto-detect the codec. If the name of the codec associated with the
+    configuration string is not known, then give this option and the
+    configuration string without the codec name prefix. The output is then a
+    list of all possible known codec configurations for which the given string
+    is valid.
+
+EXAMPLES
+========
+::
+
+    $ a2dpconf sbc:ffff0235
+    SBC <hex:ffff0235> {
+      sampling-frequency:4 = 48000 44100 32000 16000
+      channel-mode:4 = JointStereo Stereo DualChannel Mono
+      block-length:4 = 16 12 8 4
+      sub-bands:2 = 8 4
+      allocation-method:2 = Loudness SNR
+      min-bit-pool-value:8 = 2
+      max-bit-pool-value:8 = 53
+    }
+
+::
+
+    $ a2dpconf -x ffff0235
+    SBC <hex:ffff0235> {
+      sampling-frequency:4 = 48000 44100 32000 16000
+      channel-mode:4 = JointStereo Stereo DualChannel Mono
+      block-length:4 = 16 12 8 4
+      sub-bands:2 = 8 4
+      allocation-method:2 = Loudness SNR
+      min-bit-pool-value:8 = 2
+      max-bit-pool-value:8 = 53
+    }
+    MPEG-1,2 Audio <hex:ffff0235> {
+      layer:3 = MP3 MP2 MP1
+      crc:1 = true
+      channel-mode:4 = JointStereo Stereo DualChannel Mono
+      <reserved>:1
+      media-payload-format:1 = MPF-1 MPF-2
+      sampling-frequency:6 = 48000 44100 32000 24000 22050 16000
+      vbr:1 = false
+      bitrate-index:15 = 0x235
+    }
+
+COPYRIGHT
+=========
+
+Copyright (c) 2016-2024 Arkadiusz Bokowy.
+
+The bluez-alsa project is licensed under the terms of the MIT license.
+
+SEE ALSO
+========
+
+``bluealsactl(1)``, ``bluealsad(8)``
+
+Project web site
+  https://github.com/arkq/bluez-alsa
diff --git a/doc/bluealsactl.1.rst b/doc/bluealsactl.1.rst
index f05db3e4f..c418a4935 100644
--- a/doc/bluealsactl.1.rst
+++ b/doc/bluealsactl.1.rst
@@ -6,7 +6,7 @@ bluealsactl
 a simple command line interface for the BlueALSA D-Bus API
 ----------------------------------------------------------
 
-:Date: August 2024
+:Date: Septemner 2024
 :Manual section: 1
 :Manual group: General Commands Manual
 :Version: $VERSION$
@@ -105,7 +105,7 @@ info *PCM_PATH*
         Available codecs: SBC:ffff02fa AAC:c0ffff035b60
         Selected codec: AAC:400084035b60
 
-    A tool such as ``a2dpconf`` can be used to decode the hex string.
+    A tool such as ``a2dpconf(1)`` can be used to decode the hex string.
 
     The list of available A2DP codecs requires BlueZ SEP support
     (BlueZ >= 5.52)
@@ -285,7 +285,7 @@ The bluez-alsa project is licensed under the terms of the MIT license.
 SEE ALSO
 ========
 
-``bluealsad(8)``, ``bluealsa-aplay(1)``, ``bluealsa-rfcomm(1)``
+``a2dpconf(1)``, ``bluealsa-aplay(1)``, ``bluealsa-rfcomm(1)``, ``bluealsad(8)``
 
 Project web site
   https://github.com/arkq/bluez-alsa