Split audio troubleshooting to own section under Specific Guides

pjsip · Feb 3, 2023 · 8d07f89 · 8d07f89
1 parent f5b8e5a
commit 8d07f89
Show file tree

Hide file tree

Showing 26 changed files with 53 additions and 41 deletions.
diff --git a/docs/source/api/pjsua-lib/samples.rst b/docs/source/api/pjsua-lib/samples.rst
@@ -22,7 +22,7 @@ PJSUA-LIB Samples
        device performance such as bursts, latency, and drifts, AEC performance, as well as
        displaying basic audio system information.
 
-       See :any:`/specific-guides/audio/checks/pjsystest`
+       See :any:`/specific-guides/audio-troubleshooting/checks/pjsystest`
    * - `vidgui <https://github.com/pjsip/pjproject/tree/master/pjsip-apps/src/vidgui/>`_
      - PJSUA-LIB
      - GUI user agent supporting video. Requires Qt toolkit.

diff --git a/...uides/audio/troubleshooting_checklist.rst → ...uides/audio-troubleshooting/checklist.rst b/...uides/audio/troubleshooting_checklist.rst → ...uides/audio-troubleshooting/checklist.rst
diff --git a/...ecific-guides/audio/checks/codec_nego.rst → ...dio-troubleshooting/checks/codec_nego.rst b/...ecific-guides/audio/checks/codec_nego.rst → ...dio-troubleshooting/checks/codec_nego.rst
diff --git a/...-guides/audio/checks/conf_connections.rst → ...oubleshooting/checks/conf_connections.rst b/...-guides/audio/checks/conf_connections.rst → ...oubleshooting/checks/conf_connections.rst
diff --git a/...urce/specific-guides/audio/checks/cpu.rst → ...ides/audio-troubleshooting/checks/cpu.rst b/...urce/specific-guides/audio/checks/cpu.rst → ...ides/audio-troubleshooting/checks/cpu.rst
diff --git a/...guides/audio/checks/dangling_pbx_call.rst → ...ubleshooting/checks/dangling_pbx_call.rst b/...guides/audio/checks/dangling_pbx_call.rst → ...ubleshooting/checks/dangling_pbx_call.rst
diff --git a/...cific-guides/audio/checks/dev_quality.rst → ...io-troubleshooting/checks/dev_quality.rst b/...cific-guides/audio/checks/dev_quality.rst → ...io-troubleshooting/checks/dev_quality.rst
@@ -8,8 +8,8 @@ Checking the quality of the sound device
 In some cases, some of the audio problems may come from the sound
 device itself, causing problems such as:
 
-- :any:`/specific-guides/audio/problems/stutter`, 
-- :any:`/specific-guides/audio/problems/breaking_up`
+- :any:`/specific-guides/audio-troubleshooting/problems/stutter`, 
+- :any:`/specific-guides/audio-troubleshooting/problems/breaking_up`
 
 It may not be the sound device itself that is causing the problem, but
 could be the operating system driver for the device. For example, on
@@ -85,7 +85,7 @@ device may deliver a little less or more than 8000 samples per second.
 Testing the Sound Device
 ------------------------
 Use **pjsystest** to test the performance of the sound device. See
-:any:`/specific-guides/audio/checks/pjsystest` for more information.
+:any:`/specific-guides/audio-troubleshooting/checks/pjsystest` for more information.
 
 Specifically, run *pjsystest* **Device Test** (menu **01**) to test
 the audio device's burst and clock drifts problem. Below is a sample 

diff --git a/...uides/audio/checks/dev_under_overflow.rst → ...bleshooting/checks/dev_under_overflow.rst b/...uides/audio/checks/dev_under_overflow.rst → ...bleshooting/checks/dev_under_overflow.rst
diff --git a/...e/specific-guides/audio/checks/device.rst → ...s/audio-troubleshooting/checks/device.rst b/...e/specific-guides/audio/checks/device.rst → ...s/audio-troubleshooting/checks/device.rst
diff --git a/...specific-guides/audio/checks/loopback.rst → ...audio-troubleshooting/checks/loopback.rst b/...specific-guides/audio/checks/loopback.rst → ...audio-troubleshooting/checks/loopback.rst
diff --git a/...pecific-guides/audio/checks/no_rx_rtp.rst → ...udio-troubleshooting/checks/no_rx_rtp.rst b/...pecific-guides/audio/checks/no_rx_rtp.rst → ...udio-troubleshooting/checks/no_rx_rtp.rst
diff --git a/...pecific-guides/audio/checks/pjsystest.png → ...udio-troubleshooting/checks/pjsystest.png b/...pecific-guides/audio/checks/pjsystest.png → ...udio-troubleshooting/checks/pjsystest.png
diff --git a/...pecific-guides/audio/checks/pjsystest.rst → ...udio-troubleshooting/checks/pjsystest.rst b/...pecific-guides/audio/checks/pjsystest.rst → ...udio-troubleshooting/checks/pjsystest.rst
@@ -25,7 +25,7 @@ Objectives
 
 The objectives are: 
 
-- to eliminate audio device impairments as explained in :any:`/specific-guides/audio/checks/dev_quality`
+- to eliminate audio device impairments as explained in :any:`/specific-guides/audio-troubleshooting/checks/dev_quality`
 - to minimize audio latency
 
 Using pjsystest

diff --git a/...specific-guides/audio/checks/play_wav.rst → ...audio-troubleshooting/checks/play_wav.rst b/...specific-guides/audio/checks/play_wav.rst → ...audio-troubleshooting/checks/play_wav.rst
diff --git a/...ecific-guides/audio/checks/rx_quality.rst → ...dio-troubleshooting/checks/rx_quality.rst b/...ecific-guides/audio/checks/rx_quality.rst → ...dio-troubleshooting/checks/rx_quality.rst
diff --git a/.../specific-guides/audio/checks/tx_addr.rst → .../audio-troubleshooting/checks/tx_addr.rst b/.../specific-guides/audio/checks/tx_addr.rst → .../audio-troubleshooting/checks/tx_addr.rst
diff --git a/...specific-guides/audio/troubleshooting.rst → ...ic-guides/audio-troubleshooting/index.rst b/...specific-guides/audio/troubleshooting.rst → ...ic-guides/audio-troubleshooting/index.rst
diff --git a/...fic-guides/audio/problems/breaking_up.rst → ...-troubleshooting/problems/breaking_up.rst b/...fic-guides/audio/problems/breaking_up.rst → ...-troubleshooting/problems/breaking_up.rst
@@ -11,14 +11,14 @@ Checklists:
 #. Check that no other application is using the devices. It is common to not 
    be able to use sound device when the device is being used by other 
    applications.
-#. :any:`/specific-guides/audio/checks/cpu`
-#. :any:`/specific-guides/audio/checks/dangling_pbx_call`. A dangling call is call that 
+#. :any:`/specific-guides/audio-troubleshooting/checks/cpu`
+#. :any:`/specific-guides/audio-troubleshooting/checks/dangling_pbx_call`. A dangling call is call that 
    is left active in the PBX because previous (*pjsua*) application has terminated
    abruptly.
-#. :any:`Check for high network jitter, packet loss, etc. </specific-guides/audio/checks/rx_quality>`. 
+#. :any:`Check for high network jitter, packet loss, etc. </specific-guides/audio-troubleshooting/checks/rx_quality>`. 
 #. Check if audio is breaking up when playing file locally:
-   :any:`/specific-guides/audio/checks/play_wav`
+   :any:`/specific-guides/audio-troubleshooting/checks/play_wav`
 #. Check if the breakup is coming from the sound device:
-   :any:`/specific-guides/audio/checks/dev_quality`
+   :any:`/specific-guides/audio-troubleshooting/checks/dev_quality`
 #. Check if local audio is breaking up by looping back microphone signal to the speaker:
-   :any:`/specific-guides/audio/checks/loopback`
+   :any:`/specific-guides/audio-troubleshooting/checks/loopback`
diff --git a/...ific-guides/audio/problems/loud_noise.rst → ...o-troubleshooting/problems/loud_noise.rst b/...ific-guides/audio/problems/loud_noise.rst → ...o-troubleshooting/problems/loud_noise.rst
@@ -3,8 +3,8 @@ Loud static noise
 Checklists:
 
 #. Check that audio device is functioning properly and noise is not heard when looping microphone to the speaker,
-   by following: :any:`/specific-guides/audio/checks/loopback`
-#. :any:`Check that codec is negotiated properly by both parties </specific-guides/audio/checks/codec_nego>`.
+   by following: :any:`/specific-guides/audio-troubleshooting/checks/loopback`
+#. :any:`Check that codec is negotiated properly by both parties </specific-guides/audio-troubleshooting/checks/codec_nego>`.
 #. Be mindful with combination of sampling rate and ptime that causes non-whole number of samples,
    such as:
 

diff --git a/docs/source/specific-guides/audio-troubleshooting/problems/no_audio.rst b/docs/source/specific-guides/audio-troubleshooting/problems/no_audio.rst
@@ -0,0 +1,16 @@
+No audio is heard in local speaker
+========================================
+
+Checklists:
+
+#. :any:`/specific-guides/audio-troubleshooting/checks/device`
+#. Check that no other application is using the devices. It is common to not be 
+   able to use sound device when other application is using the device.
+#. :any:`/specific-guides/audio-troubleshooting/checks/loopback`. Check that speaker is functioning 
+   properly by looping-back microphone to speaker device.
+#. :any:`/specific-guides/audio-troubleshooting/checks/play_wav`.
+#. :any:`/specific-guides/audio-troubleshooting/checks/no_rx_rtp`
+#. :any:`/specific-guides/network_nat/nat_guide`
+#. :any:`/specific-guides/audio-troubleshooting/checks/conf_connections`. Check that the call is 
+   connected to the sound device in the conference bridge.
+#. :any:`/specific-guides/audio-troubleshooting/checks/cpu`
diff --git a/...fic-guides/audio/problems/quiet_noise.rst → ...-troubleshooting/problems/quiet_noise.rst b/...fic-guides/audio/problems/quiet_noise.rst → ...-troubleshooting/problems/quiet_noise.rst
@@ -3,7 +3,7 @@ Soft/quiet noise
 Checklists:
 
 #. Check that you're using the latest (git) version of the libraries.
-#. :any:`Check whether you have this noise when looping the microphone to the speaker locally </specific-guides/audio/checks/loopback>`: 
+#. :any:`Check whether you have this noise when looping the microphone to the speaker locally </specific-guides/audio-troubleshooting/checks/loopback>`: 
    If yes, then the noise is
    probably introduced by your sound device (it's quite common with onboard sound 
    adapters).

diff --git a/...guides/audio/problems/remote_no_audio.rst → ...ubleshooting/problems/remote_no_audio.rst b/...guides/audio/problems/remote_no_audio.rst → ...ubleshooting/problems/remote_no_audio.rst
@@ -3,15 +3,15 @@ No audio is heard by remote party
 
 Checklists:
 
-#. :any:`/specific-guides/audio/checks/device`
-#. :any:`Check that microphone is functioning properly</specific-guides/audio/checks/loopback>`
+#. :any:`/specific-guides/audio-troubleshooting/checks/device`
+#. :any:`Check that microphone is functioning properly</specific-guides/audio-troubleshooting/checks/loopback>`
    by looping-back microphone to speaker device.
 #. Check that no other application is using the sound devices. It is common to not be 
    able to use sound device when other application is using the device.
-#. :any:`Check that the microphone is connected to the call in the conference bridge </specific-guides/audio/checks/conf_connections>` 
-#. :any:`/specific-guides/audio/checks/tx_addr`.
+#. :any:`Check that the microphone is connected to the call in the conference bridge </specific-guides/audio-troubleshooting/checks/conf_connections>` 
+#. :any:`/specific-guides/audio-troubleshooting/checks/tx_addr`.
 #. Use *pjsua* on the remote side to check that packets are received. Follow 
-   :any:`/specific-guides/audio/checks/no_rx_rtp` on how to use *pjsua* to verify 
+   :any:`/specific-guides/audio-troubleshooting/checks/no_rx_rtp` on how to use *pjsua* to verify 
    receipt of incoming RTP packets.
-#. :any:`/specific-guides/audio/checks/cpu`
+#. :any:`/specific-guides/audio-troubleshooting/checks/cpu`
 
diff --git a/...pecific-guides/audio/problems/stutter.rst → ...udio-troubleshooting/problems/stutter.rst b/...pecific-guides/audio/problems/stutter.rst → ...udio-troubleshooting/problems/stutter.rst
@@ -11,16 +11,16 @@ Hear the stutters at 2.5, 3.8, and 8.8 second.
 
 Checklists:
 
-#. :any:`/specific-guides/audio/checks/loopback`: check whether the symptom is observable
+#. :any:`/specific-guides/audio-troubleshooting/checks/loopback`: check whether the symptom is observable
    when looping the microphone to the speaker locally.
-#. :any:`/specific-guides/audio/checks/dangling_pbx_call`. A dangling call is call that 
+#. :any:`/specific-guides/audio-troubleshooting/checks/dangling_pbx_call`. A dangling call is call that 
    is left active in the PBX because previous (*pjsua*) application has terminated
    abruptly.
-#. :any:`Check for high network jitter, packet loss, etc. </specific-guides/audio/checks/rx_quality>`
-#. :any:`/specific-guides/audio/checks/cpu`
+#. :any:`Check for high network jitter, packet loss, etc. </specific-guides/audio-troubleshooting/checks/rx_quality>`
+#. :any:`/specific-guides/audio-troubleshooting/checks/cpu`
 #. Try to enlarge :cpp:any:`PJMEDIA_SOUND_BUFFER_COUNT` value by setting it in your 
    :any:`config_site.h`. Increase it to, say, 16, and see if it fixes the problem. But be 
    aware that enlarging this buffer will increase the audio latency, so find a minimum value
    where the sound quality doesn't break.
-#. :doc:`/specific-guides/audio/checks/dev_under_overflow`
+#. :doc:`/specific-guides/audio-troubleshooting/checks/dev_under_overflow`
 
diff --git a/...cific-guides/audio/problems/tx_jitter.rst → ...io-troubleshooting/problems/tx_jitter.rst b/...cific-guides/audio/problems/tx_jitter.rst → ...io-troubleshooting/problems/tx_jitter.rst
diff --git a/docs/source/specific-guides/audio/problems/no_audio.rst b/docs/source/specific-guides/audio/problems/no_audio.rst
diff --git a/docs/source/specific-guides/index.rst b/docs/source/specific-guides/index.rst
@@ -16,6 +16,18 @@ Audio
 
    audio/*
 
+.. _audio_troubleshooting_toc:
+
+Audio Troubleshooting
+*****************************************
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   audio-troubleshooting/problems/*
+   audio-troubleshooting/checklist
+
 .. _build_int_guide_toc:
 
 Build & Integration