README.md 5.79 KB
Newer Older
Lorenzo Setale's avatar
Lorenzo Setale committed
1
2
3
# Koalalorenzo's Twitch Meme Bot
This Twitch bot is capable to listen for `!meme` commands in a Twitch chat and
generate on the fly memes to display as an overlay for OBS. 
Lorenzo Setale's avatar
Lorenzo Setale committed
4

Lorenzo Setale's avatar
Lorenzo Setale committed
5
If you like it, please follow me on 
6
7
8
[Twitch channel](https://twitch.tv/koalalorenzo). Original source code 
[available here](https://gitlab.com/koalalorenzo/twitch-meme-generator)

Lorenzo Setale's avatar
Lorenzo Setale committed
9
10
See it live [here](https://clips.twitch.tv/VibrantHotZucchiniAsianGlow-iTtCXFtzvn8cBljd)

Lorenzo Setale's avatar
Lorenzo Setale committed
11
## Building
Lorenzo Setale's avatar
Lorenzo Setale committed
12
13
To build the code into a portable binary you need the following things installed

Lorenzo Setale's avatar
Lorenzo Setale committed
14
15
16
17
- [GNU Make](https://www.gnu.org/software/make/) 
  (`brew install make`, but it is often pre-installed)
- [Go 1.16](https://go.dev) 
  (`brew install golang`)
Lorenzo Setale's avatar
Lorenzo Setale committed
18
19
20
21
22
23
24
25
26
27
28
29
30

After that you can run:

```bash
make clean build
```

and you will find all the files needed in the `build` directory. You can also
cross compile for Raspberry Pi by running:

```bash
make clean build -e BUILD_TARGET=rpi
```
Lorenzo Setale's avatar
Lorenzo Setale committed
31

Lorenzo Setale's avatar
Lorenzo Setale committed
32
## Usage
Lorenzo Setale's avatar
Lorenzo Setale committed
33
### Start the Server locally
34
35
36
37
38
39
40
41
To start the server locally you can use the built binary as in the following
exampoe:

```
./build/koalalorenzo-meme-generator --channel koalalorenzo
```

If you need more help feel free to run the command with `--help` flag.
Lorenzo Setale's avatar
Lorenzo Setale committed
42
Have a look at it because you can customize things like display time and 
43
host address (default to: `0.0.0.0:8000`).
Lorenzo Setale's avatar
Lorenzo Setale committed
44

Lorenzo Setale's avatar
Lorenzo Setale committed
45
### OBS Setup
Lorenzo Setale's avatar
Lorenzo Setale committed
46
47
48
49
50
51
52
53
54
Once the server is listening and ready you can load a new Browser Source in
OBS. The URL of the source should the one printed in the logs. 

The size of the window can be arbitrary based on the custom images. I suggest
to use:

- Width: 800
- Height: 600

Lorenzo Setale's avatar
Lorenzo Setale committed
55
By default this url will be [http://localhost:8000/sv](http://localhost:8000/sv).
Lorenzo Setale's avatar
Lorenzo Setale committed
56
57
If you are running on a different platform like Heroku or DigitalOcean please
use the URL provided by those platforms.
Lorenzo Setale's avatar
Lorenzo Setale committed
58

59
Remember to have dibled the following options: 
Lorenzo Setale's avatar
Lorenzo Setale committed
60
61
62
63
64
  - Refresh browser when scene becomes active
  - Shutdown source when not visible

The reason is this that this uses WebSockets and it is better to no have 
_multiple listners_ at the same time (aka: reuse the same source by 
65
_Copy Reference_). In case of issues the web page should reconnect automagically
66
67

### Adding files
Lorenzo Setale's avatar
Lorenzo Setale committed
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
You can add files any time into the `assets` directory (please note that the
path of the directory can be customized using flags). 

**IMPORTANT**: The file name convention is the following:

```xml
<meme>.<font-size>.<extension>
```

where:
- `meme` is the 1-word used after the `!meme` chat command to slect the image
- `font-size` is the size of the text that will be in the image, this is 
  a value that depends on the size of the image. Test it!
- `extension` is the image format. 
  It can be one of the following: `gif`, `png`, `jpeg` or `jpg`.

84
85
86
87
88
89
You can test the meme by running `generate` subcommand:

```bash
./build/koalalorenzo-meme-generator generate deal Dogs are cool, DEAL WITH IT
```

Lorenzo Setale's avatar
Lorenzo Setale committed
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
### Chat usage
The server  is connected to the Twitch Channel (IRC channel) using an anonymous
client. Therefore is not capable of announcing himself in the chat.

If the server is running you should be able to use the bot by writing a message
with the following syntax:

```xml
!meme <meme> <phrase to write...>
```

For example:

```xml
!meme pathetic Humans? Pathetic servants
```

Will display in the Browser source for a few seconds the following image:

![Picture of a cat master](example.jpg)
110

Lorenzo Setale's avatar
Lorenzo Setale committed
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
### WebHook usage
It is possible to set up a custom webhook that will queue memes and show them.
This is useful if you want to hook up some other tools or manually generate 
memes without using the chat (ex: From Apple Shortcuts or from `curl` for 
testing).

By default the webhook is disabled, to enable it you can pass the flag 
`--webhook-enable` to `true` or set the env variable `KTMG_WEBHOOK_ENABLE=true`.
This endpoint can be _protected_ by basic http authentication. Please use
`--help` flag to check all the options availalbe.

For example if I set the following env variables and run the app:

```bash
export KTMG_LOGLEVEL=debug
export KTMG_WEBHOOK_ENABLE=true
export KTMG_WEBHOOK_USERNAME=koalalorenzo
export KTMG_WEBHOOK_USERNAME=SuperSecretPassword
./build/koalalorenzo-meme-generator
```

I will then be able to queue memes to be generated on the fly by running 
http POST request to the endpoint `/wh`, like this:

```bash
curl http://127.0.0.1:8000/wh \
  -X POST --data '{ "kind":"pathetic", "text":"Humans? Pathetic servants"}' \
  -u koalalorenzo:SuperSecretPassword
```
140

141
## Deploy on Heroku
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

To quickly deploy on Heroku you can click on the following button and follow
the instructions:

[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/koalalorenzo/twitch-meme-generator/tree/main)

Follow the instructions and remember to customize the twitch channel and display
time as env variables.

**Important**: Please note that the name of the application will impact on the
URL that will be used in the OBS Browser Source. Do not share this URL/address
with anybody and try to keep it hard to find. (_hint_: try adding random
characters in the name might help)

**Important**: Due to security restrictions on some browser, using HTTP instead
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
of HTTPs in the OBS Browser Source URL will fix connectivity issues.

## Docker usage
It is possible to run Lorenzo's Twitch Bot meme generator using Docker.
The docker image is downloadable from 
[the project GitLab Docker Registry](https://gitlab.com/koalalorenzo/twitch-meme-generator/container_registry)

You can use both env variables as well as command line to configure the app:

```bash
docker run -p 8005:8005 registry.gitlab.com/koalalorenzo/twitch-meme-generator:latest
```

You can also mount the temporary directory (under path `/tmp`) to save the cache
of generated memes, this will speed up future requests.

You can mount the `/assets` path to a custom directory path where you can drop
the images that will be used as base for the memes.