source: skype/README @ 56d88ba

Last change on this file since 56d88ba was 56d88ba, checked in by Miklos Vajna <vmiklos@…>, at 2008-09-05T19:54:46Z

docu update and remove todo item

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