---
url: 'https://adk.nht.io/api/@nhtio/adk/common/interfaces/MediaReader.md'
description: Re-openable byte source contract for a Media instance.
---

# Interface: MediaReader

Defined in: [lib/contracts/media\_reader.ts:20](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/media_reader.ts#L20)

Re-openable byte source contract for a Media instance.

## Remarks

Peer to [@nhtio/adk!SpoolReader](../../spooled_artifact/interfaces/SpoolReader.md) but tuned for binary streaming rather than line-indexed text.
Each `stream()` call must return a fresh, drainable `ReadableStream` over the same underlying
bytes — implementations model replay: in-memory readers reconstitute the stream from the
buffer, file-backed readers reopen the file handle, HTTP-backed readers re-issue the fetch,
cloud blob readers re-issue the GET. The implementor owns the storage and the cost of keeping
the underlying source addressable. Implementors whose underlying source is genuinely
non-replayable (a raw HTTP body they were handed once) are responsible for caching locally
before constructing the Media.

Both methods may be synchronous or asynchronous to accommodate both in-memory and I/O-backed
implementations without forcing unnecessary promise overhead on simple cases.

## Methods

### byteLength()

```ts
byteLength(): number | Promise<number | undefined> | undefined;
```

Defined in: [lib/contracts/media\_reader.ts:43](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/media_reader.ts#L43)

Returns the total number of bytes in the underlying data, or `undefined` if unknown.

#### Returns

`number` | `Promise`<`number` | `undefined`> | `undefined`

The byte length of the underlying data, or `undefined` when unknown.

#### Remarks

Used for telemetry, budget checks, and pre-flight provider size validation without forcing
a stream drain. Sources of unknown length may return `undefined` — absence is treated as
"unknown", not "zero".

***

### stream()

```ts
stream():
  | ReadableStream<Uint8Array<ArrayBufferLike>>
| Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
```

Defined in: [lib/contracts/media\_reader.ts:31](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/media_reader.ts#L31)

Re-opens the underlying byte source and returns a fresh ReadableStream.

#### Returns

| `ReadableStream`<`Uint8Array`<`ArrayBufferLike`>>
| `Promise`<`ReadableStream`<`Uint8Array`<`ArrayBufferLike`>>>

A drainable ReadableStream of Uint8Array chunks over the underlying bytes.

#### Remarks

Each call yields a new, drainable stream over the same bytes. Render code that needs the
full buffer (e.g. base64-encoding an inline image\_url) drains the stream; render code that
can forward the stream (e.g. multipart upload) passes the stream through without buffering.