Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

4 Commits
bot
bot
 
 
.env.example
.env.example
 
 
README.md
README.md
 
 
backend.js
backend.js
 
 
ecosystem.config.js
ecosystem.config.js
 
 
package.json
package.json
 
 
setup.sh
setup.sh
 
 

Repository files navigation

RaiX Studio

RaiX — Your AI-Powered Telegram Studio

Download · Clip · Summarize · Study · Chat — all from Telegram.

Stars Forks Issues License Node Platform

Features • Quick Start • Configuration • Architecture • Commands • Troubleshooting • Contributing

🚀 What is RaiX?

RaiX is a self-hosted, button-driven Telegram bot that turns any video link into actionable content — downloads, clips, AI summaries, interactive quizzes, flashcards, and more. It is designed to run 24/7 on a Raspberry Pi or any Linux VPS with zero maintenance.

No commands to memorize. Paste a link → pick an action → done.

Two services, one folder. The Express API backend (backend.js) handles yt-dlp, ffmpeg, and AI. The Telegram bot (bot/) presents it all through inline buttons. Both run under PM2 and share a single .env.

✨ Features

🎬 Video & Music

  • Search YouTube directly from Telegram
  • Download in any quality (360p → 1080p)
  • Audio-only extraction (MP3/M4A)
  • Playlist browsing & batch downloads
  • Multi-platform — YouTube, Instagram, Twitter/X, TikTok, Facebook, Vimeo, Pinterest, Snapchat

✂️ Clip Studio

  • Trim any video to a 60-second clip
  • Reframe to 9:16 (Shorts/Reels) or 1:1 (Feed)
  • AI Viral Finder — automatically locates the most engaging 30 seconds
  • Accepts flexible time formats: 90, 1:30, 0:01:30

🧠 AI Studio

  • Summarize — brief, detailed, key points, or timestamped chapters
  • Generate titles — viral, curiosity, how-to, or listicle tones
  • Generate tags — 15 SEO-optimized tags from any title
  • Write descriptions — with timestamps, hashtags, CTAs, custom keywords
  • Powered by Groq (free) or OpenRouter with multi-key failover

📚 Study Tools

  • Full transcript — timestamped spoken text, downloadable
  • Class notes — AI-structured revision notes
  • Interactive quiz — 5 exam-style MCQs played inside Telegram
  • Flashcards — tap to flip, swipe through the deck
  • Study planner — paced daily schedule for any course

💬 Video Chat

  • Ask questions about any video's content
  • AI reads the transcript and answers in context
  • Maintains chat history within the session

🛡️ Access Control & Admin

  • Private by default — only the owner can use it
  • Request/Approve flow for new users
  • Role system — Owner, Admin, User
  • Owner Panel — manage users, cookies, restart services, view stats
  • Cookie upload — update yt-dlp cookies straight from your phone

📦 Quick Start

Prerequisites

Requirement Minimum Notes
OS Debian 11+ / Ubuntu 20.04+ / Raspberry Pi OS Any Linux with apt
Node.js v18+ Installed automatically by setup.sh
RAM 1 GB 2 GB+ recommended for concurrent clips

One-Command Install

git clone https://github.com/raimohan/raixyt.git
cd raixyt
chmod +x setup.sh
./setup.sh

The setup script automatically installs:

Component Purpose
Node.js 20 Runtime for backend + bot
yt-dlp Video extraction (private virtualenv)
ffmpeg Audio/video muxing & clip re-encoding
Deno YouTube n-challenge solver
PM2 Process manager — keeps everything alive 24/7

Configure

After setup, edit .env with your tokens:

# Required
BOT_TOKEN=your-token-from-botfather
OWNER_ID=your-telegram-numeric-id

# AI (free tier is enough)
GROQ_API_KEY_1=your-groq-api-key

Then start:

./setup.sh --start

💡 Tip: Send /id to your bot (or to @userinfobot) to find your numeric Telegram ID.

Setup Modes

./setup.sh                # Full install + start
./setup.sh --no-start     # Install only, configure later
./setup.sh --start        # Skip install, just (re)start services
./setup.sh --update       # Update yt-dlp + npm deps + restart
./setup.sh --skip-apt     # Skip apt packages (re-runs)

⚙️ Configuration

All configuration lives in a single .env file. Copy from the template:

cp .env.example .env
📋 Full Environment Variable Reference

Telegram Bot

Variable Required Default Description
BOT_TOKEN ✅ — Token from @BotFather
OWNER_ID ✅ — Your numeric Telegram ID
ADMIN_IDS — Comma-separated admin IDs
OPEN_ACCESS false Set true to allow anyone
BOT_NAME RaiX Studio Shown in the welcome screen

Backend API

Variable Required Default Description
PORT 3000 API server port
API_BASE http://127.0.0.1:3000 Bot → backend URL
ADMIN_TOKEN — Token for /api/admin/* routes

AI Provider

Variable Default Description
GROQ_API_KEY_1 … _10 — Up to 10 Groq keys (auto-rotate)
GROQ_MODEL llama-3.3-70b-versatile Primary model
GROQ_MODEL_FALLBACKS llama-3.3-70b-versatile,llama-3.1-8b-instant Fallback chain
AI_PROVIDER auto-detect Force groq or openrouter
OPENROUTER_API_KEY_1 … _5 — Up to 5 OpenRouter keys

Performance Tuning

Variable Default Description
MAX_UPLOAD_MB 49 Telegram's 50 MB bot upload limit
MAX_CONCURRENT_JOBS 2 Simultaneous heavy jobs
THROTTLE_MAX 4 Rate limit per window
THROTTLE_WINDOW_MS 1000 Rate limit window
API_TIMEOUT_MS 180000 API call timeout
DOWNLOAD_IDLE_TIMEOUT_MS 240000 Stalled transfer timeout

🏗 Architecture

raixyt/
│
├── backend.js                 # Express API server (yt-dlp + AI + clips)
├── ecosystem.config.js        # PM2 process definitions
├── setup.sh                   # One-shot installer
├── package.json
├── .env.example               # Configuration template
│
└── bot/                       # Telegram bot (Telegraf)
    ├── index.js               # Entry point, middleware, graceful shutdown
    ├── config.js              # Environment parsing & validation
    │
    ├── api/
    │   └── client.js          # Typed HTTP wrapper over backend.js
    │
    ├── core/
    │   ├── router.js          # Callback/text/document dispatch + error boundary
    │   ├── flow.js            # Shared "send me a link / text" prompts
    │   ├── cache.js           # Token store for oversized callback payloads
    │   ├── session.js         # Per-user state & chat history
    │   └── queue.js           # Concurrency limiter for heavy jobs
    │
    ├── middleware/
    │   ├── auth.js            # Access gate (owner → admin → user)
    │   └── throttle.js        # Per-user rate limiter
    │
    ├── services/
    │   ├── users.js           # User registry & persistence
    │   ├── prefs.js           # Per-user preferences
    │   ├── stats.js           # Usage counters
    │   └── downloads.js       # Streaming download pipeline
    │
    ├── ui/
    │   ├── render.js          # Message renderer & progress bars
    │   ├── keyboards.js       # Inline keyboard builder
    │   └── text.js            # Shared copy & formatting
    │
    └── features/              # Self-registering feature modules
        ├── home.js            # Main menu & welcome screen
        ├── video.js           # 🎬 Video search & download
        ├── music.js           # 🎵 Music search & download
        ├── downloader.js      # ⬇️ Universal link downloader
        ├── clip.js            # ✂️ Clip Studio (trim + reframe)
        ├── subtitles.js       # 📝 Subtitle extraction
        ├── ai.js              # 🧠 AI Studio (summarize, tags, titles, descriptions)
        ├── study.js           # 📚 Study tools (quiz, flashcards, notes, plan)
        ├── chat.js            # 💬 Video Chat (conversational Q&A)
        ├── analytics.js       # 📊 Channel & video insights
        ├── course.js          # 🎓 Course discovery
        ├── settings.js        # ⚙️ User preferences
        └── admin.js           # 🛠 Owner Panel (users, cookies, services)

How It Works

┌──────────────┐      HTTP/JSON      ┌──────────────────┐
│              │ ◄──────────────────► │                  │
│  Telegram    │                     │   backend.js     │
│  Bot (bot/)  │                     │   (Express API)  │
│              │                     │                  │
│  • Telegraf  │                     │  • yt-dlp        │
│  • Buttons   │                     │  • ffmpeg        │
│  • Sessions  │                     │  • Groq/OpenRouter│
│  • Progress  │                     │  • Cron jobs     │
│              │                     │                  │
└──────┬───────┘                     └────────┬─────────┘
       │                                      │
       │  Telegram Bot API                    │  Spawns
       ▼                                      ▼
  ┌──────────┐                         ┌─────────────┐
  │ Telegram │                         │ yt-dlp      │
  │ Servers  │                         │ ffmpeg      │
  └──────────┘                         │ deno/node   │
                                       └─────────────┘

Adding a feature = one file in bot/features/, register routes with router.onMany({...}), add a button to the home menu. Nothing else changes.

🔧 Commands

Telegram Commands

Command Description
/start Open the main menu
/menu Back to the main menu
/id Show your Telegram ID
/cancel Cancel the current action

PM2 Management

pm2 logs raix-bot          # Follow bot logs
pm2 logs raix-api          # Follow API logs
pm2 restart raix-bot       # Restart the bot
pm2 restart raix-api       # Restart the API
pm2 monit                  # Live CPU/RAM dashboard
pm2 status                 # Process overview

💡 Pro tip: The Owner Panel can restart either service directly from your phone — no SSH needed.

🍪 Cookie Management

The backend uses Netscape-format cookie files for authenticated downloads.

File Platforms
youtube.txt YouTube, Twitter/X, TikTok, Facebook, Vimeo, Pinterest, Snapchat
instagram.txt Instagram

How to Update Cookies

  1. Install a "Get cookies.txt LOCALLY" browser extension
  2. Log in to the platform and export cookies
  3. Upload via Telegram: Owner Panel → 🍪 Cookies → Upload

The file is validated, written with 0600 permissions, and picked up immediately — no restart needed.

⚠️ Warning: An empty cookie file is worse than none — yt-dlp aborts on a rejected jar instead of falling back to anonymous access. Delete empty cookie files.

🔌 Supported Platforms

Platform Download Cookies Needed
YouTube ✅ Recommended
Instagram ✅ Required
Twitter / X ✅ Recommended
TikTok ✅ Optional
Facebook ✅ Optional
Vimeo ✅ Optional
Pinterest ✅ Optional
Snapchat ✅ Optional

Powered by yt-dlp — any site yt-dlp supports will work.

🐛 Troubleshooting

Bot starts then exits immediately

BOT_TOKEN or OWNER_ID is missing or invalid.

pm2 logs raix-bot --lines 20

Check .env for empty values. Get a fresh token from @BotFather.

"The backend is not reachable"

The API server isn't running.

pm2 start raix-api
curl http://localhost:3000/health
Every YouTube download fails

Usually means no JavaScript runtime for the YouTube n challenge solver.

./deno --version        # Should print deno version
./setup.sh --update     # Re-install if missing

Check logs for: "n challenge solving failed" — this confirms the runtime is missing.

"Sign in to confirm you're not a bot"

Cookies are stale. Re-export from your browser and upload via Owner Panel → Cookies.

Downloads are slow

Expected on a Raspberry Pi for 1080p — yt-dlp downloads video + audio separately, then ffmpeg muxes them. 720p is ~3× faster.

Out-of-memory restarts

Lower the concurrency in .env:

MAX_CONCURRENT_JOBS=1

🤝 Contributing

Contributions are welcome! Here's how:

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

Development

# Check all files for syntax errors
npm run check

# Start the backend only
npm start

# Start the bot only
npm run bot

📄 License

This project is open source. See the LICENSE file for details.

👤 Author

raimohan
@raimohan

If you found this useful, consider giving it a ⭐

GitHub

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages