Payload Video Streaming Plugin

A Payload CMS plugin that enables seamless video uploads directly to streaming providers from Payload upload collections. This plugin automatically handles video file uploads to streaming platforms, providing optimized video delivery for your Payload CMS applications.

Features

• 🎥 Direct video uploads to streaming providers from Payload upload collections
• ☁️ Cloudflare Stream support (currently available)
• 🔌 Extensible adapter architecture for adding more streaming providers
• 🔄 Automatic video processing and optimization
• 📊 Stream metadata integration with Payload documents
• 🎯 Type-safe configuration with TypeScript support

Supported Providers

Currently supported:

• Cloudflare Stream - Complete integration with Cloudflare's video streaming platform

Planned support:

• Mux
• AWS MediaConvert
• Azure Media Services
• Other streaming API providers

Installation

npm install payload-video-stream
# or
yarn add payload-video-stream
# or
pnpm add payload-video-stream

Quick Start

1. Configure the Plugin

Add the plugin to your 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. Environment Variables

Create a .env file with your streaming provider credentials:

CLOUDFLARE_STREAM_API_TOKEN=your_cloudflare_api_token
CLOUDFLARE_STREAM_ACCOUNT_ID=your_cloudflare_account_id
NEXT_PUBLIC_CLOUDFLARE_STREAM_CUSTOMER_SUBDOMAIN=https://customer-<YOUR_CUSTOMER_ID>.cloudflarestream.com

3. Create a Video Collection

The plugin works with Payload upload collections:

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',
    },
  ],
}

Configuration Options

Plugin Options

type VideoStreamConfig = {
  collections?: {
    [collectionSlug: string]: boolean
  }
  enabled?: boolean
  defaultAdapter: StreamAdapter
  disabled?: boolean
  requireSignedURLs?: boolean
}

Cloudflare Stream Configuration

To use Cloudflare Stream:

1. Sign up for Cloudflare Stream
2. Get your Account ID from the Cloudflare dashboard
3. Create an API token with Stream permissions
4. Add credentials to your environment variables

Background Jobs & Status Polling

The plugin automatically manages video processing status through Payload's job queue system. When you upload a video, the plugin continuously polls the streaming provider to check when the video is ready for playback.

Automatic Task Injection

The plugin automatically injects background tasks into your Payload configuration. Each streaming adapter gets its own task that runs on the payloadVideoStream queue:

• Task Name: payloadStreamUpdateStatusFor{AdapterName} (e.g., payloadStreamUpdateStatusForCloudflareStream)
• Queue Name: payloadVideoStream
• Behavior: Automatically registered and managed by the plugin

// The plugin injects tasks like this (happens automatically)
config.jobs = {
  ...config.jobs,
  tasks: [
    ...(config.jobs?.tasks || []),
    updateStreamStatusTask(cloudflareStreamAdapter),
  ],
}

How Status Updates Work

1. Video Upload: When you upload a video to a collection with the plugin enabled:

   • The video is sent to your streaming provider (e.g., Cloudflare Stream)
   • The stream field is populated with metadata (videoId, status: 'pending')

2. Background Polling: The plugin creates a background task that:

   • Runs periodically on the payloadVideoStream queue
   • Queries the streaming provider for the current video status
   • Updates the document in Payload with the latest status

3. Self-Requeuing: If the video is still processing:

   • The task automatically re-queues itself on the payloadVideoStream queue
   • Retries with exponential backoff (max 3 retries)
   • Continues until the video reaches ready status

4. Status Lifecycle:

   • pending → Video is being processed by the provider
   • ready → Video processing complete, ready for playback
   • error → Processing failed

Monitoring Status Updates

You can track video status in several ways:

In the Payload Admin UI:

• Go to your video collection (e.g., /admin/collections/videos)
• The stream.status field shows the current status
• Refresh to see the latest status from the background job

Programmatically:

const video = await payload.findByID({
  collection: 'videos',
  id: videoId,
})

const streamStatus = (video.stream as { status?: string })?.status
// 'pending', 'ready', or 'error'

Queue Configuration

The payloadVideoStream queue is automatically created and configured. No additional setup is required. However, you can monitor queue status through:

• Payload's admin UI (Jobs panel, if enabled)
• Your job queue provider's dashboard
• Application logs

Task Input Parameters

When the plugin queues a status update task, it passes:

• documentId: The ID of the video document to update
• collectionSlug: The collection containing the video

Example task payload:

{
  "documentId": "abc123",
  "collectionSlug": "videos"
}

Development

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm/yarn
• A Payload CMS project for testing

Setup

1. Clone the repository:

git clone https://github.com/webowodev/payload-video-stream.git
cd payload-video-stream

2. Install dependencies:

pnpm install

3. Set up the dev environment:

cd dev
cp .env.example .env

4. Update the .env file with your configuration:

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-<YOUR_CUSTOMER_ID>.cloudflarestream.com

5. Start the development server:

pnpm dev

The dev server will be available at http://localhost:3000

Project Structure

payload-video-stream/
├── src/
│   ├── index.ts              # Main plugin export
│   ├── adapters/
│   │   ├── streamAdapter.ts  # Base adapter interface
│   │   ├── cloudflareStream.ts # Cloudflare implementation
│   │   └── types.ts          # Adapter type definitions
│   ├── fields/
│   │   └── stream.ts         # Custom field definitions
│   └── hooks/
│       └── afterOperation.ts # Upload hooks
├── dev/                      # Development Payload instance
│   ├── payload.config.ts
│   └── app/                  # Next.js app router
└── test-results/             # Test output

Testing

Run the test suite:

pnpm test

Run tests in watch mode:

pnpm test:watch

Run integration tests:

pnpm test:int

Run E2E tests:

pnpm test:e2e

Building

Build the plugin for production:

pnpm build

Contributing

We welcome contributions! Here's how you can help:

Adding a New Streaming Provider

1. Create a new adapter in src/adapters/:

// src/adapters/yourProvider.ts
import type { StreamAdapter } from './streamAdapter'

export class YourProviderAdapter implements StreamAdapter {
  async upload(file: File): Promise<StreamResult> {
    // Implement upload logic
  }
  
  async delete(videoId: string): Promise<void> {
    // Implement delete logic
  }
}

2. Export your adapter in src/adapters/index.ts

3. Add configuration types in src/adapters/types.ts

4. Write tests for your adapter

5. Update documentation

Contribution Guidelines

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass: pnpm test
6. Commit your changes: git commit -m 'Add amazing feature'
7. Push to the branch: git push origin feature/amazing-feature
8. Open a Pull Request

Code Style

• Follow the existing code style
• Use TypeScript for all new code
• Add JSDoc comments for public APIs
• Run pnpm lint before committing

Commit Messages

Follow Conventional Commits:

• feat: New features
• fix: Bug fixes
• docs: Documentation changes
• test: Test additions or changes
• refactor: Code refactoring
• chore: Maintenance tasks

Roadmap

• Cloudflare Stream adapter
• Mux adapter
• AWS MediaConvert adapter
• Azure Media Services adapter
• Video thumbnail generation
• Webhook support for processing status
• Custom video player integration
• Analytics integration

License

MIT License - see the LICENSE file for details.

Copyright (c) 2025

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Acknowledgments

Built with Payload CMS - The most powerful TypeScript headless CMS.

---

Made with ❤️ by webowodev