🎧 ArcMusic

A blazing-fast, reliable, and feature-packed Telegram bot for streaming music in group voice chats — built with Go.

---

🚀 Quick Start

☁️ Deploy to Heroku (One-Click)

Click the button below to deploy ArcMusic instantly on Heroku:

---

Prerequisites

• Go 1.25 or higher
• MongoDB (Cloud or Local)
• Telegram Bot Token (from @BotFather)
• API ID & Hash (from my.telegram.org)
• Assistant Account Session String

Installation

1. Clone Repository

git clone https://github.com/tusar404/ArcMusic.git
cd ArcMusic

2. Install Dependencies

bash install.sh && go mod tidy

3. Configure Environment

cp sample.env .env
# Edit .env with your credentials

4. Get Required Credentials

• Bot Token: Message @BotFather, use /newbot
• API ID & Hash: Visit my.telegram.org
• Session String: Use @StringFatherBot or online generator
• MongoDB: Free tier at MongoDB Atlas

5. Start the Bot

go run ./cmd/app

---

⚙️ Configuration

All configuration is managed through environment variables. For detailed configuration instructions, see:

📖 Configuration Guide

Key Variables

Variable	Required	Purpose
API_ID	✅	Telegram API ID
API_HASH	✅	Telegram API Hash
TOKEN	✅	Bot token from @BotFather
MONGO_DB_URI	✅	MongoDB connection string
STRING_SESSIONS	✅	Assistant account session strings
OWNER_ID	❌	Your Telegram User ID
LOGGER_ID	❌	Log channel ID

See Configuration Reference for complete list of variables with examples.

---

📚 Commands

User Commands

Command	Description
/play <query>	Play a song from YouTube or Telegram
/queue	Show current queue
/position	Show current track position
/help	Show command help
/ping	Check bot status

Admin Commands

Command	Description
/pause [seconds]	Pause for playback (optionally auto-resume)
/resume	Resume paused track
/mute [seconds]	Mute playback (optionally auto-unmute)
/unmute	Unmute playback
/seek <seconds>	Seek to specific position
/loop <count>	Loop track N times
/shuffle	Toggle shuffle mode
/speed <speed>	Set playback speed (0.5-4.0x)
/skip	Skip to next track
/fplay <query>	Force play (skip queue)
/clear	Clear entire queue
/remove <index>	Remove track from queue
/move <from> <to>	Move track in queue
/jump <position>	Jump to position in current track
/replay	Replay current track
/addauth <user>	Grant user playback permission
/delauth <user>	Revoke user playback permission
/authlist	List authorized users
/reload	Reload admin cache
/cplay	Channel play mode

Owner Commands

Command	Description
/addsudo <user>	Add sudo user
/delsudo <user>	Remove sudo user
/sudolist	List all sudo users
/maintenance <on/off>	Toggle maintenance mode
/broadcast <message>	Broadcast to all chats
/stats	Show bot statistics
/restart	Restart bot

---

🎼 Platform System

YukkiMusic uses a modular platform system to support multiple music sources:

Supported Platforms

1. Telegram (Priority: 100) - Direct Telegram audio/video files
2. YouTube (Priority: 90) - YouTube videos and playlists
3. Youtubify API (Priority: 80) - Premium YouTube downloads
4. Arc API (Priority: 75) - YouTube downloads via Arc API
5. YT-DLP (Priority: 70) - Direct yt-dlp integration

How It Works

• When you request a song, the bot checks each platform by priority
• First valid platform handles the request
• Automatic fallback if one method fails
• Seamless track fetching and downloading

📖 Platform System Guide - Learn how to add custom platforms

---

📖 Documentation

• Configuration Guide - All environment variables explained
• Platform System - How platforms work and add custom sources
• Database Layer - MongoDB schemas, queries, and bot data management
• Modules System - Command handlers, permissions, and feature modules

---

🏗️ Project Structure

ArcMusic/
├── .github/
│   └── README.md              # Main documentation (you are here)
├── cmd/app/
│   └── main.go                # Entry point
│   └──...
├── internal/
│   ├── config/                # Configuration management
│   │   ├── config.go
│   │   └── README.md          # Detailed config guide
│   ├── core/                  # Core bot logic
│   │   ├── clients.go         # Bot & assistant initialization
│   │   ├── room_state.go      # Playback state management
│   │   ├── chat_state.go      # Chat & assistant state
│   │   └── ...
│   ├── database/              # MongoDB operations
│   │   ├── bot_state.go
│   │   ├── chat_settings.go
│   │   └── ...
│   ├── modules/               # Command handlers
│   │   ├── play.go            # Play command
│   │   ├── queue.go           # Queue management
│   │   └── ...
│   ├── platforms/             # Music sources
│   │   ├── youtube.go         # YouTube integration
│   │   ├── telegram.go        # Telegram media
│   │   ├── ytdlp.go           # YT-DLP downloader
│   │   └── ...
│   ├── locales/               # Multi-language support
│   │   ├── en.yml            # English
│   │   └── ...
│   ├── utils/                 # Utility functions
│   ├── cookies/               # YouTube cookie files
│   └── ...
├── go.mod                     # Go module definition
├── go.sum                     # Dependency checksums

---

🐛 Bug Reports & Features

Found a bug? Have a feature request?

• Use /bug command in the bot to report directly
• Join our Support Chat for discussions
• Open an Issue on GitHub

---

🤝 Contributing

Contributions are welcome! Here's how to help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Adding a New Platform

See Platform System Guide for step-by-step instructions.

---

📜 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

ArcMusic — A Telegram bot that streams music into group voice chats
Copyright (C) 2026 Team Arc

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

---

🙌 Credits

• Maintainer: Tosu
• Contributors: All amazing developers who contributed to this project
• Base Repo: YukkiMusic
• Libraries: Built with gogram, ntgcalls, and more

---

📞 Support

• Telegram Support Chat: @ArcChatz
• Updates Channel: @ArcUpdates
• GitHub Issues: Report bugs

---

⚡ Performance Tips

1. Use multiple assistant accounts - Distributes load across accounts
2. Set appropriate limits - Adjust QUEUE_LIMIT and DURATION_LIMIT
3. Enable auto-leave - Removes bot from inactive chats automatically
4. Use MongoDB Atlas - Better performance than local MongoDB
5. Set up logger - Monitor errors and optimize accordingly

---

Happy Streaming! 🎶