Media Library Workflows

This guide covers how the plugin behaves inside the WordPress Media Library.

The Three Main Workflows #

1. Upload to the normal WordPress Media Library #

This is a local-first workflow.

What happens:

• WordPress creates a normal local media item.
• If auto-import is enabled, the plugin queues an upload to Cloudflare Stream.
• The attachment eventually becomes Local + Stream or Stream only, depending on your retention policy.

2. Upload directly to Stream #

This is a Stream-first workflow.

What happens:

• the video is uploaded directly to Cloudflare Stream
• WordPress creates an attachment that points to the Stream video
• a local file is not created automatically

This is useful when you do not want the initial file to live on the WordPress server.

3. Import an existing Stream video #

You can import a Cloudflare Stream video that WordPress does not know about yet.

What happens:

• the plugin creates a WordPress attachment for the existing Stream video
• the attachment starts as Stream only
• you can later restore a local file if needed

Attachment Details Screen #

Open any video attachment and you will see Stream-specific fields such as:

• Stream UID
• Stream status
• Storage state
• Asset origin
• Local file status
• Stream URL
• Shortcode

Attachment Actions #

Depending on the current storage state, the plugin shows different actions.

Local only #

Common actions:

• Upload to Stream

Local + Stream #

Common actions:

• Sync Stream Data
• Delete local file
• Delete from Stream

Stream only #

Common actions:

• Download to Local
• Sync Stream Data
• Delete from Stream

What the States Mean #

Local only #

The file exists in WordPress and is not currently linked to Cloudflare Stream.

Local + Stream #

The attachment has both:

• a WordPress local file
• a Cloudflare Stream copy

Stream only #

The attachment points to Cloudflare Stream but no local WordPress file currently exists.

Missing local file #

The attachment once had a local file, but that local file is gone. Stream may still be available.

Media Library Filters #

The plugin adds a Cloudflare Stream filter to the Media Library so you can list Stream-linked videos more easily.

This works in:

• grid view
• list view

Bulk Actions #

The plugin adds bulk actions for video attachments:

• Upload to Stream
• Sync Stream Data
• Download to Local

Use these when you want to process many existing attachments at once.

Preview Behavior #

The plugin aims to keep Media Library previews as close to native WordPress behavior as possible.

In general:

• grid view uses thumbnails when available
• attachment details prefer a playable Stream preview when the Stream video is ready
• if the Stream video is not yet playable, the UI falls back to a thumbnail

What This Plugin Does Not Assume #

The plugin does not assume:

• that every Stream video has a local WordPress file
• that every local WordPress file has a Stream copy
• that deleting one copy should automatically delete the other
• deleting an attachment will delete local file and/or stream file all together

Those are explicit actions.