source: skype/README @ f5ae4a10

Last change on this file since f5ae4a10 was 8fcb196, checked in by Miklos Vajna <vmiklos@…>, at 2010-08-02T21:54:24Z

update skype api link

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