This commit is contained in:
Ubuntu
2026-07-03 16:58:28 +08:00
commit 32b43f85bd
6240 changed files with 1987678 additions and 0 deletions
+271
View File
@@ -0,0 +1,271 @@
# 📚 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