{"id":18133318,"url":"https://github.com/andreapavoni/ttfm_bot","last_synced_at":"2025-04-06T16:23:22.883Z","repository":{"id":64304343,"uuid":"466205734","full_name":"andreapavoni/ttfm_bot","owner":"andreapavoni","description":"A bot to bring some fun and utils on turntable.fm rooms","archived":false,"fork":false,"pushed_at":"2022-04-20T16:18:44.000Z","size":221,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-12T22:19:38.997Z","etag":null,"topics":["bot","go","golang","music","turntable-fm","turntablefm"],"latest_commit_sha":null,"homepage":"","language":"Go","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/andreapavoni.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}},"created_at":"2022-03-04T17:04:58.000Z","updated_at":"2023-03-10T12:11:56.000Z","dependencies_parsed_at":"2023-01-15T10:15:28.058Z","dependency_job_id":null,"html_url":"https://github.com/andreapavoni/ttfm_bot","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/andreapavoni%2Fttfm_bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreapavoni%2Fttfm_bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreapavoni%2Fttfm_bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreapavoni%2Fttfm_bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andreapavoni","download_url":"https://codeload.github.com/andreapavoni/ttfm_bot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247510038,"owners_count":20950367,"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","go","golang","music","turntable-fm","turntablefm"],"created_at":"2024-11-01T13:07:25.607Z","updated_at":"2025-04-06T16:23:22.858Z","avatar_url":"https://github.com/andreapavoni.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TTFM Bot\n\nA bot to bring some fun and utils on [turntable.fm](https://turntable.fm) rooms.\n\nIt's based on [alaingilbert/ttapi](https://github.com/alaingilbert/ttapi), a Golang library to build bots for Turntable.fm.\n\n## Features\n\nFeatures are inspired by [chillybot](https://github.com/jaycammarano/chillybot), with some differences here and there.\n\n- [x] Easy to install and use: download the binary for your platform and run it!\n- [x] Queue moderation\n  - [x] Auto-enabled when stage is full. Auto-disabled when stage has free slots and queue is empty.\n  - [ ] Max songs per DJ: how many songs before forwarding queue (eg: default 1 song)\n- [ ] Max songs per DJ when queue is disabled (0 means unlimited)\n  - [ ] Rest time for DJ who has reached max songs limit and has been escorted (eg: default 5 mins)\n- [x] Enforce song length limit (10 minutes by default)\n- [x] Show song stats when song finishes (only when enabled, and bot is moderator)\n- [x] Room greeting (only when enabled, and bot is moderator)\n  - [ ] Greeting message configurable\n- [x] Playlists\n  - [x] Add/Remove songs to your bot's playlists\n  - [x] Create/Remove playlists\n  - [x] Switch to another playlist\n- [x] Auto SNAG every song into current playlist\n- [x] Auto BOP\n- [x] Favorite rooms\n  - [x] Manage the list of favorite rooms\n  - [x] Join another room\n- [x] Auto DJ when there are `1` (default) or less djs\n- [x] GIF reactions\n  - [x] Use as many reactions you want\n  - [x] Add new reactions or new GIFs to an existing one\n  - [ ] Remove reactions or GIFs\n- [x] Escorting: a DJ can ask to be escorted immediately or after the current song has been played\n- [x] Logging\n  - [x] More details for some events/actions\n  - [x] Logs rotation\n- [ ] Configure a path where to write bot's saved data and logs\n- [ ] afk limit\n- [ ] afk audience limit(separate from afk limit, both can be toggled on and off)\n- [x] DJ stats (shown when dj goes off the stage)\n- [x] Print room rules (by command and/or when user joins)\n- [x] Room music current theme (default \"free play\")\n- [ ] Bot info (by command: print version, uptime, ...)\n- [x] custom prefix for commands (actual is `!`)\n- [x] kill switch command (kills/disconnects bot, useful when it turns unresponsive/misbehaved)\n\n## Installation and setup\n\n- Ensure to put the executable where you can write files (bot's saved data and logs)\n- Download [latest release](https://github.com/andreapavoni/ttfm_bot/releases/latest) binary for your platform (recommended) or source code (you'll need Go v1.18 or higher to build this project)\n- Set environment variables (see below) on the host you want to run the bot\n- Run with `./ttfm_bot` (better if you run it from `screen` or `tmux` session)\n\n### Configuration settings\n\nThese environment variables are required to make the bot work\n\n- `TTFM_API_AUTH`: the API key to connect to Turntables.fm\n- `TTFM_API_USER_ID`: User ID for the user\n- `TTFM_API_ROOM_ID`: ID of the room to join\n- `TTFM_MAIN_ADMIN_ID`: the ID of the user that will be the first and main admin\n\n## Commands\n\nEach command can be either issued on the chat room or by private message. Bot _might_ reply (or not) in the proper place.\n\nA command might require a certain user (and sometimes bot's) role to execute a command.\n\n### Command prefix customization\n\nBy default, the bot has `!` as command prefix (eg: `!command`). It's possible to customize it with `!cfg cmdprefix \u003cnew_prefix\u003e`. You can use whatever ASCII character or string.\n\n**NOTE:** when you change prefix, the new one will be the effective prefix to use to run commands. \n\n### Users\n\nUsers are the lowest role, basically anyone who isn't bot's admin or room moderator\n\n- `!props` let the current DJ know you're appreciating the song\n- `!help \u003ccmd\u003e` shows description of a command. Without `cmd` shows the list of commands available for the role of the user that issued the command\n- `!q [add|rm]` add or remove yourself from the queue. Without args shows the current line in queue\n- `!qadd` adds user into queue\n- `!qrm` removes user from queue\n- `!r \u003creaction\u003e` shows a funny gif reaction. Without `reaction` shows available ones\n- `!r add \u003creaction\u003e \u003curl\u003e` shows a funny gif reaction. Without `reaction` shows available ones\n\n### DJs\n\n- `!escortme` will escort the DJ off the stage after they played the last song. Requires the bot to be a moderator in the current room.\n\n### Bot admins\n\nAdmins are users which can run commands on bot\n\n- `!dj` tells the bot to jump on the stage and starts playing songs, or jump off if it's already djing\n- `!snag` tells the bot to snag the current playing song\n- `!bop` tells the bot to bop for the current playing song\n- `!fan \u003cuser_name\u003e` and `!unfan \u003cuser_name\u003e` respectively fan/unfan the specified `user_name`\n- `!p [[add | rm | switch] \u003cplaylist_name\u003e | list | rmsong]` handles playlists\n- `!say \u003csomething\u003e` say something in the room\n- `!cfg \u003cconfig_key\u003e [\u003cconfig_value\u003e]` sets config key and value. Without `config_value`, it replies with current configuration for `\u003cconfig_key\u003e`\n- `!room [list | \u003csub_command\u003e \u003croom_slug\u003e]` handles favorite rooms\n- `!die` kills the bot (useful if/when it becomes unresponsive due to some bug)\n- `!admin [add | remove \u003cuser_name\u003e]`. Without args shows the current admins\n\nThese ones require the bot to be moderator of the room to be executed\n\n- `!skip` tells the bot to skip the current playing song\n- `!escort \u003cuser_name\u003e` tells the bot to escort the specified `user_name` off the stage\n- `!boot \u003cuser_name\u003e` tells the bot to kick the specified `user_name` off the room\n\n### Upgrading to newer versions\n\nExcept if it has been specified differently in a new release notes, it should suffice to:\n\n- Download the new release\n- Stop the currently running bot\n- Replace old binary with the one from the new release\n- Restart the bot\n\n\n\n## Credits\n\n- [turntable.fm](https://turntable.fm) for the awesome platform\n- [alaingilbert/ttapi](https://github.com/alaingilbert/ttapi) because without it I should have to hack a lot more to get here\n- [nugget/cowgod](https://github.com/nugget/cowgod) another Golang bot for Turntable.fm, I did a look at it to learn\n- [jaycammarano/chillybot](https://github.com/jaycammarano/chillybot) a JS bot, maybe the most used, I got some inspiration for features from there\n- [I ❤️ The 80's](https://turntable.fm/i_the_80s) the best room I've found, full of friendly people\n\n## Rooms\n\nAn 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.\n\n- [Disco Clubbing](https://turntable.fm/disco_clubbing) (its main room, here it's moderator)\n- [I ❤️ The 80's](https://turntable.fm/i_the_80s)\n- [Aunt Jackie](https://turntable.fm/aunt_jackie)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandreapavoni%2Fttfm_bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandreapavoni%2Fttfm_bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandreapavoni%2Fttfm_bot/lists"}