Introduction

Botsu is a Discord bot to log immersion time for language learning. It is primarily intended for use with Japanese media. Some advantages of Botsu include:

Stats across mutliple servers.
Shortcuts for quickly logging based on media type. For example, you can log a YouTube video with /log video url:https://www.youtube.com/watch?v=oSMHn6Dbd2o.
Import and export functionality. See the Import and Export section for more details.
Fun stats like your most logged YouTube channel and guild leaderboards.

This guide goes over how to use Botsu as a user, guild admin, and for self-hosting.

Invite Botsu

You can invite a public instance of Botsu to your server with this link.

See some screenshots of the bot in action.

Support

Issues and feature requests can be submitted on the GitHub repository. You are encouraged to regularly export your data as a backup.

Screenshots

Usage

This section goes over how to use Botsu as a user. This page will provide a brief overview of the commands available to you.

Command Groups

Here are the primary command groups available to you:

/log - Log immersion time.
/history - View your immersion history.
/chart - View your immersion history as a chart.
/leaderboard - View the immersion leaderboard for your guild.
/config - Configure Botsu (user).
/guild-config - Configure Botsu (guild admin).
/export - Export your immersion data.
/import - Import your immersion data and manage imports.
/goals - Manage your immersion goals.

Before you start logging, it is recommended to set your timezone with /config timezone. This will ensure that your logs are recorded with the correct time in the case that you input a time manually.

To log immersion time, use the /log command and select the best subcommand for your media type. To manually enter all the required information, you can use the manual subcommand.

A summary of your log should be displayed after you log. View your full log history with /history.

Configuration

Use /config to configure Botsu for your user account.

Time Zone

Use /config timezone to set your timezone. Try typing the name of a major city in your timezone, such as New York, London, or Chicago.

Your timezone is used to parse times when provided manually. It will also be used to display dates in contexts where native Discord timestamps are not available, such as in embed titles or images.

Speed

Your speed for various media types can be configured with /config x-speed. For example, to set your speed for visual novels, use /config vn-speed.

These speeds use the following units:

vn-speed - Characters per minute.
book-speed - Pages per minute.
manga-speed - Pages per minute.

Daily Goal

Deprecated: Use /goal instead.

Set your daily goal in minutes. This will be used in duration charts to show your progress towards your goal over time.

Guild Configuration

Use /guild-config to configure Botsu for your guild. You must have the Manage Server permission to use this command.

Time Zone

Because not all users will have their timezone configured, you can set a default timezone for your guild with /guild-config timezone. This is not required, but may be useful if you have a large number of users in the same timezone.

See Configuration for more details on how timezones are used.

Logging

For basic logging, use /log manual. This will prompt you for the required information. You can also use the /log command with a subcommand for your media type. For example, /log video will prompt you for a video URL.

Logs

A log is simply a record of immersion time and associated information, such as a name, date, media type, media metadata, etc.

Although not all subcommands explicitly require a time as input, all other forms of logging will be converted to an estimated time internally. Thus, it is recommended to always provide a time when you know it, and to configure your speeds for more accurate estimates.

See the export section for more details on working with logs.

Default Speeds

Although it is recommended to configure your speeds, here are the default speeds used for each media type:

Media Type	Conversion Factor	Speed
`anime`	24	-
`book`	1/2	2 pages per minute
`manga`	1/2	2 pages per minute
`vn`	1/200	200 characters per minute

For anime, you should use the episode-length field to specify the length of the episode in minutes.

Duration Overrides

All commands provide alternative ways to specify the duration of a log.

Duration

You can explicitly specify the duration of a log with the duration field (book, manga, vn, and video). When using the duration field, you may use 0 for book, manga, and vn pages/characters to indicate that you did not record these values.

Episode Length

For anime, you should use the episode-length field to specify the length of each episode in minutes.

Reading Speed (One Time)

For VNs, you can also use the reading-speed or reading-speed-hourly fields to specify the reading speed. This will not affect your configured speed for VNs, however it will be used to suggest a speed when you do configure your speed.

Complex Durations

For videos, you have an additional option, duration-complex. This field allows you to specify the duration of the video in a more complex format. For example, you can specify the duration as 1m30s or as a slice of the video, such as 2m30s: (2 minutes and 30 seconds into the video until the end).

You can also use _ and t as special values to specify the sum of your previous logs on this video and the timestamp provided in the video URL (YouTube only). For example, if you have logged 1 minute and 30 seconds on a video, you can specify the duration as _: to log the remaining time on the video, or _:t to log the time from where you left off, until the time specified in the video URL.

Date and Time

By default, the current date and time will be used for your log. You can override this with the date field. Although multiple formats are supported, it is recommended to use the YYYY-MM-DD or YYYY-MM-DD HH:MM formats. To ensure the correct time is used, you should configure your timezone.

Import and Export

Botsu supports importing and exporting your immersion data. This is useful for backing up your data, or if you want to switch to a different instance of Botsu.

Note that both import and export are heavily rate limited.

Export

You can export your immersion data with /export. This will generate a GZip-compressed JSONL file containing all of your immersion logs. You can use this file to import your data into another instance of Botsu.

Import

You can import your immersion data with /import. This will prompt you to upload a JSONL file containing your immersion logs. You can generate this file with the /export command.

Unpreserved Fields

The following fields are not preserved when importing:

id
user_id
imported_at

IDs will only be used for error reporting. The imported_at field will be set to the current time when importing and user_id will be set to your user ID.

Botsu Files

The files generated by Botsu are in JSONL format and compressed with GZip. Each line is a JSON object representing a single log.

Log Format

Field	Type	Description
`id`	`int64`	The log ID.
`user_id`	`string`	The user ID (Discord snowflake).
`guild_id`	`string?`	The guild ID (Discord snowflake).
`media_type`	`string?`	The media type.
`primary_type`	`string`	The primary immersion type.
`duration`	`int64`	The duration of the log in nanoseconds.
`date`	`string`	The date of the log in RFC3339 format.
`name`	`string`	The name of the log.
`meta`	`any`	The metadata of the log.
`imported_at`	`string?`	The time the log was imported in RFC3339 format.
`deleted_at`	`string?`	The time the log was deleted in RFC3339 format.
`created_at`	`string`	The time the log was created in RFC3339 format.

For the primary type, only 'listening' and 'reading' are valid, and for the media type, only 'anime', 'book', 'manga', 'visual_novel', and 'video' are valid.

Example

{
  "id": 280,
  "user_id": "131118523085881345",
  "guild_id": null,
  "name": "【OnlyUp!】頂上へ行くまで終わらない！耐久【湊あくあ/ホロライブ】",
  "primary_type": "listening",
  "media_type": "video",
  "duration": 4293000429568,
  "date": "2023-06-24T15:00:00Z",
  "meta": {
    "channel_handle": "@MinatoAqua",
    "channel_id": "UC1opHUrw8rvnsadT-iGp7Cg",
    "channel_name": "Aqua Ch. 湊あくあ",
    "linked_channels": [],
    "linked_videos": [],
    "platform": "youtube",
    "thumbnail": "https://i.ytimg.com/vi/Ix5mVmXnpcs/maxresdefault.jpg?v=648f21f0",
    "url": "https://www.youtube.com/live/Ix5mVmXnpcs?feature=share&t=4293",
    "video_duration": 26561000000000,
    "video_id": "Ix5mVmXnpcs",
    "video_title": "【OnlyUp!】頂上へ行くまで終わらない！耐久【湊あくあ/ホロライブ】"
  },
  "created_at": "2023-11-30T02:48:31.069008Z",
  "deleted_at": null,
  "imported_at": null
}

Special Metadata

The following metadata fields are currently being used by Botsu or are reserved for future use and should be modified with caution:

channel_handle
video_id
thumbnail
url
vndb_id
anidb_id

Goals

View your goals using /goal list
Create goals using /goal create
Delete goals using /goal delete

Creating Goals

Goals are a target amount of minutes you want to reach in a given interval. Imports do not count towards goals.

To create a goal, you must specify a:

Name
Target (minutes)
Cron (pre-provided, or a cron expression)

You can optionally provide filters:

Primary Type
Media Type
Video Channels (comma separated uploader IDs, i.e. @HakuiKoyori,@MinatoAqua)
- May or may not work well with platforms other than YouTube

For a log to count towards your goal, it must satisfy all filters, not a single filter.

Hosting

This section will cover how to host your own instance of the bot.

Prerequisites

Go 1.21+
PostgreSQL

Installation

Use go install github.com/xoltia/UTD-JLA/cmd/botsu@latest to install the bot. Alternatively, view the releases page for pre-built binaries.

Database Setup

You will need to create a database and user for Botsu. The user should have full access to the database.

Configuration

By default, Botsu will look for a config.toml file in the current working directory. You can specify a different path with the --config flag.

The following is an example configuration file:

token = "XXXXXXXXX"
use_members_intent = true

[database]
user = "user"
password = "password"
host = "localhost"
port = 5432
database = "botsu"

You may also use environment variables for some configuration options. For example:

BOTSU_TOKEN
BOTSU_USE_MEMBERS_INTENT
BOTSU_CONNECTION_STRING

For all options, use botsu --help.

Data Sources

Botsu makes use of the following data sources:

They will be downloaded automatically when the bot starts, and will be updated periodically. This can be customized with the data_update_interval (nanoseconds) option in the configuration file. You can also skip the first update with the --skip-data-update flag (useful when you are frequently restarting the bot).

Running the Bot

Simply run botsu to start the bot. You can use botsu --help for more options. Note that the bot will automatically migrate the database on startup, and will also download data into the working directory.

Botsu Documentation