yogeto / voice-ann Goto Github PK

DSTAR voice announcement system


* Introduction
Up till now, the DSTAR-system only has limited support for playing
voice-announcement.

The only two possibilities sofar to play out a voice-announcement are:
- play out the pre-recorded messages that come with certain D-STAR
packages like Dplus or DExtra
- Record a message yourself using dvtool, the java-based tools that
comes with the DVdongle and play out that complete message.

As the message needs to be pre-recorded beforehand, both systems are
good for announcing a fixed message, it is not very well
suited for messages generated "on the fly".


This software package is designed for a D-STAR repeater system to allow
any kind of message to be played out.
This would include:
- time-messages "good morning, the time is now 9 AM"
- linking/unlinking messages "repeater module B is now linked to reflector 001 A"
- weather messages: "the local weather-rapport for today is ..."
- command announcements: "linking request received from Oscar November 1 Alpha Romeo Fox"
- play out long audio-messages: weather buletins, "this week in ham" news broadcasts, etc.
...


As DSTAR uses the patented AMBE voice codec, any conversion of WAV-files to AMBE-encoded files
require some kind of encoding hardware. Currently, the only option is the USB DVdongle.



* Possible implementation senario

There are multiple senarios on how to implement voice-announcement on a D-STAR
repeater, all with their advantages and disadvantages:


1/ Using "dvtool":

As described above, the first option is to use the "dvtool" application that comes
with the DVdongle. This allows a message that is read into the computer to be
encoded into the AMBE format, which can then be played out on the repeater.

Note that the dvtool can only encode wav-files directly spoken into the
microphone of the computer.


2/ Using "wav2ambe":
This application allows any wav-file to be encoded into the ambe-format.

As this application allows any wav-file to be encoded, allowing messages
to be created in a number of different ways:
- recorded and processed with your favourite audio-processing tool
- created by a text-to-speech tool
- created by concatenating multiple wav-files containing words or parts of
sentences together to form one single announcement


Note that wav2ambe is only needed to _create_ the AMBE-file. For playing it
out to the repeater, other tools need to be used (like some tools that come
with Dplus or Dextra, or ambestream)

This means that if a message needs to be playout out on multiple repeaters;
a possible senario is to encode it on at one place (a repeater or any
linux box that has a DV-dongle attached), copy it over to the
other repeaters (e.g. using ssh) to play it out overthere, or stream it
over the internet to a remote-repeater.

This requires only one single host/repeater to be equiped with a DVdongle.


Also note that the DVdongle is a "real-time" device: it can only encode
AMBE-files as fast it as it takes to play it out.
This means that encoding a 10-second announcement ("good morning, this is
D-STAR repeater of <your-city> <repeater-callsign>, the time is now
9 O'oclock and the outside temperature is a mild 21 degrees") will also
take 10 seconds to encode.

Hence, this create a 10-second delay in-between creating the message
and playing it out.


3/ Using "ambestream":
Ambestream is an application simular to the tools that come with dplus or
dextra to play out a ambe-file on a repeater, with some additional features:
- in addition to playing out a message on the local repeater, it also allows
the audio-message to be played out on a remote repeater.
- streaming to other repeaters can be done using the "callsign routing"
protocol (UDP port 40000) or the dextra linking-protocol (UDP port 30001)
- it allows a audio-message to be played out to a XRF reflector
- it allows you to set the "mycall" field, allowing the originator of the
stream to identify himself/herself
- it has the "auto-break" feature, which is needed to deal with the "3 minute
rule" of repeaters based on i-com hardware.
- The application runs on a fixed "heartbeat" generated by the linux-kernel.
This is needed to stream out long audio-fragments on repeaters based
a platform that does "resyncronise" the audio-stream.
- it supports both ipv4 and ipv6
- it allows streaming of a PCM audio-stream, directly from "standard in". This
allows aplication to be "piped together". An example of this is to read a
mp3-file from the internet and stream it out D-STAR repeater at the same
time.


4/ Using "wavstream":

This technique is simular to the one described above, but with the difference
that this application does not generate a AMBE-file, but streams it out to
the repeater or reflector directly in real-time.
In essence, it's a combination of the "wav2ambe" tool and "ambestream".

This does away with the delay between encoding the message and playing it
out.


5/ concating ambe-files:

A 4th methode to create voice-announcement works by creating a AMBE-encoded
message, based on concatenating pre-AMBE-encoded words or parts of
messages together.

As the binary .dvtool file-format (natively used by the repeater) cannot be
used for this, a new text-based .ambe file-format has been created.

The big advantage of this system is that -as it based on pre-encoded
audio-fragments- it does not need a DVdongle to create a complete
voice-announcement.

However, the quality of announcements created via this methode will depend
completely on the quality of the library of AMBE-encoded audio-fragments.





* The files:

The voice-announcement package contains the following programs:
- wav2ambe:

A C-program that converts a PCM (.wav) file into a ambe-encoded file, either
in the .ambe or the .dvtool fileformat.
This program needs a DVdongle to be attached to the computer for the actual
AMBE encoding.

- wavstream:
A C-program that converts a PCM (.wav) file to ambe-format and at the same
time streams it out to a repeater or XRF-reflector.
This program requires a DVdongle for the actual AMBE encoding.

- ambestream:
A C-program that streams out a AMBE encoded file to a repeater or XRF
reflector. This application does not need a DVdongle.

- ambe2wav: decode AMBE-files:
This program is able to decode AMBE-encoded audio (contained in files in
either the .ambe or .dvtool format) to be decoded back to wav-format.

- ambe2dvtool.pl and dvtool2ambe.pl:
Two programs to converts AMBE-files from the binary .dvtool format into the
text-based .ambe file-format and the other way around.

- dvtooltext.pl:
A program to change or delete the 20-octets text-segment in a .dvtool file

- cp2dpl: "Copy 2 dplus".
This is a program that copies a file to /dstar/tmp/play-<module>.dvtool
The reason this program has been written is because -by default- Dplus runs as
root on a D-STAR repeater and -thereby- the priviledge-settings on the 
directory /dstar/tmp/ only allow programs with root-access to write into it.

As cp2dpl is installed with "setuid" priviledges, this allows the
voice-announcment-system to be run as non-root and still have write-access
to that directory.



In addition to these programs, the package also contains the following files:

- README.txt: what you are reading now
- COPYING.txt: the GPL license

- docs/readme_wav2ambe.txt: readme text on the wav2ambe tool.
This text gives a high-level overview of the wav2ambe tool, including
information on the DVdongle, the sndfile-library.

- docs/readme_formats.txt: documentation on the different file-formats
and stream-formats used on D-STAR and the voice-announcement package:
. stream-format of a UDP-stream containing a D-STAR DV-conversation
. file-format of the .dvtool files
. file-format of the .ambe files
. description of the slow-speed data inside a DV-stream


- The source-code itself also contains a lot of comments which explain
the internal working of these applications.

Do take a look overthere too!


A binary distribution for linux/i386 of the programs in C (wav2ambe,
wavstream, ambe2wav and cp2dpl) can also be downloaded from the website.
These versions are "statically linked". This means that the binairy files
include all the code of the all the libraries used by the application.

This has the advantage that these programs can be executed on any
linux-machine, no matter what libraries are installed on that machine.
On the downside, this means that the executables are very large compaired
to the side of the executables obtained via the normal installation
procudure.



Release-info:
17 okt. 2010: Version 0.0.1: Initial release
25 okt. 2010: Version 0.0.2: rewrite ambe2dvtool in perl. Added dvtool2ambe
2  nov. 2010: Version 0.0.3: Added code in wav2ambe to deal with 
overruns/underruns
11 nov. 2010: Version 0.1.0: rewrite of wav2ambe using threads and timed interrupts
22 nov. 2010: version 0.1.1: wavstream and add support for text-message announcements
3  Jan. 2011: version 0.1.2: support for text-messages in ambe2dvtool and dvtool2ambe, added: dvtooltext and ambe2wav, improved CLI-options and static-build executable
27 Mar. 2011: Version 0.2.1: ambestream, support for DNS lookups, ipv6, auto-break, dextra linking
21 May  2012: version 0.2.2: source ip address

73
Kristoff ON1ARF