Metadata-Version: 1.0
Name: dendrotox
Version: 2018.3.3.110
Summary: Python interface to Tox distributed communications
Home-page: https://github.com/wdbm/dendrotox
Author: Will Breaden Madden
Author-email: wbm@protonmail.ch
License: GPLv3
Description-Content-Type: UNKNOWN
Description: .. figure:: https://raw.githubusercontent.com/wdbm/dendrotox/master/media/dendrotox.png
           :alt: 
        
        ``dendrotox`` is a Python module designed to enable Python code to
        interact with the `Tox <https://tox.chat/>`__ distributed communications
        network, including for the purposes of scripts communicating with people
        or other scripts. It uses a 2015 version of
        `ToxCore <https://github.com/irungentoo/toxcore/releases/tag/api_old_version>`__
        and `ratox <https://github.com/kytvi2p/ratox>`__ for interfacing with
        the Tox network and `megaparsex <https://github.com/wdbm/megaparsex>`__
        for parsing.
        
        In particular, ``dendrotox`` interacts with the filesystem provided by
        the FIFO Tox client `ratox <https://github.com/kytvi2p/ratox>`__.
        ``dendrotox`` also provides functionality to send and receive messages,
        to parse input, to send files, to request confirmations, to provide
        information such as IP address and weather information, and to run
        arbitrary commands, including functionality to launch reverse-SSH
        connections and to restart a script.
        
        Tox
        ===
        
        Tox is a peer-to-peer instant-messaging and video-calling protocol that
        has end-to-end encryption.
        
        The following is a typical Tox ID that one contact can give to another
        contact in order to connect:
        
        ::
        
            56A1ADE4B65B86BCD51CC73E2CD4E542179F47959FE3E0E21B4B0ACDADE5185520B3E6FC5D64
            <--------------------------------------------------------------><------><-->
                                            ^                                  ^      ^
                                            |                                  |      |
                                            |                                  |      |
                                        PUBLIC KEY                        NOSPAM      CHECKSUM
        
        The Tox ID is a public key (64 characters), a nospam value (8
        characters) and a checksum (4 characters) concatenated in hexadecimal
        format. The result is a 76 character string.
        
        The public key is generated by the NaCl (Networking and Cryptographic
        library) ``crypto_box_keypair`` function. It is 32 bytes (64 hexadecimal
        characters). The nospam value is a generated pseudorandom number
        appended to the public key. A connect request sent without the correct
        nospam value is ignored. The nospam value can be changed at any time
        without affecting the public key, stopping all requests to the current
        ID, in order to fight spam. The checksum is a simple XOR checksum of the
        public key and the nospam value. It is used to quickly verify the
        integrity of the Tox ID.
        
        Because Tox has no central servers, it is necessary to know a node that
        is already in the network before a client can be connected suffessfully.
        Some nodes are listed `here <https://nodes.tox.chat/json>`__.
        
        setup
        =====
        
        .. code:: bash
        
            sudo apt install    \
                autoconf        \
                autotools-dev   \
                automake        \
                build-essential \
                checkinstall    \
                check           \
                cmake           \
                festival        \
                git             \
                libtool         \
                libsodium-dev   \
                sox             \
                yasm
        
        .. code:: bash
        
            mkdir ~/Tox
            cd ~/Tox
        
        Install FFmpeg.
        
        .. code:: bash
        
            sudo apt install lame libmp3lame-dev
            wget http://ffmpeg.org/releases/ffmpeg-3.3.2.tar.bz2
            tar -xvf ffmpeg-3.3.2.tar.bz2
            cd ffmpeg-3.3.2
            ./configure --enable-libmp3lame
            make -j$(nproc)
            sudo make install
            cd ..
            rm ffmpeg-3.3.2.tar.bz2
            rm -rf ffmpeg-3.3.2
        
        Set up `Festival <http://www.cstr.ed.ac.uk/projects/festival/>`__,
        `eSpeak <http://espeak.sourceforge.net/>`__, Pico TTS and
        `deep\_throat <https://github.com/wdbm/deep_throat>`__ for speech
        capabilities.
        
        .. code:: bash
        
            sudo apt install     \
                festival         \
                espeak           \
                libttspico0      \
                libttspico-utils \
                libttspico-data
            sudo pip install deep_throat
        
        Install the Sodium crypto library.
        
        .. code:: bash
        
            git clone https://github.com/jedisct1/libsodium.git
            cd libsodium
            git checkout tags/1.0.3
            ./autogen.sh
            ./configure
            make check
            sudo checkinstall --install --pkgname libsodium --pkgversion 1.0.0 --nodoc
            sudo ldconfig
            cd ..
        
        Install the libvpx codec.
        
        .. code:: bash
        
            git clone https://chromium.googlesource.com/webm/libvpx
            cd libvpx
            git checkout tags/v1.4.0
            ./configure --enable-shared --disable-static
            make -j$(nproc)
            sudo make install
            cd ..
        
        Install ToxCore.
        
        .. code:: bash
        
            wget --content-disposition https://codeload.github.com/irungentoo/toxcore/tar.gz/api_old_version
            tar -xvf toxcore-api_old_version.tar.gz
            cd toxcore-api_old_version
            autoreconf --install --force
            mkdir _build
            cd _build
            ../configure
            make -j$(nproc)
            sudo make install
            sudo ldconfig
            cd ../..
        
        Install ``ratox``.
        
        .. code:: bash
        
            git clone https://github.com/wdbm/ratox.git
            cd ratox
            make -j$(nproc)
            sudo make install
        
        Install dendrotox.
        
        .. code:: bash
        
            sudo pip install dentrodox
        
        When ``ratox`` is launched for the first time, it creates a Tox profile
        file ``.ratox.tox`` at the working directory to store Tox profile
        details. While running, the file ``id`` contains the Tox ID.
        
        examples
        ========
        
        ``dendrotox`` is imported and launched in the following way:
        
        .. code:: python
        
            import dendrotox
            dendrotox.start_messaging()
            print("Tox ID: " + dendrotox.self_ID())
        
        sending messages
        ----------------
        
        A message can be sent to a contact in the following way, where a contact
        is specified using a string containing their Tox ID:
        
        .. code:: python
        
            dendrotox.send_message(contact = contact, text = "oohai")
        
        A message can be sent to multiple contacts in the following way, where
        contacts are specified as a list of strings containing contacts' Tox
        IDs.
        
        .. code:: python
        
            dendrotox.send_message(contacts = [contact_1, contact_2], text = "sup")
        
        A message can be sent to all contacts in the following way.
        
        .. code:: python
        
            dendrotox.send_message(contacts = "all", text = "yo yo yo")
        
        receiving messages
        ------------------
        
        A list of unseen messages received recently can be accessed in the
        following ways:
        
        .. code:: python
        
            messages = dendrotox.received_messages()
            print(messages[0].sender())
        
        .. code:: python
        
            message = dendrotox.last_received_message()
            print(message)
        
        sending sound calls
        -------------------
        
        A sound call can be sent to a contact in a few ways. One way is by
        sending a sound file:
        
        .. code:: python
        
            dendrotox.send_call(contact = contact, filepath = "alert.wav")
        
        Another way is by using synthesized speech:
        
        .. code:: python
        
            dendrotox.send_call_synthesized_speech(contact = contact, text = "This is an alert.")
        
        Another way is by using a microphone:
        
        .. code:: python
        
            dendrotox.send_call(contact = contact, record = True)
        
        Sending a sound call by using a microphone can feature a record duration
        specification in order to ensure that the process does not hang:
        
        .. code:: python
        
            dendrotox.send_call(contact = contact, record = True, duration_record = 30)
        
        receiving sound calls
        ---------------------
        
        A sound call can be received from a contact in a few ways. One way is by
        using speakers:
        
        .. code:: python
        
            dendrotox.receive_call(contact = contact)
        
        If a contact is not specified, the first contacted identified as calling
        is used to receive a call:
        
        .. code:: python
        
            dendrotox.receive_call()
        
        Another way is by receiving a sound file:
        
        .. code:: python
        
            dendrotox.receive_call(filepath = "call.wav")
        
        See module code and example bot code for more advanced usage, including
        calls, message parsing, confirmations and running commands.
        
        dendrotox\_alert.py
        ===================
        
        The script ``dendrotox_alert.py`` is a command line script that can be
        used to send a message to contacts. It attempts to connect with any
        specified contacts before attempting to send a message to them. If no
        contacts are specified, it attempts to send a message to all known
        contacts.
        
        .. code:: bash
        
            dendrotox_alert.py --text="alert"
        
        future
        ======
        
        Under consideration is speech-to-text for receiving calls.
        
Platform: UNKNOWN
