Ittybit

Introduction

Media objects in ittybit represent organized collections of files related to the same content.

{
  "id": "med_abcdefgh1234",
  "object": "media",
  "kind": "video",
  "title": "Big Buck Bunny",
  "files": [
    {
      "id": "file_abcdefgh1234",
      "object": "source",
      "kind": "video",
      "type": "video/mp4;codecs=avc1,mp4a",
      "url": "https://your-project.ittybit.net/bunny/video.mp4",
      "ref": "original",
    }
  ],
  "urls": {
    "original": "https://your-project.ittybit.net/bunny/video.mp4",
  },
  "created": "2025-01-01T01:23:45Z",
  "updated": "2025-01-01T01:23:45Z"
}

(Simplified example. We'll cover additional props in later sections.)

Multiple Files

Each media object can contain multiple file objects.

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	source
poster	A poster image	source
subtitles	A subtitles track	track
speech	The full transcript	intelligence

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

{
  "id": "med_abcdefgh1234",
  "object": "media",
  "kind": "video",
  "title": "Big Buck Bunny",
  "files": [
    {
      "id": "file_abcdefgh1234",
      "object": "source",
      "kind": "video",
      "type": "video/mp4;codecs=avc1,mp4a",
      "url": "https://your-project.ittybit.net/bunny/video.mp4",
      "ref": "original",
    },
    {
      "id": "file_abcdefgh5678",
      "object": "source",
      "kind": "image",
      "type": "image/png",
      "url": "https://your-project.ittybit.net/bunny/poster.png",
      "ref": "poster",
    },
    {
      "id": "file_ijklmnop1234",
      "object": "track",
      "kind": "subtitles",
      "type": "text/vtt",
      "url": "https://your-project.ittybit.net/bunny/subtitles.vtt",
      "ref": "subtitles",
    },
    {
      "id": "file_qrstuvwx1234",
      "object": "intelligence",
      "kind": "speech",
      "type": "application/json",
      "url": "https://your-project.ittybit.net/bunny/speech.json",
      "ref": "speech",
    }
  ],
  "urls": {
    "original": "https://your-project.ittybit.net/bunny/video.mp4",
    "poster": "https://your-project.ittybit.net/bunny/poster.png",
    "subtitles": "https://your-project.ittybit.net/bunny/subtitles.vtt",
    "speech": "https://your-project.ittybit.net/bunny/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.

<video src="https://your-project.ittybit.net/bunny/video.mp4" type="video/mp4;codecs=avc1,mp4a">

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 for the video, which can be used to display a thumbnail or preview before playback begins.

<video poster="https://your-project.ittybit.net/bunny/poster.png">
  <source src="https://your-project.ittybit.net/bunny/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.

<video poster="https://your-project.ittybit.net/bunny/poster.png">
  <source src="https://your-project.ittybit.net/bunny/video.webm" type="video/webm">
  <source src="https://your-project.ittybit.net/bunny/video.mp4" type="video/mp4">
</video>

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.

See the Sources section for more details.

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, chapters, and thumbnails.

<video>
  <source src="https://your-project.ittybit.net/bunny/video.mp4" type="video/mp4">
  <track src="https://your-project.ittybit.net/bunny/subtitles.vtt" kind="subtitles">
  <track src="https://your-project.ittybit.net/bunny/chapters.vtt" kind="chapters">
  <track src="https://your-project.ittybit.net/bunny/thumbnails.vtt" kind="thumbnails">
</video>

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.

See the Tracks section for more details.

Tracks

Intelligence

Intelligence files are generated by AI models and contain rich data about the media.

For example, a video might have intelligence files with a transcript, a list of tags, and a short but detailed description.

{
  "id": "med_abcdefgh1234",
  "object": "media",
  "kind": "video",
  "title": "Big Buck Bunny",
  "files": [
    // ... other files
    {
      "id": "file_qrstuvwx1234",
      "object": "intelligence",
      "kind": "speech",
      "type": "application/json",
      "url": "https://your-project.ittybit.net/bunny/speech.json",
      "ref": "speech"
    },
    {
      "id": "file_qrstuvwx5678",
      "object": "intelligence",
      "kind": "tags",
      "type": "application/json",
      "url": "https://your-project.ittybit.net/bunny/tags.json",
      "ref": "tags"
    },
    {
      "id": "file_qrstuvwx9012",
      "object": "intelligence",
      "kind": "description",
      "type": "application/json",
      "url": "https://your-project.ittybit.net/bunny/description.json",
      "ref": "description"
    }
  ],
  "urls": {
    "original": "https://your-project.ittybit.net/bunny/video.mp4",
    // ... other urls
    "speech": "https://your-project.ittybit.net/bunny/speech.json",
    "tags": "https://your-project.ittybit.net/bunny/tags.json",
    "description": "https://your-project.ittybit.net/bunny/description.json",
  },
  // ... other props
}

See the Intelligence section for more details.

Intelligence

Media Props

ID

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

It is set by the API and is immutable.

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

Object

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

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

Kind

The kind property is inherited from the media object's original file.

{
  "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.

{
  "id": "med_abcdefgh1234",
  "object": "media",
  "kind": "video",
  "title": "Big Buck Bunny",
  // ... 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.

{
  "id": "med_abcdefgh1234",
  "object": "media",
  "kind": "video",
  "title": "Big Buck Bunny",
  "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.

Files

Files can be Source, Track, or Intelligence objects.

Sources

Tracks

Intelligence

URLs

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

{
  "id": "med_abcdefgh1234",
  // ... other props,
  "urls" : {
    "original": "https://your-project.ittybit.net/bunny/video.mp4",
    "webm": "https://your-project.ittybit.net/bunny/video.webm",
    "poster": "https://your-project.ittybit.net/bunny/poster.png",
    "subtitles": "https://your-project.ittybit.net/bunny/subtitles.vtt",
    "speech": "https://your-project.ittybit.net/bunny/speech.json",
  }
}

Created

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

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

Ittybit uses 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.

{
  "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.

Status

The status property is the current status of the media object.

{
  "id": "med_abcdefgh1234",
  // ... other props
  "status": "ready",
}

The status property is one of pending, processing, ready, or failed.

Media

Introduction

Multiple Files

Sources

Sources

Tracks

Tracks

Intelligence

Intelligence

Media Props

ID

Object

Kind

Title

Alt

Files

Files

Sources

Tracks

Intelligence

URLs

Created

Updated

Status

Metadata

Metadata

API Reference

API Reference

On this page

Media

Why would I need multiple sources?

Sources

Why would I need tracks?

Tracks

Intelligence

Files

Sources

Tracks

Intelligence

Metadata

API Reference

On this page