source: protocols/skype/README @ e93fa05

Last change on this file since e93fa05 was 43b1cd7, checked in by Miklos Vajna <vmiklos@…>, at 2011-04-12T00:10:57Z

Merge bitlbee-skype into bitlbee

  • Property mode set to 100644
File size: 12.5 KB
Line 
1= Skype plugin for BitlBee
2Miklos Vajna <vmiklos-at-vmiklos-dot-hu>
3
4== Status
5
6[quote, Wilmer van der Gaast (author of BitlBee)]
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
15One day I browsed the BitlBee bugtracker and found
16http://bugs.bitlbee.org/bitlbee/ticket/82[this] ticket. Then after a while I
17returned and saw that it was still open. So I wrote it.
18
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.
23
24NOTE: You will see that this implementation of the Skype plug-in still requires
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
31== Requirements
32
33* Skype >= 1.4.0.99. The latest version I've tested is 2.1.0.81.
34* BitlBee >= 3.0. The latest 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.
37* Skype4Py >= 0.9.28.7. Previous versions won't work due to API changes.
38  The latest version I've tested is 1.0.32.0.
39
40* Python >= 2.5. Skype4Py does not work with 2.4.
41
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.
45
46== How to set it up
47
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
51package) and `skyped` will connect to to your Skype client.
52
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.
56
57NOTE: The order is important. First `skyped` starts Skype. Then `skyped`
58connects to Skype, finally BitlBee can connect to `skyped`.
59
60=== Installing under Frugalware or Debian
61
62- Install the necessary packages:
63
64----
65# pacman-g2 -S bitlbee-skype
66----
67
68or
69
70----
71# apt-get install skyped bitlbee-plugin-skype
72----
73
74(the later from the unstable repo)
75
76and you don't have to compile anything manually.
77
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
89and you have to install `bitlbee-skype` and `skype4py` from
90source.
91
92=== Installing from source
93
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
96or you want to use skyped with a public server (like
97`bitlbee1.asnetinc.net`), you don't need both.
98
99- You need the latest stable BitlBee release (unless you want to use a
100  public server):
101
102----
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@
106----
107
108- Now compile and install it:
109
110----
111$ ./configure
112$ make
113# make install install-dev
114----
115
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
125- Get the plugin code (in an empty dir, or whereever you want, it does
126  not matter):
127
128----
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@
132----
133
134- Compile and install it:
135
136----
137$ ./configure
138$ make
139# make install
140----
141
142This will install the plugin to where BitlBee expects them, which is
143`/usr/local/lib/bitlbee` if you installed BitlBee from source.
144
145=== Configuring
146
147- Set up `~/.skyped/skyped.conf`: Create the `~/.skyped` directory, copy
148  `skyped.conf` and `skyped.cnf` from
149  `/usr/local/etc/skyped/skyped.conf` to `~/.skyped`, adjust `username`
150  and `password`. The `username` should be your Skype login and the
151  `password` can be whatever you want, but you will have to specify that
152  one when adding the Skype account to BitlBee (see later).
153
154NOTE: Here, and later - `/usr/local/etc` can be different on your installation
155if you used the `--sysconfdir` switch when running bitlbee-skype's `configure`.
156
157- Generate the SSL pem files:
158
159----
160# cd ~/.skyped
161# openssl req -new -x509 -days 365 -nodes -config skyped.cnf -out skyped.cert.pem \
162        -keyout skyped.key.pem
163----
164
165NOTE: Maybe you want to adjust the permissions in the `~/.skyped`
166dir. For example make it readable by just your user.
167
168- Start `skyped` (the tcp server):
169
170----
171$ skyped
172----
173
174- Start your `IRC` client, connect to BitlBee and add your account:
175
176----
177account add skype <user> <pass>
178account skype set server localhost
179----
180
181<user> should be your Skype account name, <pass> should be the one you declared
182in `skyped.conf`. If you want to run skyped on a remote machine, replace
183`localhost` with the name of the machine.
184
185If you are running skyped on a custom port:
186
187----
188account skype set port <port>
189----
190
191If you want to set your full name (optional):
192
193----
194account skype set display_name "John Smith"
195----
196
197If you want to see your skypeout contacts online as well (they are
198offline by default):
199
200----
201account skype set skypeout_offline false
202----
203
204== Setting up Skype in a VNC server (optional)
205
206Optionally, if you want to run Skype on a server, you might want to setup up
207a `VNC` server as well. I used `tightvnc` but probably other `VNC` servers will
208work, too.
209
210First run
211
212----
213$ vncpasswd ~/.vnc/passwd
214----
215
216and create a password. You will need it at least once.
217
218Now create `~/.vnc/xstartup` with the following contents:
219
220----
221#!/bin/sh
222
223blackbox
224----
225
226Adjust the permissions:
227
228----
229$ chmod +x ~/.vnc/xstartup
230----
231
232Then start the server:
233
234----
235$ vncserver
236----
237
238Then connect to it, start an `xterm`, set up Skype (username, password,
239enable X11 API and allow the `Skype4Py` client), quit from Skype, and
240start `skyped`. If you want to watch its traffic, enable debug messages
241and foreground mode:
242
243----
244$ skyped -n -d
245----
246
247== Features
248
249- Download nicks and away statuses from Skype
250
251- Noticing joins / parts while we're connected
252
253- Sending messages
254
255- Receiving messages
256
257- Receiving away status changes
258
259- `skyped` (the tcp daemon that is a gateway between Skype and tcp)
260
261- Error handling when `skyped` is not running and when it exits
262
263- Marking received messages as seen so that Skype won't say there are unread messages
264
265- Adding / removing contacts
266
267- Set away state when you do a `/away`.
268
269- When you `account off`, Skype will set status to `Offline`
270
271- When you `account on`, Skype will set status to `Online`
272
273- Detect when somebody wants to add you and ask for confirmation
274
275- Detect when somebody wants to transfer a file
276
277- Group chat support:
278
279  * Detect if we're invited
280
281  * Send / receive group chat messages
282
283  * Invite others (using `/invite <nick>`)
284
285  * Part from group chats
286
287  * Starting a group chat (using `/j #nick`)
288
289- Topic changes in group chats:
290
291  * Show the current topic (if any) on join
292
293  * Notice when someone changes the topic
294
295  * Support changing the topic using `/topic`
296
297- Viewing the profile using the `info` command.
298
299- Handling skype actions (when the `CHATMESSAGE` has `EMOTED` type)
300
301- Setting your display name using the `nick` command.
302
303- Running Skype on a machine different to BitlBee is possible, the
304  communication is encrypted.
305
306- Managing outgoing calls (with call duration at the end):
307
308  * `/ctcp nick call`
309  * `/ctcp nick hangup`
310
311- Managing outgoing SkypeOut or conference calls:
312
313  * `account skype set call +18005551234`
314  * `account skype set call nick1 nick2`
315  * `account skype set -del call`
316
317- Managing incoming calls via questions, just like when you add / remove
318  contacts.
319
320- Querying the current SkypeOut balance:
321
322  * `account skype set balance query`
323
324- For debug purposes, it's possible to send any command to `skyped`. To
325  achieve this, you need to:
326
327  * `account skype set skypeconsole true`
328
329  * then writing `skypeconsole: <command>` will work in the control
330    channel.
331
332  * `account skype set skypeconsole_receive true` will make the
333    `skypeconsole` account dump all the recieved raw traffic for you
334
335- If you want to automatically join bookmarked groupchats right after
336  you logged in, do:
337
338  * `account skype set auto_join true`
339
340- Edited messages are shown with the `EDIT:` prefix. If you don't like
341  this, you can set your own prefix using:
342
343  * `account skype set edit_prefix "updated message:"`
344
345- The `echo123` test account is hidden by default. If you want to see it:
346
347  * `account skype set test_join true`
348
349- Mood texts are not shown by default. If you want to see it:
350
351  * `account skype set show_moods true`
352
353- Group support:
354
355  * Skype groups are told to BitlBee
356  * The usual `/invite` in a group channel adds the buddy to the group in skype
357    as well (and if necessary, it creates a new group in Skype)
358
359== What needs to be done (aka. TODO)
360
361- Notice if foo invites bar. Currently you can see only that bar joined.
362
363- Public chats. See
364  link:https://developer.skype.com/jira/browse/SCL-381[this feature
365  request], this is because it is still not possible (under Linux) to
366  `join_chat` to a public chat..
367
368- Add yasrd (Yet Another Skype-Related Daemon) to allow using a public
369  server for users who are behind NAT.
370
371== I would like to have support for ...
372
373If something does not work and it's not in the TODO section, then please
374contact me! Please also try the link:HACKING[git version] before reporting a bug, your
375problem may be already fixed there.
376
377In fact, of course, I wrote this documentation after figured out how to do this
378setup, so maybe I left out some steps. If you needed 'any' additional tricks,
379then it would be nice to include them here.
380
381== Known bugs
382
383- File transfers are view-only from BitlBee. Quoting the
384  https://developer.skype.com/Docs/ApiDoc/FILETRANSFER_object[relevant
385  documentation]: 'File transfers cannot be initiated nor accepted via
386  API commands.' So it's not something I can add support for, sadly.
387
388== Screenshots
389
390You can reach some screenshots link:shot[here].
391
392== Additional resources
393
394You can reach the Changelog link:Changelog[here], and a gitweb interface
395http://vmiklos.hu/gitweb/?p=bitlbee-skype.git[here].
396
397The Skype API documentation is
398http://developer.skype.com/resources/public_api_ref.zip[here] if you're
399interested.
400
401== Testimonials
402
403----
40400:56 < scathe> I like your skype plugin :)
405----
406
407----
408It's really working great so far.
409
410Good Job and thank you!
411Sebastian
412----
413
414----
415Big respect for your work, i really appreciate it.
416
417Martin
418----
419
420----
421Thanks for bitlbee-skype. As a blind Linux user, I cannot use the
422skype GUI client because qt apps ar not accessible yet with the
423available screen readers. bitlbee-skype allows me to make use of skype
424without having to interact much with the GUI client, which helps me a
425lot.
426
427Lukas
428----
429
430----
43102:12 < newton> i must say, i love this little bee ;)
43202:15 < newton> tried it out today with the skype plugin, good work!
433----
434
435----
43618:10 < miCSu> it works fine
437----
438
439----
44013:56 < seo> i just want to thank you :)
44113:56 < seo> for bitlbee-skype
44213:57 < seo> it's working very well, so, again, thank you for your work, and for sharing it
443----
444
445----
44622:16 < ecraven> vmiklos: thanks a lot for the skype plugin for bitlbee!
447----
448
449----
450I'm blind and so I have to use a screen reader, in my case Gnome-Orca.
451But since Skype is written in QT, while Orca uses gtk+, I have no direct
452access to the Skype interface. That's why I desided to use Skyped and
453Erc.
454The text console is fully accessible.
455Thank you very much.
456
457Hermann
458----
459
460----
461i love that bitlbeeplugin. big thx for that.
462
463michael
464----
465
466----
46723:47 < krisfremen> thanks for creating this fabulous piece of software vmiklos :)
468----
469
470== Thanks
471
472to the following people:
473
474* people in link:AUTHORS[AUTHORS] for their contributions
475
476* Arkadiusz Wahlig, author of skype4py, for making suggestions to skyped
477
478* Gabor Adam Toth (tg), for noticing extra code is needed to handle multiline
479  messages
480
481* Cristobal Palmer (tarheelcoxn), for helping to testing the plugin in a
482  timezone different to mine
483
484* people on `#bitlbee` for feedback
485
486Back to my link:/projects[projects page].
487
488// vim: ft=asciidoc
Note: See TracBrowser for help on using the repository browser.