> ## Documentation Index
> Fetch the complete documentation index at: https://flex-fields.bjanczak.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Examples target Filament 5. Verify optional dependencies before configuring integrations.
> Upload transfer completion, permanent storage and record acceptance are separate milestones. Native and Spatie image conversions retain the original.

# Media OS

> Store, validate, secure and process media in your Laravel application.

Media OS gives your application one API for storing files on Laravel disks, generating image variants, connecting Spatie Media Library, scanning files and managing temporary uploads. Use it directly in your application services or through [FLEX File Upload](https://flex-fields.bjanczak.com/docs/flexfileupload-and-fleximageupload.md).

Laravel filesystemsOptional Spatie

## Choose your integration

> [card] [Storage API](https://flex-fields.bjanczak.com/docs/media-os-api.md)
>
> Store uploads, local files, streams and bytes using a typed write policy.

> [card] [Configuration](https://flex-fields.bjanczak.com/docs/media-os-configuration.md)
>
> Choose disks, limits, visibility, worker settings and cleanup policies.

> [card] [Image conversions](https://flex-fields.bjanczak.com/docs/media-os-images.md)
>
> Generate thumbnails and WebP/AVIF variants, synchronously or in a worker.

> [card] [Spatie integration](https://flex-fields.bjanczak.com/docs/media-os-spatie.md)
>
> Use collections, native conversions, responsive images and model relationships.

> [card] [Temporary uploads](https://flex-fields.bjanczak.com/docs/media-os-lifecycle.md)
>
> Handle staging, record acceptance, recovery and abandoned files.

> [card] [Extensions and events](https://flex-fields.bjanczak.com/docs/media-os-extensions.md)
>
> Connect your antivirus scanner, processors and access policy.

> [card] [Capture and retention](https://flex-fields.bjanczak.com/docs/media-os-capture.md)
>
> Configure transcription, signature evidence and retention services.

> [card] [Browser integrations](https://flex-fields.bjanczak.com/docs/media-os-browser.md)
>
> Build a custom capture interface with the public browser helpers.

## Understand the upload lifecycle

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    A[Select or capture] --> B[Temporary transfer]
    B --> C[Inspect and validate]
    C --> D[Permanent storage]
    D --> E[Record accepted]
    E --> F[Optional queued conversions]
```

Record acceptance (Confirmation that your application's saved record references the permanent media.) is separate from transfer completion. Queued conversion files can become available after the record has been saved.

## Your first stored file

The following example stores a PDF on the Laravel `local` disk. `$path` is a readable local path supplied by your application. Import the classes shown in each example into the class where you use them.

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
use Bjanczak\FilamentFlexFields\Support\Media\FlexMedia;
use Bjanczak\FilamentFlexFields\Support\Media\Data\MediaPolicy;
use Bjanczak\FilamentFlexFields\Support\Media\Data\MediaWrite;
use Bjanczak\FilamentFlexFields\Support\Media\Sources\MediaSource;

$intent = new MediaWrite(
    disk: 'local',
    directory: 'contracts',
    policy: new MediaPolicy(
        maxBytes: 10 * 1024 * 1024,
        mimeTypes: ['application/pdf'],
    ),
);

$receipt = FlexMedia::store(MediaSource::path($path, 'contract.pdf'), $intent);
```

The result is a `MediaReceipt`. Save the attachment reference in your own model or use a FLEX upload field to manage form persistence for you.

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
$attachment->disk = $receipt->disk;
$attachment->path = $receipt->path;
$attachment->mime_type = $receipt->file->mimeType;
$attachment->size = $receipt->file->bytes;
$attachment->save();
```

A successful browser transfer and a saved record are different milestones. With a FLEX field, choosing a file transfers it to temporary storage; the form's save flow creates and accepts the permanent attachment. Background thumbnail generation is a third, independent step.

## Files and images in forms

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexFileUpload;

FlexFileUpload::make('contract')
    ->withRecommendedDefaults()
    ->acceptedFileTypes(['application/pdf'])
    ->disk('local')
    ->directory('contracts');
```

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexImageUpload;

FlexImageUpload::make('photos')
    ->withRecommendedDefaults()
    ->multiple()
    ->uploadLayout('grid')
    ->reorderable()
    ->maxFiles(10);
```

## What is included

* Inspected MIME types, byte limits, SHA-256 integrity checks and private/public visibility.
* Local disks and configured cloud disks, including S3, through Laravel's filesystem.
* Named native image conversions, separate conversion disks, optimized previews and optional background jobs.
* Optional Spatie collections, conversions, responsive images and custom properties.
* Configurable antivirus integrations, processing, access policies and Laravel events.
* Temporary staging, explicit recovery and scheduled cleanup.
* Configurable capture transcription, signature evidence and retention services.

> [!NOTE]
>
> Media OS does not include an antivirus engine or a cloud-storage account. Configure those services in your application when you enable them. Disk storage does not require Spatie. Native raster conversions require PHP GD; the available output codecs depend on your GD installation.

## Originals and converted files

> [!WARNING]
>
> Image conversions **retain the original** and create additional files. This applies to native synchronous conversions, native queued conversions and Spatie conversions. An optimized preview does not mean the original has been deleted.

If your storage policy permits only a reduced master image and a thumbnail, normalize the source before permanent storage, then create the thumbnail from that normalized master. There is no built-in conversion option that deletes the stored original while keeping its derivative records. [Learn about originals and previews](https://flex-fields.bjanczak.com/docs/media-os-images.md#original-retention).

## Configuration and next steps

The configuration namespace is `filament-flex-fields.media_capture`. Per-operation `MediaWrite` and `MediaPolicy` objects let you override storage and validation for a particular upload.

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
$intent = new MediaWrite(
    disk: 's3',
    directory: 'products/photos',
    policy: new MediaPolicy(
        maxBytes: 5 * 1024 * 1024,
        mimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
        visibility: 'public',
    ),
);
```

Continue with [configuration](https://flex-fields.bjanczak.com/docs/media-os-configuration.md), [storage examples](https://flex-fields.bjanczak.com/docs/media-os-api.md) or [FLEX upload fields](https://flex-fields.bjanczak.com/docs/flexfileupload-and-fleximageupload.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.