From Trac audio problem, ported high tx jitter, problematic clock rat…

…e, and how to record audio. Audio problem is done

docs/source/specific-guides/audio-troubleshooting/checks/problematic_clock_rate.rst

@@ -0,0 +1,7 @@
+Check for problematic clock rate
+======================================
+Be mindful with combination of sampling rate and ptime that causes non-whole number of samples,
+such as:
+
+- 10ms of 22050 Hz (220.5 samples), 
+- 20ms of 11025 Hz (also 220.5 samples).

docs/source/specific-guides/audio-troubleshooting/problems/high_tx_jitter.rst

@@ -1,3 +1,17 @@
 High jitter value observed by remote party 
 ================================================
 
+Checklists:
+
+#. Check if this is a network condition rather than problem with transmission.
+#. Since the transmission of the RTP packet is driven by the sound device clock
+   (see :any:`/specific-guides/media/audio_flow` page for the complete explanation),
+   the performance of the transmission is affected by the performance of the sound
+   device. If the sound device doesn't deliver the captured frame in timely manner,
+   the outgoing RTP transmission will have jitter in it. See
+   :any:`/specific-guides/audio-troubleshooting/checks/dev_quality`
+   for more information.
+
+Note that normally a jitter in the transmission shouldn't cause problems, since 
+the jitter is not very big and the receiving party should be able to accomodate this
+with a de-jitter buffer.

docs/source/specific-guides/audio-troubleshooting/problems/how_to_record.rst

@@ -0,0 +1,83 @@
+How to record audio with pjsua
+==============================
+Follow this guide to record any audio coming into the conference bridge to a WAV file.
+
+#. Run pjsua with additional ``--rec-file`` argument:
+
+   .. code-block:: shell
+
+       $ ./pjsua --rec-file OUTPUT.WAV
+
+   .. note::
+
+      Make sure *pjsua* quits properly before reading the WAV file,
+      otherwise the WAV file may be detected as corrupt because
+      the header does not contain the correct information.
+
+#. See that the file has been registered to the conference
+   bridge with ``cl`` command:
+
+   ::
+
+      >>> cl
+      Conference ports:
+      Port #00[16KHz/10ms] Primary Sound Capture Driver  transmitting to:
+      Port #01[16KHz/10ms]           OUTPUT.WAV  transmitting to:
+
+#. Make a call and establish media as usual.
+#. When the call is established, normally it is
+   "connected" to the sound device in the bridge. This can be confirmed
+   with the ``cl`` command below:
+
+   ::
+
+      >>> cl
+      Conference ports:
+      Port #00[16KHz/10ms] Primary Sound Capture Driver  transmitting to: #2
+      Port #01[16KHz/10ms]           OUTPUT.WAV  transmitting to:
+      Port #02[16KHz/20ms]   sip:user@localhost  transmitting to: #0
+
+#. Now connect whatever port(s) to record to
+   the OUTPUT.WAV port. For example, this command would record the audio
+   from remote call to the WAV:
+
+   ::
+
+      >>> cc 2 1
+       09:40:08.969   conference.c Port 2 (sip:user@localhost) transmitting to port 1
+      (OUTPUT.WAV)
+      Success
+
+#. You can also, for example, record the audio from the microphone to
+   the WAV file at the same time:
+
+   ::
+
+      >>> cc 0 1
+       09:40:47.894   conference.c Port 0 (Primary Sound Capture Driver) transmitting
+      to port 1 (OUTPUT.WAV)
+      Success
+
+   In this case, the audio from both the call and the microphone will be
+   first mixed in the conference bridge before it is recorded to the WAV
+   file. 
+
+#. Now both the audio from the remote call and the audio from the
+   microphone will be recorded to the WAV file, as can be seen with
+   ``cl`` command:
+
+   ::
+
+      >>> cl
+      Conference ports:
+      Port #00[16KHz/10ms] Primary Sound Capture Driver  transmitting to: #2 #1
+      Port #01[16KHz/10ms]           OUTPUT.WAV  transmitting to:
+      Port #02[16KHz/20ms]   sip:user@localhost  transmitting to: #0 #1
+
+   As can be seen from above output, both the sound device (port 0) and the
+   call (port 2) are both transmitting to the WAV file, thus output from
+   both will be mixed and recorded to the WAV file.
+
+#. Note that when debugging audio problem, it's probably best **not** to mix the audio
+   from the problematic source with other sources so that we can be clear
+   about the source of the problem.

docs/source/specific-guides/audio-troubleshooting/problems/loud_noise.rst

@@ -5,10 +5,5 @@ 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-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:
-
-   - 10ms of 22050 Hz (220.5 samples), 
-   - 20ms of 11025 Hz (also 220.5 samples).
-
-
+#. Be mindful with combination of sampling rate and ptime that causes non-whole number of samples.
+   See :any:`/specific-guides/audio-troubleshooting/checks/problematic_clock_rate`.

docs/source/specific-guides/audio-troubleshooting/problems/soft_noise.rst

@@ -7,8 +7,5 @@ Checklists:
    If yes, then the noise is
    probably introduced by your sound device (it's quite common with onboard sound 
    adapters).
-#. Be mindful with combination of sampling rate and ptime that causes non-whole number of samples,
-   such as:
-
-   - 10ms of 22050 Hz (220.5 samples), 
-   - 20ms of 11025 Hz (also 220.5 samples).
+#. Be mindful with combination of sampling rate and ptime that causes non-whole number of samples.
+   See :any:`/specific-guides/audio-troubleshooting/checks/problematic_clock_rate`.

docs/source/specific-guides/index.rst

@@ -25,6 +25,7 @@ Audio Troubleshooting
    :maxdepth: 1
    :glob:
 
+   audio-troubleshooting/problems/how_to_record
    audio-troubleshooting/problems/*
    audio-troubleshooting/checklist
 
@@ -50,6 +51,8 @@ Development & Programming
    :glob:
 
    develop/*
+   ../api/pjsip/guide
+
 
 
 .. _media_guide_toc:
@@ -106,6 +109,7 @@ SIP
    :maxdepth: 1
    :glob:
 
+   ../api/pjsip/guide
    sip/*
 
 .. _video_guide_toc: