webowodev/payload-video-stream
GitHub: webowodev/payload-video-stream
一个 Payload CMS 插件，用于将视频上传到 Cloudflare Stream 等云端流媒体平台，实现自动化的视频处理和优化。
Stars: 8 | Forks: 0
# Payload 视频流媒体插件
一个 [Payload CMS](https://payloadcms.com) 插件，可直接从 Payload 上传集合将视频无缝上传到流媒体提供商。该插件自动处理视频文件上传到流媒体平台，为您的 Payload CMS 应用提供优化的视频传输服务。
## 功能特性
- 🎥 直接从 Payload 上传集合将视频上传到流媒体提供商
- ☁️ **Cloudflare Stream** 支持（当前可用）
- 🔌 可扩展的适配器架构，便于添加更多流媒体提供商
- 🔄 自动视频处理和优化
- 📊 流媒体元数据与 Payload 文档集成
- 🎯 使用 TypeScript 支持的类型安全配置
## 支持的提供商
当前支持：
- **Cloudflare Stream** - 与 Cloudflare 视频流媒体平台的完整集成
计划支持：
- Mux
- AWS MediaConvert
- Azure Media Services
- 其他流媒体 API 提供商
## 安装
```
npm install payload-video-stream
# 或者
yarn add payload-video-stream
# 或者
pnpm add payload-video-stream
```
## 快速入门
### 1. 配置插件
将插件添加到您的 `payload.config.ts`：
```
import { buildConfig } from 'payload/config'
import { videoStream } from 'payload-video-stream'
import { cloudflareStreamAdapter } from 'payload-video-stream/adapters'
export default buildConfig({
plugins: [
// configure your s3 storage configuration
s3Storage({
bucket: process.env.S3_BUCKET ?? 'romonoa',
clientUploads: true, // enable client-side uploads
collections: {
video: true,
},
config: {
credentials: {
accessKeyId: process.env.S3_ACCESS_KEY_ID ?? '',
secretAccessKey: process.env.S3_SECRET_ACCESS_KEY ?? '',
},
endpoint: process.env.S3_ENDPOINT,
region: process.env.S3_REGION,
// ... Other S3 configuration
},
signedDownloads: {
// expires in 24 hours
expiresIn: 60 * 60 * 24,
}, // enable signed download URLs
}),
// configure video stream plugin
videoStream({
collections: {
media: true,
},
// configure default adapter, currently only support cloudflare stream adapter
defaultAdapter: cloudflareStreamAdapter({
accountId: process.env.CLOUDFLARE_STREAM_ACCOUNT_ID || '',
apiToken: process.env.CLOUDFLARE_STREAM_API_TOKEN || '',
customerSubdomain: process.env.NEXT_PUBLIC_CLOUDFLARE_STREAM_CUSTOMER_SUBDOMAIN || '',
requireSignedURLs: true // OPTIONAL: enable this if you enabled the signed downloads on your storage so the plugin will use the signed s3 url to the cloudflare stream copy video url function
}),
}),
],
// ... rest of your config
})
```
### 2. 环境变量
创建包含流媒体提供商凭据的 `.env` 文件：
```
CLOUDFLARE_STREAM_API_TOKEN=your_cloudflare_api_token
CLOUDFLARE_STREAM_ACCOUNT_ID=your_cloudflare_account_id
NEXT_PUBLIC_CLOUDFLARE_STREAM_CUSTOMER_SUBDOMAIN=https://customer-.cloudflarestream.com
```
### 3. 创建视频集合
该插件适用于 Payload 上传集合：
```
import type { CollectionConfig } from 'payload/types'
export const Videos: CollectionConfig = {
slug: 'videos',
upload: {
mimeTypes: ['video/*'],
},
fields: [
{
name: 'title',
type: 'text',
required: true,
},
{
name: 'description',
type: 'textarea',
},
],
}
```
## 配置选项
### 插件选项
```
type VideoStreamConfig = {
collections?: {
[collectionSlug: string]: boolean
}
enabled?: boolean
defaultAdapter: StreamAdapter
disabled?: boolean
requireSignedURLs?: boolean
}
```
### Cloudflare Stream 配置
要使用 Cloudflare Stream：
1. 注册 [Cloudflare Stream](https://www.cloudflare.com/products/cloudflare-stream/)
2. 从 Cloudflare 仪表板获取您的账户 ID
3. 创建具有 Stream 权限的 API 令牌
4. 将凭据添加到您的环境变量
## 后台任务和状态轮询
该插件通过 Payload 的任务队列系统自动管理视频处理状态。上传视频后，插件会持续轮询流媒体提供商以检查视频何时可以播放。
### 自动任务注入
该插件会自动将后台任务注入到您的 Payload 配置中。每个流媒体适配器都有自己的任务，在 **`payloadVideoStream`** 队列上运行：
- **任务名称**：`payloadStreamUpdateStatusFor{AdapterName}`（例如，`payloadStreamUpdateStatusForCloudflareStream`）
- **队列名称**：`payloadVideoStream`
- **行为**：由插件自动注册和管理
```
// The plugin injects tasks like this (happens automatically)
config.jobs = {
...config.jobs,
tasks: [
...(config.jobs?.tasks || []),
updateStreamStatusTask(cloudflareStreamAdapter),
],
}
```
### 状态更新工作原理
1. **视频上传**：当您上传视频到启用插件的集合时：
- 视频会发送到您的流媒体提供商（例如 Cloudflare Stream）
- `stream` 字段会填充元数据（`videoId`、`status: 'pending'`）
2. **后台轮询**：插件创建一个后台任务，该任务会：
- 在 `payloadVideoStream` 队列上定期运行
- 查询流媒体提供商的当前视频状态
- 在 Payload 中使用最新状态更新文档
3. **自动重新排队**：如果视频仍在处理中：
- 任务会自动在 `payloadVideoStream` 队列上重新排队
- 使用指数退避重试（最多 3 次重试）
- 持续运行直到视频达到 `ready` 状态
4. **状态生命周期**：
- `pending` → 视频正在由提供商处理
- `ready` → 视频处理完成，可以播放
- `error` → 处理失败
### 监控状态更新
您可以通过多种方式跟踪视频状态：
**在 Payload 管理界面中：**
- 转到您的视频集合（例如 `/admin/collections/videos`）
- `stream.status` 字段显示当前状态
- 刷新以查看后台任务的最新状态
**通过编程方式：**
```
const video = await payload.findByID({
collection: 'videos',
id: videoId,
})
const streamStatus = (video.stream as { status?: string })?.status
// 'pending', 'ready', or 'error'
```
### 队列配置
`payloadVideoStream` 队列会自动创建和配置。无需额外设置。但是，您可以通过以下方式监控队列状态：
- Payload 管理界面（如果启用了任务面板）
- 您的任务队列提供商的仪表板
- 应用日志
### 任务输入参数
当插件排队状态更新任务时，会传递：
- `documentId`：要更新的视频文档的 ID
- `collectionSlug`：包含视频的集合
示例任务负载：
```
{
"documentId": "abc123",
"collectionSlug": "videos"
}
```
## 开发
### 前置条件
- Node.js 18+
- pnpm（推荐）或 npm/yarn
- 用于测试的 Payload CMS 项目
### 设置
1. 克隆仓库：
```
git clone https://github.com/webowodev/payload-video-stream.git
cd payload-video-stream
```
2. 安装依赖：
```
pnpm install
```
3. 设置开发环境：
```
cd dev
cp .env.example .env
```
4. 使用您的配置更新 `.env` 文件：
```
DATABASE_URI=postgres://root:secret@127.0.0.1:5432/videostream
PAYLOAD_SECRET=your-secret-key
CLOUDFLARE_STREAM_API_TOKEN=your_cloudflare_api_token
CLOUDFLARE_STREAM_ACCOUNT_ID=your_cloudflare_account_id
NEXT_PUBLIC_CLOUDFLARE_STREAM_CUSTOMER_SUBDOMAIN=https://customer-.cloudflarestream.com
```
5. 启动开发服务器：
```
pnpm dev
```
开发服务器可在 [http://localhost:3000]( {
// Implement upload logic
}
async delete(videoId: string): Promise {
// Implement delete logic
}
}
```
2. 在 `src/adapters/index.ts` 中导出您的适配器
3. 在 `src/adapters/types.ts` 中添加配置类型
4. 为您的适配器编写测试
5. 更新文档
### 贡献指南
1. Fork 仓库
2. 创建功能分支：`git checkout -b feature/amazing-feature`
3. 进行您的更改
4. 为新功能添加测试
5. 确保所有测试通过：`pnpm test`
6. 提交您的更改：`git commit -m 'Add amazing feature'`
7. 推送到分支：`git push origin feature/amazing-feature`
8. 打开 Pull Request
### 代码风格
- 遵循现有代码风格
- 所有新代码使用 TypeScript
- 为公共 API 添加 JSDoc 注释
- 提交前运行 `pnpm lint`
### 提交消息
遵循 [Conventional Commits](https://www.conventionalcommits.org/)：
- `feat:` 新功能
- `fix:` 错误修复
- `docs:` 文档更改
- `test:` 测试添加或更改
- `refactor:` 代码重构
- `chore:` 维护任务
## 路线图
- [x] Cloudflare Stream 适配器
- [ ] Mux 适配器
- [ ] AWS MediaConvert 适配器
- [ ] Azure Media Services 适配器
- [ ] 视频缩略图生成
- [ ] 处理状态 Webhook 支持
- [ ] 自定义视频播放器集成
- [ ] 分析集成
## 许可证
MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。
版权所有 (c) 2025
特此免费授予获得本软件及相关文档文件（"软件"）副本的任何人不受限制地处理本软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售本软件副本的权利，并允许获得本软件的人员在满足以下条件的情况下这样做：
上述版权声明和本许可声明应包含在本软件的所有副本或重要部分中。
本软件按"原样"提供，不提供任何形式的明示或暗示保证，包括但不限于对适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任承担责任，无论是在合同、侵权或其他诉讼中，均由本软件或本软件的使用或其他交易引起或与之相关。
## 支持
- 📖 [文档](https://github.com/webowodev/payload-video-stream#readme)
- 🐛 [问题跟踪器](https://github.com/webowodev/payload-video-stream/issues)
- 💬 [讨论区](https://github.com/webowodev/payload-video-stream/discussions)
## 致谢
基于 [Payload CMS](https://payloadcms.com) 构建 —— 最强大的 TypeScript 头部 CMS。
由 [webowodev](https://webowo.dev) 用 ❤️ 制作。
标签：AWS MediaConvert, Azure Media Services, Cloudflare Stream, CMS插件, GNU通用公共许可证, MITM代理, Mux, Node.js, Payload CMS, TypeScript, 云存储, 后端开发, 媒体服务API, 安全插件, 流媒体服务, 视频上传, 视频优化, 视频处理, 视频流媒体, 适配器架构