zidanaetrna/aetrna-music: public instance is available if you want to test things out before setting up

Showcase & Feature Demo

Real-Time Web Control Panel

Analytics overview, live audio stream telemetry, memory consumption metrics, active queue inspector, and multi-guild server selector.

Interactive Now Playing Card (/nowplaying)	Rich Hybrid Embed Playlist (/playlist play)	Live Synced LRC Lyrics (/lyrics)

Why aetrna-music?

• Lavalink-Free: No separate Lavalink server or Java runtime required. Lightweight native Go + Node.js architecture.
• Self-Hosted: Run everything on your own server with full control.
• Web Dashboard: React 18 + TypeScript control panel with real-time stream status, active queue inspector, memory consumption telemetry, and multi-guild switcher.
• Rich Hybrid Embed UI: Aesthetic Discord embed cards with full-width thumbnails, clickable track list previews (1. [Title](https://github.com/zidanaetrna/aetrna-music/blob/main/URL) (3:45)), and 2-row interactive control button matrices ([ Pause ], [ Skip ], [ Prev ], [ Loop ], [ Shuffle ], [ Vol- ], [ Vol+ ], [ Lyrics ], [ Favorite ], [ Stop ]).
• Custom Saved Playlists: Create, save, manage, and play custom user playlists (/playlist create, /playlist add-track, /playlist play, /playlist list-tracks). Supports YouTube links, Spotify URLs, and manual title searches (query: FLOW Sign).
• Synced LRC Lyrics: Live line-by-line synchronized lyrics directly in Discord embeds with dual-orientation candidate matching (Title - Artist vs Artist - Title) for Japanese/Anime/J-Pop tracks (/lyrics). Read full documentation in docs/lyrics-ranking.md.
• Audio Filters: On-the-fly FFmpeg DSP filters (bassboost, nightcore, vaporwave, 8d, pop).
• Docker-Ready: Instant containerized setup without assembling dependencies manually.
• Smart YouTube Search Ranker: Deterministic 5-candidate ranking in Go (< 0.05ms) with zero network overhead. Solve broadcaster TV-size clip traps for anime/J-Pop queries without query manipulation. Read full documentation in docs/search-ranking.md.

Try the Bot

A public instance is available if you want to test things out before setting up your own.

Add to your server

It's the same codebase. No guarantees on uptime.

Quick Start & Installation

Option 1: Interactive CLI Setup Wizard (Recommended)

Run the interactive wizard to generate .env and initialize configuration:

npx aetrna-music init

Option 2: Docker Compose (Recommended for servers)

1. Clone repository:

   git clone https://github.com/zidanaetrna/aetrna-music.git
   cd aetrna-music
   

2. Copy environment template:

   cp .env.example .env
   

   Edit .env and set at minimum your DISCORD_TOKEN and ADMIN_KEY (fallback: DASHBOARD_PASSWORD still works for legacy configs).

3. Optional: Add YouTube cookies for unrestricted playback:

   # Copy your exported Netscape-format YouTube cookies here
   cp /path/to/exported.txt ./cookies.txt
   

   See the YouTube Cookies Setup Guide for step-by-step instructions. docker-compose.yml automatically mounts ./cookies.txt into /app/cookies.txt inside the container (read+write, not read-only — yt-dlp needs to update cookie expiry state).

4. Start container:

   docker compose up -d --build
   

   Your bot is now running, and the Web Dashboard is live at http://localhost:8080!

Option 3: Manual Execution (Local Run)

Prerequisites:

• Go: 1.23+
• Node.js: 22+
• FFmpeg: Installed and added to system PATH
• yt-dlp: Installed and added to system PATH

1. Install Node dependencies:

   npm install
   

2. Start Voice Worker (Terminal 1):

   node voice-server/server.js
   

3. Start Go Core Bot & Web Server (Terminal 2):

   go run ./cmd/bot
   

Web Control Panel / Dashboard

aetrna-music comes with a modern React 18 + TypeScript Web Dashboard accessible at http://localhost:8080.

• React 18 + TypeScript + Vite: Built with modern component architecture, strict type safety, and embedded into the Go executable (//go:embed all:dist).
• Real-Time Telemetry & Audio Stream Inspector: Live WebSocket status updates for active guild stream engine, RAM consumption, and current playing track artwork.
• System Logs Tab: Real-time SSE-streamed Go process logs (500-entry ring buffer) with live color-highlighting for [ERROR], [WARN], [INFO], and [DEBUG] — useful for diagnostics without SSHing into the container.
• Cloudflare Dark Charcoal UI: Collapsible sidebar (250px vs 64px), quick search shortcut (Ctrl + K), and unified Deep Emerald Green theme (#10B981).
• Multi-Guild Target Selector: Switch between connected Discord servers to manage queues and playback controls.
• Multi-Language Support: Switch between English, Natural Tech Indonesian, and Japanese with sleek toast notifications.
• Password Protected: HMAC-SHA256 authenticated session via .env (ADMIN_KEY). Supports three auth paths interchangeably: HTTP Authorization: Bearer <token> header, aetrna_session cookie, or ?token= query parameter (required for browser EventSource/SSE which can't set custom headers).

Command Reference

Environment Variables Reference

Full list of supported environment variables (see .env.example for raw copy-paste):

YouTube Cookies Configuration

YouTube frequently blocks data center IPs or restricts age-gated tracks. To ensure smooth playback, supply a cookies.txt file at project root. Filename must be cookies.txt (not youtube_cookies.txt) — this matches both the default COOKIES_PATH=./cookies.txt and the docker-compose.yml volume mount. Refer to the YouTube Cookies Setup Guide for the browser-extension walkthrough.

Architecture Overview

graph TD
    subgraph Discord Client & Web Users
        A[Discord User / Slash Commands]
        W[Web Dashboard Browser http://localhost:8080]
    end

    subgraph aetrna-music Single Container / Server
        subgraph Go Core Engine
            B[Go Bot Server]
            C[SQLite Database WAL]
            D[Web API & Embedded Static Server]
            E[Auth Manager HMAC-SHA256]
        end

        subgraph Node.js Voice Server
            F[Voice Worker Server port 3005]
            G[yt-dlp Audio Stream Engine]
            H[FFmpeg DSP Audio Filter Pipeline]
            I[Prism-Media Opus Encoder]
        end
    end

    subgraph External Gateways
        J[YouTube / Audio Sources]
        K[Discord Voice Gateway UDP/WS]
    end

    A -->|Slash / Legacy Cmds| B
    W -->|HTTP REST / Auth| D
    D --> E
    B -->|State & Favorites| C
    B -->|Local IPC / HTTP + X-Internal-IPC-Token| F
    F -->|Local IPC / HTTP + X-Internal-IPC-Token| B
    F -->|Fetch Track| G
    G -->|Stream Raw Audio| J
    G --> H
    H --> I
    I -->|Opus RTP Streams| K