diff --git a/README.md b/README.md index 40342f3..c668e7f 100644 --- a/README.md +++ b/README.md @@ -2,24 +2,15 @@ A python Discord bot for controlling an instance of [Transmission](https://transmissionbt.com), the torrent client, using the [transmissionrpc](https://pythonhosted.org/transmissionrpc/) python library. This bot is built on [kkrypt0nn's bot template](https://github.com/kkrypt0nn/Python-Discord-Bot-Template) and adapted from [leighmacdonald's transmission scripts](https://github.com/leighmacdonald/transmission_scripts). -## Features -* Completely self-contained: Get the python dependencies, configure a single python file, and run -* Complete management of transfers: - * `t/add URL` Add new torrent transfers via **URL to torrent file** or **magnet link** - * `t/list [OPTIONS]` List existing transfers with filtering, sorting, and searching transfer names with regular expressions or transfer ID(s) - * `t/modify [OPTIONS]` Modify (pause, resume, remove, remove and delete, or verify data) transfer(s) specified using `list`'s options - * `t/summary` Print simple summary of all transfers -* User-friendly and attractive interface - * In-channel documentation using `t/help [COMMAND]` - * Use of `embeds` where appropriate - * Uses reactions in lieu of text input where appropriate - * Output automatically formatted to look good on desktop/mobile clients - * Can toggle override using `t/compact` - * Auto-update output for `summary` and `list` commands - * Simultaneous auto-update output messages supported - * An auto-update output message can be reprinted to the bottom of the channel by clicking its "πŸ–¨" reaction -* User whitelist and blacklist to control access -* Channel list to limit access to specified channel(s) +## Features overview +* [Interact via text channels or DMs](#channelDM) +* [Add transfers](#add) +* [Modify existing transfers](#modify) +* [Check transfer status](#status) (with optional realtime updating of output) +* [Notifications for transfer state changes](#notifications) +* [Pretty output and highly configurable](#pretty) +* [Easy setup](#setup) +* [`t/help` for usage information](#help) ## Example images * Transfer summary (and symbol legend) @@ -62,28 +53,93 @@ This bot is built on [kkrypt0nn's bot template](https://github.com/kkrypt0nn/Pyt * Optionally disable logging by setting the log level to `logger.CRITICAL` which isn't used anywhere 3. Run with `python3 /path/to/TransmissionBot/bot.py` and enjoy! +## Detailed features + +### Interact via text channels or DMs +* Use commands with `t/` prefix in text channel or via DM +* Via DM only, use full command name without prefix (*e.g.* `summary`) + +### Add transfers +* Simply drag a `.torrent` file into the channel on discord and it will be added and started +* Alternatively, enter a transfer magnet link or an address to a `.torrent` file using `t/add MAGNET_OR_URL` + +### Modify existing transfers +* `t/modify` to pause, resume, verify, remove, or remove and delete one or more transfers +* Specify transfers using sequence of ids (*e.g.* 1,3,5-8), searching transfer names with regular expressions, or filtering by transfer properties (*e.g.* downloading, finished, etc.) + * Limit number of matches using `-N` option +* Option to protext transfers using private trackers from removal +* `t/help modify` for more info + +### Check transfer status + +#### List one or more transfers with pertinent information +* `t/list` +* Specify transfers using sequence of ids[1](#idseq), searching transfer names with regular expressions, or filtering by transfer properties (e.g. downloading, finished, etc.) +* Click πŸ”„ reaction to update output in realtime (in-channel only, not through DM) +* `t/help list` for more info + +#### Print transfer summary +* `t/summary` +* Includes overall transfer rates, amount of data transferred (based on current set of transfers), transfer counts for different states (*e.g.* downloading, finished, etc.), and list of highest seed-ratio transfers (configurable) +* Click πŸ”„ reaction to update output in realtime (in-channel only, not through DM) +* Use other reactions to print filtered lists of transfers +* Print symbol `t/legend` + +### Notifications for transfer state changes +* Print notifications regarding transfer state changes in a text channel and through DMs +* Users are notified through DM about transfers they added +* Can opt in to DM notifications for other transfers by reacting with πŸ”” to `t/list` message or in-channel notifications +* Opt out of DM notifications + * Opt out of individual DM notifications by reacting with πŸ”• to `t/list` message or either in-channel or DM notifications + * Users opt out of all DM notifications using `t/notifications` through DM + * Owners can disable in-channel notifications using `t/notifications` in a listened channel +* Customize what state changes are included in the configuration + +### Pretty output and highly configurable +* Output automatically formatted for display on desktop or mobile discord clients (in-channel only, not through DM) +* Use of Embeds and unicode symbols where appropriate. +* Remove reactions from messages when no longer necessary for prettier scroll-back (in-channel only, not through DM) +* Configure user access using whitelist, blacklist and owner list +* Protect transfers using private trackers from removal +* Set realtime update and notification frequency +* Set realtime update timeout +* Listen for commands on all or only specified text channels +* Toggle in-channel or DM interaction separately, or the notification system entirely +* Set which transfer state changes are reported in notifications with separate settings for in-channel notifications, notifications sent to users that added transfers, and users that opt into DM notifications +* Toggle dry-run to control whether transfer modifications are actually carried out + +### `t/help` for usage information +* Print help for some commands using `t/help COMMAND_NAME` (*e.g.* `t/help list`) + +### Easy setup +0. Setup bot on Discord developer portal +1. Clone repository `git clone https://github.com/twilsonco/TransmissionBot` +2. Configure `CONFIG` in `bot.py` to your liking +3. Run bot `python3 /path/to/bot.py` + * Bot will create `config.json`, after which you can remove or comment the definition of `CONFIG` in `bot.py` to make future updates easier + ## To-do (~~implemented~~) * Command to print detailed information for transfer(s) * Complete connection information * Lists of transfer files, peers, trackers * ~~Add ability to verify transfer data~~ * When searching by name, update regex to include potential accented characters, eg `pokemon` would also match `pokΓ©mon` -* Specify number of transfers to show when using `list` or `modify` +* ~~Specify number of transfers to show when using `list` or `modify`~~ * Combine the `list` and `modify` commands in the code, with a simple parameter to specify whether or not modification is allowed * Currently, searching by name is done with case-insensitive regex. Update to that if a user includes upper case characters, case-sensitive search is performed * ~~Add recurring list option. Ie every five seconds replace `list` output with fresh output. This would be done by reacting to a "repeat" emoji to initiate repetition of the current search~~ (also did this for `summary`) -* ~~Add additional filtering options: stalled, error, non-zero up/down rate.~~ +* ~~Add additional filtering options: stalled, error, non-zero up/down rate. * Add shorthand for filtering options (downloading/seeding/stalled/paused become d/s/i/p etc., that's i for "idle" since s is for seeding) * Add a `top` command that'sessentially a combination of the up/down rate filter and the repeating output features * Ability to refine `list` output with filter or sort using reactions; ie click a filter or sort reaction which triggers another message with additional reactions to click to apply the extra filters or sort * Ability to specify which files to include in download (we'll see about that; sounds clunky but maybe using file ID specifiers *e.g.* `1,3-5,8`) -* Notifications for when a transfer finishes/stalls/errors - * via DM to the user that added the transfer - * or by posting to the channel from which a transfer was added - * Let other users opt to receive notifications for transfers they *didn't* add +* ~~Notifications for when a transfer finishes/stalls/errors + * ~~via DM to the user that added the transfer + * ~~or by posting to the channel from which a transfer was added + * ~~Let other users opt to receive notifications for transfers they *didn't* add * Post-download file management (*never going to happen...*) * Compress files (encrypted) and make available for direct download from server via download link posted to channel or DM'd to user -* Use JSON config file so that updating is non-destructive +* ~~Use JSON config file so that updating is non-destructive * Add `set` command so owners can edit configuration through Discord * ~~Add a toggle for minimalised output for better display on mobile devices. Toggle using `t/compact` as standalone command or by clicking a πŸ“± reaction. Store as global variable so all commands output can be affected.~~