docs: add comprehensive english readme with project structure

2026-05-28 07:03:45 +03:00
parent 7441030330
commit 723aea5b04
1 changed files with 80 additions and 0 deletions
@@ -0,0 +1,80 @@
+# Premium Glassmorphic YouTube Video & MP3 Downloader
+
+A sleek, modern, and high-performance desktop application built with Electron.js that downloads YouTube videos and extracts/converts them into high-quality MP3 audio tracks. Designed with state-of-the-art Glassmorphic aesthetics, fluid micro-animations, and a highly intuitive user interface.
+
+---
+
+## 🌟 Features
+
+*   **Dual Mode Support:** Download either full videos (MP4) or extract audio directly to high-quality MP3.
+*   **Aesthetic UI:** Premium Glassmorphic design with custom styling, custom scrollbars, vibrant gradient accent systems, and smooth transitions.
+*   **Dependency Engine:** Integrated checker for `yt-dlp` and `ffmpeg` to ensure the download and conversion utilities are always ready and verified.
+*   **Active Monitoring:** Live feedback on download progress, speed, file size, and estimated time remaining (ETA).
+*   **Safe Execution:** Implements Electron IPC context isolation to keep application security at a premium.
+
+---
+
+## 📂 Project Structure
+
+```text
+youtube-downloader/
+├── .gitignore               # Configured to exclude heavy binaries & node_modules
+├── README.md                # Project documentation and guide
+├── main.js                  # Electron main process (lifecycle & IPC registration)
+├── preload.js               # IPC bridge exposing safe downloader context to renderer
+├── package.json             # App scripts and dependencies
+├── docs/
+│   └── implementation-plan.md # Development layout & modular plan
+├── src/
+│   ├── index.html           # Main user interface structured with semantic HTML5
+│   ├── style.css            # Premium CSS tokens, animations, and glassmorphic designs
+│   └── renderer.js          # Client-side UI controllers and IPC event listeners
+└── utils/
+    └── downloader.js        # Core Downloader Engine handling child processes for yt-dlp/ffmpeg
+```
+
+---
+
+## 🛠️ Prerequisites
+
+The application uses **yt-dlp** and **FFmpeg** as the engine backends. For convenience, these should be placed in a `bin` directory inside the project root:
+
+1.  Create a `bin/` directory in the root if it does not exist.
+2.  Download the latest [yt-dlp executable](https://github.com/yt-dlp/yt-dlp/releases) and place `yt-dlp.exe` in the `bin/` folder.
+3.  Download [FFmpeg static build](https://ffmpeg.org/download.html) and place `ffmpeg.exe` in the `bin/` folder.
+
+*(Note: The `bin/` directory is automatically ignored by Git to avoid tracking large executables).*
+
+---
+
+## 🚀 Getting Started
+
+### 1. Installation
+
+Clone the repository and install the development dependencies:
+
+```bash
+npm install
+```
+
+### 2. Development Mode
+
+Run the following command to start the Electron desktop application:
+
+```bash
+npm start
+```
+
+---
+
+## ⚙️ How It Works
+
+1.  **Dependency Verification:** Upon launch, the backend checks for the presence and validity of `yt-dlp.exe` and `ffmpeg.exe` in the `bin` directory.
+2.  **Metadata Fetching:** When you paste a YouTube link, the downloader retrieves video metadata (title, thumbnail, duration, etc.) and displays a rich media preview.
+3.  **Process Spawning:** Depending on the chosen format (Video/MP3), the downloader spawns a customized background process tracking real-time status and pipe-feeds it to the UI via Electron IPC events.
+
+---
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).