MythPhone
                             =========
Release 0.15+ CVS
Paul Volkaerts
August 28th 2004


Mythphone is a phone and videophone capability on MYTH using the standard
SIP protocol.  It is compatible with Microsoft XP Messenger (see caveat
below) and with SIP Service Providers such as Free World Dialup 
(fwd.pulver.com).



COMPILING MYTHPHONE
===================
If you are not using the Festival TTS Engine, then just type
    ./configure
    qmake mythphone.pro
    make
    make install (as root)

If you want to use the TTS engine then first of all download Festival
as per below then edit the file "configure" and set the paths for where 
you have installed Festival in variables FESTIVALDIR and SPEECHTOOLSDIR. 
Then;

    ./configure --enable-festival
    qmake mythphone.pro
    make
    make install (as root)



PREREQUISITES
=============
There are no mandatory prerequisites other than Myth itself; but you can
compile in support for a Text to Speech (TTS) engine called Festival. This
enables support for voicemail and reading of the TV Guide over the phone.

Festival Text-to-Speech Engine v1.4.3 
http://www.cstr.ed.ac.uk/projects/festival/

Download and follow the instructions in the INSTALL file. You will
need to download the main file festival-1.4.3-release.tar.gz and the
toolset speech_tools-1.2.3-release.tar.gz. Then you also need some data
files, as a minimum festlex_CMU.tar.gz, festlex_POSLEX.tar.gz and
festvox_kallpc8k.tar.gz. This gives a male English voice. You can follow
the instructions to download others to try other voices. The myth setup 
screens allow you to pick from your downloaded voices.
To compile, simply run ./configure then make within first the 
speech_tools directory and then the festival directory. 




FEATURES / HOW-TO-USE
=====================
Mythphone uses a SIP stack to allow voice and/or video calls to
be placed to other SIP clients. This includes other MythFrontends on your
system, Mythfrontends over the Internet, or other standard SIP clients. 

Mythphone operates best when registered to a Service Provider such as Free
World Dialup but this is not mandatory; especially if you only want to call
between MythFrontends on your local LAN. 

Accounts with FWD are free; just go to http://www.fwd.pulver.com
and sign up. Mythphone should work with a variety of similar services but I
have only tried a couple.  Your experience, positive or negative, with other
providers is welcome.



Features:-

* Contact database for click-dialling
* Voice calls at G.711 20ms
* Video calls at H.263
* Pan and Zoom for video calls, useful if your web-cam captures at a higher 
resolution than you transmit
* Voicemail
* Send/receive DTMF (RFC 2833)
* VXML scripting with Text-To-Speech engine allows you to call in and hear 
the TV Guide / set recording etc
* Full screen video
* Call history
* Popup whilst watching TV shows a call is coming in; though currently you 
have to navigate to mythphone to answer it.
* NAT and Firewall handling (see below)

Keys:-
* Up/Down/Left/Right/Select/Exit for most features
* Menu (M) key is context sensitive
* Play (P) during a call toggles video into full screen mode
* Home/End during a call zooms local webcam
* U/D/L/R during a call pans the local webcam
* 0..9, * and # during a call send DTMF
* 0..9, * and # NOT during open a dial dialogue
* Volume Up/Down changes the speaker volume; but whilst in volume-change mode
you can use Up/Down to switch to Brightness/Colour/Contrast/frame-rate etc.
* Mute (|) mutes the microphone during a call


If you are registered with fwd.pulver.com (or similar) you call someone by 
typing their phone number.  If you are not registered with a Service Provider
then you need to dial a full URL, of the form name@hostname or name@ip-address.
This is obviously a lot more hassle when using a numeric remote control! 

Contacts can be added to the directory either before calling them (using the Menu
button) or after placing/receiving a call by going to the call-history entry then
pressing menu. Once in the menu; it is a lot easier to call people using the remote.


Status-Bar:-
The status bar, when in a call, shows 
* other party name
* Audio & Video packet loss as xx%/yy% where xx% is percentage packet loss over
the last 2 seconds and yy% packet loss is total for the call. This tells you
how good your receive signal is
* Bandwidth. This is a total figure for voice+video. If it read above 256k and
you only have a 256k upstream link then the person you are speaking to is going
to get a pretty poor signal. Use this to match the transmit rate to your 
available upstream bandwidth. You can reduce by lowering the video resolution 
or frame rate.



WEB-CAM SUPPORT
===============
I use a Logitech webcam with the Philips PWC driver built into the kernel 
(Linux 2.4.23).  For this to work at reasonable rates you need to download
the decompression module pwcx.o and install using "insmod --force pwcx.o".
You get this from www.smcc.demon.nl/webcam.

This webcam stores its settings locally; so you can download "camstream" from
the above URL to tune its settings.

You also need to set the Frames Per Second when the module is loaded too, as 
there is no support in this application for writing to these Phillips-specific
parameters. (The FPS attribute in the setup screens tells the software what to
expect from the webcam; it does not configure the webcam).

I also use the microphone built into this webcam by enabling the kernel 
option for USB audio. 

Webcam transmit frames/sec and resolution can be changed mid-call or between 
calls using the volume+/- buttons then cursor keys.



NAT and Firewall
===============
If you have NAT, and your ISP always gives you the same IP address, you can
set the NAT to "manual" and enter this IP address. This is the most efficient
way to handke NATs.

If you have NAT but your ISP can give you a variable IP addresses, you can
select the option "Web Server" and enter a URL such as "checkip.dyndns.org".
This is a web site which returns your real address in response to a HTTP GET.
It will consult this web server for every call.

Calling between local Myth Frontends that are on the same LAN is supported by
a checkbox on the directory entry called "On Local LAN".  Myth Frontends 
automatically create directory entries for themselves with this checked.

At your network router, you may need to configure it to forward port 5060 
to your Myth box that you want to receive calls.

If you have a firewall, you may need to open up port 5060 and whatever 
ports you choose for audio and video media in the config screens.



MICROSOFT XP MESSENGER COMPATABILITY 
====================================

Video calls can be made to/from a Microsoft XP Messenger client.  I have
tested this against Windows Messenger 4.7.  Note this is "not" the same 
as MSN Messenger!!!

Windows Messenger is, in its default mode, not a standards compliant SIP
endpoint.  But it does have SIP support that you can enable as follows.

1) Create an account for the Windows client at a Service Provider such as
fwd.pulver.com.

2) On Windows Messenger, click Tools->Options; select the "Accounts" tab,
and enable the lower checkbox "My contacts include users of a communications
service". Then in the Sign-in name enter the username 
e.g. 123456@fwd.pulver.com.

3) Click ADVANCED and set the server name to you service provider e.g.
fwd.pulver.com and select connect using UDP.

4) You may need to re-sign in; and when you do it should prompt you for your
password.

Now; simply call the Microsoft client using the phone number you were allocated
in step 1; (in this example 123456).

It is not worth trying high resolutions with this; Microsoft always sends at a
pretty low resolution and they always display received video in a tiny rectangle
regardless of the received resolution!





CAVEATS
=======

* There is no Microphone-volume control. This is because I use the microphone
within my USB webcam and Linux has no drivers for volume control on USB 
microphones. I will implement an attenuation algorithm if required.

* There is no echo cancellation. It really does need some. Anyone know where I
can find a public domain algorithm please let me know.

* To answer a call, you have to be in the Mythphone plugin. You do get a popup
whilst watching TV if someone calls; but in reality if you want to speak 
to someone you sort of need to call them first on a real phone!  Remember 
this is a first-cut of software so do't be too hard on me :-)




VXML PAGES
----------
VXML is a derivative of XML and HTML; but for voice calls. It allows information
in HTML pages to be read out over a phone call. It is used in this project to
provide voicemail and access to the TV guide over the phone using a text-to-speech
engine.

Within the setup there is an option which allows entry of a VXML web-page. If
you only want voicemail; leave this blank, If you want to try some more complex
things like allowing setting of recording via the phone, then enter a URL in
this field pointing to the mythweb vxml pages. The files in the "vxml" folder 
in mythweb contain some scripts that do some things but they do need 
improvement and testing.

The following is a description of these files ...

index.vxml -- This is the main VXML which you should point mythphone to. It plays
a welcome message then prompts the caller to leave a voicemail or enter a pin. 
The pin is hard-coded in this file as "12345".

voicemail.vxml -- If during the execution of the above file the user asks to 
leave a voicemail it jumps to this file for recording a prompt.

securemenu.vxml -- If during the initial menu the user enters a correct pin 
it jumps to this file which then prompt with a second-level menu such as 
"read the TV guide". Edit this file and make sure it points to your 
"program_listing.php" file within mythweb.