tv_show_v1/README_API.md

LED 与 Kodi 控制接口文档（Flask API）

本项目提供一个基于 Flask 的 HTTP API 与网页界面，用于控制展品 LED 灯效与 Kodi 播放。

环境与运行

1. 安装依赖

   pip install -r requirements.txt
   

   1. 启动服务 bash python flask_api.py

或双击 start_server.bat

1. 访问
2. 网页界面：http://localhost:5000
3. API 根路径同上（默认端口 5000，已启用 CORS）

返回格式约定

• 所有接口均返回 JSON
• 统一字段：
  • success：布尔，是否成功
  • message：字符串，结果说明
  • data：对象，可选，承载具体数据

---

页面

• GET /
  • 返回 templates/index.html 页面

---

LED 灯效控制

• GET /api/led/status

  • 说明：获取当前 LED 灯效运行状态

  • 成功响应示例：

    {
    "success": true,
    "data": {
    "is_running": true,
    "message": "灯效正在运行"
    }
    }
    

    • POST /api/led/start
    • 说明：按展品 ID 启动灯效
    • 请求体（JSON）： json { "exhibit_id": 0 }

  • 校验：exhibit_id 必须为大于等于 0 的整数

  • 成功响应示例：

    {
    "success": true,
    "message": "展品 0 的灯效已启动",
    "data": { "exhibit_id": 0, "is_running": true }
    }
    

    • POST /api/led/stop
    • 说明：停止当前灯效
    • 成功响应示例： json { "success": true, "message": "灯效已停止", "data": { "is_running": false } }

---

Kodi 播放控制

• GET /api/kodi/status

  • 说明：获取 Kodi 播放线程状态

  • 成功响应示例：

    {
    "success": true,
    "data": {
    "is_running": false,
    "message": "Kodi播放线程已停止"
    }
    }
    

    • POST /api/kodi/start
    • 说明：启动或切换 Kodi 播放到指定 video_id
    • 请求体（JSON）： json { "video_id": 1 }

  • 校验：video_id 必须为大于等于 0 的整数

  • 成功响应示例：

    { "success": true, "message": "Kodi开始/切换播放 视频ID=1", "data": { "video_id": 1 } }
    

    • POST /api/kodi/stop
    • 说明：停止 Kodi 播放
    • 成功响应示例： json { "success": true, "message": "Kodi播放已停止" }

---

失败与错误码

• 参数缺失/非法：HTTP 400

  • 示例：

    { "success": false, "message": "缺少展品ID参数" }
    

    • 服务器内部错误：HTTP 500
    • 示例： json { "success": false, "message": "启动灯效失败: error detail" }

---

curl 示例

# LED 状态
curl -s http://localhost:5000/api/led/status | jq

# 启动 LED（展品ID=0）
curl -s -X POST http://localhost:5000/api/led/start \
  -H "Content-Type: application/json" \
  -d '{"exhibit_id": 0}' | jq

# 停止 LED
curl -s -X POST http://localhost:5000/api/led/stop | jq

# Kodi 状态
curl -s http://localhost:5000/api/kodi/status | jq

# 启动/切换 Kodi（视频ID=1）
curl -s -X POST http://localhost:5000/api/kodi/start \
  -H "Content-Type: application/json" \
  -d '{"video_id": 1}' | jq

# 停止 Kodi
curl -s -X POST http://localhost:5000/api/kodi/stop | jq

---

目录结构（节选）

LEDEffectFramework_V1/
├── flask_api.py          # Flask API 入口
├── application/
│   ├── wled_thread.py    # LED 业务逻辑入口
│   └── kodi_thread.py    # Kodi 业务逻辑入口
├── hardware/             # 硬件/控制模块
├── templates/
│   └── index.html        # 网页界面
├── requirements.txt
├── start_server.bat
└── README_API.md

备注

• 端口、跨域等在 flask_api.py 中配置，默认 0.0.0.0:5000
• 具体硬件行为取决于 application/* 与 hardware/* 实现