kameloso 2.0.0
IRC bot
To use this package, run the following command in your project's root directory:
Manual usage
Put the following dependency into your project's dependences section:
kameloso
kameloso idles in your channels and listens to commands and events, like bots generally do.
Current functionality includes:
- chat monitoring in bedazzling colours like it's the 90s
- automatic mode sets (e.g. auto
+o
on join) - logs
- reporting titles of pasted URLs
- sed-replacement of messages (
s/this/that/
substitution) - saving notes to offline users that get played back when they come online
- channel polls
- works on Twitch with some common Twitch bot features
- more random stuff and gimmicks
All of the above are plugins and can be runtime-disabled or compiled out. It is modular and easily extensible. A skeletal Hello World plugin is 20 lines of code.
Testing is primarily done on freenode and on Twitch servers, so support and coverage is best there.
Please report bugs. Unreported bugs can only be fixed by accident.
tl;dr
-n --nickname Nickname
-s --server Server address [irc.freenode.net]
-P --port Server port [6667]
-A --account Services account name
-p --password Services account password
--admins Administrators' services accounts, comma-separated
-H --homeChannels Home channels to operate in, comma-separated
-C --guestChannels Non-home channels to idle in, comma-separated
--monochrome Use monochrome output
-w --save Write configuration to file
Pre-compiled binaries for Windows and Linux can be found under releases.
$ dub run kameloso -- --server irc.freenode.net --guestChannels "#d"
# alternatively
$ git clone https://github.com/zorael/kameloso.git
$ cd kameloso
$ dub build
$ ./kameloso --server irc.freenode.net --guestChannels "#d"
If there's anyone talking it should show up on your screen.
Table of contents
- Getting started
- Prerequisites
- Downloading
- Compiling
- How to use
- Configuration
- Example use
- Twitch
- Further help
- Known issues
- Windows
- Roadmap
- Built with
- License
- Acknowledgements
Getting started
Grab a pre-compiled binary from under releases; alternatively, download the source and compile it yourself.
Prerequisites
There are three D compilers available; see here for an overview. You need one based on D version 2.084 or later (January 2019).
kameloso can be built using the reference compiler dmd, which compiles very fast; and the LLVM-based ldc, which is slower at compiling but produces faster code. The stable release of the GCC-based gdc is currently based on version 2.076 and is thus too old to be used.
The package manager dub is used to facilitate compilation and dependency management. On Windows it comes bundled in the compiler archive, while on Linux it may need to be installed separately. Refer to your repositories.
Downloading
$ git clone https://github.com/zorael/kameloso.git
It can also be downloaded as a .zip
archive.
Compiling
$ dub build
This will compile the bot in the default debug mode, which adds some extra code and debugging symbols. You can automatically omit these and add some optimisations by building it in release mode with dub build -b release
. Mind that build times will increase accordingly. Refer to the output of dub build --help
for more build types.
Build configurations
There are several configurations in which the bot may be built.
application
, base configurationtwitch
, additionally includes Twitch chat support and the Twitch streamer plugindev
, all-inclusive development build equalling everything available, including things like more detailed error messages
All configurations come in a -lowmem
variant (e.g. application-lowmem
, twitch-lowmem
, ...) that lowers compilation memory at the cost of increasing compilation time, but so far they only work with ldc. (bug #20699)
List configurations with dub build --print-configs
. You can specify which to compile with the -c
switch. Not supplying one will make it build the default application
configuration.
$ dub build -c twitch
If you want to customise your own build to only compile the plugins you want to use, see the larger
versions
lists indub.sdl
. Simply add or delete a character from the line corresponding to the plugin(s) you want to omit (thus invalidating the version identifier). Mind that disabling any of the "service" plugins may break the bot in subtle ways.
How to use
Configuration
The bot ideally wants the account name of one or more administrators of the bot, and/or one or more home channels to operate in. Without either it's just a read-only log bot, which is also fine. To define these you can either specify them on the command line, with flags listed by calling the program with --help
, or generate a configuration file and input them there.
$ ./kameloso --save
A new kameloso.conf
will be created in a directory dependent on your platform.
- Linux and other Posix:
~/.config/kameloso
(alternatively where$XDG_CONFIG_HOME
points) - Windows:
%APPDATA%\kameloso
- macOS:
$HOME/Library/Application Support/kameloso
Open the file in a normal text editor. If you have your system file associations set up to open *.conf
files in such, you can pass --gedit
to attempt to open it in a graphical editor, or --edit
to open it in your default terminal one (as defined in the $EDITOR
environment variable).
Command-line arguments
Settings provided at the command line override any such already defined in your configuration file. If you specify some and also add --save
, it will apply the changes to your file in-place.
$ ./kameloso \
--server irc.freenode.net \
--nickname "kameloso" \
--admins "you,friend" \
--homeChannels "#mychannel,#elsewhere" \
--guestChannels "#d,##networking" \
--save
[12:34:56] Configuration written to /home/user/.config/kameloso/kameloso.conf
Settings not specified at invocations of --save
keep their values. Mind however that the file is parsed and rewritten, so any comments and/or invalid entries in it will be silently removed.
Display settings
If you have a bright terminal background, text may be difficult to read, depending on your terminal emulator. If so, pass the --bright
argument, and/or modify the configuration file; brightTerminal
under [Core]
. The bot uses the full range of 8-colour ANSI, so if one or more colours are too dark or bright even with the right brightTerminal
setting, please refer to your terminal appearance settings. Colouring might not work well with greyish theming.
An alternative is to disable colours entirely with --monochrome
.
Other files
More server-specific resource files will be created the first time you connect to a server. These include users.json
, in which you whitelist which accounts get to access the bot's features on a per-channel basis. Where these are stored also depends on platform; in the case of macOS and Windows they will be put in server-split subdirectories of the same directory as the configuration file, listed above. On Linux and other Posix, under ~/.local/share/kameloso
(or wherever $XDG_DATA_HOME
points to).
Example use
you joined #channel
kameloso sets mode +o you
you | I am a fish
you | s/fish/snek/
kameloso | you | I am a snek
you | !quote kameloso I am a snek
kameloso | Quote saved. (1 on record)
you | !quote kameloso
kameloso | kameloso | I am a snek
you | !seen MrOffline
kameloso | I last saw MrOffline 1 hour and 34 minutes ago.
you | !note MrOffline About the thing you mentioned, yeah no
kameloso | Note added.
MrOffline joined #channel
kameloso | MrOffline! you left note 28 minutes ago: About the thing you mentioned, yeah no
you | !operator add bob
kameloso | Added BOB as an operator in #channel.
you | !whitelist add alice
kameloso | Added Alice as a whitelisted user in #channel.
you | !blacklist del steve
kameloso | Removed steve as a blacklisted user in #channel.
you | !automode add ray +o
kameloso | Automode modified! ray on #channel: +o
ray joined #channel
kameloso sets mode +o ray
you | !poll 60 snek snik
kameloso | Voting commenced! Please place your vote for one of: snik, snek (60 seconds)
BOB | snek
Alice | snek
ray | snik
kameloso | Voting complete, results:
kameloso | snek : 2 (66.6%)
kameloso | snik : 1 (33.3%)
you | https://github.com/zorael/kameloso
kameloso | [github.com] GitHub - zorael/kameloso: IRC bot
you | https://youtu.be/ykj3Kpm3O0g
kameloso | [youtube.com] Uti Vår Hage - Kamelåså (HD) (uploaded by Prebstaroni)
<context: playing a video game>
you | !counter add deaths
kameloso | Counter deaths added! Access it with !deaths.
you | !deaths+
kameloso | deaths +1! Current count: 1
you | !deaths+
kameloso | deaths +1! Current count: 2
you | !deaths
kameloso | Current deaths count: 2
you | !deaths=0
kameloso | deaths count assigned to 0!
you | !stopwatch start
kameloso | Stopwatch started!
you | !stopwatch
kameloso | Elapsed time: 18 mins 42 secs
you | !stopwatch stop
kameloso | Stopwatch stopped after 48 minutes 10 secs.
Online help and commands
Use the !help
command for a summary of available bot commands, and !help [plugin] [command]
for a brief description of a specific one. The shorthand !help !command
also works.
The command prefix (here !
) is configurable; refer to your generated configuration file. Common alternatives are .
and ~
, making it .note
and ~quote
respectively.
[Core]
prefix "!"
It can technically be any string and not just one character. It may include spaces if enclosed within quotes, like "please "
(making it please note
, please quote
, ...). Additionally, prefixing commands with the bot's nickname also works, as in kameloso: seen MrOffline
. This is to be able to disambiguate between several bots in the same channel. Additionally, some administrative commands only work when called this way.
Except nothing happens
Before allowing anyone to trigger any restricted functionality, the bot will query the server for what services account the accessing user is logged onto. For full administrative privileges you will need to be logged in with an account listed in the admins
field in the configuration file, while other users may be defined in your users.json
file. If a user is not logged onto services it is considered as not being uniquely identifiable.
In the case of hostmasks mode, the above still applies but "accounts" are inferred from hostmasks. See the Admin plugin
!hostmask
command (and thehostmasks.json
file) for how to map hostmasks to would-be accounts. Hostmasks are a weaker solution to user identification but not all servers may offer services. See the wiki entry on hostmasks for more information.
Twitch
To connect to Twitch servers you must first build a configuration that includes support for it, which is currently either twitch
or dev
.
You must also supply an OAuth token pass (not password). These authorisation tokens are unique to your user paired with an application. As such, you need a new one for each and every program you want to access Twitch with.
Run the bot with --set twitchbot.keygen
to start the captive process of generating one. It will open a browser window, in which you are asked to log onto Twitch on Twitch's own servers. Verify this by checking the page address; it should end with .twitch.tv
, with the little lock symbol showing the connection is secure.
Note: At no point is the bot privy to your login credentials! The logging-in is wholly done on Twitch's own servers, and no information is sent to any third parties. The code that deals with this is open for audit;
generateKey
intwitchbot/api.d
.
After entering your login and password and clicking Authorize, you will be redirected to an empty "this site can't be reached" page. Copy the URL address of it and paste it into the terminal, when asked. It will parse the address, extract your authorisation token, and offer to save it to your configuration file.
If you prefer to generate the token manually, here is the URL you need to follow. The only thing the generation process does is open it for you, and help with saving the end key to disk.
https://id.twitch.tv/oauth2/authorize?response_type=token&client_id=tjyryd2ojnqr8a51ml19kn1yi2n0v1&redirect_uri=http://localhost&scope=bits:read+channel:edit:commercial+channel:read:subscriptions+user:edit+user:edit:broadcast+channel_editor+user_blocks_edit+user_blocks_read+user_follows_edit+channel:moderate+chat:edit+chat:read+whispers:edit+whispers:read
Caveats
Most of the bot's features will work on Twitch. The Automode plugin is an exception (as modes are not really applicable on Twitch), and it will auto-disable itself appropriately.
That said, in many ways Twitch chat does not behave as a full IRC server. Most common IRC commands go unrecognised. Joins and parts are not always advertised, and when they are they come in delayed batches and cannot be relied upon. You can also only join channels for which a corresponding Twitch user account exists.
Example configuration
[IRCClient]
nickname botaccount
user ignored
realName likewise
[IRCBot]
#account
#password
pass personaloauthauthorisationtoken
admins mainaccount
homeChannels #mainaccount,#botaccount
guestChannels #streamer1,#streamer2,#streamer3
[IRCServer]
address irc.chat.twitch.tv
port 6667
The Twitch SSL port is 6697 (or 443).
See the wiki page on Twitch for more information.
Streamer assistant bot
The streamer bot is enabled by default when built, and can be disabled in the configuration file under the [TwitchBot]
section. If the section doesn't exist, ensure that you have built a configuration with Twitch support, then regenerate the file with --save
. Even if enabled it disables itself on non-Twitch servers.
$ ./kameloso --set twitchbot.enabled=false --save
Properly enabled and assuming a prefix of !
, commands to test are:
!enable
,!disable
!start
,!uptime
,!stop
!phrase
!timer
!permit
!followage
...alongside !operator
, !whitelist
, !blacklist
, !oneliner
, !poll
, !counter
, !stopwatch
, and other non-Twitch-specific commands.
Note: dot
.
and slash/
prefixes will not work on Twitch.
Please make the bot a moderator to prevent its messages from being as aggressively rate-limited.
Further help
For more information and help, first see the wiki.
If you still can't find what you're looking for, or if you have suggestions on how to improve the bot, you can...
- ...pop by the
#kameloso
channel on freenode - ...start a thread under Discussions
- ...file a GitHub issue
Known issues
Compiling in a non-debug
build mode may fail (bug #18026). Try --build-mode=singleFile
, which compiles one file at a time and as such lowers memory requirements, but drastically increases build times.
Windows
If SSL doesn't work at all, you may simply be missing the required libraries. Download and install OpenSSL "Light" from here, and opt to install to system directories when asked.
Even with SSL seemingly properly set up you may see errors of "Peer certificates cannot be authenticated with given CA certificates". If this happens, download this cacert.pem
file, place it somewhere reasonable, and edit your configuration file to point to it; caBundleFile
under [Connection]
.
Roadmap
- pipedream zero: no compiler segfaults (#18026, #20562)
- pipedream: DCC
- non-blocking FIFO
- more pairs of eyes
Built with
License
This project is licensed under the MIT license - see the LICENSE file for details.
Acknowledgements
- 2.0.0 released 3 years ago
- zorael/kameloso
- www.github.com/zorael/kameloso
- MIT
- Copyright © 2021, JR
- Authors:
- Dependencies:
- dialect, requests, arsd-official:dom, lu
- Versions:
-
3.14.159 2024-Jan-27 3.13.0 2023-Sep-26 3.12.1 2023-Sep-06 3.12.0 2023-Aug-25 3.11.1 2023-Jul-21 - Download Stats:
-
-
0 downloads today
-
0 downloads this week
-
0 downloads this month
-
177 downloads total
-
- Score:
- 1.7
- Short URL:
- kameloso.dub.pm