source: skype/README @ 47c590c

Last change on this file since 47c590c was c9d6390, checked in by Miklos Vajna <vmiklos@…>, at 2010-08-18T12:52:15Z

typo

  • Property mode set to 100644
File size: 13.3 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.
[31a35ea]34* BitlBee >= 1.2.6. The lastest version I've tested is @BITLBEE_VERSION@. Use
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?)
[b0d40f5]43* pyopenssl or python-gnutls.
[22d97b4]44
[df1a59d4]45`bitlbee-skype` has been tested under Linux and Mac OS X. Skype and Skype4py is
46available under 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
92and you have to install `bitlbee-skype`, `skype4py` and `python-gnutls` from
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
[2a8d790]128- To install http://pypi.python.org/pypi/python-gnutls[python-gnutls] from source
129  (unless you want to install the plugin for a public server):
130
131----
132$ tar -zxvf python-gnutls-x.x.x.tar.gz
133$ cd python-gnutls-x.x.x
134# python setup.py install
135----
136
[720ae58]137NOTE: On OS X you will need the following hacks first:
138
139----
140$ export LD_LIBRARY_PATH=/opt/local/lib
141$ export CFLAGS="-I/opt/local/include"
142$ export LDFLAGS="-L/opt/local/lib"
143----
144
[21a387fd]145- Get the plugin code (in an empty dir, or whereever you want, it does
146  not matter):
[afe221f]147
[0c60f96]148----
[3b495c0]149$ wget http://vmiklos.hu/project/bitlbee-skype/bitlbee-skype-@VERSION@.tar.gz
150$ tar xf bitlbee-skype-@VERSION@.tar.gz
151$ cd bitlbee-skype-@VERSION@
[0c60f96]152----
[afe221f]153
154- Compile and install it:
155
[0c60f96]156----
[ccb50f5]157$ ./configure
158$ make
159# make install
[0c60f96]160----
[afe221f]161
[21a387fd]162This will install the plugin to where BitlBee expects them, which is
163`/usr/local/lib/bitlbee` if you installed BitlBee from source.
164
[d0a6a8c]165=== Configuring
166
[1b48afb]167- Set up `~/.skyped/skyped.conf`: Create the `~/.skyped` directory, copy
168  `skyped.conf` and `skyped.cnf` from
169  `/usr/local/etc/skyped/skyped.conf` to `~/.skyped`, adjust `username`
170  and `password`. The `username` should be your Skype login and the
171  `password` can be whatever you want, but you will have to specify that
172  one when adding the Skype account to BitlBee (see later).
[e65ceaa]173
[52d377d]174NOTE: Here, and later - `/usr/local/etc` can be different on your installation
175if you used the `--sysconfdir` switch when running bitlbee-skype's `configure`.
176
177- Generate the SSL pem files:
178
179----
[1b48afb]180# cd ~/.skyped
[ccb50f5]181# openssl req -new -x509 -days 365 -nodes -config skyped.cnf -out skyped.cert.pem \
[52d377d]182        -keyout skyped.key.pem
183----
184
[1b48afb]185NOTE: Maybe you want to adjust the permissions in the `~/.skyped`
[ccb50f5]186dir. For example make it readable by just your user.
187
[c9d6390]188TIP: In case you have difficulties generating `skyped.cert.pem` /
189`skyped.key.pem` and you just want to experiment, you can copy&paste the
190contents of those files from
[bb9a15f]191http://code.google.com/p/gdata-python-client/source/browse/src/gdata/oauth/rsa.py#87[here].
192
[b0d40f5]193- If both pyopenssl and python-gnutls are available, then python-gnutls
194  will be used. This behaviour can be overwritten by:
195
196----
197$ export SKYPED_NO_GNUTLS=1
198----
199
[833eaee]200- Start `skyped` (the tcp server):
[afe221f]201
[0c60f96]202----
[ccb50f5]203$ skyped
[0c60f96]204----
[ba20c39]205
[4c3a4c8]206- Start your `IRC` client, connect to BitlBee and add your account:
[7338d59]207
208----
[789d055]209account add skype <user> <pass>
210account set skype/server localhost
[7338d59]211----
212
[e65ceaa]213<user> should be your Skype account name, <pass> should be the one you declared
[10a42d9]214in `skyped.conf`. If you want to run skyped on a remote machine, replace
215`localhost` with the name of the machine.
[7338d59]216
[9ace502]217If you are running skyped on a custom port:
218
219----
220account set skype/port <port>
221----
222
[7996794]223If you want to set your full name (optional):
224
225----
226account set skype/display_name "John Smith"
227----
228
229If you want to see your skypeout contacts online as well (they are
230offline by default):
231
232----
233account set skype/skypeout_offline false
234----
235
[23b84e1]236== Setting up Skype in a VNC server (optional)
237
238Optionally, if you want to run Skype on a server, you might want to setup up
[4c3a4c8]239a `VNC` server as well. I used `tightvnc` but probably other `VNC` servers will
[23b84e1]240work, too.
241
242First run
243
244----
[ccb50f5]245$ vncpasswd ~/.vnc/passwd
[23b84e1]246----
247
248and create a password. You will need it at least once.
249
250Now create `~/.vnc/xstartup` with the following contents:
251
252----
253#!/bin/sh
254
[9d6702c]255blackbox
[23b84e1]256----
257
[57087df]258Adjust the permissions:
259
260----
[ccb50f5]261$ chmod +x ~/.vnc/xstartup
[57087df]262----
263
[23b84e1]264Then start the server:
265
266----
[ccb50f5]267$ vncserver
[23b84e1]268----
269
[ece66da]270Then connect to it, start an `xterm`, set up Skype (username, password,
271enable X11 API and allow the `Skype4Py` client), quit from Skype, and
272start `skyped`. If you want to watch its traffic, enable debug messages
273and foreground mode:
[23b84e1]274
[ece66da]275----
276$ skyped -n -d
277----
[dffa24f]278
[123e45a]279== Features
[b6d26ac]280
[adce2de]281- Download nicks and away statuses from Skype
[b6d26ac]282
[39a0d64]283- Noticing joins / parts while we're connected
284
[93ece66]285- Sending messages
286
[8dd21bb]287- Receiving messages
288
[72f697b]289- Receiving away status changes
290
[62bb4e4]291- `skyped` (the tcp daemon that is a gateway between Skype and tcp)
[ed2e37f]292
[62bb4e4]293- Error handling when `skyped` is not running and when it exits
[afe221f]294
[62bb4e4]295- Marking received messages as seen so that Skype won't say there are unread messages
[440665b]296
[6627d92]297- Adding / removing contacts
298
[23411c6]299- Set away state when you do a `/away`.
300
[d3cbd17]301- When you `account off`, Skype will set status to `Offline`
[348a3a2]302
[d3cbd17]303- When you `account on`, Skype will set status to `Online`
[348a3a2]304
[d3cbd17]305- Detect when somebody wants to add you and ask for confirmation
[8dd21bb]306
[df9255d]307- Detect when somebody wants to transfer a file
308
[d6a371e]309- Group chat support:
310
311  * Detect if we're invited
312
313  * Send / receive group chat messages
[93ece66]314
[ff58445]315  * Invite others (using `/invite <nick>`)
[c5dd164]316
[d6a371e]317  * Part from group chats
[c5dd164]318
[ff58445]319  * Starting a group chat (using `/j #nick`)
320
[e103e73]321- Topic changes in group chats:
322
323  * Show the current topic (if any) on join
324
325  * Notice when someone changes the topic
326
327  * Support changing the topic using `/topic`
328
[fb36492]329- Viewing the profile using the `info` command.
330
[a06a0a5]331- Handling skype actions (when the `CHATMESSAGE` has `EMOTED` type)
332
[6b266f6]333- Setting your display name using the `nick` command.
[a06a0a5]334
[ccb50f5]335- Running Skype on a machine different to BitlBee is possible, the
336  communication is encrypted.
337
[9aed2f1]338- Managing outgoing calls (with call duration at the end, including
339  SkypeOut calls if you use a phone number instead of a nick):
[2eb4b1f]340
341  * `account set skype/call nick`
342  * `account set -del skype/call`
[123e45a]343
[e0074cb]344- Managing incoming calls via questions, just like when you add / remove
345  contacts.
[c5dd164]346
[9aed2f1]347- Querying the current SkypeOut balance:
348
349  * `account set skype/balance query`
350
[08a355b]351- For debug purposes, it's possible to send any command to `skyped`. To
352  achieve this, you need to:
353
354  * `account set skype/skypeconsole true`
355
356  * then writing `skypeconsole: <command>` will work in the control
357    channel.
358
[b820226]359  * `account set skype/skypeconsole_receive true` will make the
360    `skypeconsole` account dump all the recieved raw traffic for you
361
[5acf9ab]362- If you want to automatically join bookmarked groupchats right after
363  you logged in, do:
364
365  * `account set skype/auto_join true`
366
[f4d37c6]367- Edited messages are shown with the `EDIT:` prefix. If you don't like
368  this, you can set your own prefix using:
369
370  * `account set skype/edit_prefix "updated message:"`
371
[49a3c02]372- The `echo123` test account is hidden by default. If you want to see it:
373
374  * `account set skype/test_join true`
375
[304aa33]376- Mood texts are not shown by default. If you want to see it:
377
378  * `account set skype/show_moods true`
379
[e0074cb]380== What needs to be done (aka. TODO)
[846ceffb]381
[d6a371e]382- Notice if foo invites bar. Currently you can see only that bar joined.
383
[6344674]384- Public chats. See
385  link:https://developer.skype.com/jira/browse/SCL-381[this feature
386  request], this is because it is still not possible (under Linux) to
387  `join_chat` to a public chat..
[d6a371e]388
[c49820d]389- Add yasrd (Yet Another Skype-Related Daemon) to allow using a public
390  server for users who are behind NAT.
391
[0c60f96]392== I would like to have support for ...
393
[23b84e1]394If something does not work and it's not in the TODO section, then please
[e72d869]395contact me! Please also try the link:HACKING[git version] before reporting a bug, your
[80d9004]396problem may be already fixed there.
[23b84e1]397
398In fact, of course, I wrote this documentation after figured out how to do this
399setup, so maybe I left out some steps. If you needed 'any' additional tricks,
400then it would be nice to include them here.
[afe221f]401
[f78f949]402== Known bugs
403
[a25bddf]404- File transfers are view-only from BitlBee. Quoting the
405  https://developer.skype.com/Docs/ApiDoc/FILETRANSFER_object[relevant
406  documentation]: 'File transfers cannot be initiated nor accepted via
407  API commands.' So it's not something I can add support for, sadly.
[f78f949]408
[0c60f96]409== Screenshots
410
[668a122]411You can reach some screenshots link:shot[here].
[ddd3502]412
[25d87e4]413== Additional resources
[a60c3c2]414
[25d87e4]415You can reach the Changelog link:Changelog[here], and a gitweb interface
[6f01885]416http://vmiklos.hu/gitweb/?p=bitlbee-skype.git[here].
[a60c3c2]417
[c09f90f]418The Skype API documentation is
[8fcb196]419http://developer.skype.com/resources/public_api_ref.zip[here] if you're
420interested.
[c09f90f]421
[ceee9c7]422
423== Testimonials
424
425----
[3e8a4ea]42600:56 < scathe> I like your skype plugin :)
[ceee9c7]427----
428
[6774d83]429----
430It's really working great so far.
431
432Good Job and thank you!
433Sebastian
434----
435
[587a921]436----
437Big respect for your work, i really appreciate it.
438
439Martin
440----
441
[93264f0]442----
443Thanks for bitlbee-skype. As a blind Linux user, I cannot use the
444skype GUI client because qt apps ar not accessible yet with the
445available screen readers. bitlbee-skype allows me to make use of skype
446without having to interact much with the GUI client, which helps me a
447lot.
448
449Lukas
450----
451
[e3d0b10]452----
45302:12 < newton> i must say, i love this little bee ;)
45402:15 < newton> tried it out today with the skype plugin, good work!
455----
456
[df482d4]457----
45818:10 < miCSu> it works fine
459----
460
[3e8a4ea]461----
46213:56 < seo> i just want to thank you :)
46313:56 < seo> for bitlbee-skype
46413:57 < seo> it's working very well, so, again, thank you for your work, and for sharing it
465----
466
[8cb17ff]467----
46822:16 < ecraven> vmiklos: thanks a lot for the skype plugin for bitlbee!
469----
470
[8ee6def]471----
472I'm blind and so I have to use a screen reader, in my case Gnome-Orca.
473But since Skype is written in QT, while Orca uses gtk+, I have no direct
474access to the Skype interface. That's why I desided to use Skyped and
475Erc.
476The text console is fully accessible.
477Thank you very much.
478
479Hermann
480----
481
[b9f2894]482----
483i love that bitlbeeplugin. big thx for that.
484
485michael
486----
487
[d0169e7]488----
48923:47 < krisfremen> thanks for creating this fabulous piece of software vmiklos :)
490----
491
[65e4020]492== Thanks
493
[37ae52a]494to the following people:
[65e4020]495
[e49da25]496* Wilmer van der Gaast, for answering questions about the BitlBee plugin interface
[65e4020]497
[56a3616]498* Arkadiusz Wahlig, author of skype4py, for making suggestions to skyped
[65e4020]499
[9834597]500* Gabor Adam Toth (tg), for noticing extra code is needed to handle multiline
501  messages
502
503* Cristobal Palmer (tarheelcoxn), for helping to testing the plugin in a
504  timezone different to mine
[65e4020]505
[4834307]506* Risko Gergely, for his SkypeOut ideas
507
[437ddf5]508* people on `#bitlbee` for feedback
509
[eb9cbb8]510Back to my link:/projects[projects page].
511
[0c60f96]512// vim: ft=asciidoc
Note: See TracBrowser for help on using the repository browser.