diff --git a/README.md b/README.md index b221c22..3f07dac 100644 --- a/README.md +++ b/README.md @@ -11,46 +11,47 @@ ## Philosophy -The main goal of this addon: **make working with videos as easy as working with images**. All the magic -happens behind the scenes: videos are mirrored to your Mux account and can start streaming within seconds -using the official `` web component as a drop-in replacement for the native video element. +The main goal of this addon: **make working with videos as easy as working with images**. + +## How it works + +Videos uploaded to an asset container are mirrored to your Mux account. Within a few seconds, they can be streamed +using the official `` web component, which is a drop-in replacement for the native video element. ## Features - **Automatic sync** Mirror locally uploaded videos to your Mux account -- **Seamless video upload workflow** - Just drop the original video files directly into the backend +- **Standard upload workflow** + Upload original video files into the control panel like any other asset - **No custom fieldtype required** Handle and display videos like any other asset in Statamic - **Instant playback** - Just-in-time encoding ensures videos can be streamed immediately + Videos can be streamed within seconds of upload, before full encoding completes - **Optimized streaming** - Smart adaptive bitrates deliver the right resolution for your viewers' bandwith + Mux delivers a resolution matched to each viewer's bandwidth - **Customizable player** - Tailor the video player component to match your site's design -- **Real-time analytics** - Get insights into your audience and video playback performance + Configure the Mux video player component to match your site's design - **Secure streaming** - Protect your content using signed urls + Restrict access to videos using signed URLs ## Getting Started Read the docs on [Installation](https://statamic-mux.daun.ltd/installation) and [Connecting Mux](https://statamic-mux.daun.ltd/connecting-mux). -## Responsive Video +## Why a video service -Just like image pipelines efficiently deliver optimized images for faster load times on a variety of devices -and connections, video encoding services like Mux play a crucial role for optimizing video content. -Video encoding demands more resources and expertise than image processing, so a dedicated service -like Mux becomes essential for performant websites. +Video encoding and delivery require more processing and storage than images. Serving video files directly +from your origin server, without adaptive bitrate streaming, results in large downloads and inconsistent +playback across devices and connections. A dedicated service handles encoding, storage, and adaptive +delivery. -## Why Mux? +## Why Mux -While there is a host of services for video encoding to choose from, Mux offers all the key -components: encoding, storage, and delivery. It stands out with its API-first approach prioritizing -developer productivity, as well as its official web components for creating rich, customized video players. +Mux provides encoding, storage, and delivery through a single API. This addon uses Mux specifically because +it exposes these features through an HTTP API and ships official web components for video playback, both of +which the addon depends on. ## License diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index fcc327a..af1edd8 100644 --- a/docs/.vitepress/config.js +++ b/docs/.vitepress/config.js @@ -62,6 +62,7 @@ export default defineConfig({ { text: 'mux:mirror', link: '/commands/mux-mirror' }, ], }, + { text: 'Control Panel', link: '/control-panel' }, { text: 'GraphQL Types', link: '/graphql' }, { text: 'Secure Playback', link: '/secure-playback' }, { text: 'Configuration', link: '/configuration' }, diff --git a/docs/commands.md b/docs/commands.md index dadb224..5a8ecf5 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -1,6 +1,10 @@ # Artisan Commands -The following commands are available for uploading videos manually or in regular intervals. +The following commands upload videos manually or on a schedule. + +While the addon automatically uploads [mirrored videos](/upload) in the background, running the `mux:mirror` +command on a schedule guards against misconfigured queues. If mirroring is already working, the command is a +no-op and returns a success message. | Command | Description | |-------|-----------| diff --git a/docs/commands/mux-mirror.md b/docs/commands/mux-mirror.md index 131c8a9..cf53de7 100644 --- a/docs/commands/mux-mirror.md +++ b/docs/commands/mux-mirror.md @@ -2,7 +2,7 @@ **Upload local videos to Mux, and remove orphaned Mux videos.** -This basically runs `mux:upload` and `mux:prune` in sequence. +Runs `mux:upload` and `mux:prune` in sequence. ```sh # Sync local assets to Mux diff --git a/docs/configuration.md b/docs/configuration.md index af94a5d..a360fa6 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,7 +1,7 @@ # Configuration -The addon config will be published to `config/mux.php` on installation. Read on -for details on each available config option. +The addon's config file is published to `config/mux.php` on installation. Each available option is +described below. ## Credentials @@ -81,10 +81,10 @@ return [ ## Control Panel Thumbnails -Configure the behavior of video thumbnails in the control panel. By default, the addon will render -animated GIF previews of the first five seconds. This is great for editors to identify and work with -videos, but uses more bandwidth than static images. You can disable this behavior entirely or switch -to static images to save on bandwidth. +Configure how video thumbnails are rendered in the control panel. By default, the addon renders +animated GIF previews of the first five seconds, which helps editors identify videos but uses more +bandwidth than static images. Set `animated` to `false` to use static images, or `enabled` to `false` +to disable thumbnails entirely. ```php return [ @@ -129,9 +129,9 @@ return [ Mux offers three quality levels. Learn more at [Choosing Video Quality](https://docs.mux.com/guides/use-video-quality-levels). -- `basic` for apps with simpler needs that need to save on bandwidth & cost -- `plus` for conistently high quality output, but incurs encoding cost -- `premium` for premium high-detail content like sports broadcasts +- `basic`: lower bandwidth and cost, lower quality +- `plus`: consistently high quality, higher encoding cost +- `premium`: highest quality, for high-detail content such as sports broadcasts ```php return [ @@ -172,6 +172,7 @@ return [ Change the default playback behavior of video streams received from Mux. Applies to any videos or players rendered using the built-in Antlers tags. +No modifiers are set by default; the entries below are examples. Learn more in the Mux docs on [Modifying Playback Behavior](https://docs.mux.com/guides/modify-playback-behavior). ```php @@ -195,19 +196,18 @@ return [ ## Storage Optimization -Define how the addon handles original video files. In most cases, you'll want to -stick with the default behavior and keep the original video files around to ensure -long-term independence from any one video provider. +Define how the addon handles original video files. By default, the original files are kept on your asset +disk, which avoids depending solely on Mux for storage and lets you stream or download from your origin +server as a fallback. -If you need to save storage space on the server, you can configure the addon to -replace video files with a smaller placeholder version. This will store a short -10s clip of the video for previewing in the backend, but will require Mux for -streaming and downloading the full video. +To save storage space, set `store_placeholders` to `true` to replace each video file with a short clip +(default 10 seconds, set by `placeholder_length`). The clip is used for previewing in the control panel; +streaming and downloading the full video then requires Mux. -Any videos shorter than the defined placeholder length will keep the original. +Videos shorter than `placeholder_length` keep their original file. -Note that this feature requires a [queue worker](https://laravel.com/docs/queues#running-the-queue-worker) -to be running, as the video processing can take some time depending on the file size. +This feature requires a running [queue worker](https://laravel.com/docs/queues#running-the-queue-worker), +as processing can take time depending on file size. ```php /* @@ -227,8 +227,8 @@ to be running, as the video processing can take some time depending on the file ## Queue Driver -Define the queue driver to be used for uploads and other long-running requests to Mux. -Leave it empty to use the default queue settings of your app. +Define the queue connection and queue name used for uploads and other long-running requests to Mux. +Leave `connection` empty to use your app's default queue connection. ```php return [ @@ -252,14 +252,12 @@ return [ Configure the output and verbosity of the addon's logs. -For troubleshooting uploads and getting insight into the processing of video files, -you can increase the log level to `debug` temporarily. Make sure to set it back to -`notice` or `warning` in production to avoid excessive log output. +To troubleshoot uploads and see how video files are processed, increase the log level to `debug` +temporarily. Set it back to `warning` in production to avoid excessive log output. -The addon creates its own log channel, writing to `storage/logs/mux.log` and -rotating biweekly. You can customize the log channel by either defining a `mux` -channel of your own in `config/logging.php` or telling the addon to use a -different channel entirely. +The addon creates its own log channel, writing to `storage/logs/mux.log`. To customize it, either define +your own `mux` channel in `config/logging.php`, or point the addon at a different channel via +`MUX_LOG_CHANNEL`. ```php return [ diff --git a/docs/connecting-mux.md b/docs/connecting-mux.md index a1bc794..7546712 100644 --- a/docs/connecting-mux.md +++ b/docs/connecting-mux.md @@ -4,15 +4,15 @@ Register a Mux account and generate API credentials. ## Account -If you haven't already, now is a good time to [register a Mux account](https://dashboard.mux.com/signup). -Once you have an account, you need to [create an environment](https://dashboard.mux.com/environments). -It's recommended to have separate Mux environments for each Statamic app environment like `development` and `production`. +[Register a Mux account](https://dashboard.mux.com/signup) if you don't have one, then +[create an environment](https://dashboard.mux.com/environments). Use a separate Mux environment for each +Statamic app environment, e.g. `development` and `production`. ## Credentials -To allow this addon to communicate with the Mux API, you'll need to create an Access Token in the -[Access Token settings](https://dashboard.mux.com/settings/access-tokens) of your Mux account dashboard. -Save the generated token and associated secret to your environment variables. +The addon communicates with the Mux API using an access token. Create one in the +[Access Token settings](https://dashboard.mux.com/settings/access-tokens) of your Mux dashboard, then save +the generated token id and secret to your environment variables. ```env MUX_TOKEN_ID=b3b7fa9b-efd6-4723-bed2-032b04e61488 diff --git a/docs/control-panel.md b/docs/control-panel.md new file mode 100644 index 0000000..ab674f8 --- /dev/null +++ b/docs/control-panel.md @@ -0,0 +1,49 @@ +# Control panel + +The addon runs in the background and does not require manual intervention in normal operation. Even so, +it can be useful to inspect the list of mirrored assets or browse your full Mux library. For that, you can +enable dedicated control panel listings under **Tools → Mux** by granting the relevant permissions to +the applicable roles. + +## Permissions + +The addon registers a permission group named **Mux**. Assign these permissions to roles under +**Users → Permissions** in the control panel. No role has them by default. + +| Permission | Grants access to | +|------------|--------| +| **Manage Mux** | Page showing assets mirrored to Mux | +| **View Mux library** | Page listing all videos in the connected Mux account | +| **Open Mux dashboard** | Opening links to the connected Mux account dashboard | +| **Delete Mux assets** | Deleting videos from Mux via row and bulk actions | +| **Trigger sync** | Running manual sync commands from the control panel | + +## Pages + +### Mirrored Assets + +Lists the local video assets in your Statamic asset containers alongside their Mux sync status. +Use it to check which videos have been uploaded and to trigger uploads manually. + +Clicking an asset opens the Statamic asset editor. Per-row actions include opening the player page and +copying the asset ID, playback ID, player URL, embed code, or thumbnail URL. Bulk actions cover uploading, +reuploading, and deleting the selected videos on Mux. + +### Mux Library + +Lists all videos in the connected Mux account, including any that were not uploaded through this addon. Use +it to review the full Mux library and reconcile it with your local assets. The library list is cached. The +**Clear cache and reload** menu item fetches fresh data from the Mux API. + +Clicking an asset opens it in the connected Mux dashboard, if granted permission. + +## Manual sync + +Both pages include a **Sync** button that runs the addon's sync commands in the background, without needing +shell access. Running the sync requires a working [queue worker](https://laravel.com/docs/queues#running-the-queue-worker), +since uploads are queued. + +## Asset editor + +The [Mirror fieldtype](/upload) shows the upload status of an individual asset, both as a column in the +asset browser and as a badge in the asset editor. diff --git a/docs/display.md b/docs/display.md index 644a512..c1f18de 100644 --- a/docs/display.md +++ b/docs/display.md @@ -1,12 +1,12 @@ # Displaying Videos in Your Frontend -Once uploaded to Mux, your videos are ready to be streamed within a few seconds, thanks to just-in-time encoding. +Once uploaded to Mux, videos can be streamed within a few seconds through just-in-time encoding. ## Video Components -Mux offers a set of [web components](https://github.com/muxinc/elements) that can be used as drop-in -replacements of the native `video` element. Instead of a source file, they receive a Mux playback id to offer -adaptive bitrate streaming. +Mux provides a set of [web components](https://github.com/muxinc/elements) that act as drop-in +replacements for the native `video` element. Instead of a source file, they take a Mux playback id and +handle adaptive bitrate streaming. ### `mux-video` @@ -21,9 +21,8 @@ and `loop` or events like `playing` will continue to work as expected. ### `mux-player` -Wraps the native `video` element in a full-fledged customizable video player. Accepts the same attributes -and emits the same events as a video element, but adds lots of useful interactive controls for video -playback. +Wraps the native `video` element in a customizable video player. Accepts the same attributes and emits the +same events as a video element, and adds interactive playback controls. ```diff -