source: protocols/skype/README @ 6efb777

Last change on this file since 6efb777 was 757e1e0, checked in by Miklos Vajna <vmiklos@…>, at 2013-01-01T16:19:09Z

skype: remove unused build system targets, references to git

  • 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.2.0.35.
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.
350
351  * If you want to see them: `account skype set show_moods true`
352  * If you want to change your mood text: `account skype set mood_text 'foo bar'`
353
354- Group support:
355
356  * To enable: `account skype set read_groups true`
357  * Skype groups are told to BitlBee
358  * The usual `/invite` in a group channel adds the buddy to the group in skype
359    as well (and if necessary, it creates a new group in Skype)
360
361== What needs to be done (aka. TODO)
362
363- Notice if foo invites bar. Currently you can see only that bar joined.
364
365- Public chats. See
366  link:https://developer.skype.com/jira/browse/SCL-381[this feature
367  request], this is because it is still not possible (under Linux) to
368  `join_chat` to a public chat..
369
370- Add yasrd (Yet Another Skype-Related Daemon) to allow using a public
371  server for users who are behind NAT.
372
373== I would like to have support for ...
374
375If something does not work and it's not in the TODO section, then please
376contact me! Please also try the bzr version before reporting a bug, your
377problem may be already fixed there.
378
379In fact, of course, I wrote this documentation after figured out how to do this
380setup, so maybe I left out some steps. If you needed 'any' additional tricks,
381then it would be nice to include them here.
382
383== Known bugs
384
385- File transfers are view-only from BitlBee. Quoting the
386  https://developer.skype.com/Docs/ApiDoc/FILETRANSFER_object[relevant
387  documentation]: 'File transfers cannot be initiated nor accepted via
388  API commands.' So it's not something I can add support for, sadly.
389
390== Screenshots
391
392You can reach some screenshots link:shot[here].
393
394== Additional resources
395
396The Skype API documentation is
397http://developer.skype.com/resources/public_api_ref.zip[here] if you're
398interested.
399
400== Testimonials
401
402----
40300:56 < scathe> I like your skype plugin :)
404----
405
406----
407It's really working great so far.
408
409Good Job and thank you!
410Sebastian
411----
412
413----
414Big respect for your work, i really appreciate it.
415
416Martin
417----
418
419----
420Thanks for bitlbee-skype. As a blind Linux user, I cannot use the
421skype GUI client because qt apps ar not accessible yet with the
422available screen readers. bitlbee-skype allows me to make use of skype
423without having to interact much with the GUI client, which helps me a
424lot.
425
426Lukas
427----
428
429----
43002:12 < newton> i must say, i love this little bee ;)
43102:15 < newton> tried it out today with the skype plugin, good work!
432----
433
434----
43518:10 < miCSu> it works fine
436----
437
438----
43913:56 < seo> i just want to thank you :)
44013:56 < seo> for bitlbee-skype
44113:57 < seo> it's working very well, so, again, thank you for your work, and for sharing it
442----
443
444----
44522:16 < ecraven> vmiklos: thanks a lot for the skype plugin for bitlbee!
446----
447
448----
449I'm blind and so I have to use a screen reader, in my case Gnome-Orca.
450But since Skype is written in QT, while Orca uses gtk+, I have no direct
451access to the Skype interface. That's why I desided to use Skyped and
452Erc.
453The text console is fully accessible.
454Thank you very much.
455
456Hermann
457----
458
459----
460i love that bitlbeeplugin. big thx for that.
461
462michael
463----
464
465----
46623:47 < krisfremen> thanks for creating this fabulous piece of software vmiklos :)
467----
468
469== Thanks
470
471to the following people:
472
473* people in link:AUTHORS[AUTHORS] for their contributions
474
475* Arkadiusz Wahlig, author of skype4py, for making suggestions to skyped
476
477* Gabor Adam Toth (tg), for noticing extra code is needed to handle multiline
478  messages
479
480* Cristobal Palmer (tarheelcoxn), for helping to testing the plugin in a
481  timezone different to mine
482
483* people on `#bitlbee` for feedback
484
485Back to my link:/projects[projects page].
486
487// vim: ft=asciidoc
Note: See TracBrowser for help on using the repository browser.