From 1e00eb121fcc2cfbdd15719c56c0467efffe2d85 Mon Sep 17 00:00:00 2001
From: jake <jake@jakes-mail.top>
Date: Thu, 12 Dec 2024 19:57:58 -0500
Subject: [PATCH] add readme

---
 README.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2cbc873
--- /dev/null
+++ b/README.md
@@ -0,0 +1,59 @@
+# Mojo Owncast IRC Bridge
+This program bridges Owncast Chat with an IRC channel
+
+# Requirements
+This program has several requirements
+* Mojolicious
+* Mojo::IRC
+* Mojo::UserAgent
+
+Acquire them.
+
+# Usage
+## Copy config file
+```code
+cp start.sh.example start.sh
+```
+
+Please edit as necessary; we will acquire access token shortly.
+
+## Webhook
+On Owncast; go to Admin -> webhooks and add:
+```code
+http://listening.address/webhook
+```
+which responds to ALL events.
+
+## Access Tokens
+On Owncast; go to Admin -> got to Access Tokens
+For name; put something short as this will appear every time a message is sent from IRC if you don't supply an admin password file environment variable.
+Scopes: 'System messages' and 'User chat messages'
+
+Copy that token and put it on the respective line in your start.sh file.
+
+## Admin Password File Environment Variable
+OWNCAST_ADMIN_PASS_FILE must be readable by the user that the program is running from.  This file is the ADMIN password for Owncast.  Obviously, this has Owncast related security implications which I won't cover.  (Maybe one day Owncast will allow for more 'admin passes' with specific scopes.)
+
+This reads the file and uses that as the admin password which will create a better chatting experience;
+
+* Automatically creates new access tokens for IRC chatters.
+* Keeps track of these tokens.
+* Will use these tokens to chat in Owncast Chat
+* Will delete these tokens when IRC participants leave channel.
+* Tries to use access tokens that were already present on program restart.
+
+This isn't a perfect program and at times you may need to clear out these 'extra' access tokens manually and restart the program since it won't know that the tokens have been deleted.
+
+OWNCAST_ADMIN_PASS_FILE environment variable doesn't need to exist; this program can chat with just it's own Access Token.
+
+## Start program
+```
+./start.sh
+```
+
+# Tips
+## Latency
+To achieve a 'low-latency' chatting experience, try to get this program on the same box that owncast is on; directly poking Owncast itself (instead of going through the TLS-Apache/Nginx/whatever-proxypass-owncast overhead.)
+
+## Create channel
+This bot is quite noisy, so its probably a good idea to create a dedicated channel just for this program.