bots/RECbot/README.md

# RECbot

A small XMPP bot written in Python that logs XMPP conversations into a HTML page, allowing collaborative log writing over time.

The bot is used in group chats, where it includes all images that are send to the group and all messages that include `@bot`.

*work-in-progress*

## Situated tails

* Archive bot, Relearn 2017, <https://gitlab.com/relearn/relearn2017/-/tree/master/xmpp-bots/archive-bot>
* Streambot, Varia website extension 2017-2018, <https://git.vvvvvvaria.org/varia/xmpp.streambot>
* Logbot, Varia XMPP extension 2017-2020, <https://git.vvvvvvaria.org/varia/bots/src/branch/master/logbot>

## Use RECbot 

* check if `RECbot` is one of the participants in the groupchat!
* send an image to the groupchat **OR** use one of the `__ACTION WORDS__` below
* the bot confirms your contribution and writes the message to a file
* check the output of RECbot (locally or online, for example: <https://vvvvvvaria.org/logs>)

RECbot works with `__ACTION WORDS__` and unique `<HANDLE>` codes.

* `__ADD__` RECbot entries with `__ADD__ <message>`, for example: `__ADD__ Logging as a form of stretching time.` or `__ADD__ https://nicelink.org` 
* `__DELETE__` RECbot entries with `__DELETE__ <HANDLE>`, for example: `__DELETE__ ~+*/+-` (\*spark)
* `__BOOK__` (\*sparks)

## Install RECbot

RECbot uses the `slixmpp` library to connect to XMPP and `beautifulsoup` to parse the HTML pages.

`$ sudo pip3 install slixmpp beautifulsoup4`

## Run RECbot! 

`$ python3 RECbot.py`

The bot will ask you to provide the following details:

* XMPP address of a (bot)account
* password
* groupchat address
* nickname for the bot
* output folder path 

You can also run it as a oneliner, for example by writing:

`$ python3 RECbot.py -u bot@vvvvvvaria.org -p CHANGEME -g roomname@muc.vvvvvvaria.org -n RECbot -o /var/www/logs/`

* `-u` / `--use` = user / use this XMPP address
* `-p` / `--password` = password
* `-g` / `--groupchat` = groupchat
* `-n` / `--nickname` = nickname
* `-o` / `--output` = output 

## \*sparks

-----------

It would be so nice to have different RECbot *modes*: `--log`, `--stream`, `--distribusi`

* `--log`: RECbot writes a growing HTML page with images and text, that can be marked up and styled in HTML/CSS.
* `--stream`: RECbot stores all images that are send to the group, and displays them as an image stream.
* `--distribusi`: RECbot saves files (images, messages as markdown, files, links as HTML pages) and generates a distribusi page of all collected material.

Under the hood the process can be cut up into two procedures:

* saving text/image/audio/video based messages as files (.txt, .png/.jpg, .ogg, .og4/.mp4)
	* recbot.py
* generating different outputs, depending on the selected *mode*
	* distribusi.py[\*]
	* log.py[\*]
	* stream.py[\*]

These modes can be changed at any moment. 

[\*] These are standalone scripts. They can be used on any set of files in a folder and generate HTML pages with customizable styling.

```
     RECbot                   <modes>                               <log HTML page>                                 

     │                        --distribusi   >    distribusi.py    
     │    [output folder]     --log          >    log.py            [output_folder/index.html]
     │    (saved as files)    --stream       >    stream.py         (saved as index.html + stylesheet.css) 
     │                        --xxx          >    xxx.py    
     │
     └──  stores text/media  
          files in output folder
          (local/server) 
```

------------

How can `__ACTION WORDS__` become magical `__MAGIC WORDS__` ???

------------