> For AI agents: the complete documentation index is available at https://docs.flashnerd.com/llms.txt, the full documentation bundle is available at https://docs.flashnerd.com/llms-full.txt.

# Package images and audio

## Purpose and location

Place ordinary image/audio files directly inside `media/`. These are binary files, not JSON or JSONL. There is no asset catalog. The directory is optional.

```text
media/
├── cat.png
└── example.wav
```

## Basic examples

Supply your own image and audio bytes for `cat.png` and `example.wav`. For downloadable placeholders, use the full example files below and keep their matching paths.

A card references them through values of fields defined in its deck. These JSON objects are **nested field-value examples**, not complete card records:

```json
{"type":"image","mediaPath":"media/cat.png"}
```

```json
{"type":"audio","mediaPath":"media/example.wav"}
```

See the [complete card example](https://docs.flashnerd.com/reference/flashnerd-format/cards.md) for where these objects go, and [all field options](https://docs.flashnerd.com/reference/flashnerd-format/fields.md) for audio autoplay and image-occlusion masks.

## Full example

The <a href="https://docs.flashnerd.com/examples/flashnerd-format/comprehensive.flashnerd" download>complete example package</a> includes these real binary files, used by its [full cards](https://docs.flashnerd.com/reference/flashnerd-format/cards.md):

| Archive path              | Download                                                                                              | Contents                                                 |
| ------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `media/station.png`       | <a href="https://docs.flashnerd.com/examples/flashnerd-format/full/media/station.png" download>station.png</a>             | Valid tiny placeholder PNG; replace with your own image. |
| `media/pronunciation.wav` | <a href="https://docs.flashnerd.com/examples/flashnerd-format/full/media/pronunciation.wav" download>pronunciation.wav</a> | Valid short silent WAV; replace with your own recording. |

The matching nested values from the inherited language card are below. They are parts of a card record, not standalone media records. Its image-occlusion field references the same PNG with rectangle data; see the [full card](https://docs.flashnerd.com/reference/flashnerd-format/cards.md). Audio autoplay is set in the [owning deck](https://docs.flashnerd.com/reference/flashnerd-format/decks.md), or in a complete card override.

```json
{
  "type": "image",
  "mediaPath": "media/station.png",
  "useTemplateSettings": true
}
```

```json
{
  "type": "audio",
  "mediaPath": "media/pronunciation.wav",
  "useTemplateSettings": true
}
```

## Filename and value options

| Option             | Accepted input / behavior                                                                                                                                     |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Filename           | A single nonempty name; ordinary names, spaces and Unicode are accepted. Use a matching file extension for your image/audio format.                           |
| Directory          | Exactly `media/`, with no nested subdirectories.                                                                                                              |
| `mediaPath`        | Exact, case-sensitive archive path including `media/`, such as `media/cat.png`. The same file may be referenced by several cards.                             |
| Blank media        | Omit `mediaPath`, set it to null, or use `""`. These all mean an intentionally blank media field.                                                             |
| Forbidden names    | `.` or `..`, forward/backslashes, and control characters.                                                                                                     |
| Default size limit | 10 MiB per referenced file; see [package limits](https://docs.flashnerd.com/reference/flashnerd-format/package.md#limits). Referenced files must be nonempty. |
| Compression        | STORE or DEFLATE. Export compresses only when the result is smaller.                                                                                          |

Do not use an absolute filesystem path, web URL, base64 payload, or asset ID in place of `mediaPath`. Package checks cover paths, byte counts, and ZIP integrity. They do not decode images or audio, or enforce a filename-extension allowlist. Display and playback support belongs to the importing app.

## Missing files and relationships

An existing referenced file must pass integrity/size checks. A missing referenced file is recoverable: the app keeps the card and leaves the field blank. If the missing image belongs to an image-occlusion field, the app clears its masks as well. Unreferenced media is skipped during payload validation.

For intentionally blank image occlusion, omit the path and masks (or use an empty mask list). Package validation accepts otherwise valid rectangles without an image path, but export rejects nonempty rectangles without an image path. Include the image for any masks you want to use. See [field values](https://docs.flashnerd.com/reference/flashnerd-format/fields.md).

There is no separate media-record schema. The <a href="https://docs.flashnerd.com/examples/flashnerd-format/schemas/field_value.schema.json" download>field-value schema</a> describes the JSON reference.