# Media

[View original](https://ittybit.com/docs/media)

### Multiple Files

Each media object can contain multiple [File Objects](/api/files).

Files are organized by their purpose: sources, tracks, and intelligence.

For example, a video in your project might have:

| Ref       | Description             | Object                                                                    |
| --------- | ----------------------- | ------------------------------------------------------------------------- |
| original  | The original video file | <Badge size="sm" icon="source" color="green">source</Badge>               |
| poster    | A poster image          | <Badge size="sm" icon="image" color="green">source</Badge>                |
| subtitles | A subtitles track       | <Badge size="sm" icon="track" color="orange">track</Badge>                |
| speech    | The full transcript     | <Badge size="sm" icon="intelligence" color="magenta">intelligence</Badge> |

It would be represented by a media object that looks like this:

```json
{
  "id": "med_abcdefgh1234",
  "object": "media",
  "kind": "video",
  "title": "My Video Example",
  "alt": "An example video used to demonstrate the ittybit API",
  "files": [
    {
      "id": "file_abcdefgh1234",
      "object": "source",
      "kind": "video",
      "type": "video/mp4;codecs=avc1,mp4a",
      "url": "https://you.ittybit.net/example/video.mp4",
      "ref": "original",
    },
    {
      "id": "file_abcdefgh5678",
      "object": "source",
      "kind": "image",
      "type": "image/png",
      "url": "https://you.ittybit.net/example/poster.png",
      "ref": "poster",
    },
    {
      "id": "file_ijklmnop1234",
      "object": "track",
      "kind": "subtitles",
      "type": "text/vtt",
      "url": "https://you.ittybit.net/example/subtitles.vtt",
      "ref": "subtitles",
    },
    {
      "id": "file_qrstuvwx1234",
      "object": "intelligence",
      "kind": "speech",
      "type": "application/json",
      "url": "https://you.ittybit.net/example/speech.json",
      "ref": "speech",
    }
  ],
  "urls": {
    "original": "https://you.ittybit.net/example/video.mp4",
    "poster": "https://you.ittybit.net/example/poster.png",
    "subtitles": "https://you.ittybit.net/example/subtitles.vtt",
    "speech": "https://you.ittybit.net/example/speech.json",
  },
  "created": "2025-01-01T01:23:45Z",
  "updated": "2025-01-01T01:23:45Z"
}
```

***

### Sources

Source files contain the actual content. They're the binary files that contain the pixels and sound.

At it's simplest, a source is what you'd pass to an `<img>` or `<video>` tag's `src` attribute.

<Tabs items={["HTML", "JSON"]}>
  <Tab value="HTML">
    ```html
    <video src="https://you.ittybit.net/example/video.mp4" type="video/mp4;codecs=avc1,mp4a">
    ```
  </Tab>

  <Tab value="JSON">
    ```json
    {
      "id": "med_abcdefgh1234",
      "object": "media",
      "kind": "video",
      "files": [
        {
          "id": "file_abcdefgh1234",
          "object": "source",
          "kind": "video",
          "type": "video/mp4;codecs=avc1,mp4a",
          "url": "https://you.ittybit.net/example/video.mp4",
          "ref": "original",
        }
      ],
      "urls": {
        "original": "https://you.ittybit.net/example/video.mp4",
      },
      // ... other props
      "created": "2025-01-01T01:23:45Z",
      "updated": "2025-01-01T01:23:45Z"
    }
    ```
  </Tab>
</Tabs>

In real projects, you'll usually want to provide multiple sources for a media object.

For example, you might want to [generate a poster image](/docs/image) for the video, which can be used to display a thumbnail or preview before playback begins.

```html
<video poster="https://you.ittybit.net/example/poster.png">
  <source src="https://you.ittybit.net/example/video.mp4" type="video/mp4">
</video>
```

You might then want to provide a version of the video in the more efficient WEBM format for browsers that support it, and fallback to your MP4 version for browsers that don't.

<Tabs items={["HTML", "JSON"]}>
  <Tab value="HTML">
    ```html
    <video poster="https://you.ittybit.net/example/poster.png">
      <source src="https://you.ittybit.net/example/video.webm" type="video/webm">
      <source src="https://you.ittybit.net/example/video.mp4" type="video/mp4">
    </video>
    ```
  </Tab>

  <Tab value="JSON">
    ```json
    {
      "id": "med_abcdefgh1234",
      "object": "media",
      "kind": "video",
      "files": [
        {
          "id": "file_abcdefgh1234",
          "object": "source",
          "kind": "video",
          "type": "video/mp4;codecs=avc1,mp4a",
          "url": "https://you.ittybit.net/example/video.mp4",
          "ref": "original",
        },
        {
          "id": "file_abcdefgh5678",
          "object": "source",
          "kind": "image",
          "type": "image/png",
          "url": "https://you.ittybit.net/example/poster.png",
          "ref": "poster",
        },
        {
          "id": "file_abcdefgh9012",
          "object": "source",
          "kind": "video",
          "type": "video/webm;codecs=vp9,opus",
          "url": "https://you.ittybit.net/example/video.webm",
          "ref": "webm",
        }
      ],
      "urls": {
        "original": "https://you.ittybit.net/example/video.mp4",
        "poster": "https://you.ittybit.net/example/poster.png",
        "webm": "https://you.ittybit.net/example/video.webm",
      },
      "created": "2025-01-01T01:23:45Z",
      "updated": "2025-01-01T01:23:45Z"
    }
    ```
  </Tab>
</Tabs>

<Accordions type="single" defaultValue="use-cases">
  <Accordion title="Why would I need multiple sources?" value="use-cases">
    There are many reasons a media object might have multiple sources:

    * The original is a large file and you want to save bandwidth by providing smaller versions to mobile users.
    * The original is a video and you want to provide compatible formats for different devices.
    * The original is an image and you want to provide more efficient formats to browsers that support them.
    * The original is an audio and you want to provide multiple languages.
  </Accordion>
</Accordions>

See the [Sources](/docs/sources) section for more details.

<Card href="/docs/sources" icon={<Icon icon="sources" className="text-brand-green" />} title="Sources" />

***

### Tracks

Tracks are supplementary files that provide additional information about the media to media players.

For example, a video might have a source file with the video and audio content, plus tracks generated for [subtitles](/docs/subtitles), [chapters](/docs/chapters), and [thumbnails](/docs/thumbnails).

<Tabs items={["HTML", "JSON"]}>
  <Tab value="HTML">
    ```html
    <video>
      <source src="https://you.ittybit.net/example/video.mp4" type="video/mp4">
      <track src="https://you.ittybit.net/example/subtitles.vtt" kind="subtitles">
      <track src="https://you.ittybit.net/example/chapters.vtt" kind="chapters">
      <track src="https://you.ittybit.net/example/thumbnails.vtt" kind="thumbnails">
    </video>
    ```
  </Tab>

  <Tab value="JSON">
    ```json
    {
      "id": "med_abcdefgh1234",
      "object": "media",
      "kind": "video",
      "files": [
        // ... other files
        {
          "id": "file_ijklmnop1234",
          "object": "track",
          "kind": "subtitles",
          "type": "text/vtt",
          "url": "https://you.ittybit.net/example/subtitles.vtt",
          "ref": "subtitles",
        },
        {
          "id": "file_ijklmnop5678",
          "object": "track",
          "kind": "chapters",
          "type": "text/vtt",
          "url": "https://you.ittybit.net/example/chapters.vtt",
          "ref": "chapters",
        },
        {
          "id": "file_ijklmnop9012",
          "object": "track",
          "kind": "thumbnails",
          "type": "text/vtt",
          "url": "https://you.ittybit.net/example/thumbnails.vtt",
          "ref": "thumbnails",
        }
      ],
      "urls": {
        "original": "https://you.ittybit.net/example/video.mp4",
        // ... other urls
        "subtitles": "https://you.ittybit.net/example/subtitles.vtt",
        "chapters": "https://you.ittybit.net/example/chapters.vtt",
        "thumbnails": "https://you.ittybit.net/example/thumbnails.vtt",
      },
      // ... other props
    }
    ```
  </Tab>
</Tabs>

<Accordions type="single" defaultValue="use-cases">
  <Accordion title="Why would I need tracks?" value="use-cases">
    Media objects might contain tracks when:

    * The original is video or audio, and you want to provide subtitles (maybe in multiple languages).
    * The original is a video and you want to provide chapters.
    * The original is a video and you want to provide thumbnails.
  </Accordion>
</Accordions>

See the [Tracks](/docs/tracks) section for more details.

<Card href="/docs/tracks" icon={<Icon icon="tracks" className="text-brand-orange" />} title="Tracks" />

***

### Intelligence

Intelligence files are [generated](/docs/tasks) by AI models and contain rich data about the media.

For example, a video might have intelligence files with a [transcript](/docs/speech), a list of [tags](/docs/tags), and a short but detailed [description](/docs/description).

```json
{
  "id": "med_abcdefgh1234",
  "object": "media",
  "kind": "video",
  "title": "My Video Example",
  "files": [
    // ... other files
    {
      "id": "file_qrstuvwx1234",
      "object": "intelligence",
      "kind": "speech",
      "type": "application/json",
      "url": "https://you.ittybit.net/example/speech.json",
      "ref": "speech"
    },
    {
      "id": "file_qrstuvwx5678",
      "object": "intelligence",
      "kind": "tags",
      "type": "application/json",
      "url": "https://you.ittybit.net/example/tags.json",
      "ref": "tags"
    },
    {
      "id": "file_qrstuvwx9012",
      "object": "intelligence",
      "kind": "description",
      "type": "application/json",
      "url": "https://you.ittybit.net/example/description.json",
      "ref": "description"
    }
  ],
  "urls": {
    "original": "https://you.ittybit.net/example/video.mp4",
    // ... other urls
    "speech": "https://you.ittybit.net/example/speech.json",
    "tags": "https://you.ittybit.net/example/tags.json",
    "description": "https://you.ittybit.net/example/description.json",
  },
  // ... other props
}
```

See the [Intelligence](/docs/intelligence) section for more details.

<Card href="/docs/intelligence" icon={<Icon icon="intelligence" className="text-brand-magenta" />} title="Intelligence" />

***

## Media Props

### ID

The `id` property is a unique identifier for the media object.

It is set by the API and is immutable.

```json
{
  "id": "med_abcdefgh1234",
  // ... other props
}
```

***

### Object

For media objects the `object` property is always `"media"`.

```json
{
  "id": "med_abcdefgh1234",
  "object": "media",
  // ... other props
}
```

***

### Kind

The `kind` property is inherited from the media object's original [file](/docs/files).

```json
{
  "id": "med_abcdefgh1234",
  "object": "media",
  "kind": "video",
  // ... other props
}
```

It will be one of `video`, `image`, or `audio`.

***

### Title

The `title` property allows you to give your media a human-readable name.

```json
{
  "id": "med_abcdefgh1234",
  "object": "media",
  "kind": "video",
  "title": "My Video Example",
  // ... other props
}
```

This is useful for organization and display purposes in your application.

***

### Alt

The `alt` property is a human-readable description of the media.

```json
{
  "id": "med_abcdefgh1234",
  "object": "media",
  "kind": "video",
  "title": "My Video Example",
  "alt": "An animated short film about a giant rabbit",
  // ... other props
}
```

This is useful for SEO and accessibility.

***

### Files

The `files` property contains an array of [file objects](/docs/files).

<Card href="/docs/files" icon={<Icon icon="files" className="text-brand-blue" />} title="Files" />

Files can be [Source](/docs/sources), [Track](/docs/tracks), or [Intelligence](/docs/intelligence) objects.

<Cards>
  <Card href="/docs/sources" icon={<Icon icon="sources" className="text-brand-green" />} title="Sources" />

  <Card href="/docs/tracks" icon={<Icon icon="track" className="text-brand-orange" />} title="Tracks" />

  <Card href="/docs/intelligence" icon={<Icon icon="intelligence" className="text-brand-magenta" />} title="Intelligence" />
</Cards>

***

### URLs

Media objects include convenience URLs for any sources, tracks, and intelligence files that have been given a `ref` prop (see [refs](/docs/files#ref)).

```json
{
  "id": "med_abcdefgh1234",
  // ... other props,
  "urls" : {
    "original": "https://you.ittybit.net/example/video.mp4",
    "webm": "https://you.ittybit.net/example/video.webm",
    "poster": "https://you.ittybit.net/example/poster.png",
    "subtitles": "https://you.ittybit.net/example/subtitles.vtt",
    "speech": "https://you.ittybit.net/example/speech.json",
    "placeholder": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAMAAAADCAYAAABWKLW/AAAACXBIWXMAAAAAAAAAAQCEeRdzAAAAMElEQVR4nGOQ4dR9qC/l+F+YQ/shg6Wq1//1Czb+D/fL/s+gpWj/sKKw47+3c8wjABmiEEDGwErfAAAAAElFTkSuQmCC",
  }
}
```

The `placeholder` URL is a tiny base64 encoded placeholder image that can be used to display a thumbnail or preview before the media is loaded. It is automatically generated for image and video `kinds`.

***

### Background

The `background` property is a hex color code that can be used to display a background color for the media.

It is automatically generated for image and video `kinds`.

```json
{
  "id": "med_abcdefgh1234",
  // ... other props,
  "background": "#2OBO75",
}
```

### Created

The `created` property is the date and time the media object was created.

```json
{
  "id": "med_abcdefgh1234",
  // ... other props
  "created": "2025-01-01T01:23:45Z",
}
```

Ittybit uses [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format for all date and time properties, and sets them to UTC (Coordinated Universal Time).

The `created` property is set automatically by the API when you create a new media object.

***

### Updated

The `updated` property is the date and time the media object was last updated.

```json
{
  "id": "med_abcdefgh1234",
  // ... other props  
  "created": "2025-01-01T01:23:45Z",
  "updated": "2025-01-01T01:23:45Z",
}
```

The `updated` property is set automatically by the API. Initially it will be the same as the `created` property, then it will be updated whenever the media object is modified.

***

### Metadata

See the [Metadata](/docs/metadata) section for more details.

<Card href="/docs/metadata" icon={<Icon icon="metadata" className="text-brand-purple" />} title="Metadata" />

***

## API Reference

See the [API Reference](/api/media) section for a full rundown of the media object, its properties, the available endpoints, and how to use them.

<Card href="/api" icon={<Icon icon="terminal" className="text-brand-green" />} title="API Reference" />

***