HH Meditation Bot (JavaScript)

A standalone Node.js version of the meditation bot. It uses Discord voice directly through discord.js and @discordjs/voice; audio is decoded locally with FFmpeg.

Setup

The bot is designed for Linux. For a native installation, install Node.js 20 or newer and FFmpeg using your distribution's package manager. For containerized operation, install Docker Engine with the Docker Compose plugin.

1. Install Node.js 20 or newer.
2. From this directory, run npm install.
3. Copy .env.example to .env and set DISCORD_TOKEN and DISCORD_CLIENT_ID.
4. Run npm start.

FFmpeg is resolved from PATH. Set FFMPEG_PATH in .env only when it needs an explicit executable path or a directory containing it.

For immediate command updates in a development server, set GUILD_ID. Without it, the bot registers global commands, which Discord may take up to an hour to propagate.

The bot needs the Guild Voice States privileged gateway intent enabled on its Discord Developer Portal application. Invite it with the bot and applications.commands scopes, and give it permission to Connect and Speak in the target voice channel.

Commands

• /meditation abspielen meditation:<title> timer:<dauer|uhrzeit> — spielt eine gespeicherte Meditation in Schleife bis zum Timer. Verwende eine Dauer wie 1h20m20s oder eine Uhrzeit im 24-Stunden-Format wie 04:00; vergangene Uhrzeiten gelten am Folgetag. Der Voice-Channel des Aufrufenden wird zuerst verwendet; DEFAULT_VOICE_CHANNEL_ID ist der Fallback.
• /meditation hinzufügen sounddatei:<file> titelname:<title> — uploads a supported audio file. Available to server administrators and roles with the Meditationen hinzufügen permission.
• /meditation stop — stops playback and leaves the voice channel; it is available to administrators and roles with the Wiedergabe stoppen permission.
• /einstellungen öffnen — sends an ephemeral settings message with actions for the voice channel, meditation uploads and permissions. Buttons without the required permission are disabled.
• /einstellungen set-channel channel:<voice channel> — saves the default voice channel; it is available to administrators and roles with the Voice-Channel ändern permission.

Only server administrators can assign roles to the separate Meditationen hinzufügen, Voice-Channel ändern and Wiedergabe stoppen permissions.

Uploaded audio lives in a server-specific directory below meditations/ and is intentionally excluded from Git. Playback repeats the selected audio until its timer elapses, is stopped, or no human user remains in its voice channel. Administrators and users with the Voice-Channel permission configure the per-server timer limit (default: 30m) in the Voice-Channel settings using the same duration format as the timer.

Docker and health monitoring

Start the container with docker compose up -d. Docker Compose pulls git.vortige.com/vortige/hh-meditation-bot:TAG, mounts uploaded audio from meditations/, and retains SQLite settings in the bot-data volume. FFmpeg is included in the image.

The bot exposes GET /health on HEALTH_PORT (default 3000). It returns 200 {"status":"ok"} only after the Discord client is ready; it returns 503 {"status":"unavailable"} while starting or disconnected. Configure Kener with the public URL https://<your-domain>/health. Point that domain, using your reverse proxy or firewall, to the Compose host's published health port; TLS and DNS are deployment-specific and are intentionally not managed by this bot.

Configuration

Required values:

• DISCORD_TOKEN: the bot token.
• DISCORD_CLIENT_ID: the Discord application ID.

Optional values:

• GUILD_ID: server ID used for fast, guild-scoped command registration.
• DEFAULT_VOICE_CHANNEL_ID: configured fallback voice channel.
• DATABASE_PATH: SQLite file for persisted settings; in Docker this is /app/data/settings.db.
• HEALTH_PORT: port serving the /health endpoint for Kener and container checks.
• FFMPEG_PATH: FFmpeg executable or containing directory.
• SENTRY_DSN: enables optional Sentry error reporting.