A general-purpose Discord bot built with discord.js v14. Features audio playback via yt-dlp and Letterboxd diary subscriptions.
Per-guild voice queue with in-memory state:
| Command | Description |
|---|---|
/play url:<url> |
Join your voice channel and play a track from a direct URL. |
/search query:<text> |
Search YouTube and play the top result. |
/pause |
Pause or resume the current track. |
/stop |
Clear the queue and disconnect. |
/skip |
Skip to the next track. |
/rewind |
Restart the current track from the beginning. |
/queue |
Show the current queue. |
/nowplaying |
Show the currently playing track. |
/loop mode:<off|track|queue> |
Set the loop mode. |
/shuffle |
Randomly shuffle the upcoming tracks. |
/remove position:<n> |
Remove a track from the queue by position. |
/save |
DM yourself a link to the currently playing track. |
Subscribe channels to a Letterboxd member's film diary. New diary entries are posted as embeds with the movie poster thumbnail.
| Command | Description |
|---|---|
/letterboxd_add username:<user> |
Subscribe this channel to a Letterboxd diary. Posts the most recent entry immediately. |
/letterboxd_list |
List all Letterboxd diaries subscribed in this channel. |
/letterboxd_remove username:<user> |
Unsubscribe this channel from a Letterboxd diary. |
/letterboxd_refresh |
Force an immediate poll of this server's Letterboxd feeds. Requires the Manage Channels permission. |
Feeds that fail 3 consecutive polls are paused automatically and a warning is posted to the channel; auto-paused feeds are retried hourly and resume once reachable again.
- Node.js latest LTS (see
.nvmrc) ffmpegandyt-dlponPATH- A Discord application / bot token
The Docker image installs ffmpeg and yt-dlp for you.
-
Copy environment template and fill it in:
cp .env.example .env
DISCORD_TOKEN— bot token from the Developer Portal.CLIENT_ID— application (client) ID.DEV_GUILD_ID— only needed in development; the guild in which slash commands are registered instantly.NODE_ENV—developmentorproduction.RSS_POLL_INTERVAL_MS— how often to poll RSS/Letterboxd feeds (default:600000= 10 min).DATABASE_PATH— path to the SQLite database file (default:./data/maple.db).
-
Invite the bot to your server with
bot+applications.commandsscopes and the Connect, Speak, and Send Messages permissions.
npm install
npm run deploy # registers slash commands in DEV_GUILD_ID
npm run dev # hot-reload via tsx watchnpm install
npm run build
NODE_ENV=production npm run deploy # registers global commands
NODE_ENV=production npm startdocker compose build
docker compose up -dRun the slash-command deployment once per command change. It can be executed inside the container:
docker compose run --rm maple node -e "process.env.NODE_ENV='production'" \
&& docker compose exec maple npx tsx scripts/deploy-commands.tsOr run it from the host with npm run deploy against the same .env.
src/
index.ts Entry point
config.ts Env loading and validation (zod)
logger.ts
modules/
audio/ Voice queue, yt-dlp integration
rss/ Feed-polling backend (DB + poller) used by letterboxd/
letterboxd/ Letterboxd diary subscriptions
general/ /help and other utility commands
core/ Command registry, interaction router, loader
db/ SQLite schema and singleton (better-sqlite3)
scripts/
deploy-commands.ts Registers slash commands