source: protocols/skype/README @ 78e103e

Last change on this file since 78e103e was 875ba16, checked in by Miklos Vajna <vmiklos@…>, at 2013-02-09T11:31:43Z

skype: move config instructions from README to the manpage

  • Property mode set to 100644
File size: 11.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.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
147See the manpage of `skyped`.
148
149== Setting up Skype in a VNC server (optional)
150
151Optionally, if you want to run Skype on a server, you might want to setup up
152a `VNC` server as well. I used `tightvnc` but probably other `VNC` servers will
153work, too.
154
155First run
156
157----
158$ vncpasswd ~/.vnc/passwd
159----
160
161and create a password. You will need it at least once.
162
163Now create `~/.vnc/xstartup` with the following contents:
164
165----
166#!/bin/sh
167
168blackbox
169----
170
171Adjust the permissions:
172
173----
174$ chmod +x ~/.vnc/xstartup
175----
176
177Then start the server:
178
179----
180$ vncserver
181----
182
183Then connect to it, start an `xterm`, set up Skype (username, password,
184enable X11 API and allow the `Skype4Py` client), quit from Skype, and
185start `skyped`. If you want to watch its traffic, enable debug messages
186and foreground mode:
187
188----
189$ skyped -n -d
190----
191
192== Features
193
194- Download nicks and away statuses from Skype
195
196- Noticing joins / parts while we're connected
197
198- Sending messages
199
200- Receiving messages
201
202- Receiving away status changes
203
204- `skyped` (the tcp daemon that is a gateway between Skype and tcp)
205
206- Error handling when `skyped` is not running and when it exits
207
208- Marking received messages as seen so that Skype won't say there are unread messages
209
210- Adding / removing contacts
211
212- Set away state when you do a `/away`.
213
214- When you `account off`, Skype will set status to `Offline`
215
216- When you `account on`, Skype will set status to `Online`
217
218- Detect when somebody wants to add you and ask for confirmation
219
220- Detect when somebody wants to transfer a file
221
222- Group chat support:
223
224  * Detect if we're invited
225
226  * Send / receive group chat messages
227
228  * Invite others (using `/invite <nick>`)
229
230  * Part from group chats
231
232  * Starting a group chat (using `/j #nick`)
233
234- Topic changes in group chats:
235
236  * Show the current topic (if any) on join
237
238  * Notice when someone changes the topic
239
240  * Support changing the topic using `/topic`
241
242- Viewing the profile using the `info` command.
243
244- Handling skype actions (when the `CHATMESSAGE` has `EMOTED` type)
245
246- Setting your display name using the `nick` command.
247
248- Running Skype on a machine different to BitlBee is possible, the
249  communication is encrypted.
250
251- Managing outgoing calls (with call duration at the end):
252
253  * `/ctcp nick call`
254  * `/ctcp nick hangup`
255
256- Managing outgoing SkypeOut or conference calls:
257
258  * `account skype set call +18005551234`
259  * `account skype set call nick1 nick2`
260  * `account skype set -del call`
261
262- Managing incoming calls via questions, just like when you add / remove
263  contacts.
264
265- Querying the current SkypeOut balance:
266
267  * `account skype set balance query`
268
269- For debug purposes, it's possible to send any command to `skyped`. To
270  achieve this, you need to:
271
272  * `account skype set skypeconsole true`
273
274  * then writing `skypeconsole: <command>` will work in the control
275    channel.
276
277  * `account skype set skypeconsole_receive true` will make the
278    `skypeconsole` account dump all the recieved raw traffic for you
279
280- If you want to automatically join bookmarked groupchats right after
281  you logged in, do:
282
283  * `account skype set auto_join true`
284
285- Edited messages are shown with the `EDIT:` prefix. If you don't like
286  this, you can set your own prefix using:
287
288  * `account skype set edit_prefix "updated message:"`
289
290- The `echo123` test account is hidden by default. If you want to see it:
291
292  * `account skype set test_join true`
293
294- Mood texts are not shown by default.
295
296  * If you want to see them: `account skype set show_moods true`
297  * If you want to change your mood text: `account skype set mood_text 'foo bar'`
298
299- Group support:
300
301  * To enable: `account skype set read_groups true`
302  * Skype groups are told to BitlBee
303  * The usual `/invite` in a group channel adds the buddy to the group in skype
304    as well (and if necessary, it creates a new group in Skype)
305
306== What needs to be done (aka. TODO)
307
308- Notice if foo invites bar. Currently you can see only that bar joined.
309
310- Public chats. See
311  link:https://developer.skype.com/jira/browse/SCL-381[this feature
312  request], this is because it is still not possible (under Linux) to
313  `join_chat` to a public chat..
314
315- Add yasrd (Yet Another Skype-Related Daemon) to allow using a public
316  server for users who are behind NAT.
317
318== I would like to have support for ...
319
320If something does not work and it's not in the TODO section, then please
321contact me! Please also try the bzr version before reporting a bug, your
322problem may be already fixed there.
323
324In fact, of course, I wrote this documentation after figured out how to do this
325setup, so maybe I left out some steps. If you needed 'any' additional tricks,
326then it would be nice to include them here.
327
328== Known bugs
329
330- File transfers are view-only from BitlBee. Quoting the
331  https://developer.skype.com/Docs/ApiDoc/FILETRANSFER_object[relevant
332  documentation]: 'File transfers cannot be initiated nor accepted via
333  API commands.' So it's not something I can add support for, sadly.
334
335== Screenshots
336
337You can reach some screenshots link:shot[here].
338
339== Additional resources
340
341The Skype API documentation is
342http://developer.skype.com/resources/public_api_ref.zip[here] if you're
343interested.
344
345== Testimonials
346
347----
34800:56 < scathe> I like your skype plugin :)
349----
350
351----
352It's really working great so far.
353
354Good Job and thank you!
355Sebastian
356----
357
358----
359Big respect for your work, i really appreciate it.
360
361Martin
362----
363
364----
365Thanks for bitlbee-skype. As a blind Linux user, I cannot use the
366skype GUI client because qt apps ar not accessible yet with the
367available screen readers. bitlbee-skype allows me to make use of skype
368without having to interact much with the GUI client, which helps me a
369lot.
370
371Lukas
372----
373
374----
37502:12 < newton> i must say, i love this little bee ;)
37602:15 < newton> tried it out today with the skype plugin, good work!
377----
378
379----
38018:10 < miCSu> it works fine
381----
382
383----
38413:56 < seo> i just want to thank you :)
38513:56 < seo> for bitlbee-skype
38613:57 < seo> it's working very well, so, again, thank you for your work, and for sharing it
387----
388
389----
39022:16 < ecraven> vmiklos: thanks a lot for the skype plugin for bitlbee!
391----
392
393----
394I'm blind and so I have to use a screen reader, in my case Gnome-Orca.
395But since Skype is written in QT, while Orca uses gtk+, I have no direct
396access to the Skype interface. That's why I desided to use Skyped and
397Erc.
398The text console is fully accessible.
399Thank you very much.
400
401Hermann
402----
403
404----
405i love that bitlbeeplugin. big thx for that.
406
407michael
408----
409
410----
41123:47 < krisfremen> thanks for creating this fabulous piece of software vmiklos :)
412----
413
414== Thanks
415
416to the following people:
417
418* people in link:AUTHORS[AUTHORS] for their contributions
419
420* Arkadiusz Wahlig, author of skype4py, for making suggestions to skyped
421
422* Gabor Adam Toth (tg), for noticing extra code is needed to handle multiline
423  messages
424
425* Cristobal Palmer (tarheelcoxn), for helping to testing the plugin in a
426  timezone different to mine
427
428* people on `#bitlbee` for feedback
429
430Back to my link:/projects[projects page].
431
432// vim: ft=asciidoc
Note: See TracBrowser for help on using the repository browser.