DEV Community

Traft
Traft

Posted on

VK Music Bot API: Open Source Backend for VK Music in Telegram

#api #backend #opensource #showdev

Hi! I’m Traft, and I want to share my new open-source project — VK Music Bot API.

The goal of this project is simple: provide a clean backend to access VK music inside Telegram Mini Apps or bots, without mixing UI, bot logic, and VK API calls.

Repository: TraftG/vk-music-bot-api

Why I Built It

Many people want to play VK music without opening the app or browser.
Most bots and scripts out there are fragile, hard to maintain, or mix everything in one place.

I wanted a solution that is:

scalable

production-ready

easy to integrate into Telegram

clean and maintainable

Features

VK Music Bot API currently supports:

Track search — by title, artist, or album, with metadata and cover images

MP3 download — direct from VK, supports FFmpeg processing

History tracking — store listened tracks and build personal recommendations

Secure auth — via Telegram WebApp InitData, no passwords needed

Recommendations — basic algorithms based on listening history

Tech Stack

Backend: FastAPI, Uvicorn, Pydantic, Motor (MongoDB async driver)

Integrations: VKPyMusic, Aiogram, yt-dlp, FFmpeg

Database: MongoDB (NoSQL)

Async: Entire project uses async/await for high throughput

Project Structure

music-bot/
├── app/
│   ├── core/       # config & DB connection
│   ├── models/     # Pydantic schemas
│   ├── routers/    # API endpoints
│   ├── services/   # business logic
│   └── main.py     # FastAPI entry point
├── .env.example
└── requirements.txt
Enter fullscreen mode Exit fullscreen mode

Separation of concerns makes the project:

easier to maintain

easy to scale

easier to test

readable for new contributors

API Endpoints

Authentication:

POST /api/auth/login       # via Telegram InitData
POST /api/auth/history     # add track to history
Enter fullscreen mode Exit fullscreen mode

Music:


GET /api/music/search?q=query        # search tracks
GET /api/music/download/{track_id}  # download MP3
GET /api/music/recommendations      # get recommendations
Enter fullscreen mode Exit fullscreen mode

Docs:

Swagger: /docs

ReDoc: /redoc
Enter fullscreen mode Exit fullscreen mode

Quick Start

git clone https://github.com/TraftG/vk-music-bot-api.git
cd vk-music-bot-api
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
docker run -d -p 27017:27017 mongo
uvicorn app.main:app --reload
Enter fullscreen mode Exit fullscreen mode

API will be available at http://localhost:8000.

Why Async and asynccontextmanager

The whole project is async using async/await and @asynccontextmanager for lifecycle management:

@asynccontextmanager
async def lifespan(app: FastAPI):
    await connect_to_mongo()
    yield
    await close_mongo_connection()

app = FastAPI(lifespan=lifespan)
Enter fullscreen mode Exit fullscreen mode

This pattern is clean, modern, and allows:

safe startup/shutdown of resources

high throughput

testable, maintainable code

Performance

Track search: < 500 ms

Recommendations: < 200 ms

Authorization: < 100 ms

Scales horizontally with multiple workers:

uvicorn app.main:app --workers 4
Enter fullscreen mode Exit fullscreen mode

Deployment

Docker-ready:

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
Enter fullscreen mode Exit fullscreen mode

Runs on:

VPS, Docker, Kubernetes

Railway / Render / Heroku

AWS, GCP

Open Source Contribution

MIT-licensed. Feel free to:

fix bugs

add new features

improve documentation

add tests

Process: fork → feature branch → PR.

Conclusion

VK Music Bot API is a production-ready backend for VK music, easy to integrate into Telegram apps or bots.

Quick start in 5 minutes

Clean and async architecture

Fully Open Source
Github Link ⭐

Top comments (0)