source: skype/README @ bc744df

Last change on this file since bc744df was b820226, checked in by Miklos Vajna <vmiklos@…>, at 2009-01-07T00:31:18Z

add new skype/skypeconsole_receive setting for receiving raw data on skypeconsole

  • Property mode set to 100644
File size: 11.7 KB
RevLine 
[0c60f96]1= Skype plugin for BitlBee
[7f1cf70]2Miklos Vajna <vmiklos-at-vmiklos-dot-hu>
[afe221f]3
[56e4ac4]4== Status
5
[9f829c4]6[quote, Wilmer van der Gaast (author of BitlBee)]
[4eaadf6]7____
8Okay, this exists now, with lots of thanks to vmiklos for his *excellent*
9work!!
10
11It's not in the main BitlBee and it'll never be for various reasons, but
12because it's a plugin that shouldn't be a problem.
13____
14
[56e4ac4]15One day I browsed the BitlBee bugtracker and found
16http://bugs.bitlbee.org/bitlbee/ticket/82[this] ticket. Then after a while I
[1138b25]17returned and saw that it was still open. So I wrote it.
[56e4ac4]18
[15e2200]19It's pretty stable (one day I wanted to restart it because of an upgrade
20and just noticed it was running for 2+ months without crashing), I use
21it for my daily work. Being a plug-in, no patching is required, you can
22just install it after installing BitlBee itself.
[75742cc]23
[4c3a4c8]24NOTE: You will see that this implementation of the Skype plug-in still requires
[54c269d]25a Skype instance to be running. This is because I'm not motivated to reverse
26engineer Skype's
27http://en.wikipedia.org/wiki/Skype_Protocol#Obfuscation_Layer[obfuscation
28layer]. (Not mentioning that you should ask your lawyer about if it is legal or
29not..)
30
[22d97b4]31== Requirements
32
[75d5e71]33* Skype >= 1.4.0.99. The latest version I've tested is 2.0.0.72.
[1f59f2f]34* BitlBee >= @BITLBEE_VERSION@. Use old versions (0.5.1 or earlier) if
35  you have older BitlBee installed.
[eb39102]36* Skype4Py >= 0.9.28.7. Previous versions won't work due to API changes.
[7199b74]37  The latest version I've tested is 1.0.31.0.
[d276c9a]38
[c60b864]39* Python >= 2.5. Skype4Py does not work with 2.4.
[e49da25]40* PyGObject >= 2.8.0. Older versions are part of PyGTK. (And you don't want to
41  install GTK for nothing, right?)
[b0d40f5]42* pyopenssl or python-gnutls.
[22d97b4]43
[df1a59d4]44`bitlbee-skype` has been tested under Linux and Mac OS X. Skype and Skype4py is
45available under Windows, too, so it probably works, but this has not been tested.
[760ed1f]46
[9e03e55]47== How to set it up
[afe221f]48
[751b149]49Before you start. The setup is the following: BitlBee can't connect directly to
50Skype servers (the company's ones). It needs a running Skype client to do so.
51In fact BitlBee will connect to `skyped` (a tcp server, provided in this
[4c3a4c8]52package) and `skyped` will connect to to your Skype client.
[751b149]53
[d0a6a8c]54The benefit of this architecture is that you can run Skype and `skyped`
55on a machine different to the one where you run BitlBee (it can be even
56a public server) and/or your IRC client.
[7e4f0ca1]57
[d0a6a8c]58NOTE: The order is important. First `skyped` starts Skype. Then `skyped`
59connects to Skype, finally BitlBee can connect to `skyped`.
60
61=== Installing under Frugalware
62
63- Install the necessary packages:
[11eed8f]64
[36fbaa0]65----
[1d14818]66# pacman-g2 -S bitlbee-skype
[36fbaa0]67----
68
[4966d841]69and you don't have to compile anything manually.
70
[d0a6a8c]71=== Installing under Debian
72
73- Install the necessary development package:
[4966d841]74
75----
[2a8d790]76# apt-get install bitlbee-dev python-gnutls
[4966d841]77----
78
[5293707]79and you have to install `bitlbee-skype` and `skype4py` from source.
[4966d841]80
[720ae58]81=== Installing under OS X
82
83- Install the necessary packages from ports:
84
85NOTE: You have to edit the Portfile manually to include the install-dev target,
86just append install-dev after install-etc.
87
88----
89# port -v install bitlbee
90# port -v install py25-gobject
91----
92
93and you have to install `bitlbee-skype`, `skype4py` and `python-gnutls` from
94source.
95
[d0a6a8c]96=== Installing from source
97
[56d88ba]98NOTE: bitlbee-skype by default builds and installs skyped and the
99plugin. In case you just want to install the plugin for a public server
[cc5f8ac]100or you want to use skyped with a public server (like
101`bitlbee1.asnetinc.net`), you don't need both.
[56d88ba]102
103- You need the latest stable BitlBee release (unless you want to use a
104  public server):
[afe221f]105
[0c60f96]106----
[1f59f2f]107$ wget http://get.bitlbee.org/src/bitlbee-@BITLBEE_VERSION@.tar.gz
108$ tar xf bitlbee-@BITLBEE_VERSION@.tar.gz
109$ cd bitlbee-@BITLBEE_VERSION@
[0c60f96]110----
[afe221f]111
112- Now compile and install it:
113
[0c60f96]114----
[ccb50f5]115$ ./configure
116$ make
117# make install install-dev
[0c60f96]118----
[afe221f]119
[56d88ba]120- To install http://skype4py.sourceforge.net/[Skype4Py] from source
121  (unless you want to install the plugin for a public server):
122
123----
124$ tar -zxvf Skype4Py-x.x.x.x.tar.gz
125$ cd Skype4Py-x.x.x.x
126# python setup.py install
127----
128
[2a8d790]129- To install http://pypi.python.org/pypi/python-gnutls[python-gnutls] from source
130  (unless you want to install the plugin for a public server):
131
132----
133$ tar -zxvf python-gnutls-x.x.x.tar.gz
134$ cd python-gnutls-x.x.x
135# python setup.py install
136----
137
[720ae58]138NOTE: On OS X you will need the following hacks first:
139
140----
141$ export LD_LIBRARY_PATH=/opt/local/lib
142$ export CFLAGS="-I/opt/local/include"
143$ export LDFLAGS="-L/opt/local/lib"
144----
145
[21a387fd]146- Get the plugin code (in an empty dir, or whereever you want, it does
147  not matter):
[afe221f]148
[0c60f96]149----
[3b495c0]150$ wget http://vmiklos.hu/project/bitlbee-skype/bitlbee-skype-@VERSION@.tar.gz
151$ tar xf bitlbee-skype-@VERSION@.tar.gz
152$ cd bitlbee-skype-@VERSION@
[0c60f96]153----
[afe221f]154
155- Compile and install it:
156
[0c60f96]157----
[ccb50f5]158$ ./configure
159$ make
160# make install
[0c60f96]161----
[afe221f]162
[21a387fd]163This will install the plugin to where BitlBee expects them, which is
164`/usr/local/lib/bitlbee` if you installed BitlBee from source.
165
[d0a6a8c]166=== Configuring
167
[52d377d]168- Edit `/usr/local/etc/skyped/skyped.conf`: adjust `username` and `password`. The
[e65ceaa]169  `username` should be your Skype login and the `password` can be whatever you
170  want, but you will have to specify that one when adding the Skype account to
171  BitlBee (see later).
172
[52d377d]173NOTE: Here, and later - `/usr/local/etc` can be different on your installation
174if you used the `--sysconfdir` switch when running bitlbee-skype's `configure`.
175
176- Generate the SSL pem files:
177
178----
[ccb50f5]179# cd /usr/local/etc/skyped
180# openssl req -new -x509 -days 365 -nodes -config skyped.cnf -out skyped.cert.pem \
[52d377d]181        -keyout skyped.key.pem
182----
183
[ccb50f5]184NOTE: Maybe you want to adjust the permissions in the `/usr/local/etc/skyped`
185dir. For example make it readable by just your user.
186
[b0d40f5]187- If both pyopenssl and python-gnutls are available, then python-gnutls
188  will be used. This behaviour can be overwritten by:
189
190----
191$ export SKYPED_NO_GNUTLS=1
192----
193
[833eaee]194- Start `skyped` (the tcp server):
[afe221f]195
[0c60f96]196----
[ccb50f5]197$ skyped
[0c60f96]198----
[ba20c39]199
[4c3a4c8]200- Start your `IRC` client, connect to BitlBee and add your account:
[7338d59]201
202----
[789d055]203account add skype <user> <pass>
204account set skype/server localhost
[7338d59]205----
206
[e65ceaa]207<user> should be your Skype account name, <pass> should be the one you declared
[10a42d9]208in `skyped.conf`. If you want to run skyped on a remote machine, replace
209`localhost` with the name of the machine.
[7338d59]210
[9ace502]211If you are running skyped on a custom port:
212
213----
214account set skype/port <port>
215----
216
[7996794]217If you want to set your full name (optional):
218
219----
220account set skype/display_name "John Smith"
221----
222
223If you want to see your skypeout contacts online as well (they are
224offline by default):
225
226----
227account set skype/skypeout_offline false
228----
229
[23b84e1]230== Setting up Skype in a VNC server (optional)
231
232Optionally, if you want to run Skype on a server, you might want to setup up
[4c3a4c8]233a `VNC` server as well. I used `tightvnc` but probably other `VNC` servers will
[23b84e1]234work, too.
235
236First run
237
238----
[ccb50f5]239$ vncpasswd ~/.vnc/passwd
[23b84e1]240----
241
242and create a password. You will need it at least once.
243
244Now create `~/.vnc/xstartup` with the following contents:
245
246----
247#!/bin/sh
248
[2dbb768]249twm
[23b84e1]250----
251
[57087df]252Adjust the permissions:
253
254----
[ccb50f5]255$ chmod +x ~/.vnc/xstartup
[57087df]256----
257
[23b84e1]258Then start the server:
259
260----
[ccb50f5]261$ vncserver
[23b84e1]262----
263
[ece66da]264Then connect to it, start an `xterm`, set up Skype (username, password,
265enable X11 API and allow the `Skype4Py` client), quit from Skype, and
266start `skyped`. If you want to watch its traffic, enable debug messages
267and foreground mode:
[23b84e1]268
[ece66da]269----
270$ skyped -n -d
271----
[dffa24f]272
[123e45a]273== Features
[b6d26ac]274
[adce2de]275- Download nicks and away statuses from Skype
[b6d26ac]276
[39a0d64]277- Noticing joins / parts while we're connected
278
[93ece66]279- Sending messages
280
[8dd21bb]281- Receiving messages
282
[72f697b]283- Receiving away status changes
284
[62bb4e4]285- `skyped` (the tcp daemon that is a gateway between Skype and tcp)
[ed2e37f]286
[62bb4e4]287- Error handling when `skyped` is not running and when it exits
[afe221f]288
[62bb4e4]289- Marking received messages as seen so that Skype won't say there are unread messages
[440665b]290
[6627d92]291- Adding / removing contacts
292
[23411c6]293- Set away state when you do a `/away`.
294
[d3cbd17]295- When you `account off`, Skype will set status to `Offline`
[348a3a2]296
[d3cbd17]297- When you `account on`, Skype will set status to `Online`
[348a3a2]298
[d3cbd17]299- Detect when somebody wants to add you and ask for confirmation
[8dd21bb]300
[df9255d]301- Detect when somebody wants to transfer a file
302
[d6a371e]303- Group chat support:
304
305  * Detect if we're invited
306
307  * Send / receive group chat messages
[93ece66]308
[ff58445]309  * Invite others (using `/invite <nick>`)
[c5dd164]310
[d6a371e]311  * Part from group chats
[c5dd164]312
[ff58445]313  * Starting a group chat (using `/j #nick`)
314
[e103e73]315- Topic changes in group chats:
316
317  * Show the current topic (if any) on join
318
319  * Notice when someone changes the topic
320
321  * Support changing the topic using `/topic`
322
[fb36492]323- Viewing the profile using the `info` command.
324
[a06a0a5]325- Handling skype actions (when the `CHATMESSAGE` has `EMOTED` type)
326
[6b266f6]327- Setting your display name using the `nick` command.
[a06a0a5]328
[ccb50f5]329- Running Skype on a machine different to BitlBee is possible, the
330  communication is encrypted.
331
[9aed2f1]332- Managing outgoing calls (with call duration at the end, including
333  SkypeOut calls if you use a phone number instead of a nick):
[2eb4b1f]334
335  * `account set skype/call nick`
336  * `account set -del skype/call`
[123e45a]337
[e0074cb]338- Managing incoming calls via questions, just like when you add / remove
339  contacts.
[c5dd164]340
[9aed2f1]341- Querying the current SkypeOut balance:
342
343  * `account set skype/balance query`
344
[08a355b]345- For debug purposes, it's possible to send any command to `skyped`. To
346  achieve this, you need to:
347
348  * `account set skype/skypeconsole true`
349
350  * then writing `skypeconsole: <command>` will work in the control
351    channel.
352
[b820226]353  * `account set skype/skypeconsole_receive true` will make the
354    `skypeconsole` account dump all the recieved raw traffic for you
355
[5acf9ab]356- If you want to automatically join bookmarked groupchats right after
357  you logged in, do:
358
359  * `account set skype/auto_join true`
360
[e0074cb]361== What needs to be done (aka. TODO)
[846ceffb]362
[d6a371e]363- Notice if foo invites bar. Currently you can see only that bar joined.
364
[6344674]365- Public chats. See
366  link:https://developer.skype.com/jira/browse/SCL-381[this feature
367  request], this is because it is still not possible (under Linux) to
368  `join_chat` to a public chat..
[d6a371e]369
[c49820d]370- Add yasrd (Yet Another Skype-Related Daemon) to allow using a public
371  server for users who are behind NAT.
372
[0c60f96]373== I would like to have support for ...
374
[23b84e1]375If something does not work and it's not in the TODO section, then please
[e72d869]376contact me! Please also try the link:HACKING[git version] before reporting a bug, your
[80d9004]377problem may be already fixed there.
[23b84e1]378
379In fact, of course, I wrote this documentation after figured out how to do this
380setup, so maybe I left out some steps. If you needed 'any' additional tricks,
381then it would be nice to include them here.
[afe221f]382
[f78f949]383== Known bugs
384
[5652d43]385- None at this time.
[f78f949]386
[0c60f96]387== Screenshots
388
[668a122]389You can reach some screenshots link:shot[here].
[ddd3502]390
[25d87e4]391== Additional resources
[a60c3c2]392
[25d87e4]393You can reach the Changelog link:Changelog[here], and a gitweb interface
[6f01885]394http://vmiklos.hu/gitweb/?p=bitlbee-skype.git[here].
[a60c3c2]395
[c09f90f]396The Skype API documentation is
397https://developer.skype.com/Docs/ApiDoc[here] if you're interested.
398
[ceee9c7]399
400== Testimonials
401
402----
40300:56 < scathe> vmiklos: I like your skype plugin :)
404----
405
[6774d83]406----
407It's really working great so far.
408
409Good Job and thank you!
410Sebastian
411----
412
[587a921]413----
414Big respect for your work, i really appreciate it.
415
416Martin
417----
418
[93264f0]419----
420Thanks for bitlbee-skype. As a blind Linux user, I cannot use the
421skype GUI client because qt apps ar not accessible yet with the
422available screen readers. bitlbee-skype allows me to make use of skype
423without having to interact much with the GUI client, which helps me a
424lot.
425
426Lukas
427----
428
[e3d0b10]429----
43002:12 < newton> i must say, i love this little bee ;)
43102:15 < newton> tried it out today with the skype plugin, good work!
432----
433
[df482d4]434----
43518:10 < miCSu> it works fine
436----
437
[65e4020]438== Thanks
439
440for the following people:
441
[e49da25]442* Wilmer van der Gaast, for answering questions about the BitlBee plugin interface
[65e4020]443
[56a3616]444* Arkadiusz Wahlig, author of skype4py, for making suggestions to skyped
[65e4020]445
[9834597]446* Gabor Adam Toth (tg), for noticing extra code is needed to handle multiline
447  messages
448
449* Cristobal Palmer (tarheelcoxn), for helping to testing the plugin in a
450  timezone different to mine
[65e4020]451
[4834307]452* Risko Gergely, for his SkypeOut ideas
453
[437ddf5]454* people on `#bitlbee` for feedback
455
[eb9cbb8]456Back to my link:/projects[projects page].
457
[0c60f96]458// vim: ft=asciidoc
Note: See TracBrowser for help on using the repository browser.