source: skype/README @ 53eb75c

Last change on this file since 53eb75c was 451f121, checked in by Miklos Vajna <vmiklos@…>, at 2010-12-13T02:22:20Z

Drop <3.0 compatibility

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