--- url: 'https://adk.nht.io/api/@nhtio/adk/common/classes/Media.md' description: 'Lazy, re-openable view over a binary asset (image, audio, video, document).' --- # Class: Media Defined in: [lib/classes/media.ts:233](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L233) Lazy, re-openable view over a binary asset (image, audio, video, document). ## Remarks Dual-peer to [@nhtio/adk!Tokenizable](Tokenizable.md) (silo) and [@nhtio/adk!SpooledArtifact](../../spooled_artifact/classes/SpooledArtifact.md) (handle). Wraps a [@nhtio/adk!MediaReader](../interfaces/MediaReader.md) contract — the framework owns the contract, the implementor owns the storage backend. Bytes are reached only through the reader; the primitive itself never inlines bytes. Construction requires `trustTier` and `modalityHazard` — the framework refuses to guess provenance or decoding hazard. Ergonomic factories ([Media.userAttachment](#userattachment), [Media.toolGenerated](#toolgenerated), [Media.retrievedPublic](#retrievedpublic), [Media.retrievedPrivate](#retrievedprivate)) force the labelling decision at the call site without becoming defaults on the bare constructor. ## Constructors ### Constructor ```ts new Media(raw: RawMedia): Media; ``` Defined in: [lib/classes/media.ts:300](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L300) #### Parameters | Parameter | Type | Description | | --------- | --------------------------------------- | ------------------------------------------------------- | | `raw` | [`RawMedia`](../interfaces/RawMedia.md) | The raw media input validated against `rawMediaSchema`. | #### Returns `Media` #### Throws [@nhtio/adk/exceptions!E\_INVALID\_INITIAL\_MEDIA\_VALUE](../../exceptions/variables/E_INVALID_INITIAL_MEDIA_VALUE.md) when `raw` does not satisfy the schema. #### Throws [@nhtio/adk/exceptions!E\_NOT\_A\_MEDIA\_READER](../../exceptions/variables/E_NOT_A_MEDIA_READER.md) when `raw.reader` does not implement [@nhtio/adk!MediaReader](../interfaces/MediaReader.md). ## Properties | Property | Modifier | Type | Default value | Description | Defined in | | --------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | | `filename` | `readonly` | `string` | `undefined` | Filename surfaced to providers that key on it. | [lib/classes/media.ts:275](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L275) | | `id` | `readonly` | `string` | `undefined` | Stable unique identifier. | [lib/classes/media.ts:269](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L269) | | `kind` | `readonly` | `"audio"` | `"document"` | `"image"` | `"video"` | `undefined` | Media kind. | [lib/classes/media.ts:271](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L271) | | `mimeType` | `readonly` | `string` | `undefined` | MIME type of the underlying bytes. | [lib/classes/media.ts:273](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L273) | | `modalityHazard` | `readonly` | `"inert"` | `"extractable-instructions"` | `"opaque-perceptual"` | `undefined` | Modality hazard declared at construction time. | [lib/classes/media.ts:281](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L281) | | `source` | `readonly` | `string` | `undefined` | `undefined` | Optional provenance pointer. | [lib/classes/media.ts:277](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L277) | | `stash` | `readonly` | [`Registry`](Registry.md) | `undefined` | Mutable per-instance metadata register; middleware pipelines append to this. | [lib/classes/media.ts:283](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L283) | | `trustTier` | `readonly` | `"first-party"` | `"third-party-public"` | `"third-party-private"` | `undefined` | Trust tier declared at construction time. | [lib/classes/media.ts:279](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L279) | | `MediaKind` | `static` | readonly \[`"image"`, `"audio"`, `"video"`, `"document"`] | `MediaKind` | The set of recognised media kinds. Exposed for downstream schemas that need to discriminate on `kind`. | [lib/classes/media.ts:243](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L243) | | `MediaModalityHazard` | `static` | readonly \[`"inert"`, `"extractable-instructions"`, `"opaque-perceptual"`] | `MediaModalityHazard` | The set of recognised modality hazards. | [lib/classes/media.ts:253](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L253) | | `MediaTrustTier` | `static` | readonly \[`"first-party"`, `"third-party-public"`, `"third-party-private"`] | `MediaTrustTier` | The set of recognised trust tiers. | [lib/classes/media.ts:248](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L248) | | `schema` | `static` | `ObjectSchema`<[`RawMedia`](../interfaces/RawMedia.md)> | `rawMediaSchema` | Validator schema that accepts a [RawMedia](../interfaces/RawMedia.md) object. | [lib/classes/media.ts:237](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L237) | ## Methods ### asBase64() ```ts asBase64(): Promise; ``` Defined in: [lib/classes/media.ts:419](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L419) Drains the reader's stream and returns the underlying bytes as a base64 string. #### Returns `Promise`<`string`> #### Remarks Cross-environment: prefers Node's `Buffer.from(buf).toString('base64')` when available; otherwise chunk-encodes through `btoa` with a 0x8000-byte window to avoid stack overflow on large buffers. *** ### asBytes() ```ts asBytes(): Promise>; ``` Defined in: [lib/classes/media.ts:389](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L389) Drains the reader's stream and returns the underlying bytes as a single `Uint8Array`. #### Returns `Promise`<`Uint8Array`<`ArrayBufferLike`>> #### Remarks Convenience for callers that need the full buffer (e.g. inline base64 encoding). Forces full materialisation — large assets should be piped through [Media.stream](#stream) instead. *** ### byteLength() ```ts byteLength(): Promise; ``` Defined in: [lib/classes/media.ts:378](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L378) Returns the total number of bytes in the underlying data, or `undefined` if unknown. #### Returns `Promise`<`number` | `undefined`> The byte length, or `undefined` when the underlying source cannot report it. *** ### stream() ```ts stream(): Promise>>; ``` Defined in: [lib/classes/media.ts:369](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L369) Re-opens the underlying byte source and returns a fresh ReadableStream. #### Returns `Promise`<`ReadableStream`<`Uint8Array`<`ArrayBufferLike`>>> A drainable `ReadableStream` over the underlying bytes. *** ### toJSON() ```ts toJSON(): SerializedMedia; ``` Defined in: [lib/classes/media.ts:434](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L434) Returns the metadata-only serialisation of this Media. Bytes and the reader are stripped so naive event/log serialisation never materialises bytes. #### Returns [`SerializedMedia`](../interfaces/SerializedMedia.md) #### Remarks Implementations that have cheap, already-cached `byteLength` may opt to include it; this default implementation omits it to preserve the "lazy by default" invariant. Consumers that need byteLength on the serialised payload should call `await media.byteLength()` and merge the result. *** ### isMedia() ```ts static isMedia(value: unknown): value is Media; ``` Defined in: [lib/classes/media.ts:264](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L264) Returns `true` if `value` is a Media instance. #### Parameters | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to test. | #### Returns `value is Media` `true` when `value` is a Media instance. #### Remarks Uses [@nhtio/adk!isInstanceOf](../../guards/functions/isInstanceOf.md) for cross-realm safety. *** ### retrievedPrivate() ```ts static retrievedPrivate(args: { filename: string; id?: string; kind: "audio" | "document" | "image" | "video"; mimeType: string; reader: MediaReader; source?: string; stash?: Record; }): Media; ``` Defined in: [lib/classes/media.ts:521](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L521) Factory: constructs a Media retrieved from a private third-party source. #### Parameters | Parameter | Type | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `args` | { `filename`: `string`; `id?`: `string`; `kind`: `"audio"` | `"document"` | `"image"` | `"video"`; `mimeType`: `string`; `reader`: [`MediaReader`](../interfaces/MediaReader.md); `source?`: `string`; `stash?`: [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`MediaStashEntry`](../interfaces/MediaStashEntry.md)>; } | | `args.filename` | `string` | | `args.id?` | `string` | | `args.kind` | `"audio"` | `"document"` | `"image"` | `"video"` | | `args.mimeType` | `string` | | `args.reader` | [`MediaReader`](../interfaces/MediaReader.md) | | `args.source?` | `string` | | `args.stash?` | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`MediaStashEntry`](../interfaces/MediaStashEntry.md)> | #### Returns `Media` #### Remarks Pre-fills `trustTier: 'third-party-private'` and derives `modalityHazard` from `kind`. *** ### retrievedPublic() ```ts static retrievedPublic(args: { filename: string; id?: string; kind: "audio" | "document" | "image" | "video"; mimeType: string; reader: MediaReader; source?: string; stash?: Record; }): Media; ``` Defined in: [lib/classes/media.ts:499](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L499) Factory: constructs a Media retrieved from a public third-party source. #### Parameters | Parameter | Type | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `args` | { `filename`: `string`; `id?`: `string`; `kind`: `"audio"` | `"document"` | `"image"` | `"video"`; `mimeType`: `string`; `reader`: [`MediaReader`](../interfaces/MediaReader.md); `source?`: `string`; `stash?`: [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`MediaStashEntry`](../interfaces/MediaStashEntry.md)>; } | | `args.filename` | `string` | | `args.id?` | `string` | | `args.kind` | `"audio"` | `"document"` | `"image"` | `"video"` | | `args.mimeType` | `string` | | `args.reader` | [`MediaReader`](../interfaces/MediaReader.md) | | `args.source?` | `string` | | `args.stash?` | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`MediaStashEntry`](../interfaces/MediaStashEntry.md)> | #### Returns `Media` #### Remarks Pre-fills `trustTier: 'third-party-public'` and derives `modalityHazard` from `kind`. *** ### toolGenerated() ```ts static toolGenerated(args: { filename: string; id?: string; kind: "audio" | "document" | "image" | "video"; mimeType: string; reader: MediaReader; source?: string; stash?: Record; }): Media; ``` Defined in: [lib/classes/media.ts:477](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L477) Factory: constructs a Media produced by a first-party tool. #### Parameters | Parameter | Type | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `args` | { `filename`: `string`; `id?`: `string`; `kind`: `"audio"` | `"document"` | `"image"` | `"video"`; `mimeType`: `string`; `reader`: [`MediaReader`](../interfaces/MediaReader.md); `source?`: `string`; `stash?`: [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`MediaStashEntry`](../interfaces/MediaStashEntry.md)>; } | | `args.filename` | `string` | | `args.id?` | `string` | | `args.kind` | `"audio"` | `"document"` | `"image"` | `"video"` | | `args.mimeType` | `string` | | `args.reader` | [`MediaReader`](../interfaces/MediaReader.md) | | `args.source?` | `string` | | `args.stash?` | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`MediaStashEntry`](../interfaces/MediaStashEntry.md)> | #### Returns `Media` #### Remarks Pre-fills `trustTier: 'first-party'` and derives `modalityHazard` from `kind`. *** ### userAttachment() ```ts static userAttachment(args: { filename: string; id?: string; kind: "audio" | "document" | "image" | "video"; mimeType: string; reader: MediaReader; source?: string; stash?: Record; }): Media; ``` Defined in: [lib/classes/media.ts:455](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/media.ts#L455) Factory: constructs a Media representing a user-supplied attachment. #### Parameters | Parameter | Type | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `args` | { `filename`: `string`; `id?`: `string`; `kind`: `"audio"` | `"document"` | `"image"` | `"video"`; `mimeType`: `string`; `reader`: [`MediaReader`](../interfaces/MediaReader.md); `source?`: `string`; `stash?`: [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`MediaStashEntry`](../interfaces/MediaStashEntry.md)>; } | | `args.filename` | `string` | | `args.id?` | `string` | | `args.kind` | `"audio"` | `"document"` | `"image"` | `"video"` | | `args.mimeType` | `string` | | `args.reader` | [`MediaReader`](../interfaces/MediaReader.md) | | `args.source?` | `string` | | `args.stash?` | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`MediaStashEntry`](../interfaces/MediaStashEntry.md)> | #### Returns `Media` #### Remarks Pre-fills `trustTier: 'third-party-private'` and derives `modalityHazard` from `kind` (`document` → `'extractable-instructions'`; everything else → `'opaque-perceptual'`). Use the bare constructor when the conservative kind→hazard mapping is wrong for your case.