I Hear U Manual Page

# IHU Manual Page

Version: 0.5.6

## Index

1. Introduction
1.1 Some important notes before starting...
1.1.1 Network settings
1.1.2 Audio settings
1.2 Quick start
2. Detailed description
2.1 The main window
2.1.1 The FILE menu
2.1.2 The OPTIONS menu
2.1.3 The HELP menu
2.2 The settings dialog
2.2.1 General settings
2.2.2 Network settings
2.2.3 Sound settings
2.2.4 Encoder settings
2.2.5 Options settings
2.2.6 Security settings
3. Quick launch
4. Final notes

## 1. Introduction

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 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, and if firewalls are present 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,

1. If both computers are accessible from each other's IP address, no problem, both can receive and make calls.
2. If one computer (or both) computers are behind firewall but you could change the rules as described abow, still no problem.
3. 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.
4. 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 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. You run two instances of IHU and, in the first IHU window you become a silent Receiver clicking on Wait for calls and on Disable audio input, instead in the second window you become a self-Caller typing "localhost" as receiver address (You may need to Disable the audio output on this one). 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 myhostname.homelinux.org); then each time you go online, your IP should update and your friends can always call you with that address.
Lets suppose now that your internet address is hostname.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 your address (hostname.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 "host.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 in the center with a little bell): 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, just disable the audio output (see 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, see below). 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 or you can't answer calls at the particular moment, then just deactivate this button.

- TX led: this red led is on when IHU is transmitting data.
- RX led: this green led is on when IHU is receiving data, or, when waiting for calls, if you missed some calls.
- TX threshold: the volume level (0-100%) to be considered silence. When threshold is greater than zero, IHU won't send any data that is considered silence. 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.
  N.B. When you are playing pre-recorded files, this slidebar becomes File progress, and you can change the current file position.
- AGC volume the volume level (0-100%) used as reference for the Automatic Gain Control (that controls the playback volume), but it is available only if you activate the AGC option (see options below).

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

- Settings (ALT+S): to open the settings dialog and configure IHU (see below).

- View Log (ALT+L): this button opens the Log window. In this window IHU keeps the most important messages that appear in the status bar when IHU is working, showing the timestamp of the message. This log window is important to see if you received some calls, the address/name of the person who called you, the encryption key used, and much more informations on calls. The log is cleared each time you close IHU, but you can also save it to file (see security settings below).

2.1.1 The FILE menu (ALT+F)
The FILE menu offers these simple functions:

- Play IHU file (CTRL+F): to play a previously recorded IHU file (please read the settings section to know how to record a stream to file). If the stream was encrypted than it is not possible to play the fileat this time, unless you know its passphrase (IHU will automatically ask you the passphrase when encountering encrypted streams).
- Convert .ihu file to .spx (CTRL+T): 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. Note that for each speex mode encountered in the .ihu file (i.e. with different sampling rates, 8000, 16000 or 32000), IHU will create a new logical stream inside the Ogg file; you can use other external applications to demultiplex the stream.
- Quit (CTRL+Q): to quit ;-)

2.1.2 The OPTIONS menu (ALT+P)
The OPTIONS menu offers some interesting functions:

- Encrypt outgoing stream (CTRL+E): if 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.
- 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 (you can set up your delay value in the settings window).
- Automatic Gain Control (AGC) (CTRL+G): check this option to activate an automatic system that keeps the playback volume always at the same level. If the voice of your partner is too soft, AGC will amplify it, instead if too loud AGC will soften it. You can adjust the volume thanks to the AGC volume level slidebar.
  Please note: this option works well only when your partner who is speaking is properly using sound threshold (greater than zero), otherwise when your partner doesn't speak, the silence will get amplified so much that when he starts to speak again, the sound will become distorted. If there is no way to convince your partner to properly use TX threshold level, than adjust gain settings manually (see below).
- Settings (CTRL+S): to open the settings dialog and adjust IHU parameters (see below).

2.1.3 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 setting dialog from the Settings button in the main window or from the option menu (ALT+S or CTRL+S). The settings dialog allows you to change all the parameters and options of IHU. It 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 immediately be able to receive calls when you launch IHU, without need to click on Wait for calls button, you can 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 use the mouse or keyboard 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.
- Record stream to file: to record the audio stream to a ".ihu" file. At the moment IHU just dumps all the data packets to file. You can only play this file using the Play file function from the File menu. Remember that if you record an encrypted stream, then you won't be able to play it, unless you know the encryption passphrase.
  Unfortunately, at the moment, it is possible only 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. But this is already useful for example to:
  1. Record messages when you can't answer calls (see the Ring button above)
  2. Save important converstations, so that you can listen them again in the future whenever you want.

##### 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 "Connection refused" or "Connection 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 main window, then IHU is using this default port.

##### 2.2.3 Sound settings

- Sound driver: here you can choose the sound driver for input (capture) and for output (playback). 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. This means that you can also choose to use JACK as input and ALSA as output, or JACK for input/output (note that you can't use ALSA for input and JACK for 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 start playback or recording, IHU Jack ports are properly connected to capture and playback devices. Note also that when using Jack as output driver, the ADR option is not available (there is no need! ;-).
- 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, please read the /proc/asound/devices file to know the device numbers). By default IHU is using the "default" interface, which will automatically choose the best interface and device for you.
  Please note: this setting 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. I recommend the use of the Jack sound driver, where possible, because doens't have the disadvantages described above.
- Input format: to change the audio quality (adjusting input sample rate and format). 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 a threshold greater than zero, 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.

##### 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 (ADR) option:

- Volume change speed: this is the speed factor of playback volume adapting, in order to reach the reference volume value (the one you control in the main window, see above). Increase if you want the volume to adapt faster, reduce to make the volume change more gradual.
- Minimum gain factor: this is the minimum amplification factor, to soften the sound. A value of zero means that sound can be reduced to total silence. Instead, if you don't want to reach silence, than increase this value.
- Maximum gain factor: this is the maximum amplification factor, to amplify the sound. You should decrease this value if silence is amplified too much and the sound gets too loud and distorted when user is speaking, instead increase if the volume is not well amplified enough.

##### 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): each time 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).
- 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 (for security reasons).
  N.B Please take care of this file because it could contain confidential informations!

## 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
            --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 qt config file, usually "$HOME/.qt/ihurc").

## 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-2006 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.