---
title: "media"
manual: "Handlebars"
version: "main"
permalink: "https://docs.typo3.org/permalink/cpsit/typo3-handlebars:data-processor-media@main"
source: "Usage/DataProcessors/Media.rst"
rendered: "2026-09-29T09:05:57+00:00"
---

# media {#data-processor-media}

**Class:** `\CPSIT\Typo3Handlebars\DataProcessing\MediaProcessor`

Resolves a file or file reference and runs it through a matching *media
processor* — a pluggable component that turns a resource into whatever
shape a template needs (for example, an image with responsive source sets).
The extension ships with a single built-in media processor for images; see
[MediaProcessor](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:developer-corner-media-processor@main) for how to register your own.

-   [Data sources](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:data-sources@main)
-   [Usage](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:usage@main)
-   [Properties](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:properties@main)
-   [Built-in media processor: image](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:built-in-media-processor-image@main)

## Data sources {#data-processor-media-data-sources}

`file` references the file or file reference to process, e.g.
the first file resolved by TYPO3's `files` processor
(`processedData:files/0`). See [Referencing data](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:usage-data-sources-payload@main)
for the syntax.

## Usage {#data-processor-media-usage}

```typoscript
tt_content.textpic = HANDLEBARSTEMPLATE
tt_content.textpic {
    templateName = @textpic

    dataProcessing {
        10 = files
        10 {
            references.fieldName = image
            as = files
        }

        20 = media
        20 {
            file = processedData:files/0
            as = image

            config {
                image {
                    sourceSets {
                        small {
                            maxW = 600c
                        }
                    }
                }
            }
        }
    }
}
```

The first file resolved by the core `files` processor is passed
to `media`, which picks the matching media processor — here,
the built-in `image` processor — and stores its result under
`image`.

> [!TIP]
> To process all files instead of only the first one, nest
> `media` inside a [process-each](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:data-processor-process-each@main) processor
> and use `file.current = 1` to reference the file currently
> being processed:
>
> ```typoscript
> 20 = process-each
> 20 {
>     dataSource = processedData:files
>     as = images
>
>     dataProcessing {
>         10 = media
>         10 {
>             file.current = 1
>
>             config {
>                 image {
>                     sourceSets {
>                         small {
>                             maxW = 600c
>                         }
>                     }
>                 }
>             }
>         }
>     }
> }
> ```
>
> Since `as` is omitted on `media`, the result is
> merged into each item. The template can then iterate over all images:
>
> ```handlebars
> {{#each images}}
>     <img src="{{sourceSets.small.src}}" alt="">
> {{/each}}
> ```

## Properties {#data-processor-media-properties}

-   **`file`**

    Data source reference the resource is read from (see
    [Data sources](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:data-processor-media-data-sources@main)). Required.

-   **`as`**

    Target key in the processed data array the media processor's result is
    stored under. Optional — if omitted, the result is merged recursively
    into the processed data instead.

-   **`config.<name>`**

    Configuration passed to the media processor registered under
    `<name>` (e.g. `config.image` for the built-in
    image processor). Only applied if that processor actually matches the
    resolved resource.

If `file` cannot be resolved, or no registered media processor
supports the resolved resource, a warning is logged and the processed data
is returned unchanged.

## Built-in media processor: image {#data-processor-media-image}

The built-in image processor matches any resource that is an image. It
generates one processed image per configured source set, using
`ContentObjectRenderer::getImgResource()` under the hood, so each
source set accepts the same configuration as TYPO3's core [imgResource](https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/Functions/Imgresource.html#imgresource)
function (e.g. `maxW`, `maxH`, `width`,
`height`).

Its configuration is nested under `config.image` (see
[Properties](https://docs.typo3.org/permalink/cpsit/typo3-handlebars:data-processor-media-properties@main) below) and results in the
following shape:

-   **`sourceSets`**

    A map of the configured source set names to their processed image data
    (`src`, `width`, `height`).

-   **`originalFile`**

    The resolved, unprocessed file (`\TYPO3\CMS\Core\Resource\AbstractFile`).