Getting Started

This guide walks you through setting up Solstice 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.20+	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, history, and playlists
yt-dlp	Latest	YouTube audio extraction fallback
Node.js	18+	JavaScript runtime for yt-dlp extraction challenges

Optional

Requirement	Purpose
Upstash Redis	Stream URL caching with smart TTL (greatly reduces extraction latency)
YouTube Cookies	Bypass YouTube bot-detection blocks on cloud provider IPs

---

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 instructions.
3. Copy the bot token (e.g. 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11).
4. Important: Disable privacy mode: 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.
2. Select API Development Tools.
3. Create a new application.
4. Copy the numeric api_id and the hex api_hash.

1.3 Assistant Account Session String

The bot requires an assistant user account to join and stream inside voice chats. Solstice's universal session decoder natively supports GoGram, Pyrogram, or Telethon session strings.

You can generate a session string using any standard Telegram session generator bot (like @SessionStringBot on Telegram) or using a quick script with your API_ID and API_HASH.

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

---

Step 2: Download or Clone

Option A: Pre-compiled Binary (Easiest)

1. Download the release archive from our Telegram Group.
2. Extract and enter the directory:

unzip solstice-release.zip -d solstice
cd solstice
cp .env.example .env

Option B: Clone & Build from Source

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

---

Step 3: Configure Environment

Edit .env with your credentials:

# Required
BOT_TOKEN=your_bot_token_here
API_ID=your_api_id
API_HASH=your_api_hash
SESSION_STRING=your_session_string
MONGO_URI=mongodb://localhost:27017/solstice
OWNER_ID=your_telegram_user_id

# Optional Web Server & Room Mini App (defaults to :8080)
PORT=8080
# WEB_APP_URL=https://your-domain.com

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

See the Configuration Reference for details on all settings.

---

Step 4: Run Solstice

Development Run (with live watchdog)

bash start.sh

Production Build

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

# Run binary directly
./solsticeio

You should see output similar to:

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

---

Step 5: Set Up Your Group

1. Add the bot to your Telegram group.
2. Promote the bot to admin with permissions to:
   • Manage voice 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. Click the [ Open Room ] button on the play card (or send /room) to open the interactive Room with live 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 is an admin 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.
• Ensure an active voice chat is started in the group before playing.

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

• YouTube blocks cloud data center IPs (AWS, Railway, DigitalOcean).
• Export a cookies.txt from a logged-in browser session and set YOUTUBE_COOKIES in your environment or upload via /setcookies.
• Verify Node.js is installed (node -v) for JavaScript extraction challenges.