Umbraco.Community.uBun 18.0.0

uBun

uBun synchronizes video files from Umbraco with Bunny Stream. When an editor saves a video, uBun creates a Bunny Stream video, uploads the file, and stores the Bunny video ID and playback URLs on the Umbraco item.

Requirements

• Umbraco CMS 17 or newer
• A Bunny.net account
• A Bunny Stream video library
• The Stream API key for that library

Installation

Install the package in your Umbraco project:

dotnet add package Umbraco.Community.uBun

Bunny Stream configuration

Add the following section to appsettings.json. Keep the API key in a secret store or an environment variable in deployed environments.

{
  "Umbraco": {
    "BunnyStream": {
      "ApiBasePath": "https://video.bunnycdn.com",
      "LibraryId": 123456,
      "ApiKey": "YOUR_STREAM_API_KEY",
      "PullZoneHostname": "vz-xxxxxxxx-xxx.b-cdn.net"
    }
  }
}

LibraryId is the numeric ID of the Bunny Stream library. ApiKey is the Stream API key belonging to that library. PullZoneHostname is the hostname used to build the HLS playback URL. Copy the exact hostname from the library's API or CDN settings.

The same settings can be supplied with environment variables:

Umbraco__BunnyStream__ApiBasePath=https://video.bunnycdn.com
Umbraco__BunnyStream__LibraryId=123456
Umbraco__BunnyStream__ApiKey=YOUR_STREAM_API_KEY
Umbraco__BunnyStream__PullZoneHostname=vz-xxxxxxxx-xxx.b-cdn.net

Create and upload videos through Bunny Stream's HTTP API by following the Bunny Stream upload guide. You can find the Stream API key in the API section of the selected video library. See How to find your Stream API key.

Add the property editor

uBun adds a Bunny Stream Sync property editor to the Umbraco backoffice. It links a local Umbraco upload property to a Bunny Stream video.

1. Open Settings > Data Types in the Umbraco backoffice.
2. Create a data type using the Bunny Stream Sync property editor.
3. In Upload Property Alias, enter the alias of the Upload property that contains the video file.
4. Add the new data type to the same media, content, or member type as the Upload property.
5. Save the data type and the content type.

The upload property and the Bunny Stream Sync property must be on the same content type. The upload property should contain a local Umbraco media file that Bunny Stream can process.

For background on Umbraco data types, see the Umbraco data types documentation.

Upload and synchronization

When an editor saves an item, uBun checks whether the configured upload property changed. If it did, uBun:

1. Deletes the previously linked Bunny video, if one exists.
2. Creates a new video in the configured Bunny Stream library.
3. Uploads the local file as binary data.
4. Stores the Bunny video ID and playback URLs in the sync property.

When the video is still being processed, the backoffice editor polls Bunny Stream and shows a Preparing status. A ready video shows Ready. Encoding failures and missing videos are shown as errors.

For a video that existed before the sync property was added, save the media item again to trigger synchronization.

Stored value

The sync property stores a JSON value that is converted to uBun.Models.BunnyStreamValue in .NET and BunnyStreamValue in TypeScript:

{
  "Src": "/media/example/video.mp4",
  "VideoId": "00000000-0000-0000-0000-000000000000",
  "HlsUrl": "https://vz-xxxxxxxx-xxx.b-cdn.net/VIDEO_ID/playlist.m3u8",
  "EmbedUrl": "https://player.mediadelivery.net/embed/123456/VIDEO_ID"
}

The Src value points to the original local Umbraco file. VideoId is the Bunny Stream video GUID. HlsUrl is suitable for an HLS-compatible player. EmbedUrl points to Bunny's embeddable player.

Embed a video

The generated value can be used with Bunny's player:

@if (Model.BunnyVideo is not null)
{
    <iframe
        src="@Model.BunnyVideo.EmbedUrl"
        style="width: 100%; border: none; aspect-ratio: 16/9;"
        allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
        allowfullscreen>
    </iframe>
}

Or use the HLS URL with a player that supports HLS:

<video controls width="720">
    <source src="@Model.BunnyVideo?.HlsUrl" type="application/x-mpegURL" />
</video>

See Bunny's documentation for embedding videos and video storage URLs.

Troubleshooting

Nothing is uploaded

• Check that Umbraco:BunnyStream:LibraryId is the numeric ID of a real Bunny Stream library.
• Check that the API key belongs to that library and has permission to upload and manage videos.
• Confirm that the Bunny Stream Sync property and the upload property are on the same content type.
• Confirm that Upload Property Alias exactly matches the upload property's alias.
• Check the Umbraco logs for the Bunny Stream request error.

The status stays at Preparing

Bunny Stream processes the uploaded file asynchronously. Check the video directly in the Bunny Stream library. If Bunny reports an encoding error, inspect the source file and the supported video formats and limits.

The player URL does not work

• Check that PullZoneHostname is the exact hostname configured for the library.
• Check that the video has reached a playable status.
• If the library uses token authentication or referrer restrictions, configure those rules for the site that embeds the video.

Contributing

The repository includes a test site for local development. It uses an unattended Umbraco installation. Check src/uBun.TestSite/appsettings.json for the local login details and Bunny Stream configuration.