source: skype/README @ fcef6e6

= Skype plugin for BitlBee
Miklos Vajna <vmiklos@vmiklos.hu>

== Status

[Wilmer van der Gaast (author of BitlBee)]
____
Okay, this exists now, with lots of thanks to vmiklos for his *excellent*
work!!

It's not in the main BitlBee and it'll never be for various reasons, but
because it's a plugin that shouldn't be a problem.
____

One day I browsed the BitlBee bugtracker and found
http://bugs.bitlbee.org/bitlbee/ticket/82[this] ticket. Then after a while I
returned and saw that it was still open. So I wrote it.

It's pretty stable, I use it for my daily work. Being a plug-in, no patching
is required, you can just install it after installing BitlBee itself.

NOTE: You will see that this implementation of the Skype plug-in still requires
a Skype instance to be running. This is because I'm not motivated to reverse
engineer Skype's
http://en.wikipedia.org/wiki/Skype_Protocol#Obfuscation_Layer[obfuscation
layer]. (Not mentioning that you should ask your lawyer about if it is legal or
not..)

== Requirements

* Skype >= 1.4.0.99. The latest version I've tested is 2.0.0.27.
* bitlbee >= 1.1.1dev. (This is the latest version I've tested, probably
  newer versions will work, too.)
* Skype4Py >= 0.9.28.7. Previous versions won't work due to API changes.
* Python >= 2.5. Skype4Py does not work with 2.4.
* pygobject

`bitlbee-skype` has been tested under Linux and Windows. Skype is available
under OSX, too, so it probably works, but this has not been tested.

== How to set it up

Before you start. The setup is the following: BitlBee can't connect directly to
Skype servers (the company's ones). It needs a running Skype client to do so.
In fact BitlBee will connect to `skyped` (a tcp server, provided in this
package) and `skyped` will connect to to your Skype client.

NOTE: The order is important. First you have to start Skype. Then `skyped` can
connect to it, finally BitlBee can connect to `skyped`. (In fact `skyped`
automatically reconnect if you restart Skype.)

- If you happen to be a happy Frugalware user, you can install the `bitlbee`
  and `bitlbee-skype` packages from
  http://ftp.frugalware.org/pub/other/people/vmiklos/bmf/[my repo].

- You need the BitlBee testing/development version:

----
$ wget http://get.bitlbee.org/src/bitlbee-1.1.1dev.tar.gz
$ tar xf bitlbee-1.1.1dev.tar.gz
$ cd bitlbee-1.1.1dev
----

NOTE: You no longer need additional patches, as of version 1.1.1dev.

- Now compile and install it:

----
$ ./configure
$ make
# make install install-dev
----

- Get the plugin code:

----
$ wget http://vmiklos.hu/project/bitlbee-skype/bitlbee-skype-@VERSION@.tar.gz
$ tar xf bitlbee-skype-@VERSION@.tar.gz
$ cd bitlbee-skype-@VERSION@
----

It doesn't matter where do you get it, it'll install the plugin to `/usr/local`
by default (that's the location where BitlBee searches for plugins by default).

- Compile and install it:

----
$ ./configure
$ make
# make install
----

- Install http://skype4py.sourceforge.net/[Skype4Py].

(You may remember that previous versions of `skyped` did not require this
package. This because it now uses the X11 interface of Skype (because the
previously used `DBus` interface had
http://forum.skype.com/index.php?s=&showtopic=94545&view=findpost&p=431710[known
problems]), but I wanted to prevent a large code duplication from that project.
In addition it then no longer requires the `dbus-python` package, just
`pygobject`.)

- Edit `/usr/local/etc/skyped/skyped.conf`: adjust `username` and `password`. The
  `username` should be your Skype login and the `password` can be whatever you
  want, but you will have to specify that one when adding the Skype account to
  BitlBee (see later).

NOTE: Here, and later - `/usr/local/etc` can be different on your installation
if you used the `--sysconfdir` switch when running bitlbee-skype's `configure`.

- Generate the SSL pem files:

----
# cd /usr/local/etc/skyped
# openssl req -new -x509 -days 365 -nodes -config skyped.cnf -out skyped.cert.pem \
        -keyout skyped.key.pem
----

NOTE: Maybe you want to adjust the permissions in the `/usr/local/etc/skyped`
dir. For example make it readable by just your user.

- Start Skype and `skyped` (the tcp server):

----
$ skype
$ skyped
----

NOTE: You should run `skyped` on the same `X11` display, otherwise it won't be
able to connect to Skype!

- Start your `IRC` client, connect to BitlBee and add your account:

----
account add skype <user> <pass> localhost
----

<user> should be your Skype account name, <pass> should be the one you declared
in `skyped.conf`. If you want to run skyped on a remote machine, replace
`localhost` with the name of the machine.

== Setting up Skype in a VNC server (optional)

Optionally, if you want to run Skype on a server, you might want to setup up
a `VNC` server as well. I used `tightvnc` but probably other `VNC` servers will
work, too.

First run

----
$ vncpasswd ~/.vnc/passwd
----

and create a password. You will need it at least once.

Now create `~/.vnc/xstartup` with the following contents:

----
#!/bin/sh

sleep 1
skype &
sleep 5
skyped
----

Adjust the permissions:

----
$ chmod +x ~/.vnc/xstartup
----

Then start the server:

----
$ vncserver
----

Then connect to it, and set up Skype (username, password, enable auto-login, and
allow the `SkypeApiPythonShell` client when Skype asks about it).

Please be aware about that Skype has serious memory leak issues. After running
with for a few weeks it may eat >300 MB of memory. Just don't forget to restart
your VNC server regularly. (How ugly.)

== What works

- Download nicks and away statuses from Skype

- Noticing joins / parts while we're connected

- Sending messages

- Receiving messages

- Receiving away status changes

- `skyped` (the tcp daemon that is a gateway between Skype and tcp)

- Error handling when `skyped` is not running and when it exits

- Marking received messages as seen so that Skype won't say there are unread messages

- Adding / removing contacts

- Set away state when you do a `/away`.

- When you `account off`, Skype will set status to `Offline`

- When you `account on`, Skype will set status to `Online`

- Detect when somebody wants to add you and ask for confirmation

- Detect when somebody wants to transfer a file

- Group chat support:

  * Detect if we're invited

  * Send / receive group chat messages

  * Invite others (using `/invite <nick>`)

  * Part from group chats

  * Starting a group chat (using `/j #nick`)

- Topic changes in group chats:

  * Show the current topic (if any) on join

  * Notice when someone changes the topic

  * Support changing the topic using `/topic`

- Viewing the profile using the `info` command.

- Handling skype actions (when the `CHATMESSAGE` has `EMOTED` type)

- Setting your mood text using the `nick` command.

- Running Skype on a machine different to BitlBee is possible, the
  communication is encrypted.

== What needs to be done (aka. TODO)

- Add a question callback for calls.

- Notice if foo invites bar. Currently you can see only that bar joined.

- Public chats. See link:http://forum.skype.com/index.php?showtopic=98872[this
  forum thread], it is still unclear how could it be done for you to be able to
  `/join` to a public chat..

- Split skyped from the plugin, so that one could install just the relevant
  code if they are not running on the same machine.

== I would like to have support for ...

If something does not work and it's not in the TODO section, then please
contact me! Please also try the link:HACKING[git version] before reporting a bug, your
problem may be already fixed there.

In fact, of course, I wrote this documentation after figured out how to do this
setup, so maybe I left out some steps. If you needed 'any' additional tricks,
then it would be nice to include them here.

== Known bugs

- None at this time.

== Screenshots

You can reach some screenshots link:shot[here].

== Additional resources

You can reach the Changelog link:Changelog[here], and a gitweb interface
http://repo.or.cz/w/bitlbee-skype.git[here].

The Skype API documentation is
https://developer.skype.com/Docs/ApiDoc[here] if you're interested.

== Thanks

for the following people:

* Wilmer van der Gaast, for answering questions about the bitlbee plugin interface

* Arkadiusz Wahlig, author of skype4py, for making suggestions to skyped

* Gabor Adam Toth (tg), for noticing extra code is needed to handle multiline
  messages

* Cristobal Palmer (tarheelcoxn), for helping to testing the plugin in a
  timezone different to mine

* people on `#bitlbee` for feedback

Back to my link:/projects[projects page].

// vim: ft=asciidoc