Getting Started

This guide walks you through setting up SolsticeIO from scratch, from obtaining Telegram credentials to streaming music in your first voice chat with the built-in Web Room.

Prerequisites

Requirement	Version	Purpose
Go	1.24+ (1.26 recommended)	Build and run the native bot engine (with CGo enabled)
GCC / Clang	Any	CGo compiler for linking native libntgcalls
FFmpeg	5.0+	Audio/video stream transcoding
MongoDB	6.0+	Persistent storage for settings, playlists, warns, and cookies
yt-dlp	Latest	YouTube audio extraction fallback
Node.js	20+ or 22+	JavaScript runtime for yt-dlp extraction challenges

---

Step 1: Obtain Telegram Credentials

You need three sets of credentials:

1.1 Bot Token (from @BotFather)

1. Open @BotFather on Telegram.
2. Send /newbot and follow the prompts to create your bot.
3. Copy the bot token (e.g. 7123456789:AAH-your-bot-token-here).
4. Important: Disable privacy mode so the bot can receive commands in groups: send /setprivacy → select your bot → choose Disable.

1.2 API ID & API Hash (from my.telegram.org)

1. Visit my.telegram.org and log in with your phone number.
2. Select API Development Tools.
3. Create a new application.
4. Copy the numeric API_ID and the hexadecimal API_HASH.

1.3 Assistant Account Session String

The bot uses an assistant user account to join and stream inside voice chats. SolsticeIO features a universal session string parser that natively supports:

• GoGram session strings
• Pyrogram session strings
• Telethon session strings

You can generate a session string using any standard Telegram session generator (or script) with your API_ID and API_HASH.

Security Note: The session string gives full account access to the assistant Telegram account. Always use a dedicated secondary account, never your personal account.

---

Step 2: Clone and Configure

Clone the repository:

git clone https://github.com/SolsticeIO/SolsticeIO.git
cd SolsticeIO
cp .env.example .env

Edit .env with your credentials:

# Required credentials
BOT_TOKEN=your_bot_token_here
API_ID=your_api_id
API_HASH=your_api_hash
SESSION_STRING=your_session_string
MONGO_URI=mongodb+srv://user:pass@cluster.mongodb.net/solsticeio
OWNER_ID=your_telegram_user_id

# Optional Web Server & Room Mini App (defaults to :8080)
PORT=8080
# WEB_APP_URL=https://music.yourdomain.com
# WEB_APP_SHORT_NAME=room

# Optional Logging
LOGGER_ID=-1001234567890
SUPPORT_CHAT=https://t.me/SolsticeIO
SUPPORT_CHANNEL=https://t.me/SolsticeIO

---

Step 3: Run SolsticeIO

Method A: Start Script (Recommended for Development & VPS)

start.sh automatically compiles the binary, unpacks the voice engine library if needed, optionally boots a local Telegram Bot API server on port 8081, and runs a crash-recovery watchdog:

chmod +x start.sh
./start.sh

Method B: Manual CGo Build

# Compile native binary with static CGo libntgcalls engine
./build.sh

# Run binary directly
./solsticeio

You should see log output similar to:

[SYSTEM] Starting SolsticeIO...
[SYSTEM] Connected to MongoDB!
[VC] Initializing Native CGo libntgcalls Voice Engine...
[VC] Assistant MTProto client started successfully
[WEB] SolsticeIO web server listening on :8080
[BOT] Bot is online and polling updates

---

Step 4: Group Setup & First Stream

1. Add the bot to your Telegram group.
2. Promote the bot to admin with permissions to:
   • Manage video chats
   • Delete messages
   • Pin messages
   • Ban users
   • Invite users via link
3. Add the assistant account to the group (the account behind SESSION_STRING).
4. Start a voice chat in the group.
5. Send /play Bohemian Rhapsody in the group to start streaming.
6. Tap the [ Open Room ] button on the player card (or send /room) to open the interactive Room with real-time waveform, scrubber, and synchronized lyrics.

---

Troubleshooting

Bot doesn't respond to commands

• Verify BOT_TOKEN is correct.
• Ensure privacy mode is disabled in @BotFather (/setprivacy → Disable).
• Verify the bot has administrative permissions in the group.

Voice chat doesn't start

• Ensure SESSION_STRING is valid and the assistant account is in the group.
• Verify FFmpeg is installed and accessible in $PATH: ffmpeg -version.
• Make sure a voice chat is open in the group before queueing a song.

YouTube extraction fails / "Sign in to confirm you're not a bot"

• Cloud provider IPs (AWS, Railway, DigitalOcean, Hetzner) are frequently blocked by YouTube.
• Export a cookies.txt file from your browser and send it to your bot in private messages, then reply with /setcookies. Cookies will be stored in MongoDB and loaded into memory on-the-fly.
• Ensure Node.js 20+ or 22+ is installed on the host for solving JavaScript extraction challenges.