source: protocols/skype/README @ 1146e21

Last change on this file since 1146e21 was 875ba16, checked in by Miklos Vajna <vmiklos@…>, at 2013-02-09T11:31:43Z

skype: move config instructions from README to the manpage

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