README.md

HCY Audio System Clone

This project aims to replicate the functionality of the HCY Audio System Telegram Mini App. It consists of two main parts:

1. Frontend (React App): A web application that provides the audio system simulator interface, including an audio player, visualizer, and equalizer controls.
2. Backend (Telegram Bot): A Python Telegram bot that serves as the entry point for the Mini App.

Project Structure

hcy_audiobot_clone/
├── frontend/             # React web application
│   ├── public/
│   ├── src/
│   │   ├── App.css
│   │   ├── App.js
│   │   ├── index.css
│   │   └── index.js
│   ├── .gitignore
│   ├── package.json
│   └── README.md
├── backend/              # Python Telegram bot
│   ├── bot.py
│   └── requirements.txt
└── README.md             # This file

Setup and Running Instructions

1. Frontend (React App)

This is the web application that will be embedded as a Telegram Mini App. It provides the user interface for the audio system simulator.

Prerequisites:

• Node.js (LTS version recommended)
• npm or yarn

Steps:

1. Navigate to the frontend directory:

   cd hcy_audiobot_clone/frontend
   

2. Install the dependencies:

   npm install
   # or
   yarn install
   

3. Start the development server:

   npm start
   # or
   yarn start
   

   This will usually open the app in your browser at http://localhost:3000.

4. Deployment: For the Telegram Mini App to work, the frontend application needs to be hosted on a publicly accessible URL (e.g., Vercel, Netlify, GitHub Pages, or your own server). Once deployed, copy the URL of your deployed application. This URL will be used in the backend bot configuration.

2. Backend (Telegram Bot)

This is the Python bot that interacts with the Telegram API and launches the Mini App.

Prerequisites:

• Python 3.8+
• A Telegram Bot Token (obtainable from BotFather on Telegram)

Steps:

1. Navigate to the backend directory:

   cd hcy_audiobot_clone/backend
   

2. Create a virtual environment (recommended):

   python3 -m venv venv
   source venv/bin/activate
   

3. Install the dependencies:

   pip install -r requirements.txt
   

4. Configure Environment Variables: You need to set two environment variables:

   • TELEGRAM_BOT_TOKEN: Your bot token obtained from BotFather.
   • WEB_APP_URL: The public URL where your frontend React app is hosted (from step 4 of Frontend deployment).

   You can set these in your terminal before running the bot:

   export TELEGRAM_BOT_TOKEN="YOUR_BOT_TOKEN_HERE"
   export WEB_APP_URL="https://your-deployed-frontend-url.com"
   

   Replace YOUR_BOT_TOKEN_HERE and https://your-deployed-frontend-url.com with your actual values.

5. Run the bot:

   python bot.py
   

3. How to use the Telegram Mini App

1. Start your Telegram bot by sending the /start command.
2. The bot will send you a message with an "Open HCY Audio System" button.
3. Click the button to launch the Mini App directly within Telegram.

Code Explanation

Frontend (frontend/src/App.js)

• AudioContext and Nodes: Initializes the Web Audio API for audio processing. It sets up an AnalyserNode for visualization, GainNode for volume control, and BiquadFilterNodes for bass and treble adjustments.
• Audio Playback: A dummy MP3 file from soundhelix.com is used for demonstration. In a real application, you would allow users to upload or select their own audio files.
• Visualizer: Uses an HTML5 <canvas> element to draw a frequency bar graph based on the audio data from the AnalyserNode.
• Controls: Sliders for volume, bass, and treble allow real-time adjustment of the audio output.
• Telegram Mini App Integration: Includes a basic useEffect hook to initialize window.Telegram.WebApp, which is essential for the web app to function within Telegram.

Backend (backend/bot.py)

• python-telegram-bot library: Used to interact with the Telegram Bot API.
• /start command handler: When a user sends /start, the bot replies with an InlineKeyboardButton that contains a WebAppInfo object. This object specifies the WEB_APP_URL which points to your deployed React application.
• Environment Variables: The bot token and web app URL are loaded from environment variables for security and flexibility.

This setup provides a functional clone of the HCY Audio System, allowing users to interact with an audio simulator directly within Telegram. You can further enhance the frontend with more advanced audio features, UI/UX improvements, and integrate with actual audio file uploads.