source: skype/README @ f4d37c6

Last change on this file since f4d37c6 was f4d37c6, checked in by Miklos Vajna <vmiklos@…>, at 2010-03-07T19:50:39Z

make the edit_prefix configurable

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