Falcon Player API完全手册：打造自定义灯光控制应用

【免费下载链接】fppFalcon Player项目地址: https://gitcode.com/gh_mirrors/fpp/fpp

Falcon Player（FPP）是一款功能强大的开源灯光控制软件，其提供的API接口为开发者和灯光爱好者打造自定义灯光控制应用提供了无限可能。通过FPP API，你可以轻松实现对灯光序列、播放列表、效果等的全面控制，让你的灯光秀更加个性化和智能化。

认识FPP API

FPP API是基于REST架构设计的接口集合，允许开发者通过HTTP请求与FPP系统进行交互。无论是创建自定义控制界面、集成第三方系统，还是实现自动化灯光控制，FPP API都能满足你的需求。

Falcon Player API接口展示 - 提供强大的灯光控制能力

FPP API的文档由PHPDoc注释自动生成，并通过Scalar在GET /api/端点提供。你可以在任何运行的FPP实例上访问http://<fpp-host>/api/来浏览完整的API文档。

API基础架构

FPP API的核心文件布局如下：

www/api/ ├── index.php # PHP路由器 — 映射URL到控制器函数 ├── openapi.json # 生成的API规范 — 不要手动编辑 ├── redoc.html # Scalar HTML界面 ├── controllers/ # 资源组控制器 │ ├── backups.php │ ├── cape.php │ ├── channel.php │ └── ... └── tools/ ├── generate_openapi.py # API文档生成器 └── build_docs.sh # 文档构建脚本

这种结构确保了API的可扩展性和可维护性，同时为开发者提供了清晰的接口调用路径。

核心API端点

FPP API提供了丰富的端点，涵盖了灯光控制的各个方面。以下是一些常用的核心端点：

播放列表管理

• 获取播放列表：GET /api/playlist/{PlaylistName}返回指定播放列表的详细信息。可通过mergeSubs参数递归合并子播放列表。

• 创建播放列表：POST /api/playlist创建新的播放列表，需要提供JSON格式的播放列表数据。

• 更新播放列表：PUT /api/playlist/{PlaylistName}更新指定的播放列表内容。

• 删除播放列表：DELETE /api/playlist/{PlaylistName}删除指定的播放列表。

序列控制

• 获取序列列表：GET /api/sequences返回所有可用的序列文件列表。

• 播放序列：POST /api/sequence/play开始播放指定的序列。

• 停止序列：POST /api/sequence/stop停止当前正在播放的序列。

灯光效果控制

• 列出可用效果：GET /api/effects返回所有可用的灯光效果列表。

• 启动效果：POST /api/effect/start启动指定的灯光效果。

• 停止效果：POST /api/effect/stop停止当前正在运行的灯光效果。

系统状态

• 获取FPP状态：GET /api/fppd/status返回FPP系统的当前状态信息。

• 获取版本信息：GET /api/fppd/version返回FPP的版本信息，包括分支、API版本等。

API调用示例

以下是一些基本的API调用示例，展示如何使用FPP API控制灯光系统：

获取当前播放列表状态

curl http://<fpp-host>/api/fppd/playlist

响应示例：

{ "currentPlaylist": "MyHolidayShow", "currentItem": 3, "status": "playing", "timeRemaining": 125 }

启动一个序列

curl -X POST http://<fpp-host>/api/sequence/play \ -H "Content-Type: application/json" \ -d '{"sequence": "ChristmasLights.fseq", "startTime": 0}'

调整音量

curl -X POST http://<fpp-host>/api/fppd/volume \ -H "Content-Type: application/json" \ -d '{"volume": 75}'

高级应用：创建自定义灯光控制界面

利用FPP API，你可以创建完全自定义的灯光控制界面。以下是实现这一目标的基本步骤：

1. 设计用户界面：创建一个直观的控制界面，包含播放/暂停按钮、进度条、效果选择器等元素。

2. 实现API通信：使用JavaScript或其他编程语言编写与FPP API通信的代码。例如：

// 获取当前播放状态 async function getCurrentStatus() { try { const response = await fetch('http://<fpp-host>/api/fppd/status'); const data = await response.json(); updateUI(data); } catch (error) { console.error('Error fetching status:', error); } } // 播放指定的播放列表 async function playPlaylist(playlistName) { try { await fetch('http://<fpp-host>/api/playlist/play', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ playlist: playlistName }) }); } catch (error) { console.error('Error playing playlist:', error); } }

3. 添加实时更新：使用WebSocket连接到FPP的状态更新端点，实现实时状态同步。

const statusSocket = new WebSocket('ws://<fpp-host>/fppdws'); statusSocket.onmessage = function(event) { const status = JSON.parse(event.data); updateUI(status); };

4. 部署应用：将你的自定义界面部署到Web服务器，或直接集成到FPP的Web界面中。

API文档与开发资源

FPP提供了全面的API文档和开发资源，帮助你快速上手：

• 官方API文档：访问http://<fpp-host>/api/查看交互式API文档。

• API规范：API规范定义在www/api/openapi.json文件中。

• 生成文档：可以使用以下命令重新生成API文档：

cd www/api && python3 tools/generate_openapi.py && cd -

• 插件开发：FPP支持插件API扩展，你可以通过docs/Plugin_Development.md了解如何开发自定义插件。

总结

Falcon Player API为灯光控制提供了强大而灵活的接口，使你能够创建各种自定义灯光应用。无论是简单的远程控制，还是复杂的自动化灯光秀，FPP API都能满足你的需求。通过本文介绍的基础知识和示例，你可以开始探索FPP API的无限可能，打造属于你的独特灯光体验。

要开始使用FPP API，只需克隆仓库并按照官方文档进行设置：

git clone https://gitcode.com/gh_mirrors/fpp/fpp

立即开始你的FPP API探索之旅，释放你的创造力，打造令人惊艳的灯光效果！

【免费下载链接】fppFalcon Player项目地址: https://gitcode.com/gh_mirrors/fpp/fpp