README.md

---
title: Bird Detection
emoji: 🦀
colorFrom: purple
colorTo: pink
sdk: gradio
sdk_version: 5.23.3
app_file: app.py
pinned: false
---

# 🐦 台灣常見鳥類偵測系統

一個以 YOLO 模型為基礎，搭配 Gradio UI 介面，支援 **圖片、影片、網路攝影機** 鳥類偵測的互動式應用系統。  
偵測結果將自動搜尋 YouTube 生態影片並產生 QR Code，可直接觀看鳥類相關影片。

---

## 🚀 功能介紹

- 📸 圖片上傳即時鳥類辨識
- 🎞️ 影片檔偵測與即時標註
- 🔴 YouTube 直播偵測（可選）
- 📷 即時攝影機串流偵測（可選）
- 🔎 自動搜尋對應 YouTube 生態影片
- 🧾 自動產生影片 QR Code 嵌入

---

## 🧠 模型資訊

- 使用模型：`YOLOv8`（ultralytics）
- 訓練資料：187 種台灣常見鳥類
- 欄位來源：`multibird_dataset.yaml`
- 欲替換模型請放置於 `best.pt`

---

## 📦 安裝套件需求

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

### 其他建議安裝（支援 YouTube 串流）：

```bash
pip install streamlink youtube-dl
```

---

## 🖼️ 使用方式

### 1. 執行主程式

```bash
python app.py
```

預設啟動在 `http://localhost:7860`  
你也可以使用 `gradio` 參數將其公開，例如透過：

```python
demo.launch(share=True, server_name="0.0.0.0", pwa=True)
```

### 2. 操作流程

| 模式 | 說明 |
|------|------|
| 📷 圖片偵測 | 上傳圖片即可自動辨識鳥種並產生影片連結與 QR Code |
| 🎞️ 影片偵測 | 上傳影片後進行即時物件偵測與視覺化 |

---

## 🌐 API & 金鑰設定

請設置環境變數以使用 YouTube Data API：

```bash
export YOUTUBE_API_KEY=你的金鑰
```

或在 `.env` 中設置。

---

## 📁 專案結構

```
.
├── app.py                 # 主程式
├── best.pt                # 訓練好的 YOLO 模型
├── multibird_dataset.yaml # 分類類別名稱
├── requirements.txt       # 套件需求
├── results/               # 偵測結果輸出影片
└── assets/                # 圖片與 QR Code
```

---

## 📱 PWA 支援

本系統已支援 Progressive Web App（PWA），可在手機或瀏覽器中：

- 加入主畫面
- 離線瀏覽 Gradio 頁面框架（UI 顯示）

---

## 🧩 已知問題

- 若 Hugging Face Space 出現未更新、無法 build 的情況，請點選 **Restart Space**。
- YouTube 串流須視 `streamlink/youtube-dl` 是否正確安裝，或 API 金鑰授權。

---

## 🔗 技術整合

- [Ultralytics YOLOv11](https://docs.ultralytics.com/)
- [Gradio](https://gradio.app/)
- [YouTube Data API](https://developers.google.com/youtube/v3)
- [Hugging Face Spaces](https://huggingface.co/spaces)
- [Streamlink](https://streamlink.github.io/)
- [QRCode](https://pypi.org/project/qrcode/)

--

## 🧠 補充：常見鳥類中英對照

預載 `bird_chinese_names` 包含 187 台灣鳥種，會自動將 YOLO 偵測結果轉換為中文後搜尋 YouTube。