---
url: 'https://adk.nht.io/api/@nhtio/adk/batteries/media/classes/MediaChain.md'
description: >-
  The chainable builder. Immutable — every verb returns a new instance sharing
  the executor. Thenable — `await` runs the chain and resolves to the terminal
  step's natural type.
---

# Class: MediaChain

Defined in: [src/batteries/media/builder.ts:55](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L55)

The chainable builder. Immutable — every verb returns a new instance sharing the executor.
Thenable — `await` runs the chain and resolves to the terminal step's natural type.

## Implements

* `PromiseLike`<`unknown`>

## Constructors

### Constructor

```ts
new MediaChain(exec: ChainExecutor, ops?: MediaOp[]): MediaChain;
```

Defined in: [src/batteries/media/builder.ts:59](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L59)

#### Parameters

| Parameter | Type                                                | Default value |
| --------- | --------------------------------------------------- | ------------- |
| `exec`    | [`ChainExecutor`](../type-aliases/ChainExecutor.md) | `undefined`   |
| `ops`     | [`MediaOp`](../interfaces/MediaOp.md)\[]             | `[]`          |

#### Returns

`MediaChain`

## Accessors

### audio

#### Get Signature

```ts
get audio(): AudioNamespace;
```

Defined in: [src/batteries/media/builder.ts:197](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L197)

Audio operations.

##### Returns

[`AudioNamespace`](../interfaces/AudioNamespace.md)

***

### image

#### Get Signature

```ts
get image(): ImageNamespace;
```

Defined in: [src/batteries/media/builder.ts:192](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L192)

Image transforms.

##### Returns

[`ImageNamespace`](../interfaces/ImageNamespace.md)

***

### sheet

#### Get Signature

```ts
get sheet(): SheetNamespace;
```

Defined in: [src/batteries/media/builder.ts:182](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L182)

Spreadsheet mutations.

##### Returns

[`SheetNamespace`](../interfaces/SheetNamespace.md)

***

### slides

#### Get Signature

```ts
get slides(): SlidesNamespace;
```

Defined in: [src/batteries/media/builder.ts:187](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L187)

Presentation mutations.

##### Returns

[`SlidesNamespace`](../interfaces/SlidesNamespace.md)

## Methods

### applyPatch()

```ts
applyPatch(patch: string, options?: {
  with?: MediaChainRef[];
}): MediaChain;
```

Defined in: [src/batteries/media/builder.ts:133](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L133)

Apply a unified-diff patch.

#### Parameters

| Parameter       | Type                                                                  |
| --------------- | --------------------------------------------------------------------- |
| `patch`         | `string`                                                              |
| `options`       | { `with?`: [`MediaChainRef`](../type-aliases/MediaChainRef.md)\[]; } |
| `options.with?` | [`MediaChainRef`](../type-aliases/MediaChainRef.md)\[]                 |

#### Returns

`MediaChain`

***

### chunk()

```ts
chunk(options?: {
  overlap?: number;
  size?: number;
  strategy?: "sentence" | "paragraph" | "fixed";
}): MediaChain;
```

Defined in: [src/batteries/media/builder.ts:169](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L169)

Chunk extracted text. Terminal: resolves to a chunk array.

#### Parameters

| Parameter           | Type                                                                                                    |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| `options`           | { `overlap?`: `number`; `size?`: `number`; `strategy?`: `"sentence"` | `"paragraph"` | `"fixed"`; } |
| `options.overlap?`  | `number`                                                                                                |
| `options.size?`     | `number`                                                                                                |
| `options.strategy?` | `"sentence"` | `"paragraph"` | `"fixed"`                                                              |

#### Returns

`MediaChain`

***

### convert()

```ts
convert(to: string): MediaChain;
```

Defined in: [src/batteries/media/builder.ts:71](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L71)

Convert to another format (requires a convert engine).

#### Parameters

| Parameter | Type     |
| --------- | -------- |
| `to`      | `string` |

#### Returns

`MediaChain`

***

### diff()

```ts
diff(other: MediaChainRef): MediaChain;
```

Defined in: [src/batteries/media/builder.ts:128](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L128)

Compare against another media. Terminal: resolves to a structured diff.

#### Parameters

| Parameter | Type                                                |
| --------- | --------------------------------------------------- |
| `other`   | [`MediaChainRef`](../type-aliases/MediaChainRef.md) |

#### Returns

`MediaChain`

***

### extractAssets()

```ts
extractAssets(options?: {
  types?: ("all" | "image" | "font" | "attachment")[];
}): MediaChain;
```

Defined in: [src/batteries/media/builder.ts:160](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L160)

Extract embedded assets. Terminal: resolves to a media list.

#### Parameters

| Parameter        | Type                                                                    |
| ---------------- | ----------------------------------------------------------------------- |
| `options`        | { `types?`: (`"all"` | `"image"` | `"font"` | `"attachment"`)\[]; } |
| `options.types?` | (`"all"` | `"image"` | `"font"` | `"attachment"`)\[]                  |

#### Returns

`MediaChain`

***

### extractMetadata()

```ts
extractMetadata(): MediaChain;
```

Defined in: [src/batteries/media/builder.ts:155](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L155)

Extract metadata. Terminal: resolves to a metadata object.

#### Returns

`MediaChain`

***

### extractText()

```ts
extractText(options?: {
  lang?: string[];
  ocr?: "off" | "auto" | "force";
  ocrOut?: "json" | "txt" | "hocr";
}): MediaChain;
```

Defined in: [src/batteries/media/builder.ts:140](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L140)

Extract text (routes by format; OCR engine used when needed). Terminal: resolves to text.

#### Parameters

| Parameter         | Type                                                                                                             |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| `options`         | { `lang?`: `string`\[]; `ocr?`: `"off"` | `"auto"` | `"force"`; `ocrOut?`: `"json"` | `"txt"` | `"hocr"`; } |
| `options.lang?`   | `string`\[]                                                                                                       |
| `options.ocr?`    | `"off"` | `"auto"` | `"force"`                                                                                 |
| `options.ocrOut?` | `"json"` | `"txt"` | `"hocr"`                                                                                  |

#### Returns

`MediaChain`

***

### merge()

```ts
merge(...others: MediaChainRef[]): MediaChain;
```

Defined in: [src/batteries/media/builder.ts:89](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L89)

Merge other media into this one, in order.

#### Parameters

| Parameter   | Type                                                  |
| ----------- | ----------------------------------------------------- |
| ...`others` | [`MediaChainRef`](../type-aliases/MediaChainRef.md)\[] |

#### Returns

`MediaChain`

***

### normalize()

```ts
normalize(): MediaChain;
```

Defined in: [src/batteries/media/builder.ts:118](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L118)

Normalize structure/encoding.

#### Returns

`MediaChain`

***

### redact()

```ts
redact(options: {
  match: string | RegExp | (string | RegExp)[];
  replace?: string;
}): MediaChain;
```

Defined in: [src/batteries/media/builder.ts:99](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L99)

Redact matching text (literals or RegExp).

#### Parameters

| Parameter          | Type                                                                                   |
| ------------------ | -------------------------------------------------------------------------------------- |
| `options`          | { `match`: `string` | `RegExp` | (`string` | `RegExp`)\[]; `replace?`: `string`; } |
| `options.match`    | `string` | `RegExp` | (`string` | `RegExp`)\[]                                       |
| `options.replace?` | `string`                                                                               |

#### Returns

`MediaChain`

***

### reorder()

```ts
reorder(order: number[]): MediaChain;
```

Defined in: [src/batteries/media/builder.ts:94](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L94)

Reorder pages by 1-based index.

#### Parameters

| Parameter | Type       |
| --------- | ---------- |
| `order`   | `number`\[] |

#### Returns

`MediaChain`

***

### run()

```ts
run(): Promise<StepResult>;
```

Defined in: [src/batteries/media/builder.ts:228](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L228)

Execute and return the raw [PlanResult](../type-aliases/PlanResult.md) (no unwrapping).

#### Returns

`Promise`<[`StepResult`](../type-aliases/StepResult.md)>

***

### sanitize()

```ts
sanitize(): MediaChain;
```

Defined in: [src/batteries/media/builder.ts:113](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L113)

Remove potentially unsafe embedded content.

#### Returns

`MediaChain`

***

### select()

```ts
select(options: {
  pages: number[];
}): MediaChain;
```

Defined in: [src/batteries/media/builder.ts:76](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L76)

Keep only the listed 1-based pages.

#### Parameters

| Parameter       | Type                       |
| --------------- | -------------------------- |
| `options`       | { `pages`: `number`\[]; } |
| `options.pages` | `number`\[]                 |

#### Returns

`MediaChain`

***

### split()

```ts
split(options?: {
  by?: "page" | "section";
  ranges?: number[][];
}): MediaChain;
```

Defined in: [src/batteries/media/builder.ts:81](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L81)

Split by page (optionally grouped `[[start,end], …]`). Terminal: resolves to media list.

#### Parameters

| Parameter         | Type                                                           |
| ----------------- | -------------------------------------------------------------- |
| `options`         | { `by?`: `"page"` | `"section"`; `ranges?`: `number`\[]\[]; } |
| `options.by?`     | `"page"` | `"section"`                                        |
| `options.ranges?` | `number`\[]\[]                                                   |

#### Returns

`MediaChain`

***

### then()

```ts
then<TResult1, TResult2>(onfulfilled?:
  | ((value: unknown) => TResult1 | PromiseLike<TResult1>)
  | null, onrejected?:
  | ((reason: unknown) => TResult2 | PromiseLike<TResult2>)
| null): PromiseLike<TResult1 | TResult2>;
```

Defined in: [src/batteries/media/builder.ts:220](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L220)

Thenable: awaiting the chain executes it.

#### Type Parameters

| Type Parameter | Default type |
| -------------- | ------------ |
| `TResult1`     | `unknown`    |
| `TResult2`     | `never`      |

#### Parameters

| Parameter      | Type                                                                              |
| -------------- | --------------------------------------------------------------------------------- |
| `onfulfilled?` | | ((`value`: `unknown`) => `TResult1` | `PromiseLike`<`TResult1`>) | `null`  |
| `onrejected?`  | | ((`reason`: `unknown`) => `TResult2` | `PromiseLike`<`TResult2`>) | `null` |

#### Returns

`PromiseLike`<`TResult1` | `TResult2`>

#### Implementation of

```ts
PromiseLike.then;
```

***

### toOps()

```ts
toOps(): MediaOp[];
```

Defined in: [src/batteries/media/builder.ts:204](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L204)

The accumulated ops (a copy).

#### Returns

[`MediaOp`](../interfaces/MediaOp.md)\[]

***

### toPipe()

```ts
toPipe(): string;
```

Defined in: [src/batteries/media/builder.ts:209](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L209)

The canonical pipe form of the accumulated chain.

#### Returns

`string`

***

### updateText()

```ts
updateText(anchor: string, replace: string): MediaChain;
```

Defined in: [src/batteries/media/builder.ts:123](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L123)

Replace the first occurrence of anchor text.

#### Parameters

| Parameter | Type     |
| --------- | -------- |
| `anchor`  | `string` |
| `replace` | `string` |

#### Returns

`MediaChain`

***

### withOp()

```ts
withOp(verb: string, args: Record<string, MediaArgValue>): MediaChain;
```

Defined in: [src/batteries/media/builder.ts:215](https://github.com/NHTIO/ADK/blob/v1.20260713.1/src/src/batteries/media/builder.ts#L215)

Internal — used by namespaces to append.

#### Parameters

| Parameter | Type                                                                                                                                                         |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `verb`    | `string`                                                                                                                                                     |
| `args`    | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`MediaArgValue`](../type-aliases/MediaArgValue.md)> |

#### Returns

`MediaChain`