PaiSong - Professional Music Streaming App

🎵 A modern, Spotify-inspired music streaming application that searches and streams high-quality FLAC audio files from Telegram channels.

✨ Features

🎨 Professional UI & UX

• 🎯 Spotify-Inspired Design: Modern dark theme with professional layout
• 📱 Fully Responsive: Mobile-first design that works on all devices
• 🌟 Glass Morphism Effects: Beautiful translucent UI elements
• 🎭 Smooth Animations: Professional loading states and transitions
• 🖱️ Touch Optimized: Gesture support and touch-friendly controls

🎵 Advanced Music Features

• 🔍 Smart Search: Intelligent search for FLAC audio files in Telegram channels
• ⚡ Instant Streaming: Zero-wait playback with range request support
• � Queue Management: Full queue system with shuffle and repeat modes
• 🎚️ Professional Player: Complete audio controls with seek, volume, and progress
• 🔄 Background Playback: Continues playing when app loses focus
• 🎛️ Media Session API: System media controls and lock screen integration

📱 Progressive Web App (PWA)

• 💾 Installable: Install as native app on mobile and desktop
• 🌐 Offline Support: Service worker with intelligent caching
• 🔔 Push Notifications: Background sync and updates
• 📲 App-like Experience: Full-screen mode and native feel

⚡ Performance Optimized

• 🚀 Fast Streaming: Direct Telegram streaming without full downloads
• 🧠 Smart Preloading: Background loading of next tracks for seamless playback
• 💾 Intelligent Caching: Concurrent downloads with background optimization
• 📊 Real-time Metrics: Health monitoring and performance tracking
• � Range Requests: HTTP range support for instant playback

🔒 Secure & Reliable

• 🛡️ Official Telegram API: Uses Pyrogram with proper authentication
• 🔐 Session Management: Secure credential handling
• 🌐 CORS Support: Proper API security and access control

Technology Stack

• Backend: FastAPI (Python)
• Telegram API: Pyrogram
• Frontend: HTML5 + CSS3 + JavaScript + Howler.js
• Audio Streaming: Real-time FLAC streaming
• Templating: Jinja2

Prerequisites

1. Python 3.8+ installed on your system
2. Telegram API credentials from my.telegram.org
3. Access to a Telegram channel containing .flac files

Installation & Setup

1. Clone and Install Dependencies

# Install Python dependencies
pip install -r requirements.txt

2. Configure Environment Variables

1. Copy the example environment file:

   cp .env.example .env

2. Edit .env and fill in your credentials:

   # Get these from https://my.telegram.org/apps
   TG_API_ID=your_api_id_here
   TG_API_HASH=your_api_hash_here
   
   # Session name (creates a .session file)
   SESSION_NAME=paisong_session
   
   # Target channel (username like @channel or channel ID)
   TG_CHANNEL=@your_channel_here
   
   # Cache directory for downloaded files
   CACHE_DIR=./cache

3. Get Telegram API Credentials

1. Go to my.telegram.org
2. Log in with your phone number
3. Create a new application
4. Copy your API ID and API Hash
5. Add these to your .env file

4. Run the Application

# Start the FastAPI server
uvicorn server:app --reload

The application will be available at: http://localhost:8000

Usage

Web Interface

1. Open http://localhost:8000 in your browser
2. Enter your search query in the search box
3. Click "SEARCH" to find .flac files
4. Click "PLAY" on any result to load the audio player
5. Use the audio controls to play, pause, seek, and adjust volume

API Endpoints

Search for Audio Files

GET /search?query=your_search_term&limit=50

Response:

{
  "query": "your_search_term",
  "results": [
    {
      "id": 12345,
      "filename": "song.flac",
      "text": "Description text",
      "date": "2024-01-15T10:30:00",
      "file_size": 45678912,
      "duration": 245,
      "stream_url": "/stream/12345"
    }
  ],
  "total": 1
}

Stream Audio File

GET /stream/{message_id}

Returns a streamable FLAC audio file.

Health Check

GET /health

Response:

{
  "status": "healthy",
  "telegram_client": "connected",
  "cache_dir": "./cache",
  "cached_files": 5
}

Configuration Options

Environment Variables

Variable	Description	Example
TG_API_ID	Telegram API ID	12345678
TG_API_HASH	Telegram API Hash	abcdef1234567890
SESSION_NAME	Session file name	paisong_session
TG_CHANNEL	Target channel	@musicchannel
CACHE_DIR	Cache directory path	./cache

Search Parameters

Parameter	Type	Default	Description
query	string	required	Search term
limit	integer	50	Max results to return

File Structure

PaiSong/
├── server.py              # FastAPI server with Pyrogram
├── requirements.txt       # Python dependencies
├── .env.example          # Environment variables template
├── .env                  # Your actual environment variables (create this)
├── README.md             # This file
├── templates/
│   └── index.html        # Frontend HTML template
├── cache/                # Downloaded files cache (auto-created)
└── *.session            # Telegram session files (auto-created)

Development

Running in Development Mode

# With auto-reload
uvicorn server:app --reload --host 0.0.0.0 --port 8000

# With custom port
uvicorn server:app --reload --port 8080

Debug Mode

Set environment variable for detailed logging:

export PYTHONPATH=.
uvicorn server:app --reload --log-level debug

Troubleshooting

Common Issues

1. "Telegram client not initialized"

   • Check your TG_API_ID and TG_API_HASH in .env
   • Make sure the session file has proper permissions
   • Try deleting the .session file and restart

2. "Audio message not found"

   • Verify the channel name/ID is correct
   • Ensure you have access to the channel
   • Check if the message still exists

3. "Failed to download file"

   • Check internet connection
   • Verify cache directory permissions
   • Ensure sufficient disk space

4. Audio won't play

   • Check browser console for errors
   • Try a different browser (Chrome/Firefox recommended)
   • Verify the file is actually a valid FLAC file

Performance Tips

• Cache Management: Cached files help performance but can consume disk space
• Search Limits: Use reasonable search limits to avoid timeouts
• Channel Size: Large channels may take longer to search

Security Notes

• Keep your .env file secure - never commit it to version control
• API credentials are sensitive - don't share them
• Session files contain authentication data - keep them private
• The app only accesses public channel content you have access to

License

This project is for educational and personal use. Make sure you comply with Telegram's Terms of Service when using their API.

---

Enjoy discovering and streaming your favorite FLAC audio files! 🎵