Help on a specific field can also be found in Twinkle itself by clicking the question mark on the top right corner of a window and then click on the field itself. Or press Shift+F1 when the field has focus.

Starting Twinkle

First usage

To use Twinkle you need to create a user profile. A user profile contains the data for your SIP account, like your username, password, SIP proxy address and more. You can create multiple user profiles for different accounts that you may have.

When you start Twinkle for the first time it will ask you to create a user profile. First you have to give your profile a name and then you fill in the data. To create the user profile you can use the user profile wizard, the user profile editor or create a Diamondcard profile.

The next time you run Twinkle it will show you a list of all your profile names and you can pick the profiles you want to run. You can also create new profiles, delete old profiles and rename profiles.

The user profile wizard

After you have named your profile you get into the user profile wizard. The user profile wizard asks you for the bare minimum of settings to create a working profile. At a later time you can always edit the full profile using the user profile editor.

The wizard contains predefined settings for a few SIP service providers. When you choose one of the predefined providers, you only have to fill in your user account information.

Wizard
Field	Explanation
SIP service provider	Choose your SIP service provider.
Your name	This is just your full name, e.g. John Doe. It is used as a display name. When you make a call, this display name might be shown to the called party.
User name	The SIP user name given to you by your provider. It is the user part in your SIP address, username@domain.com This could be a telephone number. This field is mandatory.
Domain	The domain part of your SIP address, username@domain.com. Instead of a real domain this could also be the hostname or IP address of your SIP proxy. If you want direct IP phone to IP phone communications then you fill in the hostname or IP address of your computer. This field is mandatory.
Authentication name	Your SIP authentication name. Quite often this is the same as your SIP user name. It can be a different name though.
Password	Your password for authentication.
SIP proxy	The hostname, domain name or IP address of your SIP proxy. If this is the same value as your domain, you may leave this field empty.
STUN server	The hostname, domain name or IP address of the STUN server.

The user profile editor

After you have named your first profile you get into the user profile editor. Later you might create new profiles or edit existing profiles. The user profile editor is the same in each case.

The user profile editor contains several pages. Each page will be described below.

At a minimum you have to fill in the user section. Depending on your network you may have to make some settings in the SIP server settings.

If you are behind a NAT, then you have to make some settings in the NAT section.

The default settings in all other sections should usually work for you. Depending on your preferences you may make changes here.

User

The user section contains data concerning your SIP account. If you have an account with a SIP provider, then the provider should provide you with this data. If you want to use Twinkle for direct IP phone to IP phone communications you have to create a user name yourself.

SIP account settings
Field	Explanation
Your name	This is just your full name, e.g. John Doe. It is used as a display name. When you make a call, this display name might be shown to the called party.
User name	The SIP user name given to you by your provider. It is the user part in your SIP address, username@domain.com This could be a telephone number. This field is mandatory.
Domain	The domain part of your SIP address, username@domain.com. Instead of a real domain this could also be the hostname or IP address of your SIP proxy. If you want direct IP phone to IP phone communications then you fill in the hostname or IP address of your computer. This field is mandatory.
Organization	You may fill in the name of your organization. When you make a call, this might be shown to the called party.

SIP authentication settings
Field	Explanation
Realm	The realm for authentication. This value must be provided by your SIP provider. If you leave this field empty, then Twinkle will try the user name and password for any realm that it will be challenged with.
Name	Your SIP authentication name. Quite often this is the same as your SIP user name. It can be a different name though.
Password	Your password for authentication.
AKA-OP	Operator variant key for AKAv1-MD5 authentication.
AKA-AMF	Authentication management field for AKAv1-MD5 authentication.

If Twinkle needs to authenticate (eg. for a registration) and the realm, name or password are wrong, then you will be interactively asked for your correct credentials during the authentication process. These credentials will then be cached till you exit Twinkle. They will not be written to your profile.

SIP server

Registrar settings
Field	Explanation
Registrar	The hostname, domain name or IP address of your registrar. If you use an outbound proxy that is the same as your registrar, then you may leave this field empty and only fill in the address of the outbound proxy.
Expiry	The registration expiry time that Twinkle will request.
Register at startup	Indicates if Twinkle should automatically register when you run this user profile. You should disable this when you want to do direct IP phone to IP phone communication without a SIP proxy.
Add q-value to registration	The q-value indicates the priority of your registered device. If besides Twinkle you register other SIP devices for this account, then the network may use these values to determine which device to try first when delivering a call. The q-value is a value between 0.000 and 1.000. A higher value means a higher priority.

Outbound proxy settings
Field	Explanation
Use outbound proxy	Indicates if Twinkle should use an outbound proxy. If an outbound proxy is used then all SIP requests are sent to this proxy. Without an outbound proxy, Twinkle will try to resolve the SIP address that you type for a call invitation for example to an IP address and send the SIP request there.
Outbound proxy	The hostname, domain name or IP address of your outbound proxy.
Send in-dialog requests to proxy	SIP requests within a SIP dialog are normally sent to the address in the contact-headers exchanged during call setup. If you tick this box, that address is ignored and in-dialog request are also sent to the outbound proxy.
Don't send a request to proxy if its destination can be resolved locally	When you tick this option Twinkle will first try to resolve a SIP address to an IP address itself. If it can, then the SIP request will be sent there. Only when it cannot resolve the address, it will send the SIP request to the proxy (note that an in-dialog request will only be sent to the proxy in this case when you also ticked the previous option.)

Voice mail

Voice mail settings
Field	Explanation
Voice mail address	The SIP address or telephone number to access your voice mail.
MWI type	Message waiting indication type If your provider offers the message waiting indication service, then Twinkle can show you when new voice mail messages are waiting. Ask your provider which type of message waiting indication is offered. Unsollicited Asterisk provides unsollicited message waiting indication. Sollicited Sollicited message waiting indication as specified by RFC 3842.
Mailbox user name	Your user name for accessing your voice mailbox.
Mailbox server	The hostname, domain name or IP address of your voice mailbox server.
Via outbound proxy	Check this option if Twinkle should send SIP messages to the mailbox server via the outbound proxy.
Subscription duration	For sollicited MWI, an endpoint subscribes to the message status for a limited duration. Just before the duration expires, the endpoint should refresh the subscription.

Instant message

Instant message
Field	Explanation
Maximum number of sessions	When you have this number of instant message sessions open, new incoming message sessions will be rejected.
Send composing indications when typing a message	Twinkle sends a composing indication when you type a message. This way the recipient can see that you are typing.

Presence

Presence
Field	Explanation
Publish availability at startup	Publish your availability at startup.
Publication refresh interval (sec)	Refresh rate of presence publications.
Subscription refresh interval (sec)	Refresh rate of presence subscriptions.

RTP audio

Codec settings
Field	Explanation
Available codecs	List of available codecs.
Active codecs	List of active codecs. These are the codecs that will be used for media negotiation during call setup. The order of the codecs is the order of preference of use.
G.711/G.726 payload size	The preferred payload size for the G.711 and G.726 codecs.
Follow codec preference from far end on incoming calls	For incoming calls, follow the preference from the far-end (SDP offer). Pick the first codec from the SDP offer that is also in the list of active codecs. If you disable this option, then the first codec from the active codecs that is also in the SDP offer is picked.
Follow codec preference from far end on outgoing calls	For outgoing calls, follow the preference from the far-end (SDP answer). Pick the first codec from the SDP answer that is also in the list of active codecs. If you disable this option, then the first codec from the active codecs that is also in the SDP answer is picked.

Preprocessing of the microphone signal can improve quality at the far-end of a call.

Preprocessing settings
Field	Explanation
Automatic gain control	Automatic gain control (AGC) is a feature that deals with the fact that the recording volume may vary by a large amount between different setups. The AGC provides a way to adjust a signal to a reference volume. This is useful because it removes the need for manual adjustment of the microphone gain. A secondary advantage is that by setting the microphone gain to a conservative (low) level, it is easier to avoid clipping.
Voice activity detection	When enabled, voice activity detection detects whether the input signal represents a speech or a silence/background noise.
Noise reduction	The noise reduction can be used to reduce the amount of background noise present in the input signal. This provides higher quality speech.
Acoustic echo cancelation	This is an experimental feature. In any VoIP communication, if a speech from the remote end is played in the local loudspeaker, then it propagates in the room and is captured by the microphone. If the audio captured from the microphone is sent directly to the remote end, then the remote user hears an echo of his voice. An acoustic echo cancellation is designed to remove the acoustic echo before it is sent to the remote end. It is important to understand that the echo canceller is meant to improve the quality on the remote end.

iLBC settings
Field	Explanation
iLBC payload type	The dynamic type value (96 or higher) to be used for iLBC.
iLBC payload size	The preferred payload size for iLBC.

Speex settings
Field	Explanation
VBR	Variable bit-rate (VBR) allows a codec to change its bit-rate dynamically to adapt to the "difficulty" of the audio being encoded. In the example of Speex, sounds like vowels and high-energy transients require a higher bit-rate to achieve good quality, while fricatives (e.g. s,f sounds) can be coded adequately with less bits. For this reason, VBR can achieve a lower bit-rate for the same quality, or a better quality for a certain bit-rate. Despite its advantages, VBR has two main drawbacks: first, by only specifying quality, there's no guarantee about the final average bit-rate. Second, for some real-time applications like voice over IP (VoIP), what counts is the maximum bit-rate, which must be low enough for the communication channel.
DTX	Discontinuous transmission is an addition to VAD/VBR operation, that allows to stop transmitting completely when the background noise is stationary.
Perceptual enhancement	Perceptual enhancement is a part of the decoder which, when turned on, tries to reduce (the perception of) the noise produced by the coding/decoding process. In most cases, perceptual enhancement make the sound further from the original objectively (if you use SNR), but in the end it still sounds better (subjective improvement).
Complexity	With Speex, it is possible to vary the complexity allowed for the encoder. This is done by controlling how the search is performed with an integer ranging from 1 to 10 in a way that's similar to the -1 to -9 options to gzip and bzip2 compression utilities. For normal use, the noise level at complexity 1 is between 1 and 2 dB higher than at complexity 10, but the CPU requirements for complexity 10 is about 5 times higher than for complexity 1. In practice, the best trade-off is between complexity 2 and 4, though higher settings are often useful when encoding non-speech sounds like DTMF tones.
Quality	Speex is a lossy codec, which means that it achives compression at the expense of fidelity of the input speech signal. Unlike some other speech codecs, it is possible to control the tradeoff made between quality and bit-rate. The Speex encoding process is controlled most of the time by a quality parameter that ranges from 0 to 10.
Narrow band payload type	The dynamic type value (96 or higher) to be used for speex narrow band.
Wide band payload type	The dynamic type value (96 or higher) to be used for speex wide band.
Ultra wide band payload type	The dynamic type value (96 or higher) to be used for speex ultra wide band.

G.726 settings
Field	Explanation
G.726 ... payload type	The dynamic type value (96 or higher) to be used for G.726.
Codeword packing order	There are 2 standards to pack the G.726 codewords into an RTP packet. RFC 3551 is the default packing method. Some SIP devices use ATM AAL2 however. If you experience bad quality using G.726 with RFC 3551 packing, then try ATM AAL2 packing.

DTMF settings
Field	Explanation
DTMF transport	RFC 2833 Send DTMF tones as RFC 2833 telephone events. Inband Send DTMF inband. Auto If the far end of your call supports RFC 2833, then a DTMF tone will be send as RFC 2833 telephone event, otherwise it will be sent inband. Out-of-band (SIP INFO) Send DTMF out-of-band via a SIP INFO request.
DTMF payload type	The dynamic type value (96 or higher) to be used for DTMF events (RFC 2833).
DTMF duration	Duration of a DTMF tone.
DTMF pause	The pause after a DTMF tone.
DTMF volume	The power level of the DTMF tone in dB.

SIP protocol

Protocol options
Field	Explanation
Call Hold variant	Indicates if RFC 2543 (set media IP address in SDP to 0.0.0.0) or RFC 3264 (use direction attributes in SDP) is used to put a call on-hold.
Max-Forwards header is mandatoy	According to RFC 3261 the Max-Forwards header is mandatory. But many implementations do not send this header. If you tick this box, Twinkle will reject a SIP request if Max-Forwards is missing.
Allow missing Contact header in 200 OK on REGISTER	A 200 OK response on a REGISTER request must contain a Contact header. Some registrars however, do not include a Contact header or include a wrong Contact header. This option allows for such a deviation from the specs.
Put registration expiry time in contact header	In a REGISTER message the expiry time for registration can be put in the Contact header or in the Expires header. If you tick this box it will be put in the Contact header, otherwise it goes in the Expires header.
Use compact header names	Indicates if compact header names should be used for headers that have a compact form.
Encode Via, Route, Record-Route as list	The Via, Route and Record-Route headers can be encoded as a list of comma separated values or as multiple occurrences of the same header.
Use domain name to create a unique contact header value	Twinkle creates a unique contact header value by combining the SIP user name and domain: `user_domain@local_ip` This way 2 user profiles, having the same user name but different domain names, have unique contact addresses and hence can be activated simultaneously. Some proxies do not handle a contact header value like this. You can disable this option to get a contact header value like this: `user@local_ip` This format is what most SIP phones use.
Allow SDP change during call setup	A SIP UAS may send SDP in a 1XX response for early media, e.g. ringing tone. When the call is answered the SIP UAS should send the same SDP in the 200 OK response according to RFC 3261. Once SDP has been received, SDP in subsequent responses should be discarded. By allowing SDP to change during call setup, Twinkle will not discard SDP in subsequent responses and modify the media stream if the SDP is changed. When the SDP in a response is changed, it must have a new version number in the o= line.

Redirection settings
Field	Explanation
Allow redirection	Indicates if Twinkle should redirect a request if s 3XX response is received.
Ask user permission to redirect	Indicates if Twinkle should ask the user before redirecting a request when a 3XX response is received.
Max redirections	The number of redirect addresses that Twinkle tries at a maximum before it gives up redirecting a request. This prevents a request from getting redirected forever.

SIP extensions
Field	Explanation
100rel (PRACK)	Indicates if the 100rel extension (PRACK) is supported: disabled 100rel extension is disabled supported 100rel is supported (it is added in the supported header of an outgoing INVITE). A far-end can now require a PRACK on a 1xx response. required 100rel is required (it is put in the require header of an outgoing INVITE). If an incoming INVITE indicates that it supports 100rel, then Twinkle will require a PRACK when sending a 1xx response. A call will fail when the far-end does not support 100rel. preferred Similar to required, but if a call fails because the far-end indicates it does not support 100rel (420 response) then the call will be re-attempted without the 100rel requirement.

Call transfer (REFER)
Field	Explanation
Allow call transfer (incoming REFER)	Indicates if Twinkle should transfer a call if a REFER request is received.
Ask user permission to transfer	Indicates if Twinkle should ask the user before transferring a call when a REFER request is received.
Hold call with referrer setting up call to transfer target	Indicates if Twinkle should put the current call on hold when a REFER request to transfer a call is received.
Hold call with referee before sending REFER	Indicates if Twinkle should put the current call on hold when you transfer a call.
Auto refresh subscription to refer event while call transfer is not finished	While a call is being transferred, the referee sends NOTIFY messages to the referrer about the progress of the transfer. These messages are only sent for a short interval which length is determined by the referee. If you tick this box, the referrer will automatically send a SUBSCRIBE to lengthen this interval if it is about to expire and the transfer has not yet been completed.

Transport/NAT

SIP can be transported over UDP or TCP. In this section you can select the desired transport protocol.

Transport
Field	Explanation
Transport protocol	Transport mode for SIP. In auto mode, the size of a message determines which transport protocol is used. Messages larger than the UDP threshold are sent via TCP. Smaller messages are sent via UDP.
UDP threshold	Messages larger than the threshold are sent via TCP. Smaller messages are sent via UDP.

If there is a NAT device (eg. a broadband router in a home network) between you and your SIP proxy and your SIP provider does not offer you hosted NAT traversal, then you have two options to make the SIP protocol work (see NAT traversal).

In this section you can make the proper NAT settings. STUN does not work for incoming TCP connections.

NAT traversal
Field	Explanation
NAT traversal not needed	Choose this option when there is no NAT device between you and your SIP proxy or when your SIP provider offers hosted NAT traversal.
Use statically configured public IP address inside SIP messages	Indicates if Twinkle should use the public IP address specified in the next field inside SIP message, i.e. in SIP headers and SDP body instead of the IP address of your network interface. When you choose this option you have to create static address mappings in your NAT device as well. You have to map the RTP ports on the public IP address to the same ports on the private IP address of your PC.
Public IP address	The public IP address of your NAT.
Use STUN	Choose this option when your SIP provider offers a STUN server for NAT traversal.
STUN server	The hostname, domain name or IP address of the STUN server.
Persistent TCP connection	Keep the TCP connection established during registration open such that the SIP proxy can reuse this connection to send incoming requests. Application ping packets are sent to test if the connection is still alive.

Address format

This section contains settings for displaying telephone number and add the "user=phone" parameter to a SIP URI.

Telephone number settings
Field	Explanation
Only display user part of URI for telephone number	If a URI indicates a telephone number, then only display the user part. E.g. if a call comes in from sip:123456@twinklephone.com then display only "123456" to the user. A URI indicates a telephone number if it contains the "user=phone" parameter or when it has a numerical user part and you ticked the next option.
URI with numerical user part is a telephone number	If you tick this option, then Twinkle considers a SIP address that has a user part that consists of digits, *, #, + and special symbols only as a telephone number. In an outgoing message, Twinkle will add the "user=phone" parameter to such a URI.
Remove special symbols from numerical dial strings	Telephone numbers are often written with special symbols like dashes and brackets to make them readable to humans. When you dial such a number the special symbols must not be dialed. To allow you to simply copy/paste such a number into Twinkle, Twinkle can remove these symbols when you hit the dial button.
Special symbols	The special symbols that may be part of a telephone number for nice formatting, but must be removed when dialing.
Use tel-URI for telephone number.	Expand a dialed telephone number to a tel-URI instead of a sip-URI.

Number conversion rules

Often the format of the telphone numbers you need to dial is different from the format of the telephone numbers stored in your address book, e.g. your numbers start with a +-symbol followed by a country code, but your provider expects '00' instead of the '+', or you are at the office and all your numbers need to be prefixed with a '9' to access an outside line. Here you can specify number format conversion using Perl style regular expressions and format strings.

For each number you dial, Twinkle will try to find a match in the list of match expressions. For the first match it finds, the number will be replaced with the format string. If no match is found, the number stays unchanged.

The number conversion rules are also applied to incoming calls, so the numbers are displayed in the format you want.

Assume your country code is 31 and you have stored all numbers in your address book in full international number format, e.g. +318712345678. For dialling numbers in your own country you want to strip of the '+31' and replace it by a '0'. For dialling numbers abroad you just want to replace the '+' by '00'.

You are at work and all telephone numbers starting with a 0 should be prefixed with a 9 for an outside line.

Timers

Timer settings
Field	Explanation
No answer	When an incoming call is received, this timer is started. If the user answers the call, the timer is stopped. If the timer expires before the user answers the call, then Twinkle will reject the call with a "480 User Not Responding".
NAT keep alive	Keep alive timer for the STUN protocol. If you have enabled STUN, then Twinkle will send keep alive packets at this interval rate to keep the address bindings in your NAT device alive.

Ring tones

Ring tones
Field	Explanation
Ring tone	Specify the file name of a .wav file that you want to be played as ring tone for this user. This ring tone overrides the ring tone settings in the system settings.
Ring back tone	Specify the file name of a .wav file that you want to be played as ring back tone for this user. This ring back tone overrides the ring back tone settings in the system settings.

Scripts

Scripts
Field	Explanation
Incoming call	The file name of the script that must be executed when a call comes in.
Incoming call answered	The file name of the script that must be executed when you answer a call.
Incoming call failed	The file name of the script that must be executed when an incoming call fails.
Outoing call	The file name of the script that must be executed when you make a call.
Outgoing call answered	The file name of the script that must be executed when the remote party answers your call.
Outgoing call failed	The file name of the script that must be executed when an outgoing call fails.
Call released locally	The file name of the script that must be executed when you end a call.
Call released remotely	The file name of the script that must be executed when the remote party ends a call.

Security

Security settings
Field	Explanation
Enable ZRTP/SRTP encryption	When ZRTP/SRTP is enabled, then Twinkle will try to encrypt the audio of each call you originate or receive. Encryption will only succeed if the remote party has ZRTP/SRTP support enabled. If the remote party does not support ZRTP/SRTP, then the audio channel will stay unecrypted.
Only encrypt audio if remote party indicated ZRTP support in SDP	A SIP endpoint supporting ZRTP may indicate ZRTP support during call setup in its signalling. Enabling this option will cause Twinkle only to encrypt calls when the remote party indicates ZRTP support.
Indicate ZRTP support in SDP	Twinkle will indicate ZRTP support during call setup in its signalling.
Popup warning when remote party disables encryption during call	A remote party of an encrypted call may send a ZRTP go-clear command to stop encryption. When Twinkle receives this command it will popup a warning if this option is enabled.

Create a Diamondcard user profile

With Diamondcard you can make worldwide calls to regular and cell phones and send SMS messages.

You first have to sign up for a Diamondcard account. From Diamondcard you will receive an account ID and PIN code. You enter this account ID and PIN code in Twinkle to create a user profile for your Diamondcard account.

Main window

From the main window you control your calls, register your phone if not done automatically, activate and deactivate supplementary services.

Line status

Twinkle has two lines. This allows you to receive a second call while you are already involved in a call. Or you could put your current call on-hold and make another call on the other line.

The bottom of the main window shows the status of your lines. When a line has a call it shows you:

The call buttons

By pressing the buttons in the call button bar you can make and answer calls. Depending on the state of the line some buttons can be pressed while others are enable. For example, if a line is idle, then you can press the invite button to make a call, but not the answer button to answer a call.

Call buttons
Button	Function
Call	Press this button when you want to make a call. A window pops up asking you for the address of the person you want to call and a subject. For the address you can type a full SIP address like "sip:alice@example.com" or just the user part if the person is in the same domain as you. E.g. if you have a subscription with Free World Dialup, then you have a SIP adress that looks like this 123456@fwd.pulver.com To call another user in FWD network you can just type in the number of that user, e.g. 612 to call the speaking clock. The subject is optional. If you provide a subject the phone of the called person may show this when your call comes in.
Answer	When a call comes in on the active line you can press this button to answer the call.
Bye	When you are in a call you can press this button to end the call.
Reject	When a call comes in on the active line you can press this button to reject the call.
Redirect	When a call comes in on the active line you can press this button to redirect the call. Twinkle will ask you to which address you want to redirect the call. You can specify up to 3 addresses. The caller should try these addresses in sequence, i.e. it should first redirect to the first address. If no one answers there, it should try the second and so on.
Xfer	Transfer a standing call to another party. When you press this button, Twinkle will ask you for the address of the party you want to transfer to. Depending on settings that you have made in the SIP protocol settings of the user profile, Twinkle can put the call on-hold when you press this button. Depending on the capabilities of the far-end party, you will be notified of the transfer progress or your current call may be ended immediately. When you are notified about the progress and the call transfer fails the original call will be re-established.
Hold	Press this button to put a call on-hold. Press it again to retrieve the held call.
Conf	When you have a call on both lines you can press this button to join the calls together and have a 3-way conference call.
Mute	Press this button to mute your voice. You can still hear the far-end, but they cannot hear you.
Dtmf	Pressing this button pops up a keypad. On this keypad you can push buttons to send DTMF events. You may need this to control a voice response system. Instead of pressing this button, you may also type number or letters to generate the DTMF events. A letter will be converted to the corresponding digit, i.e. A, B and C generate a 2. Note: In some cases typing might fail, e.g. when the user combo box has focus.
Msg	Send an instant message.
Redial	Repeat the last call.

The call options are also available from the system tray menu, allowing you to make and answer calls without the need to maximize the application window.

Status indicators

Status indicators
Indicator	Status
	All or some users are registered.
	No users are registered.
	All users failed to register.
	You have missed calls. This indicator will clear when you open the call history window to view the details of the missed calls.
	Message Waiting Indication
	Auto answer is activated.
	Auto answer is not activated.
	Call redirection is activated.
	Call redirection is not activated.
	Do not disturb is activated.
	Do not disturb is not activated.

You can get more details on the status by hoverin the mouse pointer over an indicator.

Dial from the main window

Instead of pressing the "call" button first, you can dial directly from the main window by entering the address in the "call" field and then press the "Dial" button.

With this way of dialing you cannot give a subject to your call. If you want to give your call a subject, then you should use the "call" button.

The "user" combo box at the top of the window shows all user profiles that you activated. From this list you should select the user from which you want to originate the call.

Switching lines (call waiting, call hold)

The radio button in front of the line indicators show which line is your active line. To switch to the other line just press the radio button. If you have a call on your active line, then switching to the other line automatically puts your call on-hold.

If you are in a call and a second call comes in you can see that call coming in on the other line (call waiting). If you want to take that call you can simply switch to the other line and answer that call. Your original call will be automatically put on-hold.

If you do not allow a call to come in when you are in a call already, then you can disable call waiting in the system settings.

3-way conference calls

If you want to make a 3-way conference call, you first call one person. Then you switch to the other line (the first call will be put on-hold now) and you call the second person. Then you press the "conf" button.

Call transfer

When you want to transfer a standing call to another party you press the Xfer button. This will popup a dialog box from which you can choose what kind of call transfer you want.

Call transfer will only work if your SIP provider and/or the remote party supports the proper SIP extensions.

Blind call transfer

Type the address of the party to transfer to. Twinkle then sends a request to your far-end party (the transferee) to contact the transfer target. This is a blind call transfer as you don't know if the party you are transferring to is able to answer the call.

Depending on the capabilities of the transferee the original call (with the transferrer) may be re-established if the transfer target does not answer the call. If Twinkle is the transferee and the transfer target cannot be reached, then Twinkle will revert back to the original call unless the transferrer already released that call.

Transfer with consultation

This transfer type is only possible when the other line is idle. Type the address of the party to transfer to. Twinkle will call this party on the other line, so you can ask if (s)he wants to accept the call. Press the Xfer button again to actually transfer the call.

Transfer to other line

This transfer type is only possible when you have a call on the other line. Twinkle transfers the remote party of the active line to the party of the other line.

Tuning call transfer

In the SIP server section of the user profile you can tune the behavior of Twinkle for call transfer operations. If the far-end of your calls tries to transfer you, Twinkle can ask your permission before calling the transfer target (if there are costs involved, you may have to pay for this call). Other settings determine wether the original call should be put on-hold during the call transfer.

Registering your phone

Registration

If you kept the default registration settings, then Twinkle will automatically register at startup. If registration failed then Twinkle will retry to register every 30 seconds.

If you disabled automatic registration at startup then you can manually register via the Registration menu.

Deregistration

When you exit Twinkle, it will automatically deregister. However, you can also deregister manually via the deregister option in the registration menu.

The "deregister all" option allows you to deregister all your registrations. If you have other SIP phones registered with the same SIP account, then with "deregister all" all these phones become deregistered.

Show registrations

The "show registrations" option in the registration menu requests the SIP proxy to tell which registrations you have and how long it takes till they expire.

Services

Do not disturb

When you activate "do not disturb" then Twinke will reject all incoming calls with a "480 Temporarily Not Available" response.

Call Redirection

When you activate "call redirection" then Twinkle will redirect incoming calls. There are 3 flavors of call redirection.

For each flavor you can specify up to 3 addresses to which the call will be redirected. The addresses should be tried in sequence. If at the first address no-one answers the caller should redirect to the second and so on.

Auto Answer

When you activate "auto answer" then Twinkle will automatically answer a call coming in on the active line.

View

Call history

The call history shows you call details of recent calls. You can select which calls you want to see, e.g. only incoming calls, all calls, only missed calls, ... For incoming calls, the caller is shown in the list. For outgoing calls the callee is shown in the list. Calls missed since the last time you viewed the call history are highlighted.

Right click on a call to popup a menu which allows you to delete a call from the history or to repeat the call/call back a caller.

The maximum number of calls kept in the call history is configurable via the system settings menu.

Log

Diamondcard

Diamondcard is a VoIP service provider offering worldwide calls to regular and cell phones and sending of SMS messages.

From the Diamondcard menu you can sign up for a Diamondcard account. When you have a Diamondcard account active in Twinkle, then from this menu you can access various web sites to manage and monitor your Diamondcard account.

Address book

Twinkle has an interface to KDE's KAddressBook and provides a very simple local address book.

KAddressbook

You manage your contacts via KAddressBook. Twinkle imports all your contacts that have a phone number. You can access this list from the call and redirect windows. When a contact has multiple phone numbers, it will appear multiple times in the list.

Note that in the phone field you may specify a full SIP address, i.e. sip:example@example.com

Buddy list

The buddy list shows your active user profiles. For each user profile you can create a buddy list. Buddy list can be used for sharing presence state, calling and sending instant messages.

For sharing presence states your SIP provider must provide a presence agent. If your SIP provider does not have a presence agent, then you can still use the buddy list as a contact list for calling and sending instant messages, but you will not be able to see the presence state of your buddies.

You can add buddies to a user profile by right clicking on the user profile. The buddy list is stored locally on your computer. If your SIP provider does not offer a presence agent, then it is best to disable the "Show availability" option.

You can change your presence state for one of your user profiles by right clicking on the user profile. By default Twinkle publishes your online presence at startup. You can disable that in your user profile.

Local address book

Instant messaging

You can send instant messages by double clicking on a buddy in your buddy list, by clicking on the Msg button or by selecting "Instant message" from the Message menu.

Instant messaging will only work if your buddy has a SIP device with instant messaging capabilities. In addition your SIP provider must allow the routing of instant messages.

When you receive a first message from someone then Twinkle will popup a new message window. You can limit the number of simultaneous message sessions in your user profile.

File transfer

You can transfer a file with an instant message. To transfer a file, click on the "send file" button in the toolbar of the instant message window. Then select the file you want to transfer.

The file transfer function is limited. By default Twinkle allows you to send and receive files up to 1 MB (this can be changed by changing the maximum SIP message size via TCP in the system settings). The possible size depends also on the settings of your SIP provider. A SIP provider most likely limits the maximum size of SIP messages. Furthermore SIP over TCP must be supported. If you SIP provider enforces a small size then file transfer may be impossible.

When someone sends you a file, then images will be shown inline (possibly scaled down). Other file types are shown as an icon in the IM window. You can click on the icon to open or save the file.

Message composition indication

If your chat partner supports sending of message composition indications, then in the IM window you can see in the lower left corner an indication when your partner types a message.

By default Twinkle sends message composition indications when you type a message. You can disbale this in your user profile.

System settings

The system settings contain settings concerning the operation of Twinkle. The settings you specify here are system wide. They apply regardless of the profile you run.

General

System tray settings
Field	Explanation
Create system tray icon on startup	Enable this option if you want a system tray icon for Twinkle. The system tray icon is created when you start Twinkle.
Hide in system tray when closing main window.	Enable this option if you want Twinkle to hide in the system tray when you close the main window.

Startup settings
Field	Explanation
Startup hidden in system tray	Next time you start Twinkle it will immediately hide in the system tray. This works best when you also select a default user profile.
Default user profiles	If you always use the same profile(s), then you can mark these profiles as default here. The next time you start Twinkle, you will not be asked to select which profiles to run. The default profiles will automatically run.

Services settings
Field	Explanation
Call waiting	With call waiting an incoming call is accepted when only one line is busy. When you disable call waiting an incoming call will be rejected when one line is busy.
Hang up both lines when ending a 3-way conference call.	Hang up both lines when you press bye to end a 3-way conference call. When this option is disabled, only the active line will be hung up and you can continue talking with the party on the other line.

Miscellaneous settings
Field	Explanation
Maximum calls in call history	The maximum number of calls that will be kept in the call history.
Auto show main window on incoming call after	Number of seconds after which the main window should be shown.

Audio

If you have multiple sound cards, you can specify which sound card to use for the ring tone, speaker and microphone. When you are using a headset it is very convenient to play the ring tone on a different device then the one your headset is connected to, otherwise you cannot hear the ring tone when you are not wearing your headset.

For each sound option you can choose between an OSS or ALSA driver. The OSS and ALSA hardware (plughw) drivers give the best quality. If your soundcard cannot mix sounds from different applications, then you can choose the ALSA default driver such that ALSA will mix sounds from different applications.

NOTE:The ALSA default device should only be used for the ring tone and/or speaker. It is not recommended to use the ALSA default device for the microphone as it gives poor quality.

Sound card settings
Field	Explanation
Ring tone	Select the sound card for playing the ring tone for incoming calls.
Speaker	Select the sound card for the speaker function during a call.
Microphone	Select the sound card to which your microphone is connected.
Validate devices before usage	Twinkle validates the audio devices before usage to avoid an established call without an audio channel. On startup of Twinkle a warning is given if an audio device is inaccessible. If before making a call, the microphone or speaker appears to be invalid, a warning is given and no call can be made. If before answering a call, the microphone or speaker appears to be invalid, a warning is given and the call will not be answered.
Reduce noise from the microphone	Recordings from the microphone can contain noise. This could be annoying to the person on the other side of your call. This option removes soft noise coming from the microphone. The noise reduction algorithm is very simplistic. Sound is captured as 16 bits signed linear PCM samples. All samples between -50 and 50 are truncated to 0.

When your sound card works, but the sound is choppy, you might try to change the advanced settings. A different fragment or period size may solve the problem.

Advanced settings
Field	Explanation
OSS fragment size	The OSS fragment size influences the real time behaviour of your soundcard. If your sound frequently drops while using OSS, you might try a different value here.
ALSA play period size	The ALSA play period size influences the real time behaviour of your soundcard for playing sound. If your sound frequently drops while using ALSA, you might try a different value here.
ALSA capture period size	The ALSA capture period size influences the real time behaviour of your soundcard for capturing sound. If the other side of your call complains about frequently dropping sound, you might try a different value here.

Ring tones

In this section you can customize the ring tones. The system wide ring tone can be overriden at the user profile level.

Ring tones
Field	Explanation
Play ring tone on incoming call	Indicates if a ring tone should be played when a call comes in.
Default ring tone	Play the default ring tone when a call comes in.
Custom ring tone	Play a custom ring tone when a call comes in. Specify the file name of a .wav file that you want to be played as ring tone.
Play ring back tone when network does not play ring back tone	Play ring back tone while you are waiting for the far-end to answer your call. Depending on your SIP provider the network might provide ring back tone or an announcement.
Default ring back tone	Play the default ring back tone.
Custom ring back tone	Play a custom ring back tone. Specify the file name of a .wav file that you want to be played as ring back tone.

Address book

In this section you can specify settings related to the interface with KAddressbook.

Address book settings
Field	Explanation
Lookup name for incoming call	On an incoming call, Twinkle will try to find the name the name belonging to the incoming SIP address in your address book. This name will be displayed.
Override received display name	The caller may have provided a display name already. Tick this box if you want to override that name with the name you have in your address book.
Lookup photo for incoming call	Lookup the photo of a caller in your address book and display it on an incoming call.

Network

Network settings
Field	Explanation
SIP port	The UDP/TCP port used for sending and receiving SIP messages.
RTP port	The UDP port used for sending and receiving RTP for the first line. The UDP port for the second line is 2 higher. E.g. if port 8000 is used for the first line, then the second line uses port 8002. When you use call transfer then the next even port (eg. 8004) is also used.
Max. SIP message size (UDP)	Maximum allowed size (0-65535) in bytes of an incoming SIP message over UDP.
Max. SIP message size (TCP)	Maximum allowed size (0-4294967295) in bytes of an incoming SIP message over TCP.

Log

In this section you can specify settings concerning the log file that is created by Twinkle (~/.twinkle/twinkle.log)

Log settings
Field	Explanation
Max log size	The maximum size of a log file in MB. When the log file exceeds this size, a backup of the log file is created and the current log file is zapped. Only one backup log file will be kept.
Log debug reports	Indicates if reports marked as "debug" will be logged.
Log SIP reports	Indicates if SIP messages will be logged.
Log STUN reports	Indicates if STUN messages will be logged.
Log memory reports	Indicates if reports concerning memory management will be logged.

NAT traversal

If there is a NAT device (eg. a broadband router in a home network) between you and your SIP server then you have 3 options to make the SIP protocol work.

If your SIP provider uses a Session Border Controller then there is nothing you have to do. It should all work. If not, then you have to use STUN or configure your NAT with static address mappings.

STUN

If your SIP provider offers a STUN server, then you can enable STUN in the NAT section of the user profile and provide the address of the STUN server. Twinkle will then use STUN for NAT traversal.

Unfortunately STUN is not a 100% guaranteed solution for NAT traversal. Depending on the implementation of your NAT device STUN may not work. At startup Twinkle tries to discover the type of your NAT and warn you if your NAT is incompatible with STUN.

Even if Twinkle thinks that your NAT is compatible with STUN, it might still not work on rare occasions (eg. you cannot receive incoming calls or you only get one-way speech on your calls).

When you use STUN, the address binding in your NAT should not time out to allow incoming calls to reach you. To prevent a time out, Twinkle will send a keep alive packet (short UDP packet) at regular intervals to your SIP proxy. By default this keep alive packet is sent every 30 seconds. You may change the interval in the timer section of the user profile.

Note that STUN does not work for incoming TCP connections, so if you want to use TCP as a transport protocol, you cannot use STUN.

If STUN does not work for you, you have to resort to the static address mappings.

Static address mappings

You have to make mappings in your NAT for the SIP and RTP ports. If you use the default SIP and RTP settings then you have to make the following bindings in your NAT.

'public' is the public IP address of your NAT
'private' is the private IP address of your computer

If you changed the SIP and/or RTP ports in the user profile then you have to modify the mappings accordingly.

In addition to this you have to make the following settings in the NAT section of your user profile.

DNS lookups

Twinkle supports DNS SRV record lookups for SIP and STUN. A DNS SRV record is a service record. A service record indicates which host(s) perform a certain service (eg. SIP over UDP) for a particular domain. A service record can point to multiple hosts each having a priority and weight for load balancing and failover when some host is down.

To resolve a hostname/domain Twinkle will first try a DNS SRV lookup. If no SRV records can be found, Twinkle will fall back to a DNS A record lookup, i.e. an oridinary host lookup. So for settings like outbound proxy and STUN server you can fill in the domain name of your service provider if that service provider provides DNS SRV records for its services.

Load balancing

If a DNS lookup results in mutliple IP addresses, Twinkle will pick one of those IP addresses based on the priorities and weights. This way requests are load balanced over the available hosts.

Failover

If a request to a host fails, and the DNS lookup resulted in multiple IP addresses, Twinkle will failover to the next IP address if the reason for failure is one of the following:

Making SIP calls from other programs

For address you should fill in a full or partial SIP URI. If you use a partial SIP URI, then Twinkle will complete the URI using the domain setting from your user profile.

If Twinke is already running, then these commands will instruct the running process to make the call.

Call from KAddressBook

To make calls to phone numbers directly from KAddressBook, create the following setting in KAddressBook - Configure KAddressBook - General - Script-Hooks - Phone

Call scripts

Script triggered by incoming call

You can customize the way Twinkle handles incoming calls. Twinkle can call a script when a call comes in. Based on the ouput of the script Twinkle accepts, rejects or redirects the call. When accepting the call, the ring tone can be customized by the script as well. The script can be any executable program.

Note: Twinkle pauses while your script runs. It will send a "100 Trying" message before executing the script. During script execution the far end will not see any call progress however (e.g. no ring back). It is recommended that your script does not take more than 200 ms.

WARNING: If your script never ends, then it will hang Twinkle forever. It is your responsibility to provide a script that terminates.

With your script you can customize call handling by outputing one or more of the following parameters to standard output. Each parameter should be on a separate line.

Output parameters

Call script output parameters

Parameter

Description

action

Indicates how Twinkle should handle the incoming call.

continue Handle call as usual, i.e. the same as it would be handled without the script.
reject Reject the call. Twinkle will send a 603 response.
dnd Activate do not disturb for this call. Twinkle will send a 480 response.
redirect Redirect the call to the destination indicated by the contact parameter.
autoanswer Automatically answer the call.

If your script does not ouput an action parameter the default action continue is taken.

reason

This is an optional parameter applicable when the action is reject or dnd. The reason string will be used as reason phrase for the 603 or 480 responses. This might be shown to the user. When your script does not output a reason, the default SIP reason phrases are used.

contact

This is a mandatory parameter when the action is redirect. The contact is the SIP address to which the call will be redirected.

caller_name

This parameter will override the display name of the caller.

ringtone

This is an optional parameter applicable when the action is continue. Twinkle will use the .wav file specified by this parameter as a ring tone for this call. If this parameter is not specified, the ring tone specified by the system settings or user profile will be used.

display_msg

This is an optional parameter specifying a string that will be shown on Twinkle's display. You may output this parameter multiple times.

end

This is an optional parameter. When Twinkle receives end, it will not wait for your script to continue. Twinkle will continue call processing based on the parameters it received before end. After end you cannot send more parameters to Twinkle.

Other trigger points for scripts

Twinkle can also call scripts based on the following call triggers. These call scripts cannot pass parameters back to Twinkle. Twinkle just calls the script and continues call processing without waiting for the script's termination. As input the script gets the header values of the corresponding SIP message as environment variables just as for the incoming call script.

Environment variables

In you script you can use the values of the SIP headers from the incoming INVITE message, e.g. reject the call when the From-header contains a certain address.

The values are passed to your script in environment variables. The following environment variables are passed:

Trigger points
TWINKLE_TRIGGER	Trigger point
in_call	Incoming call
in_call_answered	Incoming call answered
in_call_failed	Incoming call failed
out_call	Outgoing call
out_call_answered	Outgoing call answered
out_call_failed	Outgoing call failed
local_release	Call released locally
remote_release	Call released remotely

The header name in the environment variable is in capitals and minus signs are replaced by underscores. Examples:

Example scripts

The second script instructs Twinkle to play distintive ringing tones based on values set in the Alert-Info header

Security

Authentication

SIP providers usually ask for your user name and password before you can register or make a call. If you have stored your user name and password in the user profile, then Twinkle will use these credentials to authenticate.

If you do not want to store your password in the user profile then Twinkle will ask you for your password when the SIP provider asks Twinkle to authenticate. Twinkle will cache the password in memory, so you do not have to enter the password for each registration refresh or call.

ZRTP/SRTP

By default encryption is disabled. If you want to use encryption you have to enable it in the user profile. The encryption algorithms are implemented by the ccRTP libraries.

For the encryption both endpoints in a call must support ZRTP and SRTP. ZRTP/SRTP interoperability has succesfully been tested with the following endpoints:

If the audio channel is successfully encrypted, a padlock will be shown on the line status. If no padlock appears, then audio is not encrypted.

To protect against a man-in-the-middle-attack ZRTP uses a Short Authentication String (SAS). The SAS is a 4-letter string that will be shown to both parties of a call next to the padlock. The SAS should be the same at both ends. If they differ, then your call may be compromised. If they are the same, then both parties should confirm the SAS by clicking on the padlock. Once you both have confirmed, subsequent calls to the same destination will not show a SAS anymore.

Depending on the confirmation status one of the following padlock symbols is shown:

Secure voice indicator
Indicator	Status
	The audio channel is encrypted. The SAS is not confirmed. The SAS is shown next to the padlock. You can confirm the SAS by clicking the padlock.
	The audio channel is encrypted. The SAS is confirmed. You may clear the SAS confirmation by clicking the padlock.

Identity hiding

When making a call you can ask Twinkle to hide your SIP identity. To make an anonymous call you have to press the call button to make a call and check the "Hide identity" option. Twinkle will then remove your SIP identity from the outgoing SIP INVITE request.

Hiding your identity will not hide your IP address.

It depends on the capabilities of your SIP provider if identity hiding is possible. Some SIP providers reject anonymous calls. Others silently insert your identity, so the remote party will see your identity after all.

Some SIP providers require that you send a so called preferred identity for anonymous calls. This preferred identity is only sent from you to your provider. The provider should remover this identity before delivering the call to the remote party. By default Twinkle does not send a preferred identity. You can enable sending of a preferred identity in the SIP protocol section of the user profile.

Manual

Starting Twinkle

First usage

The user profile wizard

The user profile editor

User

SIP server

Voice mail

Instant message

Presence

RTP audio

SIP protocol

Transport/NAT

Address format

Number conversion rules

Timers

Ring tones

Scripts

Security

Create a Diamondcard user profile

Main window

Line status

The call buttons

Status indicators

Dial from the main window

Switching lines (call waiting, call hold)

3-way conference calls

Call transfer

Blind call transfer

Transfer with consultation

Transfer to other line

Tuning call transfer

Registering your phone

Registration

Deregistration

Show registrations

Services

Do not disturb

Call Redirection

Auto Answer

View

Call history

Log

Diamondcard

Address book

KAddressbook

Buddy list

Local address book

Instant messaging

File transfer

Message composition indication

System settings

General

Audio

Ring tones

Address book

Network

Log

NAT traversal

STUN

Static address mappings

DNS lookups

Load balancing

Failover

Making SIP calls from other programs

Call from KAddressBook

Call scripts

Script triggered by incoming call

Output parameters

Other trigger points for scripts

Environment variables

Example scripts

Security

Authentication

ZRTP/SRTP

Identity hiding