source: skype/README @ 1b48afb

Last change on this file since 1b48afb was 1b48afb, checked in by Miklos Vajna <vmiklos@…>, at 2009-04-29T17:24:18Z

add support for user-wide config files

in the past the config file was expected in /etc/skyped, change this to
~/.skyped, and just fall back to the previous path if it's not
available.

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