{"id":13471188,"url":"https://github.com/SleepyLili/tlapbot","last_synced_at":"2025-03-26T13:30:53.190Z","repository":{"id":62828206,"uuid":"535571690","full_name":"SleepyLili/tlapbot","owner":"SleepyLili","description":"Owncast bot written in Python+Flask, providing channel points and channel point redeems for your owncast stream. Reward your viewers for watching, and infuse your stream with fun interactions and challenges.","archived":false,"fork":false,"pushed_at":"2025-03-07T22:11:50.000Z","size":152,"stargazers_count":38,"open_issues_count":2,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-07T23:20:17.982Z","etag":null,"topics":["bot","flask","owncast","python","streaming","webhooks"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SleepyLili.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-12T08:18:42.000Z","updated_at":"2024-09-08T07:00:15.000Z","dependencies_parsed_at":"2024-03-10T18:26:14.292Z","dependency_job_id":"0d0ef16f-b1ab-44d6-b8ba-94350a575719","html_url":"https://github.com/SleepyLili/tlapbot","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SleepyLili%2Ftlapbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SleepyLili%2Ftlapbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SleepyLili%2Ftlapbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SleepyLili%2Ftlapbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SleepyLili","download_url":"https://codeload.github.com/SleepyLili/tlapbot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245662763,"owners_count":20652077,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","flask","owncast","python","streaming","webhooks"],"created_at":"2024-07-31T16:00:41.270Z","updated_at":"2025-03-26T13:30:52.819Z","avatar_url":"https://github.com/SleepyLili.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Tlapbot\nTlapbot is an [Owncast](https://owncast.online/) bot that adds channel points and\nchannel point redeems to your Owncast page.\n\nSimilar\nto [Twitch channel points](https://help.twitch.tv/s/article/viewer-channel-point-guide), Tlapbot rewards your viewers with points for watching, and allows them to spend their points on fun gimmicks, challenges, reaction requests, or whatever else you decide.\n\nTlapbot makes use of [Owncast webhooks](https://owncast.online/thirdparty/webhooks/) for chat interactions and \n[Owncast external actions](https://owncast.online/thirdparty/actions/) to display an informative dashboard.\n\n## Features\nThe bot gives points to everyone in chat -- 10 points every 10 minutes by\ndefault, but the time interval and amount of points can be changed.\n\nThe users in chat can then use their points on redeems -- rewards like \"choose my\nbackground music\", \"choose what level to play next\", \"react to this video\" etc.\nYou can configure redeems to fit your stream and the activities you're\ndoing, and sort them into categories that can be turned on and off.\n\nThe redeems then show on a \"Redeems dashboard\" that everyone can view\nas an External Action on the Owncast stream, or at its standalone URL.\nThis allows easy browsing of active challenges and recent redeems, without quitting the stream.\n\n**Tlapbot currently doesn't support any automated integrations (or an API). That means no 'Crowd Control' plugin, no instant effects in OBS or VTube Studio, etc. The streamer decides how they respond to redeems or how to make them take effect.** (I'd love to support more seamless, automatic redeems in the future!)\n### Tlapbot bot commands\nTlapbot has these basic commands:\n- `!help` sends a help string in the chat, explaining how tlapbot works.\n- `!points` shows a chatter how many points they have.\n- `!name_update` is a special debug command, to be used with the user's name displays wrong in the redeem dashboard. Normally, it shouldn't have to be used at all, as display names get updated automatically when the bot is running.\n\n(If you change the default prefix of `!` to something else, these commands will\nuse the new prefix instead.)\n\nTlapbot also automatically adds a command for each redeem in the redeems file.\n\n### Tlapbot dashboard\nTlapbot dashboard is a standalone page available at `/dashboard`, made to be easily viewable as an owncast external action. The Tlapbot dashboard shows all redeems and active counters.\n\nCounters are at the top, followed by a list of active milestones and their progress.\n\nTlapbot dashboard also shows the chatter's points balance when they open it as an external action.\n\n![Tlapbot dashboard](https://ak.kawen.space/media/f9e29757f02996f363f25226f04a97ac711a95831bfaba9dcfd42158e78831c4.png)\n\n*Tlapbot dashboard when viewed as an external action.*\n#### Redeem queue tab\nThe redeem queue shows a chronological list of note and list redeems with timestamps, the redeemer's username, and the note sent.\n![Redeem queue tab](https://ak.kawen.space/media/a1f44cc1a4011309a08361ca7f2ce24837d5daadd045910bf33fcd40b01d0a27.png)\n\n*Redeem queue tab.*\n#### Redeems help tab\nThe dashboard also has a \"Redeems help\" tab. It shows an explanation of redeem types,\nand lists all active redeems, along with their price, type and description.\n\n### Passive mode\nTlapbot can also be run in passive mode. In passive mode, no redeems will be available, and Tlapbot will not send any messages.\n\nHowever, it will still give points to viewers, and track username changes.\n\nThe Tlapbot dashboard will display a passive mode disclaimer instead of redeems.\n\n### Tlapbot redeems types\nTlapbot currently supports four different redeem types. Each type of a redeem\nworks slightly differently, and displays differently on the redeems dashboard.\n\nRedeems can also optionally be sorted into \"categories\" that can be turned on\nor off in the config file. This means that the redeems file can list redeems\nfor different types of streams, and you can turn them on or off. Examples on how\nto do that are listed later in the config file examples.\n#### List\nList redeems are basic redeems, most similar to the ones on Twitch.\n\nEvery time a chatter redeems a List redeem, the redeem gets added to the list of recent redeems with a timestamp, similar to how redeems on Twitch get added to the [Twitch redeem queue](https://help.twitch.tv/s/article/making-the-most-of-channel-points?language=en_US#manage).\n\nUnlike the Note redeems, chatters can't write messages to send along with their List redeems, so make sure the redeem makes sense on its own, like \"stop talking for one minute\", or \"drop your weapon\", etc.\n#### Note\nNote redeems are like List redeems, they get added to the list of recent redeems.\n\nUnlike the List redeems, chatters can add a message to their Note redeems, so this is the ideal type for open-ended redeems like \"choose what character I play as next\", \"choose what song to play next\", etc.\n#### Counter\nCounter is a unique redeem type, in that it doesn't show up in the list of recent redeems, and counters don't list the people who redeemed them. This redeem type is good for any rewards or incentives where the important thing isn't \"who redeemed it?\" but rather \"how many people redeemed it?\"\n\nInstead, the tlapbot dashboard keeps a number for each \"counter\", and each redeems adds +1 to it.\n\nCounter redeems can be used to gauge interest, tally up votes, or to keep track of how many emotes should be added to an OBS scene.\n\n#### Milestone\nMilestone redeems are long-term goals that are reset separately from other redeems.\nViewers donate variable amounts of points that add up together to fulfill the milestone goal.\n\nEach milestone has a goal, a number of points required to send, and the points from\nall users add together to progress and reach the goal.\n\nMilestones show as a progress bar on the dashboard.\n\nMilestone redeems can be used as long-term community challenges, to start streamer\nchallenges, decide new games to play, etc.\n\n\n## License \u0026 Contributions\nTlapbot as it currently is does not come with a license. If you're a content creator, streamer, vtuber, etc. I'll be happy to give you permission to use Tlapbot, or make changes that'd fit your stream.\n\nI didn't make Tlapbot available under a permissive or a free software license, as Owncast is also used by some religious groups, extremist individuals, and dubious corporations to self-host their streams, and I do not want for them to use the bot.\n## Setup\nTlapbot requires Python 3, probably a fairly recent version of it too. (My live instance runs on Python 3.9.2.)\n\nThe Python prerequisites for running tlapbot are the libraries `flask`,\n`requests` and `apscheduler`. If you follow the installation steps below,\nthey should automatically be installed if you don't have them.\n\nYou can also run Tlapbot in a [Python virtual environment](https://flask.palletsprojects.com/en/2.2.x/installation/#virtual-environments).\n### Install from git repo (as a folder)\n1. Clone the repository.\n2. Run `pip install -e .` in the root folder. This will install tlapbot\nas a package in editable more.\n3. Set the `FLASK_APP` environment variable.\n    ```bash\n    export FLASK_APP=tlapbot\n    ```\n4. Initialize the database:\n    ```bash\n    python -m flask init-db\n    ```\n5. Create an `instance/config.py` file and fill it in as needed.\nDefault values are included in `tlapbot/default_config.py`, and values in\n`config.py` overwrite them. (The database also lives in the instance folder\nby default.)\n\n    Tlapbot might not work if you don't overwrite these:\n    ```bash\n    SECRET_KEY # get one from running `python -c 'import secrets; print(secrets.token_hex())'`\n    OWNCAST_ACCESS_TOKEN # get one from owncast instance\n    OWNCAST_INSTANCE_URL # default points to localhost owncast on default port\n    ```\n6. OPTIONAL: Create an `instance/redeems.py` file and add your custom redeems.  \n  If you don't add a redeems file, the bot will initialize the default redeems from `tlapbot/default_redeems.py`.  \n  More details on how to write the config and redeems files are written later in the readme.\n7. If you've added any new counters or milestones, run `refresh-counters` or `refresh-milestones` commands to initialize them into the database.\n\nThis installation is fine both for just running Tlapbot as it is, but it also works as a dev setup if you want to make changes or contribute.\n\nUpdating should be as easy as `git pull`ing the new version.\nSometimes, if an update adds new database tables or columns, you will also need to\nrerun the `init-db` CLI command.\n## Owncast  configuration\nIn the Owncast web interface, navigate to the admin interface at `/admin`,\nand then go to Integrations.\n### Access Token\nIn the Access Tokens tab, generate an Access Token to put in\nthe config file in the instance folder. The bot needs both the \"send chat messages\" and \"perform administrative actions\"\npermissions, since getting the list of all connected chat users is an administrator-only\naction.\n### Webhook\nIn the webhooks tab, create a Webhook, and point it at your bot's URL with\n`/owncastWebhook` added.\n\nIn debug, this will be something like `localhost:5000/owncastWebhook`. If you're not running the debug Owncast instance and bot on the same machine,\nyou can use a tool like [ngrok](https://ngrok.com/)\nto redirect Owncast traffic to your `localhost`.\n### External Action\nIn External Actions, point the external action to your bot's URL with `/dashboard` added.\n\n**External Actions only work with https. Your server will need to support SSL and\nhttps connections for this part to work.**\n\nIn development, a `localhost` address will not work with External Actions, since it doesn't provide https.\nIf you use [ngrok](https://ngrok.com/) to redirect Owncast traffic to localhost,\nit will work because the ngrok connection is https.\n\n**External Action config example:**\n```\nURL: MyTlapbotServer.example/dashboard\nAction Title: Redeems Dashboard\n```\n#### Note about https and reverse proxying\nSince External Actions require a secure https connection (for the tlapbot dashboard to work), you will need to set up a reverse proxy for tlapbot on your server. I'm not including much information about it here, since some knowledge of the topic is required to set up Owncast itself.\n\nThe Owncast documentation about SSL and Reverse proxying is here: https://owncast.online/docs/sslproxies/\n\nIf your followed the [Owncast recommendation to use Caddy](https://owncast.online/docs/sslproxies/caddy/) you'd only need to include this in your caddyfile to make the tlapbot dashboard work:\n\n```\nMyTlapbotServer.example {\n        reverse_proxy localhost:8000\n}\n```\nthen MyTlapbotServer.example/owncastWebhook is the URL for webhooks,\nand MyTlapbotServer.example/dashboard is the URL for the dashboard.\n\n(And, obviously, you'd need to own the MyTlapbotServer.example domain, and have an A record pointing to your server's IP address.)\n## Running the bot\n### Running in debug:\nSet the FLASK_APP variable:\n```bash\nexport FLASK_APP=tlapbot\n```\nor in Powershell on Windows:\n```powershell\n$Env:FLASK_APP = \"tlapbot\"\n```\nRun the app (in debug mode):\n```bash\npython -m flask --debug run \n```\n### Running in production:\nSet the FLASK_APP variable:\n```bash\nexport FLASK_APP=tlapbot\n```\n\nUsing the flask debug server for running apps for non-development purposes is not recommended. Rather, you should be using a proper [Python WSGI server](https://flask.palletsprojects.com/en/2.2.x/deploying/).\nOn my own live owncast instance, I use gunicorn.\n\nInstall gunicorn (if you don't have it installed):\n```bash\npip install gunicorn\n```\nRun the app (with gunicorn):\n```bash\ngunicorn -w 1 'tlapbot:create_app()'\n```\n\nYou should also set `GUNICORN` in your `config.py` file to `True` to see Tlapbot logs in your gunicorn output. By default, gunicorn will only show `error` and `critical` warnings, but you can set the `--log-level` argument when running the app to set it to `warning`, `debug` or `info` too.\n\n```bash\ngunicorn -w 1 --log-level debug 'tlapbot:create_app()'\n```\n\n**⚠️WARNING:** Because of the way the scheduler is initialized in the project,\nI recommend running tlapbot with only one gunicorn worker. (`-w 1`)\n\nIf you use multiple workers, each worker sets up its own scheduler, and then users\nget given points by each worker. (So running the app with `-w 4` means users get four times as many points than listed in the config.)\n\nI'd like to fix this shortcoming of tlapbot at some point in the future (so that it can take advantage of extra workers), but for now it's broken like this.\n\n## CLI commands: Updating redeems, clearing the queue\nTlapbot comes with a few Click CLI commands. The commands let you clear out counters and the redeems dashboard.\n\n#### init-db\nThe init-db command initializes the database.\n\n**This command should only be run when first installing tlapbot,\nor when updating to a tlapbot version that changed the database schema.**\n#### clear-queue\nThe clear-queue command clears the redeem queue and resets all active counters to zero.\nYou should run this command if you're about to start a new stream, and want to start with empty counters and queue.\n\n```bash\npython -m flask clear-queue\n```\n\n**If you've changed the config, and want new/different counters to work, you should run the `refresh-counters` command first.**\n#### refresh-counters\nThis command deletes old counters that are no longer in the config file, and then adds all counters from the config file.\nYou should run this command every time you've added or removed counters from `redeems.py`.\n```bash\npython -m flask refresh-counters\n```\nThis command only changes counters, so if you want to clear the queue with list and note redeems too, you should run `clear-queue` after it, or run `clear-refresh` to do both actions together.\n\n#### clear-refresh\nDoes the same as `clear-queue` and `refresh-counters` together.\n```bash\npython -m flask clear-refresh\n```\nRun this if you're adding/removing counters, want to reset them to zero and want to clear all redeems as well.\n#### refresh-milestones\nDeletes old milestones and initializes new ones from the redeems file.\n```bash\npython -m flask refresh-milestones\n```\nRunning this command shouldn't reset progress on milestones that are already in the database\nand are still in the redeems file.\n#### reset-milestone\nResets progress on a milestone, but only if the milestone had been completed.\n```bash\npython -m flask reset-milestone milestone\n```\n#### hard-reset-milestone\nResets progress on a milestone, regardless of completion status.\n```bash\npython -m flask hard-reset-milestone milestone\n```\n## Configuration files\nConfiguration files should be in the instance folder. For folder installation of tlapbot,\nthat's `instance/` from the root of the Github repository.\n\nTake care not to replace `tlapbot/redeems.py` with your redeems config.\n`tlapbot/redeems.py` contains functions that handle redeems interactions with the db,\nand not the redeems config.\n### config.py\nValues you can include in `config.py` to change how the bot behaves.\n\n(`config.py` should be in the instance folder: `instance/config.py` for folder install.)\n#### Mandatory\nIncluding these values is mandatory if you want tlapbot to work.\n- `SECRET_KEY` is your secret key. Get one from running `python -c 'import secrets; print(secrets.token_hex())'`\n- `OWNCAST_ACCESS_TOKEN` is the owncast access token that owncast will use to get list of users in chat. Generate one in your owncast instance.\n- `OWNCAST_INSTANCE_URL` is the full URL of your owncast instance, like `\"http://MyTlapbotServer.example\"`\n#### Optional\nIncluding these values will overwrite their defaults from `/tlapbot/default_config.py`.\n- `POINTS_CYCLE_TIME` decides how often channel points are given to users in chat,\nin seconds. \n- `POINTS_AMOUNT_GIVEN` decides how many channel points users receive.\n- `PASSIVE` if `True`, sets Tlapbot into passive mode, where no redeems are available. The bot will still track username changes and give out points.\n- `LIST_REDEEMS` if `True`, all redeems will be listed after the `!help` command in chat.\nThis makes the !help output quite long, so it's `False` by default.\n- `GUNICORN` if `True`, sets logging to use gunicorn's logger. Only set this to True if you're using Gunicorn to run tlapbot.\n- `ACTIVE_CATEGORIES` can be an empty list `[]`, or a list of strings of activated categories (i.e. `[\"chatting\", \"singing\"]`). Redeems with a category included in the list will be active, redeems from other categories will not be active. Redeems with no category are always active.\n- `PREFIX` is a *single character string* that decides what character gets used as a prefix for tlapbot commands. (i.e. you can use `?` instead of `!`). Symbols are recommended. Prefix cannot be longer than one character.\n#### Example config:\nAn example to show what your config like could look like\n```python\nSECRET_KEY= # string with secret key would be here.\nOWNCAST_ACCESS_TOKEN=\"5AT0gbe9ZuzDunsBG0rcwfalQNTi3fvV70NPvvQHk3I=\"\nOWNCAST_INSTANCE_URL=\"http://MyTlapbotServer.example\"\nPOINTS_CYCLE_TIME=300\nLIST_REDEEMS=True\nACTIVE_CATEGORIES=[\"gaming\"]\n```\n### redeems.py\n`redeems.py` is a file where you define all your custom redeems. Tlapbot will work without it, but it will load a few default, generic redeems from `tlapbot/default_redeems.py`.\n\n(`redeems.py` should be in the instance folder: `instance/redeems.py` for folder install.)\n#### `default_redeems.py`:\n```python\nREDEEMS={\n    \"hydrate\": {\"price\": 60, \"type\": \"list\"},\n    \"lurk\": {\"price\": 1, \"type\": \"counter\", \"info\": \"Let us know you're going to lurk.\"},\n    \"react\": {\"price\": 200, \"type\": \"note\", \"info\": \"Attach link to a video for me to react to.\"},\n    \"request\": {\"price\": 100, \"type\": \"note\", \"info\": \"Request a level, gamemode, skin, etc.\"},\n    \"go_nap\": {\"goal\": 1000, \"type\": \"milestone\", \"info\": \"Streamer will go nap when the goal is reached.\"},\n    \"inactive\": {\"price\": 100, \"type\": \"note\", \"info\": \"Example redeem that is inactive by default\", \"category\": [\"inactive\"]}\n}\n```\n#### File format\n`redeems.py` is a config file with just a `REDEEMS` key, that assigns a dictionary of redeems to it.\nEach dictionary entry is a redeem, and the dictionary keys are strings that decide the chat command for the redeem.\nThe redeem names shouldn't have spaces in them.\nThe value is another dictionary that needs to have an entry for `\"type\"` and\nan entry for `\"price\"` for non-milestones or `\"goal\"` for milestones.\nOptionally, each redeem can also have `\"info\"` and `\"category\"` entries.\n\n- `\"price\"` value should be an integer that decides how many points the redeem will cost. Milestone redeems don't use the `\"price\"` value, they instead need to have a `\"goal\"`.\n- `\"goal\"` is a required field for milestone goals. It should be an integer, deciding the amount of points required to complete the milestone.\n- `\"type\"` value should be either `\"list\"`, `\"counter\"`, `\"note\"` or `\"milestone\"`. This decided the redeem's type, and whether it will show up as a counter at the top of the dashboard or as an entry in the \"recent redeems\" chart.\n- `\"info\"` value should be a string that describes what the command does. It's optional, but I recommend writing one for all `\"list\"`, `\"note\"` and `\"milestone\"` redeems (so that chatters know what they're redeeming and whether they should leave a note).\n- `\"category\"` is an optional list of strings, the categories the redeem is in.\nIf a category from the list is in `ACTIVE_CATEGORIES` from `config.py`,\nthen the redeem will be active. It will not be active if none of the categories\nare in `ACTIVE_CATEGORIES`. Redeems with no category are always active.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSleepyLili%2Ftlapbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSleepyLili%2Ftlapbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSleepyLili%2Ftlapbot/lists"}