Anon/MiraiNikkiBot
Archived
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Added documentation

Browse Source
This commit is contained in:
Anon 2022-08-31 21:57:47 -07:00
parent 3468411ab1
commit 12edf7b601
2 changed files with 265 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
README.md
View File

@ -1,7 +1,158 @@
# Readme # Readme
Placeholder text Mirai Nikki Bot is a customizable, no frills image-posting bot for Pleroma.
A live example can be viewed at [GNU/Yandere](https://yandere.cc/MiraiNikkiBot).
Currently the bot will only run on Linux. I believe it should run on most distros but I have only tested it on Arch and Raspbian.
## About ## About
I'll write up proper documentation later. This code is based off [Yandere Lewd Bot](https://git.yandere.cc/Anon/YandereLewdBot). Read the documentation for that if you want to clone this repository :) Mirai Nikki Bot is designed to be simple to understand (from a technical perspective) and easy to modify/extend. It's main purpose is to pick a random video from a pre-configured list of profiles, and upload a screenshot (at a random point in the video) to your Pleroma account. The render scripts themselves are just shell scripts, making it easy to swap out different command line screenshot utilites that you prefer.
You need mpv and imagemagick installed for this bot to function out of the box (or modify src/render_script.py to use a different screenshot program). This project is licensed under GPLv3. See [LICENSE.txt](./LICENSE.txt).
The bot is still in development and can easily be crashed by writing a poorly configured `cfg.py` file. It may also crash with encoding errors for files with non-unicode filenames.
## Installing
To setup the python3 environment (for Arch Linux) run the following commands:
```
sudo pacman -Syu
sudo pacman -S --needed python git
git clone 'https://git.yandere.cc/Anon/MiraiNikkiBot.git'
cd MiraiNikkiBot/
python -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
deactivate
cp -vn default/cfg.py src/
./run.sh -h
```
If everything worked correctly you should see usage information on Mirai Nikki Bot.
The ./run.sh file will automatically activate and deactivate the python virtual environment. You may want add a symlink to `/usr/local/bin` for convenience.
```
sudo ln -s "$(pwd)/run.sh" "/usr/local/bin/miraiNikkiBot"
miraiNikkiBot -h
```
For Debian or Ubuntu based distros I believe you need to change python with python3 for the package and command name `¯\_(ツ)_/¯`
## Generating your OAuth Tokens
Before you can begin posting from the bot, you must first create an account on the instance of your choice, and then generate your OAuth tokens.
To generate your tokens, run the following commands and follow the interactive prompts.
```
cd ..
git clone 'https://git.yandere.cc/Anon/CreatePleromaApp.git'
ln -s "$(pwd)"/MiraiNikkiBot/venv CreatePleromaApp/venv
ln -s "$(pwd)"/MiraiNikkiBot/src/cfg.py CreatePleromaApp/src/cfg.py
cd CreatePleromaApp/
./run.sh -c cfg
# Follow the interactive prompts.
```
If you did everything correctly you should see `Success! :)` at the end of the terminal, as well as your credentials in the format below:
```text
settings_server = OrderedDict([
"app_name": "app",
"api_base_url": "https://yandere.cc",
"client_id": "Long String of Text",
"client_secret": "Long String of Text",
"access_token": "Long String of Text"
])
settings_reminder = "09/20/2020 02:58PM"
settings_encrypt = {
"encrypt": False,
"salt": "",
}
```
If you used encryption, everything in the `settings_server` dictionary will be encrypted and you will have to enter your password every time you start the bot. Copy and paste these values from the terminal into your `src/cfg.py` file. **Make sure you paste over or delete the placeholder values with the same names.**
## Posting
To begin posting:
- Read [docs/configuration.md](./docs/configuration.md) to customize the bot for your purposes.
- Start the bot with `./run.sh`
- Enter your password if you encrypted your OAuth tokens.
- If you symlinked the file in the [Installing](#installing) section you can simply run `miraiNikkiBot` instead of changing directories and starting the bot with `./run.sh`
- If everything worked correctly, you should see your first image posted to your account.
- Hit Ctrl+C to stop the bot.
- Keep in mind that the bot's default visibility setting is set to unlisted for testing. You may want to update it to public.
# Donate
XMR: 493HynLQA4z71b3j9ZDXRNQudpdFW8GxeBGD8ahRctKn97RRurMVd35DqVqdAdjv68TcXTJWUwm6ee81ujDXGcmtKFixwQk
BAT: [Basic Attention Token](https://basicattentiontoken.org/)
# Useful Tips
## Installing Screen
Most likely, you will want this bot to run over a long period of time. It is probably best to install the `screen` package for your distro so you don't have to have a terminal window constantly open (especially if you are running it from a remote machine such as a Raspberry Pi or server).
```
sudo pacman -Syu
sudo pacman -S --needed screen
# Screen cheatsheet
# To create a new screen session named 'miraiNikkiBot'
screen -S miraiNikkiBot
# To detach from the screen session
Ctrl+a d
# To reconnect to the screen session
screen -r miraiNikkiBot
# List screen sessions
screen -ls
# Kill the screen session
Ctrl+a k y
# Scroll back
Ctrl+a ESC Page Up
# Cancel scroll back
ESC
```
## Quickly Create Configuration Files
Configuration files for Mirai Nikki Bot are just python files. Because of this we can easily create multiple configurations by importing the main configuration file, and overriding the values we need. This is useful for creating holiday and debug configurations without needing to create a new configuration file from scratch.
```
# Name: alt.py
# Post to an alt account using the exact same settings as the main configuration file
# Run with the following command: ./run.sh -c alt
# cfg.py is the default configuration.
from cfg import *
settings_server = OrderedDict([
("app_name", "generate from ./bin/create_app.py"),
("api_base_url", "generate from ./bin/create_app.py"),
("client_id", "generate from ./bin/create_app.py"),
("client_secret", "generate from ./bin/create_app.py"),
("access_token", "generate from ./bin/create_app.py")
])
settings_reminder = "generate from ./bin/create_app.py"
settings_encrypt = {
"encrypt": False,
"salt": "generate from ./bin/create_app.py"
}
# Uncommenting the below might be useful if your alt is used for debugging and testing
# settings_behavior["visibility"] = "private"
# settings_behavior["debug"] = True
```
```
# Name: xmas.py
# An xmas themed config file!
# Run with the following command: ./run.sh -c xmas
# cfg.py is the default configuration.
from cfg import *
# Prepend '#Merry #Christmas' to the beginning of the first line in each post
for setting in settings_post:
if len(setting["message"]) and issubclass(type(setting["message"][0]), str):
new_msg = "#Merry #Christmas {}".format(setting["message"][0])
setting["message"] = (new_msg,) + setting["message"][1:]
```

111
docs/configuration.md Normal file
View File

@ -0,0 +1,111 @@
# Configuration
Mirai Nikki Bot uses regular python files to configure posts. The default configuration is `cfg.py`
There are two default configuration files located in `default/`:
- **`cfg.py:`** Is a script that demonstrates the full funcitonality of the bot. It is production configuration for [Mirai Nikki Bot](https://yandere.cc/MiraiNikkiBot). This config will show you how to skip certain segments of a video file (such as the OP and ED of an anime) as well as mark nsfw scenes as sensative.
- **`cfg_netoge.py:`** Is much simpler. It also skips the OP and ED of the anime, but there are no nsfw scenes.
# Render scripts
To generate screenshots, the bot will call shell scripts located in the `src/` directory and specified in the `render_script` value in the `setup_episode()` function. By default the two scripts are included:
- **`render_mirai_nikki_script.sh:`** This script will use mpv to generate a screenshot *with the first subtitle track overlayed.*
- **`render_netoge_script.sh:`** Is a more basic script that will simply render a frame with no subtitles.
The bot will call these scripts with positional arguments for the input path, output path, and frame position (in seconds). Please modify these scripts to suit your preferances.
## setting_server
Paste the generated credentials from `create_app.py` in the fields below.
**`app_name:`** The name of the application.
**`api_base_url:`** The URL of the instance.
**`client_id:`** The client ID generated by `create_app.py`
**`client_secret:`** The client secret generated by `create_app.py`
**`access_token:`** The client token generated by `create_app.py`
**NOTE:** If you enabled encryption when generating your tokens, the above should be long strings of seemingly incoherent text.
## settings_reminder
A setting to remind the user to regenerate their OAuth tokens
**`settings_reminder:`** A date and time, formatted as `settings_time["long_date_format"]`. Used to remind the user to regenerate their OAuth tokens.
## settings_encrypt
Paste the generated credentials from `create_app.py` in the fields below.
**`encrypt:`** If encryption is enabled this should be set to `True`
**`salt:`** The salt value generated by `create_app.py`
## settings_credentials
If a back end supports or requires an account to use their api, the credentials for your account input here, and used by the back end. This is not required unless you have a premium account from Danbooru.
## settings_behavior
This is the main configuration setting for the bot.
**`visibility:`** The visibility of the post ('public', 'unlisted', 'private', or 'direct').
**`feature_set:`** The feature set of the instance you are connecting to ('mainline', 'fedibird', or 'pleroma'). **This bot has only been tested with 'pleroma'.**
**`sleep_seconds:`** The time between posts (in seconds)
**`uploads_per_post:`** The number of times the bot should post after `sleep_seconds`
**`retry_seconds:`** The time the bot should wait before attempting to re-upload a post that failed (in seconds). This value is ignored if the bot experiences a FileNotFoundError (the file was deleted after the bot was started) or encounters a 413 error (file upload size is too large). In either of the two cases the bot will continue posting the next image in the list.
**`content_type:`** The content type of the post ('text/plain' (default), 'text/markdown', 'text/html', 'text/bbcode'). **This bot has only been tested with `'text/plain'` and `'text/markdown'`**.
**`content_newline:`** The newline character or string. This will be inserted between each line in the message. If `content_type` is `'text/plain'`, this value should be `'\n'`. If `content_type` is `'text/markdown'` you may need to experiment. On some instances the default `'\n'` works, on others you may need to change this to `'<br/>'`.
**`post_image_link:`** If set to `True` this will insert a direct media link at the end of the message for each media file uploaded. If `content_type` is `'text\markdown'` it will make the link actionable, otherwise it will simply be a plain text html link. Some instances add this link automatically, in which case this should be set to `False`. See `content_newline` and `content_type` to correctly configure actionable links.
**`debug:`** Set this to true for testing. This will prevent Mirai Nikki Bot from logging into the mastodon instance and asking for your encryption password (meaning that nothing will actually get posted to your account, but it will still do everything else).
## settings_time
Time localization settings.
**`time_format:`** This is used to schedule posts using the `-t` switch. Referenced in `set_pretimer_hour()`
**`time_format_seconds:`** Unused. Should be the same as `time_format` but with a resolution in seconds.
**`date_format:`** This is used to schedule posts using the `-d` switch. Referenced in `set_pretimer_day()`
**`long_date_format:`** Time and date format. `settings_encrypt["reminder"]` Should be in this format. Referenced in `print_header_stats()` and `_sanity_warnings()`
**`long_date_seconds_format:`** Unused. Should be the same as `long_date_format` but with a resolution in seconds.
**`long_date_week:`** The same as `long_date_format` but with the day of the week specified. Referenced in `print_header_stats()`
**`datetime:`** A custom time to be printed by the bot if ${datetime} substitution is used in the profile output path.
## settings_post
Configure Mirai Nikki Bot profiles. Use the `setup_profile()` function to set profiles up in a single line.
# Setting Up Profiles
Each profile in `settings_post` contains a dictionary with the below keywords. Use the `setup_episode()` function with the same parameter names to setup posts in a single line.
Below is an explanation of each keyword:
* **`profile_name:`** String value. The name of the profile. This is mainly used to help you identify what profile is being applied to posts. This information is printed by the bot, but is otherwise unused.
* **`path:`** The input path of the video file.
* **`frames:`** The final frame of the video file (in seconds).
* **`skip:`** A tuple of tuples of time ranges to skip.
* **`nsfw:`** A tuple of tuples of time ranges to mark as sensative (nsfw)
* **`output_name:`** The output path of the string. This string can include the following shell-like variables that the bot will automatically substitute:
* **`${frame}:`** The selected frame in seconds.
* **`${profile_name}:`** The name of the profile.
* **`${datetime}:`** The date and time of the selection formatted in the settings_time["datetime"] variable
* **`message:`** String value. The body of the post when a *safe* frame is selected.
* **`message_nsfw:`** String value. The body of the post when a *nsfw* frame is selected.