README

DSDPlus User Guide
-------------------


Installation

This application can create many audio files and log files,
so consider using a dedicated folder to run it from.

The folder can be on your desktop (desktop\DSDPlus) or
off the root folder (C:\DSDPlus), for example.

After copying the zip file contents to the installation folder,
you should probably create a shortcut on your desktop.
The shortcut should run cmd.exe in the installation folder

Shortcut properties:

Target: %windir%\system32\cmd.exe

Start in: <your DSDPlus folder>

Layout / Window size:  Width should be about 100




Usage/Options Summary

Usage:

  DSDPlus [options]            Live scanner mode
  DSDPlus [options] <file      Decode from .wav file
  DSDPlus -h                   Show help

Options ( [...] = default value):

Display/Logging options:
  --          Don't show command line options in window title
  -v<num>     Frame information verbosity (0-4) [-v2]

Input/Output options:
  -i<spec>    Input audio device (1-255) and channel (M/L/R) [-i1M]

  -g<num>     Output audio gain (0.001-999; 0=auto) [-g0]

  -o<spec>    Output audio device (1-255; 0=none) and channel (M/L/R) [-o1]
                in/out channels are optional; default=in:mono, out:mode based

  -Och <file> Output audio file channel count and name/type [-O DSDPlus.wav]
                ch: M=mono,S=stereo,blank=auto; file: .wav or .mp3 (NUL=none)

  -I<num>     Create new .wav/.mp3 file every <num> minutes (1440=daily) [-I0]

Decoder options:
  -mp         optimize for PSK modulation

  -fa         Auto-detect all protocols / frame types [-fa]
  -fd         Decode only D-STAR (no audio)
  -fn         Decode only NXDN4800 (Kenwood NEXEDGE and Icom IDAS)
  -fN         Decode only NXDN9600 (Kenwood NEXEDGE)
  -fr         Decode only DMR/MotoTRBO
  -f1         Decode only P25 Phase 1
  -fx         Decode only X2-TDMA
  -fp         Decode only ProVoice

  -xx         Expect inverted X2-TDMA signal
  -u<num>     Unvoiced speech quality (1-64) [-u3]

Advanced decoder options:
  -dr<num>    Rolloff filter (1-5; 0=auto) [-dr0]
  -dh<num>    Hotspot size (1-8; 0=auto) [-dh0]
  -ds<num>    Scaling factor (50-80; not used with D-Star or ProVoice) [-ds64]
  -dd<num>    Damping level (1-100; not used with D-Star or ProVoice) [-dd10]
  -dv<num>    Viewport size (1-30; not used with D-Star or ProVoice) [-dv20]

Active keys:
  -           Toggle command line options display
  I           Toggle input audio level display
  R           Start/stop recording of raw input audio to .wav file
  S           Display group/user stats
  Esc         Terminate real time decoding
  Ctrl-C      Terminate .wav file decoding



Run Modes

The program can decode live discriminator audio or recorded .wav files.
Recorded audio files must be 48 or 96 kHz 16 bit mono PCM .wav files.



Logging

-v
-v0 generates minimal output.
Use -v3 for maximum data logging.
Program output can be sent to a log file ( DSDPlus >logfile )



Input/Output

-i -o
WaveIn/Out devices are listed at program startup.
Select your devices if you don't want to use the defaults.
Use -o0 to disable output audio.

-O
By default, all synthesized audio is written/appended to DSDPlus.wav
Use -O name.ext to write synthesized audio to another .wav or .mp3 file.
Use -O NUL to disable recording of synthesized audio.

-I
Use -I# to start a new synthesized audio recording file every # minutes.



Decoder Options

-fa
Using -fa (or nothing) will auto-decode all supported protocols.
Polarity of signals is auto-detected.

-fd -fn -fN -fr -f1 -fx -fp
When monitoring a single type of traffic,
locking the protocol can provide slightly better decoding results.

-D1 -D2
Use -D# to control which DMR voice slot is decoded and synthesized.

-xr -xR
Use these to force the polarity used for DMR decoding.
If these are not used, the program will attempt to auto-detect DMR polarity.

-xx
X2-TDMA signals are assumed to be inverted unless this option is used.

-u
Lower values (slightly) reduce CPU load.



Advanced Decoder Options

Fine tuning the advanced decoder options can greatly increase decoding rates.

Different systems, protocols, receivers and PC sound devices require unique
fine tuning values.

A 60 second recording of voice traffic on a target system should be made
and used as the input for tuning runs.  Use the 'R' key to make recordings.

To speed up the tuning process, audio synthesis should be disabled
and the protocol should be locked correctly:

DSDPlus <rawAudio.wav -o0 -O NUL -f1

A decoding score will be displayed.

Pressing the up arrow will redisplay the previous command line,
which you can then edit and re-run.

Adjust a single parameter to determine which value produces the highest score:

DSDPlus <rawAudio.wav -o0 -O NUL -f1 -dr1
DSDPlus <rawAudio.wav -o0 -O NUL -f1 -dr2
DSDPlus <rawAudio.wav -o0 -O NUL -f1 -dr3
DSDPlus <rawAudio.wav -o0 -O NUL -f1 -dr4

When the optimal value for a tuning parameter is determined,
use that value (#) and add another parameter and repeat the tuning steps:

DSDPlus <rawAudio.wav -o0 -O NUL -f1 -dr# -dh1
DSDPlus <rawAudio.wav -o0 -O NUL -f1 -dr# -dh2
DSDPlus <rawAudio.wav -o0 -O NUL -f1 -dr# -dh3
...


Repeat until all advanced decoding options have been fine tuned.

Check your tuning by re-enabling voice synthesis:

DSDPlus <rawAudio.wav -f1 -dr# -dh# -ds# -dd# -dv#


The recommended tuning order is Rolloff, Hotspot, Damping, Viewport.

Damping and Viewport settings do not affect D-Star or ProVoice,
so don't bother tweaking them for those protocols.

The Scaling factor value is an initial value only.
It auto-optimizes during frame decoding.

The default Viewport setting of 20 is usually optimal.


When the optimal values for a system + receiver + sound input is determined,
consider creating a batch file to store the settings:

Local-PD.bat:

DSDPlus -f1 -dr1 -dh3 -ds66 -dd40 -dv20 -O PD.mp3

DMR.bat:

DSDPlus -fd -d21 -dh2 -ds58 -dd5 -dv20 -O DMR.mp3

Then to monitor a specific system, run its batch file.

If you scan multiple systems and protocols with a single receiver,
you can run multiple copies of DSDPlus in parallel with each one
protocol-locked and fine tuned as required.  Each copy of the program
should write synthesized audio to separate files.



Active Keys

R
'R' starts/stops recording of discriminator audio.  Use 'R' to make 60
second source recordings of tuning data.  Rename the files to identify
what they are.

Esc
To terminate real time decoding, press Esc.

Ctrl-C
To terminate .wav file decoding, press Ctrl-C.



Window Title

The window title area shows the command line parameters used (unless -- specified),
symbol tracking/centering, auto-scaling factor, output audio gain,
symbol rate (2400/4800/9600), and protocol.

During raw audio recording, "<REC>" is displayed.

---