Getting Started (User Guide)

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• src/app.ts
• src/commands/join.ts
• src/commands/start.ts
• src/commands/stop.ts
• src/commands/leave.ts
• src/commands/status.ts
• src/commands/languages.ts
• src/processors/recordAudio.ts
• src/processors/recognizeRecording.ts
• src/processors/translate.ts
• src/processors/readText.ts
• stt/src/main.rs
• docker-compose.prod.yml
• src/env.ts
• src/interactions.ts
• src/deploy.ts

This guide provides an overview of the Discord Live Translation Bot, its core functionalities, and instructions for both standard users and those looking to self-host the application. The bot is designed to automatically translate voice chat in real-time into a language selected by the user, facilitating communication between individuals who speak different languages.

The primary interaction with the bot is through a set of slash commands. Users can invite the bot to their voice channel, start a translation session for a specific language, and then stop the session and remove the bot when finished. The bot listens to a user's speech, translates it, and plays back the translated audio in the voice channel.

Sources: README.md:5-9

User Commands

The bot is controlled via a set of slash commands. The main application file, app.ts, routes these commands to their respective handlers.

Sources: src/app.ts:28-48

Command Summary

The following table summarizes the available slash commands for interacting with the bot.

Command	Description	File
/join	Move the bot into your current voice channel.	src/commands/join.ts
/leave	Move the bot out of your current voice channel.	src/commands/leave.ts
/start <target>	Start the translation for yourself into the specified target language.	src/commands/start.ts
/stop	Stop the translation for yourself.	src/commands/stop.ts
/status	Show your current translation settings.	src/commands/status.ts
/languages	Show all available languages for translation.	src/commands/languages.ts

Sources: src/interactions.ts:12-19, README.md:18-21

Basic Usage Flow

A typical user session with the bot follows a simple sequence of commands. The diagram below illustrates this flow.

Sources: README.md:11-17

How It Works: The Translation Pipeline

The core of the bot's functionality is a multi-step pipeline that processes a user's voice and produces a translated audio output. This process is initiated when a user, who has an active translation session, starts speaking in a voice channel where the bot is present.

Sources: src/commands/join.ts:100-116

The following sequence diagram details the entire translation process, from initial voice capture to the final audio playback.

Sources: src/commands/join.ts:100-116, src/processors/recordAudio.ts, src/processors/recognizeRecording.ts, stt/src/main.rs, src/processors/translate.ts, src/processors/readText.ts, src/utils/AudioQueue.ts, docker-compose.prod.yml

Key Processing Steps

1. Audio Recording (recordAudio.ts): When a user speaks, the bot's VoiceReceiver subscribes to their audio stream. This stream is decoded from Opus format and saved as a .wav file. Recording stops after a brief period of silence (100ms).
   Sources: src/processors/recordAudio.ts:28-34
2. Speech-to-Text (recognizeRecording.ts & stt/): The recorded .wav file is sent via a POST request to the Speech-to-Text (STT) service. This service, built in Rust, uses the whisper-rs library to transcribe the audio into English text.
   Sources: src/processors/recognizeRecording.ts:9-15, stt/src/main.rs:27-46
3. Translation (translate.ts): The recognized English text is sent to a translation service (e.g., LibreTranslate). The bot makes a POST request with the text, source language (en), and the user's selected target language.
   Sources: src/processors/translate.ts:9-17, docker-compose.prod.yml:21
4. Text-to-Speech (readText.ts): The translated text is converted back into audio. A Python script is executed, which uses a TTS model (specified in languages.ts) to generate a new .wav file.
   Sources: src/processors/readText.ts:11-16
5. Audio Playback (AudioQueue.ts): The final audio file is added to a queue for the specific voice channel and played back through the bot's voice connection. The queue ensures that multiple translations are played sequentially without overlapping.
   Sources: src/utils/AudioQueue.ts:63-67

Self-Hosting

For users who prefer to run their own instance, the bot can be deployed using Docker. This requires setting up credentials and running the provided Docker Compose file.

Sources: README.md:23-26

Docker Architecture

The docker-compose.prod.yml file defines four main services that work together.

Sources: docker-compose.prod.yml:3-32

Configuration

Before starting the services, you must create a .env file with the necessary environment variables.

Variable	Description	Required	Default	Source File
BOT_TOKEN	The bot token from the Discord Developer Portal.	Yes	-	src/env.ts:12
CLIENT_ID	The application's client ID. Optional for running, but needed for deploying commands.	No	-	src/env.ts:13
GUILD_ID	If set, commands are automatically deployed to this specific server on startup.	No	-	src/env.ts:14
STT_HOST	The URL for the Speech-to-Text service.	Yes	-	src/env.ts:19
TRANSLATION_HOST	The URL for the translation service.	Yes	-	src/env.ts:20
REDIS_URL	The URL for the Redis instance, used for storing user settings.	No	-	src/env.ts:18
HEARTBEAT_URL	A URL to send a POST request to every minute as a health check.	No	-	src/env.ts:21
LOG_PATH	A file path to write logs to.	No	-	src/env.ts:15

Sources: src/env.ts:10-23, README.md:28

Deployment Steps

1. Clone the repository.
2. Create and configure the .env file with at least BOT_TOKEN.
   Sources: README.md:27-28
3. Start the services using Docker Compose:

   docker compose -f docker-compose.prod.yml up -d
   

   Sources: README.md:29
4. Deploy Slash Commands: After the bot container is running, you must deploy the slash commands to Discord. This can be done by executing a command inside the running container or locally.

   # On the server running the container
   docker exec <container_name> pnpm run deploy
   
   # Or, run locally if you have Node.js/pnpm installed
   pnpm run deploy
   

   This script runs ts-node src/deploy.ts, which registers all commands globally with Discord's API.
   Sources: README.md:33-37, package.json:11, src/deploy.ts