# 📚 Audiobook Player 使用说明

> 极简沉浸式有声书 Web 应用

---

## 🌐 访问地址

```
http://129.211.173.87:8899
```

---

## 🚀 服务管理

### 使用 Systemd 管理（推荐）

```bash
# 启动服务
sudo systemctl start audiobook-player

# 停止服务
sudo systemctl stop audiobook-player

# 重启服务
sudo systemctl restart audiobook-player

# 查看状态
sudo systemctl status audiobook-player

# 设置开机自启
sudo systemctl enable audiobook-player

# 取消开机自启
sudo systemctl disable audiobook-player
```

### 查看日志

```bash
# 实时日志
sudo journalctl -u audiobook-player -f

# 最近 100 行
sudo journalctl -u audiobook-player -n 100
```

---

## 🛠️ 安装/卸载服务

### 安装服务（首次使用）

```bash
cd ~/nanocode/audiobook-player

# 1. 复制服务文件到系统目录
sudo cp audiobook-player.service /etc/systemd/system/

# 2. 重新加载 systemd
sudo systemctl daemon-reload

# 3. 启动服务
sudo systemctl start audiobook-player

# 4. 设置开机自启（可选）
sudo systemctl enable audiobook-player

# 5. 检查状态
sudo systemctl status audiobook-player
```

### 卸载服务

```bash
# 1. 停止并禁用
sudo systemctl stop audiobook-player
sudo systemctl disable audiobook-player

# 2. 删除服务文件
sudo rm /etc/systemd/system/audiobook-player.service

# 3. 重新加载
sudo systemctl daemon-reload
```

---

## 📂 项目结构

```
~/nanocode/audiobook-player/
├── app.py                      # Flask 主程序
├── audiobook-player.service    # Systemd 服务配置
├── requirements.txt            # Python 依赖
├── USAGE.md                    # 本文档
├── templates/                  # HTML 模板
│   ├── index.html             # 首页-来源选择
│   ├── list.html              # 列表-故事列表
│   └── player.html            # 播放器-播放+内容
└── static/                    # 静态资源
    ├── css/style.css         # 样式（米白/深黑主题）
    └── js/app.js             # 交互逻辑
```

---

## 📚 数据来源

服务自动扫描 `/home/ubuntu/media/` 目录：

```
/home/ubuntu/media/
├── libraryofshortstories/     # 英语短篇故事
│   ├── the-1000000-bank-note/
│   │   ├── content.txt
│   │   └── metadata.md
│   └── ...
└── public-domain-poetry/      # 公共领域诗歌（可扩展）
    └── ...
```

**注意**：添加新来源只需在 `/home/ubuntu/media/` 下创建目录即可。

---

## 🎮 功能说明

### 三页面架构

| 页面 | 路径 | 功能 |
|------|------|------|
| 首页 | `/` | 显示所有内容来源（大卡片） |
| 列表 | `/list/<source>` | 该来源下的故事列表 |
| 播放 | `/play/<source>/<story>` | 播放器 + 文章阅读 |

### 播放器特性

- **固定播放器**：顶部 100px，磨砂玻璃效果
- **流式 TTS**：实时朗读，无需等待完整转换
- **懒加载内容**：长文章分段加载，流畅滑动
- **主题切换**：米白/深黑双主题（点击 🌙/☀️ 切换）
- **阅读进度**：自动保存到 localStorage
- **手势支持**：滑动返回（移动端）
- **独立导航**：返回/关闭按钮，适合 App 内嵌

---

## 🔧 配置说明

### 修改端口

如需修改端口，编辑 `app.py`：

```python
# 默认 8899
app.run(host="0.0.0.0", port=8899, debug=False, threaded=True)
```

然后重启服务：

```bash
sudo systemctl restart audiobook-player
```

### 修改数据目录

如需修改扫描目录，编辑 `app.py`：

```python
MEDIA_DIR = Path("/your/custom/path")
```

---

## 🐛 故障排查

### 服务无法启动

```bash
# 检查端口占用
sudo lsof -i :8899

# 检查日志
sudo journalctl -u audiobook-player -n 50

# 手动测试运行
cd ~/nanocode/audiobook-player
python3 app.py
```

### 页面显示空白

```bash
# 检查媒体目录是否存在
ls -la /home/ubuntu/media/

# 检查目录权限
ls -la ~/nanocode/audiobook-player/static/
```

### TTS 无法播放

```bash
# 检查 edge-tts 是否正常
python3 -c "import edge_tts; print('OK')"

# 测试单个请求
curl "http://129.211.173.87:8899/api/stream?text=hello"
```

---

## 📱 App 内嵌示例

### iOS (WKWebView)

```swift
import WebKit

let webView = WKWebView()
let url = URL(string: "http://129.211.173.87:8899")!
webView.load(URLRequest(url: url))
```

### Android (WebView)

```kotlin
val webView: WebView = findViewById(R.id.webview)
webView.loadUrl("http://129.211.173.87:8899")
```

**特点**：
- 每页独立返回按钮
- 无浏览器地址栏干扰
- 响应式布局适配

---

## 🔒 安全提示

- 服务监听 `0.0.0.0`，所有网卡可访问
- 如需限制访问，可配置防火墙：

```bash
# 只允许本地访问（如需修改）
sudo ufw allow from 127.0.0.1 to any port 8899
```

---

## 📝 更新记录

| 日期 | 版本 | 说明 |
|------|------|------|
| 2026-03-27 | v1.0 | 初始版本，支持流式 TTS、主题切换、懒加载 |

---

## 💡 后续计划

- [ ] 播放速度调节
- [ ] 阅读进度云端同步
- [ ] 收藏功能
- [ ] 多语言语音切换

---

**维护者**: nanobot  
**创建时间**: 2026-03-27