ratox

FIFO based tox client
git clone git://git.2f30.org/ratox.git
Log | Files | Refs | README | LICENSE

README (5732B)


      1             __                    
      2            /\ \__                 
      3  _ __   __ \ \ ,_\   ___   __  _  
      4 /\`'__/'__`\\ \ \/  / __`\/\ \/'\ 
      5 \ \ \/\ \L\.\\ \ \_/\ \L\ \/>  </ 
      6  \ \_\ \__/.\_\ \__\ \____//\_/\_\
      7   \/_/\/__/\/_/\/__/\/___/ \//\/_/
      8                                    -- by sin and FRIGN
      9 ======================================================
     10 
     11 
     12 What is it?
     13 ===========
     14 
     15 ratox is a client implementation of the rather popular tox protocol[0].
     16 Unlike other clients relying on GUIs as an interface to the user, ratox is
     17 developed with the UNIX-philosophy in mind and allows complete
     18 interaction through named pipes.
     19 
     20 There's also a set of scripts[1] developed by various people that build on
     21 top of the FIFO interface.
     22 
     23 
     24 Getting started
     25 ===============
     26 
     27 Get the latest version from the git-repository; build and install it.
     28 Run ratox in an empty directory and it will create a set of files and
     29 folders allowing you to control the client.
     30 
     31 
     32 File structure
     33 ==============
     34 
     35 A typical filesystem structure is shown below along with some comments
     36 to help explain the semantics of the individual files.
     37 
     38 .
     39 |-- .ratox.data			# ratox save file
     40 |
     41 |-- 0A734CBA717CEB7883D....	# friend's ID excluding nospam + checksum
     42 |   |-- call_in			# 'arecord -r 48000 -c 1 -f S16_LE > call_in' to initiate a call
     43 |   |-- call_out		# 'aplay -r 48000 -c 1 -f S16_LE - < call_out' to answer a call
     44 |   |-- call_state		# (none, pending, active)
     45 |   |-- file_in			# 'cat foo > file_in' to send a file
     46 |   |-- file_out		# 'cat file_out > bar' to receive a file
     47 |   |-- file_pending		# contains filename if transfer pending, empty otherwise
     48 |   |-- name			# friend's nickname
     49 |   |-- online			# 1 if friend online, 0 otherwise
     50 |   |-- remove			# 'echo 1 > remove' to remove a friend
     51 |   |-- state			# friend's user state; could be any of {none,away,busy}
     52 |   |-- status			# friend's status message
     53 |   |-- text_in			# 'echo yo dude > text_in' to send a text to this friend
     54 |   `-- text_out		# 'tail -f text_out' to dump to stdout any text received
     55 |
     56 |-- 00000000
     57 |   |-- members                 # list of people in the conference
     58 |   |-- invite                  # 'echo 0A734CBA717CEB7883D.... >invite' to invite
     59 |   |-- leave                   # 'echo 1 >leave' to leave the conference
     60 |   |-- title_in                # 'echo new-title >title_in' to update the conference title
     61 |   |-- title_out               # contains the current title
     62 |   |-- text_in                 # 'echo blablahumbla >text_in' to message the other conference members
     63 |   |-- text_out                # contains the messages sent so far in the conference
     64 |
     65 |-- id				# 'cat id' to show your own ID, you can give this to your friends
     66 |
     67 |-- conf			# managing conferences
     68 |   |-- err			# conference related errors
     69 |   |-- in			# 'echo 't group title' >in' for creating a new text group
     70 |   |-- out			# 'echo 1 >out/ID_COOKIE' for joining a conference
     71 |
     72 |-- name			# changing your nick
     73 |   |-- err			# nickname related errors
     74 |   |-- in			# 'echo my-new-nick > in' to change your name
     75 |   `-- out			# 'cat out' to show your name
     76 |
     77 |-- nospam			# changing your nospam
     78 |   |-- err			# nospam related errors
     79 |   |-- in			# 'echo AABBCCDD > in' to change your nospam
     80 |   `-- out			# 'cat out' to show your nospam
     81 |
     82 |-- request			# send and accept friend requests
     83 |   |-- err			# request related errors
     84 |   |-- in			# 'echo LONGASSID yo dude add me > in' to send a friend request
     85 |   `-- out			# 'echo 1 > out/LONGASSID' to accept the friend request
     86 |
     87 |-- state			# changing your user state
     88 |   |-- err			# user status related errors
     89 |   |-- in			# 'echo away > in' to change your user state; could be any of {none,away,busy}
     90 |   `-- out			# 'cat out' to show your user state
     91 |
     92 `-- status			# changing your status message
     93     |-- err			# status message related errors
     94     |-- in			# 'cat I am bored to death > in' to change your status message
     95     `-- out			# 'cat out' to show your status message
     96 
     97 
     98 Features
     99 ========
    100 
    101 1 v 1 messaging: Yes
    102 File transfer: Yes
    103 Group chat: Yes
    104 Audio: Yes
    105 Video: No
    106 DNS discovery: No
    107 Chat logs: Yes
    108 Proxy support: Yes
    109 Offline message: Yes
    110 Offline transfers: Yes
    111 Contact aliases: No
    112 Contact blocking: No
    113 Save file encryption: Yes
    114 Multilingual: No
    115 Multiprofile: Yes
    116 Typing notification: No
    117 Audio notifications: No
    118 Emoticons: No
    119 Spell check: No
    120 Desktop sharing: No
    121 Inline images: No
    122 File resuming: No
    123 Read receipts: No
    124 Message splitting: Yes
    125 Changing nospam: Yes
    126 toxi URI: No
    127 
    128 NOTE: Some of these features are not intended to be developed
    129 in ratox itself but rather in external scripts[1] that are built upon
    130 ratox.
    131 
    132 Group chats do not have audio yet.
    133 
    134 
    135 Examples
    136 ========
    137 
    138 SSH over TOX for the practical paranoid
    139 ---------------------------------------
    140 
    141 On the sender side (the client):
    142 1) cd into the friend's directory (the server)
    143 2) nc -lv 1234 > file_in < file_out
    144 
    145 On the receiver side (the server):
    146 1) cd into the friend's directory (the client)
    147 2) cat < file_out | nc localhost 22 > file_in
    148 
    149 Now on the client run the following:
    150 ssh -o ProxyCommand="nc %h 1234" user@localhost
    151 
    152 Screencasting using ffmpeg and mplayer
    153 --------------------------------------
    154 
    155 On the sender side:
    156 ffmpeg -f x11grab -r 10 -s 1366x768 -i :0.0 -vcodec libx264 \
    157 	-pix_fmt yuv420p -preset fast -tune zerolatency -b:v 500k \
    158 	-f flv pipe: > file_in
    159 
    160 On the receiver side:
    161 mplayer -cache 1024 file_out
    162 
    163 You may have to play about with the cache size.
    164 
    165 
    166 Portability
    167 ===========
    168 
    169 Builds and works on *BSD and Linux.  To build on OSX you need
    170 to apply a patch[2].
    171 
    172 
    173 Contact
    174 =======
    175 
    176 You can reach us through the freenode IRC network at #2f30 or
    177 through tech@lists.2f30.org.
    178 
    179 [0] https://tox.chat/
    180 [1] https://git.2f30.org/ratox-nuggets/
    181 [2] https://ratox.2f30.org/ratox-os_x.patch