diff --git a/README.md b/README.md index b8a2ea6..54427c0 100644 --- a/README.md +++ b/README.md @@ -4,17 +4,52 @@ A bot to bring some fun and utils on [turntable.fm](https://turntable.fm) rooms. It's based on [alaingilbert/ttapi](https://github.com/alaingilbert/ttapi), a Golang library to build bots for Turntable.fm. -## Installation and setup +## Features + +Features are inspired by [chillybot](https://github.com/jaycammarano/chillybot), with some differences here and there. + +- [x] Easy to install and use: download the binary for your platform and run it! +- [x] Queue moderation + - [x] Auto-enabled when stage is full. Auto-disabled when stage has free slots and queue is empty. + - [ ] Max songs per DJ: how many songs before forwarding queue (eg: default 1 song) +- [ ] Max songs per DJ when queue is disabled (0 means unlimited) + - [ ] Rest time for DJ who has reached max songs limit and has been escorted (eg: default 5 mins) +- [x] Enforce song length limit (10 minutes by default) +- [x] Show song stats when song finishes (only when enabled, and bot is moderator) +- [ ] Show DJ stats when DJ leaves the stage (only when enabled, and bot is moderator) +- [x] Room greeting (only when enabled, and bot is moderator) + - [ ] Greeting message configurable +- [x] Playlists + - [x] Add/Remove songs to your bots playlist + - [x] Create/Remove playlists + - [x] Switch to another playlist +- [x] Auto SNAG every song into current playlist +- [x] Auto BOP +- [x] Favorite rooms + - [x] Manage the list of favorite rooms + - [x] Join another room +- [x] Auto DJ when there are `1` or less djs +- [x] GIF reactions + - [x] Use as many reactions you want + - [x] Add new reactions or new GIFs to an existing one + - [ ] Remove reactions or GIFs +- [x] Escorting: a DJ can ask to be escorted immediately or after the current song has been played +- [x] Logging + - [ ] More details for some events/actions + - [x] Logs rotation +- [ ] afk limit +- [ ] afk audience limit(separate from afk limit, both can be toggled on and off) -**IMPORTANT: Requires Go >= 1.18beta1 because it uses generics!** +## Installation and setup -- Install the package with `go install https://github.com/andreapavoni/ttfm_bot/` +- Esnure to have at least a directory where you can write files (bot saved data, logs) +- Download binary (recommended) or source code (requires Go v1.18 or higher) of the [latest release](https://github.com/andreapavoni/ttfm_bot/releases/latest) - Set environment variables (see below) on the host you want to run the bot -- Run with `$GOPATH/bin/ttfm_bot` +- Run with `./ttfm_bot` ### Configuration settings -#### Mandatory +These environment variables are required to make the bot work - `TTFM_API_AUTH`: the API key to connect to Turntables.fm - `TTFM_API_USER_ID`: User ID for the user @@ -25,13 +60,13 @@ It's based on [alaingilbert/ttapi](https://github.com/alaingilbert/ttapi), a Gol **NOTES:** -- Each command can be either issued on the chat room or by private message. -- A command might require a certain user role to execute a command. -- commands which accept `on` or `off` to enable/disable some feature, can be called without arguments to get the current status +- Each command can be either issued on the chat room or by private message. Bot _might_ reply (or not) in the proper place. +- A command might require a certain user (and sometimes bot's) role to execute a command. +- Commands which accept `on` or `off` to enable/disable some feature, can be called without arguments to get the current status ### Users -Users are the lowest role, basically are listeners or want to DJ +Users are the lowest role, basically anyone who isn't bot's admin or room moderator - `!props` let the current DJ know you're appreciating the song - `!help ` shows description of a command. Without `cmd` shows the list of commands available for the role of the user that issued the command @@ -46,14 +81,14 @@ Users are the lowest role, basically are listeners or want to DJ ### Bot admins -Admins are users which were previously configured on the bot to run commands on it. +Admins are users which can run commands on bot - `!dj` tells the bot to jump on the stage and starts playing songs, or jump off if it's already djing - `!autodj [on|off]` enables/disables autodj mode. Without `on` or `off` replies with current status - `!snag` tells the bot to snag the current playing song - `!autosnag [on|off]` enables/disables automatic snag. Without `on` or `off` replies with current status - `!bop` tells the bot to bop for the current playing song -- `!autobop [on|off]` enables/disables automatic bop. Without args replies with current status +- `!autobop [on|off]` enables/disables automatic bop. Without Without `on` or `off` replies with current status - `!fan ` and `!unfan ` respectively fan/unfan the specified `user_name` - `!padd ` creates a new playlist - `!pdel ` deletes a playlist @@ -64,9 +99,7 @@ Admins are users which were previously configured on the bot to run commands on - `!cfg []` sets config key and value. Without `config_value`, it replies with current configuration for `` - `!room [list | ]` handles favorite rooms -### Moderators - -Bot can obey to moderators commands, however it depends by the kind of command issued and by the bot's role in the current room. +These ones require the bot to be moderator of the room to be executed - `!skip` tells the bot to skip the current playing song - `!escort ` tells the bot to escort the specified `user_name` off the stage @@ -77,9 +110,13 @@ Bot can obey to moderators commands, however it depends by the kind of command i - [turntable.fm](https://turntable.fm) for the awesome platform - [alaingilbert/ttapi](https://github.com/alaingilbert/ttapi) because without it I should have to hack a lot more to get here - [nugget/cowgod](https://github.com/nugget/cowgod) another Golang bot for Turntable.fm, I did a look at it to learn +- [jaycammarano/chillybot](https://github.com/jaycammarano/chillybot) +- [I ❤️ The 80's](https://turntable.fm/i_the_80s) the best room I've found, full of friendly people -### Rooms +## Rooms + +An instance of this bot is called `Mrs.Beats` and can be found in one of these channells. Author username is `pavonz` both on turntable.fm and on Discord servers. -- [Disco Clubbing](https://turntable.fm/disco_clubbing) (here you can find this bot running) -- [Aunt Jackie](https://turntable.fm/aunt_jackie) - [I ❤️ The 80's](https://turntable.fm/i_the_80s) +- [Disco Clubbing](https://turntable.fm/disco_clubbing) (here is moderator) +- [Aunt Jackie](https://turntable.fm/aunt_jackie)