HKTM

README

HKTM

High-performance Discord music bot written in Go, designed to stream audio directly from YouTube using a tightly controlled pipeline.

⚠️ Work in Progress
This project is developed for personal use in a private Discord server. While the code is open-source for educational purposes, it is not production-ready and may lack general support or stability guarantees.

Features

• Direct Audio Pipeline — yt-dlp → FFmpeg → gopus for full transparency
• No DCA Dependency — Avoids DCA’s silent failures and black-box behavior
• Stream-First Design — Built for low-latency, stable audio playback
• Battle-Tested Tools — Leverages mature tools (FFmpeg, yt-dlp) instead of wrappers

Architecture

The audio streaming flow is purpose-built for performance and clarity:

graph LR;
    A["yt-dlp"] --> B["FFmpeg (PCM)"];
    B --> C["gopus (Opus Encoder)"];
    C --> D["Discord Voice Channel"];

Pipeline Breakdown:

1. yt-dlp – Extracts direct audio stream URLs from YouTube.
2. FFmpeg – Converts audio to raw PCM format (48kHz, 16-bit, stereo).
3. gopus – Encodes PCM to Opus (optimized for Discord).
4. Discord – Streams Opus frames to voice channels via Discord Gateway.

Why This Approach?

• Full Pipeline Control – Know exactly what’s happening at each stage
• Zero Black Boxes – Easier to debug and extend than DCA-based solutions
• Granular Error Recovery – Handle broken pipes, subprocess failures, etc.
• Pure Go Integration – gopus enables native Opus encoding

---

Requirements

Make sure the following are installed and available in your PATH:

• Go 1.23+
• FFmpeg
• yt-dlp
• Discord Bot Token

Getting Started

1. Clone the repository

git clone https://github.com/latoulicious/HKTM.git

1. Navigate to the repository

cd Tarumae

1. Install the dependencies

go mod tidy

1. Configure your Discord bot token (via .env).
2. Run the bot:

go run cmd/main.go 

# or using makefile 

make run

See the Makefile for more available commands.

Commands

Check the full list of available commands.

Known Issues

• Audio may cut off abruptly after prolonged playback — suspected stream or subprocess timeout. Currently under investigation.

Made Possible By

Special thanks to bwmarrin/discordgo — the foundation that made this bot possible.

• yt-dlp — For extracting high-quality audio from YouTube
• FFmpeg — For reliable audio stream decoding and conversion
• layeh/gopus — For direct Opus encoding in Go