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:
    ```bash
    cd hcy_audiobot_clone/frontend
    ```

2.  Install the dependencies:
    ```bash
    npm install
    # or
    yarn install
    ```

3.  Start the development server:
    ```bash
    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:
    ```bash
    cd hcy_audiobot_clone/backend
    ```

2.  Create a virtual environment (recommended):
    ```bash
    python3 -m venv venv
    source venv/bin/activate
    ```

3.  Install the dependencies:
    ```bash
    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:
    ```bash
    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:
    ```bash
    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 `BiquadFilterNode`s 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.