source: protocols/skype/README @ e88fe7da

Last change on this file since e88fe7da was e88fe7da, checked in by Veres Lajos <vlajos@…>, at 2015-08-07T21:53:25Z

typofix - https://github.com/vlajos/misspell_fixer

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