ohphoneX Manual

Overview

  1. Introduction
  2. Hardware/Software Requirements and Installation
  3. Getting Started
  4. H.323 and ohphoneX Preferences
  5. Working with ohphoneX
  6. Miscellaneous
  7. Known Bugs
  8. Glossary

Working with ohphoneX

On this page, you find information in how to use ohphoneX in everyday use.

Locations

The ability to store the preferences in Locations is a new feature introduced in ohphoneX 0.3. Its goal is to ease the usage of ohphoneX within different networks. The new architecture also allows a much more flexible handling of callto URL's and Phonebook entries.

Suppose you are using a PowerBook or iBook and want to make audio/video conferences with ohphoneX. Your company hosts a gatekeeper and other people call you by entering your office phone number. Sometimes, you want to make audio/video conferences at home but want still use the gatekeeper service. The problem is: at home, you have a LAN with private ip addresses, bridged via a NAT to the rest of the internet. If you want ohphoneX to register at your company's gatekeeper from home, you need to enable IP Address Translation. Eventually you don't have the same bandwidth at home as at your work, so you'd like to change some of the audio/video settings as well.

Everytime you want to do that, you need to change some of your preferences. This is not a confortable situation and can be quite frustrating, especially when done regularly.
The solution for this are the so called Locations. A Location is a set of preferences which you label with a name. In the main window, you have a pop-up button which contains the list of Locations you've specified. You can easily switch back and forth between the Locations, allowing you to quickly adapt to a new network situation.

In the preferences window, you have a pop up button at the top of the window view. There you can set which Location you want to edit. The list also contains an element for adding a new Location and an element for editing the list of Locations itself (renaming & deleting Locations). The images below show this.

Video Conferences

ohphoneX allows you to use any QuickTime-compliant video device for video conferences. If such a device is plugged in at launch time, the local video will appear in a drawer at the right side of the main window. You can start/stop video capturing if you want. If there are multiple devices attached to your computer, you can choose which device to use there. In Preferences, you can specify which device should be treated as the default one. If this device is attached to the computer at the time ohphoneX is launched, ohphoneX will use this device's input. If you forgot to attach the video device before ohphoneX was launched, you can choose Control->Update Video Input Device List and all new devices should appear in the list.

When you have video receive enabled in Preferences, the main window of ohphoneX will look as follows when in a call:

The text field where you can enter the remote party's name has been replaced by the remote video image. The small image in the drawer at the right side shows the local video from your webcam. Pressing the small arrow button at the right bottom of the main window shows/hides this drawer.
You also have the chance to specify a still image which will be sent whenever video capturing is stopped - provided you have enabled video transmission. This may be helpful if you have a low-bandwidth connection but you still want to show other people some sort of image.

In-Call Text Chat

When you are inside a call, you have the possibility to send each other small text messages, resulting in a text chat. This requires that the remote party also support such text messages. Pressing the button In-Call Functions at the left bottom of the main window brings the In-Call functions window to the front. Simply enter some text and press enter.

Connection Statistics

The main window of ohphoneX does itself show some connection statistics. Pressing the Connection Statistics button at the bottom of the main window brings the connection statistics window to the front.


This window provides you with detailed information about which codecs are used, the current bitrate of the audio/video streams and some additional information concerning network quality.
These informations can be really useful if you need to optimize your settings, investigate bugs etc.

Callto URLs

This section makes a short introduction to callto URLs, explains their syntax (as much as ohphoneX is concerned) and shows how to use callto URLs with ohphoneX.

What are Callto URLs?
Callto URLs were first introduced by Microsoft NetMeeting. They contain all necessary informations for making a call to a H.323-client and can be placed as links in a HTML page. When the user clicks on such a link, ohphoneX will launch if necessary and call the client defined in this URL. This mechanism is very similar to the mailto-URLs where you can define an e-mail address and the Operating System will automatically launch the appropriate e-mail application.

For an in-dept definition of callto-URLs, please visit the Microsoft NetMeeting callto-URL page

Callto URL Syntax
A callto-URL consists of one of four types of addresses. These four types are:

  • ip (IP Addresses)
  • host (Host Addresses)
  • phone (Phone Addresses)
  • directory (Directory Addresses)
ohphoneX does only support IP Addresses and Phone Addresses.

The general syntax of a callto-URL is:
"callto:/ADDRESS+type=TYPE" whereas ADDRESS is the address to call and TYPE is one of these four types described above. The type phone is the default one, so if no type is specified, the address will be treated as a phone address.
If the remote party at ADDRESS listens under a different port than a the default H.323 port, you can use the following callto-URL syntax:
"callto:/ADDRESS:PORT+type=TYPE"
The slash after the callto: string is optional and actually not part of the callto-URL specification. However, in some occasion this slash is needed to "trick" around some WebBrowsers such as Safari. They tend sometimes to interpred the callto-URL as a natural HTTP-URL.

When TYPE is ip, ohphoneX makes a direct call, not using a gatekeeper. If TYPE is phone, a gatekeeper is required to resolve the phone number. Normally, the default gatekeeper (the one specified in Preferences) is used. In some occasions it is necessary to use a different gatekeeper than the default one. In this case, you may add a "+gatekeeper=GATEKEEPER:PORT" to the URL. (PORT is here optional as well)
When using a different gatekeeper, eventually it is also necessary to use a different username and / or phone number as well. For this calse, ohphoneX will understand "+username=USERNAME" and "+phonenumber=PHONENUMBER" as well.
Note: These last three additions to callto-URLs are not part of the original callto-URL specification from Microsoft. ohphoneX will understand them and interpret them correctly, but other clients most probably won't. It is also very unlikely that you will encounter a situation where these additions useful. In most cases, you don't need to use them.

Examples of callto-URLs
Here are some examples of callto-URLs:

callto:/192.168.1.1+type=ip
(Calls host 192.168.1.1 at the default port 1720)

callto:/192.168.1.1:1721+type=ip
(Calls host 192.168.1.1 at port 1721)

callto:123456
(Calls phone number 123456 by using a gatekeeper)

callto:123456+type=phone+gatekeeper=mygatekeeper.mycompany.com:1800+username=myname+phonenumber=111111
(Calls phone number 123456 by using gatekeeper "mygatekeeper.mycompany.com" at port 1800, registering with "myname" and phonenumber "111111")

Using callto-URLs with ohphoneX
If ohphoneX is installed in /Applications or ~/Applications, ohphoneX will launch automatically when you click a callto-URL in a web browser such as Safari and try to call the address specified in the URL.
Another option is to use the Services facility from MacOSX. If you select a callto-URL, you can choose the Call in ohphoneX command from the Services menu. ohphoneX will then try to call this address.

Phone Book

This section describes how to work with the Phone Book of ohphoneX.
ohphoneX integrates Support for Apple's Address Book API. For each record in Address Book, you can add the required informations for making H.323 calls to this person. Internally, this is done by using callto-URLs (see section above) so that potentially other H.323 clients also have access to these informations.
For users which don't use Apple's Address Book for storing their addresses, ohphoneX provides a way to add simple records to the Address Book database without having to launch the Address Book application itself. The data is still stored in the Address Book database, though.
When launching the Address Book, you will not see the callto-URL entries. Only ohphoneX does extract them from the database and display them on screen.

Using the Phone Book
Pressing the Phone Book button in the main window opens the Phone Book window which looks as follows:


You can browse your records, search for matches etc. If you want to call the selected record, either press the Call this Person button or simply press the Return key.

Editing Phone Book Records Pressing the Edit in Address Book button launches the Address Book application and allows you to edit the general settings of the selected user such as name, streed, phone number etc. You cannot change the Callto-URL from within Address Book.
This is more four your convenience.

If you want to edit the Callto-URL associated with the selected record, you have to press the Edit Callto-Info button. In the displayed sheet, you can edit all H.323 relevant information.


The Call Type pop up list allows you to define the type of the callto-URL. If you specify No Callto-URL, ohphoneX will not store any callto-URL for this record. Existing callto-URL entries for this record will be deleted. By choosing Direct Call or Using a Gatekeeper, you can specify which type of calls you make to this person. When using a gatekeeper, you also have the options to specify another gatekeeper / username / E.164-Number as the default ones. (specified in Preferences)

Adding a new Record
When pressing the New Record button, you have the ability to add a new record to the Address Book database. The only values you can enter are the First- and Last Name.
If you want to add additional informations besides name and callto-URLs, you have to use the Address Book application itself.