ankibot

A Twitch chat bot that runs Anki flashcard quiz rounds for your viewers. Chat members type answers directly in chat to earn points. Includes an optional OBS browser overlay that shows the card and reveals the answer at the end of each round.

Designed for Japanese vocabulary decks but works with any Anki deck.

How it works

1. A viewer (or you) types !ajatt in chat
2. The bot pulls a random card from Anki and posts the front of the card in chat (and on the overlay)
3. Viewers have a configurable time window to type the reading and/or meaning in chat
4. When time runs out, the bot reveals the answer and awards points to everyone who got it right
5. Points are tracked locally across sessions

Prerequisites

• Node.js v18 or later
• Anki desktop app, running while the bot is active
• AnkiConnect add-on installed in Anki (add-on code: 2055492159)
• Some decks to pull from
• A Twitch account to use as the bot (can be your main account or a dedicated bot account)

Setup

1. Install dependencies

npm install

2. Get a Twitch OAuth token

Twitch requires you to register an app to get a token. This is a one-time setup.

Register an app:

1. Optional but recommended: create a dedicated Twitch account for the bot so it posts under its own username rather than yours
2. Go to dev.twitch.tv/console/apps and log in as the bot account (or your main if you skipped step 1)
3. Click Register Your Application and fill in:
   • Name: anything (e.g. ankibot)
   • OAuth Redirect URLs: http://localhost
   • Category: Chat Bot
4. Click Create, then Manage — copy the Client ID

Get a token:

5. Paste this URL into your browser, replacing YOUR_CLIENT_ID:

https://id.twitch.tv/oauth2/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost&response_type=token&scope=chat:read+chat:edit

6. Click Authorize — your browser will redirect to http://localhost (the page won't load, that's fine)
7. Look at the URL bar — it will look like:

http://localhost/#access_token=abcdef123456&scope=...

8. Copy the value between access_token= and &scope — that's your token

3. Configure the bot

Copy the example config and fill in your details:

cp config.example.json config.json

Edit config.json:

{
  "twitch": {
    "botUsername": "your_bot_account_name",
    "oauthToken": "oauth:your_token_here",
    "channel": "your_channel_name"
  },
  "overlay": {
    "port": 3000
  },
  "game": {
    "answerWindowSeconds": 30,
    "cooldownSeconds": 15,
    "pointsBoth": 10,
    "pointsOne": 5
  }
}

channel is the channel the bot will join and post in — typically your own channel name.

4. Start the bot

Make sure Anki is open, then run:

npm start

The bot will connect to your channel and the overlay server will start at http://localhost:3000.

Chat commands

Command	Description
!ajatt	Start a quiz round with a random card from any deck
!ajatt <deck>	Start a round from a specific deck (partial name match)
!decks	List available decks
!points	Check your own point total
!leaderboard / !top	Show the top 5 players

Answering

During a round, viewers type their answers directly in chat — no command prefix needed. The bot checks every message against the card's reading and meaning.

• Both reading and meaning correct — full points (pointsBoth, default 10)
• Either reading or meaning correct — half points (pointsOne, default 5)
• Each viewer can only answer once per round

Readings are accepted in hiragana or romaji. Meanings are matched case-insensitively, and the bot strips punctuation and parenthetical notes, so partial matches like if possible work even if the full meaning is if possible; somehow.

OBS overlay (optional)

The bot runs a local web server that the overlay polls every 500ms for state changes.

1. In OBS, add a Browser Source
2. Set the URL to http://localhost:3000
3. Set the width and height to match your canvas (e.g. 1920×1080)
4. Check Refresh browser when scene becomes active

The overlay has a transparent background so it can sit on top of your other sources. It shows the card front during the answer window, then reveals the word, reading, and meaning when time is up.

Card compatibility

The bot auto-detects which fields to use for the front, reading, and meaning based on common field names. It looks for these names in priority order:

Slot	Field names checked
Front	expression, front, word, kanji, japanese, vocab, vocabulary
Reading	word reading, reading, kana, word furigana, furigana, hiragana, pronunciation
Meaning	word meaning, meaning, english, back, definition, translation, gloss

If none of these match, it falls back to the first and second fields of the card. Most standard Japanese vocabulary decks (Core 2k/6k, JLPT decks, etc.) will work out of the box.

Config reference

Key	Default	Description
twitch.botUsername	—	Twitch username of the bot account
twitch.oauthToken	—	OAuth token for the bot account
twitch.channel	—	Channel the bot joins
overlay.port	3000	Port for the overlay web server
game.answerWindowSeconds	30	Seconds viewers have to answer
game.cooldownSeconds	15	Cooldown between rounds
game.pointsBoth	10	Points for matching both reading and meaning
game.pointsOne	5	Points for matching either reading or meaning