🎵 ˹ʜᴀꜱɪɪ ꭙ ᴍᴜꜱɪᴄ˼

A Modern Telegram Music Bot for High-Quality Voice Chat Streaming

An open-source Telegram music bot built with Python, Pyrogram, PyTgCalls, and FFmpeg, delivering fast, reliable, and high-quality audio streaming directly to Telegram voice chats.

˹ʜᴀꜱɪɪ ᴍᴜꜱɪᴄ˼ is a powerful and modern Telegram music bot built for seamless voice chat streaming. It enables users to play music directly in Telegram voice chats using YouTube links, search queries, and live radio stations while offering administrators complete control over playback.

Designed with performance, stability, and simplicity in mind, the project combines modern asynchronous technologies to provide a fast, reliable, and highly customizable music streaming experience. Whether you're hosting a small community or managing a large Telegram group, Hasii Music is built to deliver consistent performance with minimal configuration.

• 📖 About
• ⭐ Why Hasii Music?
• ✨ Features
• 🏗 Tech Stack
• 📋 Requirements
• 🚀 Quick Start
• ⚙️ Environment Variables
• 🛠 Installation
• 📖 Commands
• 📂 Project Structure
• 🤝 Contributing
• 📞 Support
• 🙏 Credits
• 📄 License

Choosing the right Telegram music bot shouldn't mean sacrificing performance, reliability, or ease of deployment. Hasii Music is designed with developers and communities in mind, providing a clean architecture, modern technologies, and powerful features while remaining simple to deploy and maintain.

• 🚀 Fast and lightweight architecture
• 🎵 High-quality voice chat streaming
• 🎧 YouTube search and direct URL playback
• 📻 Built-in live radio support
• 📝 Smart queue management
• 🛡 Powerful administrator controls
• 👥 User authorization system
• 🔄 Automatic voice chat cleanup
• 🐳 Docker and Docker Compose support
• ⚙️ Environment-based configuration
• 📂 Modular and maintainable codebase
• ❤️ Open-source under the GPL-3.0 License

Experience smooth and crystal-clear music playback optimized for Telegram voice chats using the Opus codec and FFmpeg.

Play music instantly from:

• YouTube links
• Search queries
• Supported playlists

Access and stream a collection of online radio stations directly within Telegram voice chats.

Manage playlists effortlessly with a built-in queue system.

• Add songs
• View queue
• Skip tracks
• Clear queue

Built with asynchronous libraries for efficient resource usage and responsive performance.

Complete playback management with support for:

• Play
• Pause
• Resume
• Skip
• Stop
• Seek

Restrict playback controls to:

• Chat administrators
• Authorized users
• Bot owner
• Sudo users

Automatically detects inactive voice chats and leaves them to conserve server resources.

Deploy effortlessly using Docker or Docker Compose for a consistent production environment.

Configure the bot entirely through environment variables without modifying the source code.

Before deploying ˹ʜᴀꜱɪɪ ᴍᴜꜱɪᴄ˼, ensure your system meets the following requirements.

Before starting, install the required runtimes:

# Install FFmpeg
sudo apt update && sudo apt install ffmpeg -y

# Install Deno
curl -fsSL https://deno.land/x/install/install.sh | sh

Clone the repository.

git clone https://github.com/hasindu-nagolla/HasiiMusicBot.git

Move into the project directory.

cd HasiiMusicBot

Install the required dependencies.

pip install -r requirements.txt

Create your environment configuration.

cp sample.env .env

Update the values inside .env.

Start the bot in another session.

bash start

Create a .env file in the project's root directory.

# Telegram API
API_ID=
API_HASH=
BOT_TOKEN=

# MongoDB
MONGO_DB_URI=

# Bot Configuration
OWNER_ID=
LOGGER_ID=

# Assistant Account
STRING_SESSION=

# Essential
COOKIE_URL=

Clone the repository.

git clone https://github.com/hasindu-nagolla/HasiiMusicBot.git

Enter the project directory.

cd HasiiMusicBot

Install Python dependencies.

pip install -r requirements.txt

Create the environment file.

cp sample.env .env

Configure all required environment variables.

Start the bot.

bash start

Build the Docker image.

docker build -t hasiimusicbot:latest .

Run the container.

docker run -d \
  --restart unless-stopped \
  --env-file .env \
  -v ./HasiiMusic/cookies:/app/HasiiMusic/cookies \
  -v ./downloads:/app/downloads \
  --name hasiimusicbot \
  hasiimusicbot:latest

Deploy using Docker Compose.

docker compose up -d --build

View container logs.

docker compose logs -f

Stop the services.

docker compose down

Restart the services.

docker compose restart

| /maintenance | Enable or disable maintenance mode | | /restart | Restart the bot | | /logs | Retrieve the latest bot logs |

HasiiMusicBot/
├── HasiiMusic/
│   ├── __init__.py
│   ├── __main__.py
│   ├── cookies/
│   ├── core/
│   ├── helpers/
│   ├── locales/
│   └── plugins/
│
├── config.py
├── sample.env
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
├── setup
├── start
├── LICENSE
└── Readme.md

Contributions are welcome and greatly appreciated.

Whether you're fixing bugs, improving documentation, optimizing performance, or adding new features, your contributions help make ˹ʜᴀꜱɪɪ ᴍᴜꜱɪᴄ˼ better for everyone.

Please read the CONTRIBUTING.md guide before opening an issue or submitting a pull request.

Need help with deployment or encountered an issue?

Feel free to reach out through the following platforms.

If you discover a bug, please open a GitHub Issue with detailed information so it can be reproduced and fixed quickly.

This project would not have been possible without the amazing open-source community.

Special thanks to:

• Anony — Inspiration for the original project.
• Pyrogram — Telegram MTProto framework.
• PyTgCalls — Telegram voice chat streaming library.
• FFmpeg — Audio processing and transcoding.

Thank you to everyone who has contributed through code, bug reports, feature suggestions, testing, and community support.

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

You are free to use, modify, and distribute this software. However, any derivative works must also be open-source and released under the exact same license.

For more information, see the LICENSE file.