# interactive-pdf-reader

**Repository Path**: Jackzhou1/interactive-pdf-reader

## Basic Information

- **Project Name**: interactive-pdf-reader
- **Description**: 基于 Flask 的交互式 PDF 阅读器，支持仿真翻页效果，点击文字/图片即可跳转播放关联视频。


- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-04
- **Last Updated**: 2026-04-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Interactive PDF Reader

<div align="center">

![PDF](https://img.shields.io/badge/PDF-Reader-red?style=for-the-badge)
![Flask](https://img.shields.io/badge/Flask-Powered-green?style=for-the-badge&logo=flask)
![MySQL](https://img.shields.io/badge/MySQL-Backend-orange?style=for-the-badge&logo=mysql)
![JavaScript](https://img.shields.io/badge/JavaScript-Interactive-yellow?style=for-the-badge&logo=javascript)

**📖 Read PDFs. 🎬 Watch Videos. One Click.**

</div>

---

## 🚀 What Is This?

> **Imagine reading a PDF textbook** — you see a term you don't understand.  
> **Instead of Googling**, you just *click the word* → **Boom!** A video explanation pops up.

This isn't just a PDF reader. It's a **multimedia learning machine**.

```
┌─────────────────────────────────────────────────────────────┐
│                    INTERACTIVE PDF ENGINE                   │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   📄 PDF Page           🔗 Click "docker"                  │
│   ┌───────────────┐                                         │
│   │  Docker is a  │ ──────▶ 🎬 Video plays instantly       │
│   │  container... │                                         │
│   └───────────────┘                                         │
│                                                             │
│   🖼️ Image Detected      🔗 Click image      ▶ 🎬 Video    │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## ⚡ Features

| Feature | Description |
|---------|-------------|
| 📚 **Realistic Page Turning** | Powered by turn.js — flip pages like a real book |
| 🖱️ **Click-to-Play Video** | Bind keywords to video URLs, click any word to watch |
| 🖼️ **Image Hotspots** | Images in PDFs can trigger video popups too |
| 🗄️ **MySQL Backend** | Persistent storage for PDFs, keywords, and video links |
| 🎨 **Modern UI** | Tailwind CSS + custom animations for a clean experience |
| 🔧 **Manager Panel** | Web-based admin interface to manage keyword→video mappings |

---

## 🛠️ Tech Stack

```
┌────────────────────────────────────────────────────────┐
│                     TECH ARCHITECTURE                   │
├────────────────────────────────────────────────────────┤
│                                                         │
│   FRONTEND                BACKEND           DATABASE    │
│   ├── HTML5               ├── Flask (Python) ├── MySQL  │
│   ├── Tailwind CSS        ├── PyMySQL        │          │
│   ├── jQuery              └── python-dotenv  │          │
│   ├── PDF.js                                              │
│   └── turn.js                                             │
│                                                         │
└────────────────────────────────────────────────────────┘
```

**Core Dependencies:**
- `Flask==2.0.1`
- `PyMySQL==1.0.2`
- `python-dotenv==0.19.0`

---

## 📦 Installation

### 1. Clone the Repository

```bash
git clone https://github.com/JackZho/interactive-pdf-reader.git
cd interactive-pdf-reader
```

### 2. Install Python Dependencies

```bash
pip install -r requirements.txt
```

### 3. Setup MySQL Database

```sql
-- Create database
CREATE DATABASE pdf_reader CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- Import schema
source pdf_reader.sql
```

### 4. Configure Environment

Copy `.env.example` (or create new `.env`):

```env
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DB=pdf_reader
FLASK_ENV=development
FLASK_APP=app.py
```

### 5. Run the Server

```bash
# Option 1: Direct run
python app.py

# Option 2: Use batch file (Windows)
run.bat
```

🌐 **Access the app:** `http://localhost:5000`  
🔧 **Manager panel:** `http://localhost:5000/manager`

---

## 📖 Usage Guide

### Adding a PDF

1. Put PDF file in `static/pdfs/`
2. Insert record into `pdfs` table:
   ```sql
   INSERT INTO pdfs (filename, filepath) 
   VALUES ('mybook.pdf', 'static/pdfs/mybook.pdf');
   ```

### Binding Keywords to Videos

1. Open **Manager Panel** at `/manager`
2. Click **Add Link** button
3. Enter keyword (e.g., `docker`) and video URL
4. Save — now clicking "docker" in any PDF plays that video!

### Supported Video Sources

- Remote URLs: `https://example.com/video.mp4`
- Local paths: `./static/videos/tutorial.mp4`
- Embedded players: Any iframe-compatible URL

---

## 🎯 API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/pdfs` | List all PDFs |
| `GET` | `/api/pdf/<id>` | Get PDF info |
| `GET` | `/api/keywords` | Get all keywords |
| `GET` | `/api/video/<keyword>` | Get video URL for keyword |
| `GET` | `/api/video_links` | List all video links |
| `POST` | `/api/video_links` | Add video link |
| `PUT` | `/api/video_links/<id>` | Update video link |
| `DELETE` | `/api/video_links/<id>` | Delete video link |

---

## 📁 Project Structure

```
interactive-pdf-reader/
├── app.py                 # Flask main application
├── requirements.txt       # Python dependencies
├── pdf_reader.sql        # Database schema + sample data
├── .env                  # Environment configuration
├── templates/
│   ├── index.html        # Main reader UI
│   └── manager.html      # Admin panel
├── static/
│   ├── css/
│   │   └── style.css     # Custom styles
│   ├── js/
│   │   └── main.js       # Core reader logic
│   ├── pdfs/             # PDF files directory
│   ├── imgs/             # Image assets
│   └── videos/           # Local video files
└── run.bat               # Quick start script (Windows)
```

---

## 🔥 Demo Screenshots

```
┌─────────────────────────────────────────────────────────┐
│                                                         │
│   ┌─────────────────┐  ┌─────────────────────────────┐ │
│   │ 📁 PDF List     │  │      PDF Reader View        │ │
│   │                 │  │                             │ │
│   │ ├ 1900.pdf      │  │   ╔═════════════════════╗   │ │
│   │ ├ 123.pdf       │  │   ║                     ║   │ │
│   │ └ 这是一个...   │  │   ║   Click any word    ║   │ │
│   │                 │  │   ║   → Video popup!    ║   │ │
│   └─────────────────┘  │   ║                     ║   │ │
│                        │   ╚═════════════════════╝   │ │
│                        └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```

---

## 🐛 Troubleshooting

| Issue | Solution |
|-------|----------|
| PDF not loading | Check `static/pdfs/` path and database `filepath` field |
| Video not playing | Ensure URL is accessible and iframe-compatible |
| Database connection failed | Verify MySQL is running and `.env` credentials are correct |
| turn.js not working | Check internet connection for CDN resources |

---

## 🤝 Contributing

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

---

## 📄 License

This project is licensed under the **MIT License**. See [LICENSE](LICENSE) file for details.

---

## 👨‍💻 Author

<div align="center">

**JackZhou**

[![GitHub](https://img.shields.io/badge/GitHub-JackZho-181717?style=for-the-badge&logo=github)](https://github.com/JackZho)
[![Gitee](https://img.shields.io/badge/Gitee-Jackzhou1-C71D23?style=for-the-badge&logo=gitee)](https://gitee.com/Jackzhou1)

</div>

---

<div align="center">

**Made with ❤️ by JackZhou**

⭐ Star this repo if you find it useful!

```
   ╔═══════════════════════════════════════════╗
   ║  📖 Read More · 🎬 Watch More · Learn More ║
   ╚═══════════════════════════════════════════╝
```

</div>