IHU Manual Page

Welcome to I Hear U (IHU), a Voice over IP (VoIP) application for Linux, that creates an audio stream between two computers easily and with the minimal traffic on the network.

The main features are:

Peer-to-Peer: the communication takes place directly between the computers (UDP and TCP both supported), without need of session protocols (such as SIP or H323) or other servers in the middle.
Good audio performance: IHU was born to give the best audio performance, low latency above all. For this purpose IHU is compatible with ALSA, now the default Linux sound architecture, but also with JACK, a low latency sound server. For the audio compression, IHU uses Speex, a codec optimized for speech (and completely free and open source).
Crypted stream: you have also the possibility to Encrypt/Decrypt the stream using a fast hybrid cryptographic system (RSA + Blowfish)
Command-line support: the Qt GUI is not strictly necessary, you can run also a textual IHU from command-line (for example if you need to run the program on remote computers).
Free and Open Source: IHU is totally free and distributed under the terms of the GNU General Public License.

The possibilities of use of IHU are endless, for example you can use it like a phone to talk with your friends all around the world, or at home/work to talk between computers in the LAN (talkback), etc.

1.1 Some important notes before starting...

First of all make sure you have the latest version of IHU (http://ihu.sourceforge.net). Follow the instructions contained in README and INSTALL files to compile the sources (you'll need the QT libraries, the ALSA sound driver, the Speex codec, the Soundtouch library, and the Ogg library). Anyway the automatic configure script will tell you what is missing.
If you want to transmit your voice/audio, then you need a microphone linked to your computer (but it's not necessary to use IHU) and, finally, you need a person to talk with, who has a computer linked to you (through the Internet or LAN) and IHU installed as well (unfortunately IHU it's not so useful alone on your computer, even if I spent hours talking to myself for tests ;-). Finally, I suggest to use headphones, to prevent feedback.
IHU's way to work is similar to a telephone: there is somebody who is waiting for phone calls, and somebody who wants to call this person. In the next paragraphs, the computer that will make the call will be named Caller and the computer that will receive the call will be named Receiver.

Now the next two steps are external to IHU and are necessary before continuing: setting up the network and the audio system.

1.1.1 Network settings

You need to know how your network is organized (is there any firewall between you and your IHU partner?). The most important thing is:

If you want to receive calls, then your computer must be able to receive incoming connections.

Those situations are possible:

If your computer is connected directly to Internet (or LAN) and Callers can access it directly with an IP or DNS address, then you should be ready to make calls without problems.

If your computer is connected through a gateway with NAT and/or a firewall, then: in order to receive calls, you have set up the firewall/gateway rules to forward incoming connections to 1793 TCP/UDP port (default, but you can change it from IHU settings).
Instead, in order to make calls, you have to make sure that the firewall (usually possible) is allowing outgoing connections on port 1793 (TCP and/or UDP). If you can't change the rules and you have a very strict firewall that allows only outgoing connections to important ports like 80, 25, etc., you could change the port of IHU to those allowed ones, but then you have to ask the Receiver to change his port, and for those port he needs root privileges.

Briefly,

If both computers are accessible from each other's IP address, no problem, both can receive and make calls.
If one computer (or both) computers are behind firewall but you could change the rules as described abow, still no problem.
If one computer is behind firewall and you can't change rules, then on this computer you can't receive calls, but you can still make calls.
If both computers are behind firewalls and it is not possible to change any rules (it seems that you are very unlucky!), then you have no chances to talk to your friend :-(

Tip: You can easily test if everything is fine using the netcat program: Receiver runs "nc -l -p 1793" (or for UDP "nc -u -l -p 1793"), and Caller runs "nc RECEIVER_IP_ADDRESS 1793" (or for UDP "nc -u RECEIVER_IP_ADDRESS 1793"). If you can see what your partner is typing (and viceversa), then IHU won't have any kind of problems.

1.1.2 Audio Settings

Then you need to set up the audio mixer, selecting the audio source and the optimal volumes. To do this you can open any mixer program (like "kmix" for KDE), paying attention to the recording source, that usually should be set to Microphone if you want to send your voice, and to the recording level (that for ALSA is usually named "Capture"). Also, take note of the playback volume (usually named "PCM", the one that you control also with XMMS, for example), because if it's too low, it will be hard to hear your partner.

Tip: You can easily test the audio settings directly with IHU. Click on Wait for calls button and then call yourself by typing "localhost" as receiver address and clicking the Call button. You will now hear yourself and you can check settings. But read the quick start to know how to do this if you have problems calling.

1.2 Quick start

Ok, you are ready to use IHU! Now you just need to know the address (IP or DNS) of the friends to call. Each IHU user who wants to receive calls should give his address to his IHU friends. Personally, I strongly suggest to register to a dynamic DNS service (such as dyndns), where you can register your computer with a fancy DNS address easy to remember (such as ihu.homelinux.org); then each time you go online, your IP should update and your friends can always call you with that address.
Let's suppose now that your internet address is ihu.homelinux.org and that you want the receive calls from your friends. Then, first of all, you have to run IHU and press the Wait for calls button. Your friend now will type ihu.homelinux.org in the Receiver address field and will press the Call button. Hopefully you will see an inbound call notification and sound and if you want, you can answer by clicking on the Answer button. At this point you should see the TX and RX leds flashing, and you should hear something, now you can finally cry out: "I Hear U!!!" ;-)

2. Detailed description

2.1 The main window

The main window (see screenshot) is composed by:

Receiver address: here you write the address (IP or DNS hostname) of the computer that you want to call, then press Enter or click the Call button to start the communication. As port, IHU is using the default port in the Settings (usually 1793), but if you want to temporarily use another port for a specific host (without changing the default port in the settings), you can quickly specify the port just after the IP address in the form ADDRESS:PORT (for example to use the port number 1790 "ihu.homelinux.org:1790").

Call (Alt+C): after you type the Receiver address, click this button to start the communication. IHU will first ring the Receiver and then, if he answers, it will capture and send your voice to your partner and you will receive your partner's voice. If your are Waiting for calls and you received a new call, than this button will become Answer (Alt+A), and will allow you to answer the call.

Ring (Alt+B) (the button with a little bell between Call and Hang Up): this is a special button. When you click this button, your partner, instead of listening to your voice, will hear a nice ringing sound, similar to the phone (it is usually so loud that could eventually damage his ears ;-). To stop ringing just click the button again. The button is available also during conversation, useful for example when you want to notify you're back after a pause, or for other many reasons you can think of. To disable the ringing tone when receiving new calls, see the settings below.
N.B. IHU will automatically activate this button when you make a call, and will stop ringing either if your partner answers or refuses. But you can also stop ringing before, without waiting for the answer clicking the button manually. This is useful, for example, to:
1. Let your partner recognize your voice, or call him by voice (funny, isn't it? ;-).
2. Leave a message (like an answering machine) if your partner is recording calls (see below for details).

Hang up (Alt+H): when you click this button, IHU will close the current communication. If you are waiting for calls and you just received a new call, this button will become Refuse (Alt+R) and you can refuse the call.

Wait for calls (Alt+W): when you click this button IHU will wait for incoming calls (remember that it isn't toggled by default when you run IHU, unless you enable the proper option in the settings). When you receive an incoming call, IHU will NOT send your voice to the caller until you press Answer. If you don't want to receive calls, then just deactivate this button.

TX led: this red led is on when IHU is transmitting data.
RX led: this green ledis on when IHU is receiving data.

Disable audio input globally (Alt+I) (button with microphone): click this button to disable audio capture or to mute your microphone for all the calls
Disable audio output globally (Alt+O) (button with speaker): click this button to disable playback or to mute the speakers for all the calls (but incoming data will be received anyway, and eventually recorded).

TX threshold: the volume level (-96dB/0dB) to be considered silence. When the sound level is softer than the threshold, IHU will consider that sound level as silence and won't send any data. This allows you to save network bandwith when you are not speaking. You should change this value to a suitable value so that TX led is off when you are not speaking. Of course this does not affect the data that you are receiving.
Recording level: useful to monitor the current volume level (-96dB/0dB) recorded on your sound card.

2.1.1 The FILE menu (Alt+F)

The FILE menu offers these simple functions:

New call (Ctrl+N): to create a new call tab. When you create multiple call tabs you will be able to make and receive multiple calls at the same moment.
Close call (Ctrl+W): to close the current CALL tab. If the call is active this operation will also close the communication. Note that the "Default" call tab can't be closed.

File Player (Ctrl+P): this button opens the File Player window. With IHU you have the possibility to save the outgoing/incoming streams to a .ihu file and then play them using the File Player. With the File Player it's also possible to convert .ihu files to .spx files.
Log Viewer (Ctrl+L): this button opens the Log window. The Log is the place where IHU records some informations about the incoming/outgoing calls, the address/name of the person who called you, the encryption key used, and other informations. The log is cleared each time you close IHU, but you can also save it to file using the proper button in the dialog or you can always save a copy of this log to file (see settings below).

Quit (Ctrl+Q): to quit ;-)

2.1.2 The CALL menu (Alt+L)

This menu contains functions that will affect only the call in the current tab:

Encrypt outgoing stream (Ctrl+E): when you check this option IHU will encrypt the outgoing stream. Your partner will be able to decrypt thanks to an automatic (and secure) key exchange. You can check/uncheck this option also during the communication.
N.B. This option will only affect your outgoing traffic. The incoming traffic is independent and can be encrypted or not, it doesn't matter. However, when one peer is encrypting the stream, then his partner will be "invited" to do the same, automatically enabling encryption too, but the user is always able to decide whether to crypt or not. So you can disable this option at any time during conversation.
Change encryption key (Ctrl+K): to change your encryption key with a new key. You can change the key also during communication, whenever you want (so IHU is compatible with paranoid individuals ;-)
Set/reset decryption key (Ctrl+D): this is useful to reset the decryption key or to change it, but, at the moment, it is only possible to set a text passphrase. So if you need, for any reason, to set a different passphrase, or you want to reset your decryption key in order to receive a fresh decryption key, then this function is for you.
Record incoming/outgoing stream to file: to record the audio stream to a .ihu file. At the moment IHU just dumps all the data packets to file, and the if the file doesn't exist itwill be created otherwise data will be appended to the file. You can only play a .ihu file using the IHU File Player (you can find it in the File menu). Unfortunately, at the moment, it's only possible to record the incoming stream seperately from the outoing stream. This means that your voice will be recorded to one file, while your partner's voice will be recorded to another file.
The .ihu files are useful also to:
1. Record messages when you can't answer calls (see the Ring button above)
2. Save important conversations, so that you can listen them again in the future whenever you want.
N.B. If the recorded stream is encrypted, then you won't be able to play it, unless you know the encryption passphrase
Tip: to play multiple files together you can convert them to .spx (See File Player) and play them all at the same time using the speexdec program (remember to set TX Threshold to minimum or to uncheck DTX to avoid discontinuos TX when recording).

2.1.3 The OPTIONS menu (Alt+P)

The OPTIONS menu offers some interesting functions:

Audio Delay Reduction (ADR) (Ctrl+R): since there might be a delay between the time you receive the data and the time you listen through your speakers, you may want to reduce this delay. Check this option to let IHU keep the audio delay as minimum as possible (please see settings below for details).
Automatic Gain Control (AGC) (Ctrl+G): check this option to activate an automatic system that keeps the recording level constant. If your voice is too soft, AGC will amplify it, instead if too loud AGC will soften it (please see settings below for details).
Please note: this option works well if TX Threshold is properly set, otherwise when you don't speak the silence will get amplified too much and when you start to speak again, the sound will become distorted.
Clear Host History (Ctrl+H): to clear the history of the Receiver address field.
Clear Missed Calls (Ctrl+M): when you don't answer or refuse a call IHU will show you an alarm icon in the tray and will notice that there are some missed in calls in the status bar. Use this function to clear the tray icon and to set the missed calls to 0.
Settings (Ctrl+S): to open the settings dialog and adjust IHU parameters (see below).

2.1.4 The HELP menu (Alt+E)

There are not so many things to say here, the only help available is what you are reading now! ;-)

2.2 The settings dialog

You can access the settings dialog from the Settings button in the main window or from the option menu (or Ctrl+S). The settings dialog allows you to change all the parameters and options of IHU, that are saved in a XML config file (default is "$HOME/.ihu.xml"). You can also save the configuration file manually, using the "Save to file" button in the dialog. The Settings dialog is organized in several tabs (please note that the default button will set the default parameters only for the current tab):

2.2.1 General settings

My name: here you can write your name, nickname, address, or whatever you want that your partner will see in order to recognize you. In my opinion it's important to write something here, but feel free to leave it empty.
Wait for incoming calls at startup: if you prefer to be able to receive calls immediately when you launch IHU, without need to click on Wait for calls button, you might want to enable this option.
Answer automatically the calls: with this option you have the ability to automatically answer a new incoming call, without need to click the Answer button. This is useful for example if you want to receive calls but you're too busy to click the button.
N.B. When IHU automatically answers, it will start to send to your partner audio captured by the microphone (unless you disable the audio input), so be careful to not use this option when you actually can't answer the call!
Show tray icon: to enable/disable the IHU system tray icon. The tray icon is useful if you need to have a quick access to IHU buttons without need of keeping the window visible.
Start minimized: when you enable the system tray icon, you have the possibility to launch IHU without opening the main window. This is useful, for example, when you enable IHU to auto-run at system startup.
Max Call Number: this is the maximum number of calls that it's possible to use at the same time.
Save Host History: this is the number of host addresses savd from the Receiver Address history (use Ctrl+H to clear the history).

2.2.2 Network settings

This tab is divided into two parts. The first is about your IHU as Receiver (when you receive calls), the second is about your IHU as Caller (when you make calls):

Receiver allowed protocols: here you can choose which protocol you want to enable on your Receiver. IHU can accept both UDP and TCP by default (recommended), so that callers can choose their preferred protocol, but you have the possibility to disable the protocols that you don't want to use. Of course you have to enable at least one protocol to receive calls.
Receiver port: this is the UDP/TCP port number on which your IHU is receiving calls (default is 1793). Please note: this port is very important and usually you shouldn't change it. If you really need to change this port, please make sure that your callers know your new port number, otherwise nobody can call you. In order to use ports lower than 1024 you must have root privileges.

Caller preferred protocol: this is the protocol used for outgoing calls (only one protocol is possible for each call). If the Receiver you want to call has both TCP and UDP enabled, then you can choose your preferred protocol, otherwise you have to use the protocol chosen by the Receiver. If you receive errors like "call rejected" when making a call, try to change the protocol.
Caller default port: this is the default port number for outgoing calls. If you don't specify any port after the address in the Receiver address, then IHU is using this default port.

2.2.3 Sound settings

Sound driver: here you can choose the sound driver for input (capture). By default IHU is using ALSA for both input/output, but if you have JACK sound driver installed on your computer, then IHU should have compiled with JACK driver support, and you can also choose to use JACK as input and ALSA as output.
A little note for JACK sound driver: Jack can give better sound performance (against audio latency), but requires a little more attention: please make sure that your Jack server is properly configured for IHU (i.e. the same sample rate, sample width, etc..) and that when you make a call, IHU Jack ports are properly connected to capture and playback devices.
Sound interface: here you can choose the input and output interfaces for ALSA. For each sound card ALSA offers two interfaces, hw and plughw. If you have more than one sound card, you can change the sound card, giving the right card number (for example plughw:1, please read the /proc/asound/card file to know the card numbers). And, for each soundcard you can change the device, giving the right device number (for example plughw:1,3, the /proc/asound/devices file contains the device numbers). By default IHU is using the "default" interface, which will automatically choose the best interface and device for you.
Please note: the sound interface is VERY important for IHU, so I strongly suggest to select the interfaces which work better for your computer. The plughw and hw should give better performance and low latency, but they have one disadvantage: they don't allow more than one capture stream per time on the interface (and eventually also playback, depends on your soundcard). So if you need to use other capture programs, then you have to choose another interface which use the dsnoop plugin. Or if you have other kind of problems then try to change the interface (try first the plughw interface, then the hw interface, or other custom interfaces). Anyway, if you decide to change the interface, than you're responsible to check the ALSA settings (read ALSA documentation for more informations on how to configure ALSA), and keep in mind that the performance of IHU can be greatly affected (long delay and bad sound quality) if you choose the wrong interface. Anyway the Jack sound driver doesn't have the disadvantages described above, have a look if you're interested.
Input format: to change the audio quality (by changing the sample rate). At the moment only three rates are possible (according to Speex rates): 8000 Hz (low quality), 16000 Hz (medium quality) and 32000 Hz (high quality). The higher the quality, the higher the use of network.
Stop TX after (silence secs): when you are using TX Threshold to stop transmission when you don't speak, it's useful to continue the transmission for some seconds, to preserve the stream against small speech pauses.
Packets prebuffer: number of packets to prebuffer before starting to play. A high number of packets ensure audio continuity, but it could increase the audio delay.
Ring Volume: here you can adjust the volume of ring tone for incoming calls.

2.2.4 Encoder settings

Here you can change the settings of your Speex encoder (so only for your outgoing stream). Those settings are very important to determine the sound quality of your voice and the use of network, so adjust them very carefully (please refer to the Speex website for more details).

Bitrate mode: you can choose a Constant Bitrate (CBR), where bitrate stays constant during the communication, using always the same amount of outgoing traffic (adjust bitrate with CBR Quality, see below). Or you can choose a Variable Bitrate (VBR), where the encoder decides automatically which bitrate to use for each frame, according to the complexity of data (adjust bitrate with VBR Quality, see below). Or you can finally choose an Average bitrate (ABR), that is a kind of variable bitrate, but the average bitrate is constant (adjust bitrate directly with ABR kbps parameter, see below).
CBR Quality: to select the bitrate for CBR (1: lowest quality, 10: highest quality).
VBR Quality: to select bitrate for VBR (1: lowest quality, 10: highest quality). Higher quality means higher bitrate, but due to variable bitrate, it can be lower or higher than what you chose, depending on the complexity of audio signal to be encoded.
ABR kbps: to select an average bitrate for ABR (Kbit/second). Bitrate is variable but the average should be around the value you specified.
Complexity: it is a parameter to select the algorithmic quality. (1: lowest, 10: highest). Higher complexity means also higher CPU use.
Voice Activity Detection (VAD): when enabled, it detects whether the audio being encoded is speech or silence/background noise. VAD is implicitly activated when encoding is VBR.
Discontinuous TX (DTX): it's an addition to VAD/VBR operation, that allows to stop transmitting completely when background noise is stationary. TX Threshold will be disabled if you decide to not use DTX.

2.2.5 Options settings

Here you find some settings about the Audio Delay Reduction (ADR) option:

Time change percentage: this is the time percentage (0-50%) that determines the speed of delay adjustment. With a high time change, the delay will be adapted faster, instead with a small time change, the delay will be adjusted more gradually (suggested, because a time change too high might affect the sound quality or might render the speech incomprehensible, or just too fast ;-).
Minimum delay: this is the minimum delay (milliseconds). When ADR is activated, if the delay on the playback sound interface is smaller than this value, IHU will try to increase the delay to this reference value, in order to avoid sound crackle.
Maximum delay: this is the maximum delay (milliseconds). If you activated ADR, IHU will try to minimize the audio delay to this value. Be careful with too little values of max delay, which could deteriorate the sound quality, or with values of Maximum delay too near to Minimum Delay, give at least 40/50 ms of tolerance.

You find also some settings about the Automatic Gain Control (AGC) option. There are two methods of AGC, you can choose to use only one of them, or you can use them together:

ALSA Mixer Control: this is the first method of AGC. IHU will try to adjust the volume of the specified mixer control (usually "Capture" on most sound cards) to reach the desired sound level. This method is used by default and it's recommended because maintains a good audio quality, since the gain is changed in the hardware. Disable this method only if you don't want to touch the mixer levels.
IHU Internal Control: this is the second method of AGC. IHU will amplify or soften the audio signal using its internal routines, without touching the mixer levels. Anyway the sound quality might be slightly damaged since the gain is virtually changed by software.
Volume Level: this is the volume level used as reference by AGC. IHU will take the peak value of the recorded sample and will adjust the volume according to this reference value.
Volume change speed: this value will influence the rapidity of volume adjustment.

2.2.6 Security settings

Here you can find some settings about security and cryptography:

Encryption key type: you can choose the type of key used for the symmetric encryption (Blowfish) of your data. You have two possibilities:
1. Random with constant length: if you choose a random key, than IHU will automatically choose a new random key each time you enable Encrypt outgoing stream, or each time you Change the encryption key. You can choose the length of the key (in bits); bigger keys should be more difficult to crack. Please remember also that with a random key it will be impossible to play recorded streams.
2. Text passphrase (please use phrases of at least 30 chars, max 56 chars): when you enable Encrypt outgoing stream, or you Change the encryption key, IHU will ask you to enter a new passphrase, that will be used for encryption. This is useful, for example, if you want to record the crypted stream to file and you want to have the possibilty to play this file later with IHU (instead with a random key it's not possible).
Set Passphrase: here you have the possibility to save the passphrase in the config file so that it won't be asked each time you decide to encrypt the communication; or it will be used if your partner is using encryption and IHU will start automatically to encrypt. To clear the passphrase just leave blank and press OK; instead to use a different temporary passphrase use the Change the encryption key function in the Call menu.
Please note: the passphrase will be saved as cleartext in the config file, so be careful!
Show decryption key of incoming stream in the Log: this option will show the decryption key type, and eventually the passphrase, of the incoming stream in the Log. When the incoming stream is using a new encyrption key, then a new message will appear in the Log, and if the key is a text passphrase, then it will be showed, otherwise IHU will just write "random key". This is useful if you are recording the stream and you want to be able to play the stream with Play File option. Since the passphrase is a confidential information, if you don't need to know the passphrase, then please do not use this option.
Write a copy of the Log also to file: if you want to save the Log (the one you open with View Log button) to file. This is useful if you want to save call informations for the future, or if you want to carefully log all incoming connections and calls.
N.B Please take care of this file because it could contain confidential informations!

2.3 The file player dialog

The file player gives you the possibility to play a previously recorded IHU file (please above to know how to record a stream to file). If the stream was encrypted than it is not possible to play the file at this time, unless you know its passphrase (IHU will automatically ask you the passphrase when encountering encrypted streams).

Open File (Alt+O): to open a IHU file to play.
Pause (Alt+P): this button will pause the file currently played.
Stop (Alt+S): this button will stop and close the file.
Convert .ihu file to .spx (Alt+C): this function is useful to convert the files recorded with IHU (.ihu extension) to standard speex files (.spx extension). The .spx files are standard Ogg files and are readable also by other applications, such as speexdec.

3. Quick launch

If you are a command-line lover, you have the possibility to launch IHU with some quick launch options. Here is the list of available options (which you can get by starting with "--help"):

USAGE
        ihu [OPTIONS]
OPTIONS
        --conf  FILE    Use FILE as configuration file
        --wait          Wait for incoming calls
        --call  HOST    Call HOST (DNS or IP address)
        --file  FILE    Play a IHU FILE
        --encrypt       Encrypt the outgoing stream
        --noinput       Disable audio INPUT
        --nooutput      Disable audio OUTPUT
        --nogui         Start without GUI (no interaction)

As you can see there is one option (--nogui), which allows you to run IHU without GUI. This is useful when you don't have the possibility to use a X server or when you want to launch IHU on remote computers, but then you don't have any possibility to interact with the program. I strongly suggest to use this option only for special cases, please use the GUI instead, which offers a better interface (please note that when using --nogui you have to change settings directly from config file, the default is "$HOME/.ihu.xml").

4. Final notes

Please use the Tracker at IHU sourceforge page to report bugs, patch, support requests. For any other kind of informations, suggestions, flames (ouch!), just mail the author. Now enjoy IHU!!

Copyright (C) 2003-2008 Matteo Trotta <mtrotta@users.sourceforge.net>

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License.