LyraBot

Telegram bot that receives music files, optionally publishes lyrics to Telegraph, and posts curated tracks to a channel.

Features

• Accepts music via direct upload or forwarded messages
• Prompts for lyrics (with skip option) and creates a Telegraph page when provided
• Collects hashtags and builds a formatted caption
• Sends a preview to the user before publishing
• Publishes to a configured channel after confirmation

Requirements

• Python 3.12+
• A Telegram bot token (@BotFather)
• A Telegram channel where the bot is an admin

Setup

1. Clone the repository and create a virtual environment:

python -m venv .venv
.venv\Scripts\activate   # Windows
# source .venv/bin/activate  # Linux/macOS

2. Install dependencies:

pip install -r requirements.txt
pip install -e . -i https://pypi.org/simple

If editable install fails due to network issues, run with:

set PYTHONPATH=src          # Windows
# export PYTHONPATH=src    # Linux/macOS
python -m lyrabot

3. Copy the example environment file and fill in your values:

copy .env.example .env   # Windows
# cp .env.example .env   # Linux/macOS

Variable	Description
BOT_TOKEN	Telegram bot token
CHANNEL_ID	Channel ID (-100…) or @username
CHANNEL_NAME	Name shown in captions (e.g. @mychannel)
TELEGRAPH_ACCESS_TOKEN	Optional; created automatically on first run
TELEGRAPH_SHORT_NAME	Short name for Telegraph account creation
TELEGRAPH_AUTHOR_NAME	Author name on Telegraph pages

4. Run the bot:

lyrabot
# or
python -m lyrabot

Usage Flow

1. Send /start or directly send a music file
2. Paste lyrics or tap Skip lyrics
3. Send hashtags (e.g. #pop #iran)
4. Review the preview and tap Publish or Cancel

Use /cancel at any time to abort the current session.

Project Structure

src/lyrabot/
├── __main__.py          # Entry point
├── config.py            # Settings via pydantic-settings
├── bot/
│   ├── app.py           # Handler registration
│   ├── keyboards.py     # Inline keyboards
│   ├── states.py        # Conversation states
│   └── handlers/        # Step-by-step handlers
├── models/
│   └── track.py         # Track data model
└── services/
    ├── caption.py       # Caption builder
    └── telegraph.py     # Telegraph page creation

License

MIT