Video

Video info are stored in a JSON document directly on swarm.

The JSON contains various details such as video title and description, video duration, quality and sources. Each source has its own info such as quality, size, bitrate and reference to the hash.

Schema versions

Schema v2.0

preview

type SwarmVideoPreview = {
    /** Schema version */
    v: "2.0"
    /** Title of the video */
    title: string
    /** Video creation timestamp */
    createdAt: number
    /** Video creation timestamp */
    updatedAt?: number | null
    /** Address of the owner of the video */
    ownerAddress: string
    /** Duration of the video in seconds */
    duration: number
    /** Thumbnail raw image */
    thumbnail?: SwarmImage | null
}

The schema info for the image can be found here.

detail

type SwarmVideoDetail = {
    /** Description of the video */
    description: string
    /** Video aspect ratio (width / height) */
    aspectRatio: number
    /** batch id used */
    batchId: string
    /** Optional extra data */
    personalData?: string | null
    /** List of available qualities of the video */
    sources: Array<
        | {
                type: "mp4"            
                /** Video resolution (eg: 1080p) */
                quality: string
                /** Path of the video */
                path: string
                /** Video size in bytes */
                size: number
          }
        | {
                type: "hls" | "dash"
                /** Path of the source */
                path: string
                /** Video size in bytes */        
                size: number
          }
    >
}

Regarding the hls and dash source type, each transcoded source is referenced in the list, but only the video sources (or playlists in case of hls) have the size field set. This is useful to calculate the price of the video depending on the selected quality in the player.

For the master playlist or dash manifest, the size field is set to 0.

Folders

Video v2 is folder based, so each resource is included under the same swarm hash.

The thumbnail images are store in a folder named thumb, while the video sources and manifests are stored under the sources folder.

Preview / Details files

The preview and details are 2 seprate files stored in root path of the video folder, with the same name without extension.

Both files are of application/json format and they are accessible at the url /bzz/<hash>/preview and /bzz/<hash>/details. The preview file is also set to be default entry point of the folder, hence it is also accessible at the url /bzz/<hash>.

preview example:

{
  "v": "2.0",
  "title": "Test encoding",
  "createdAt": 1684736940828,
  "updatedAt": 1684737204404,
  "ownerAddress": "0xbC47f778b1655fA004a351cD171f034f8422c047",
  "duration": 63,
  "thumbnail": {
    "aspectRatio": 1.7777777777777777,
    "blurhash": "UTHoa:-VEVO=??v]SlOu2ep0slR:kisia*bJ",
    "sources": [
      {
        "width": 720,
        "type": "png",
        "path": "thumb/720-png"
      },
      {
        "width": 720,
        "type": "png",
        "path": "thumb/720-png"
      },
      {
        "width": 480,
        "type": "png",
        "path": "thumb/480-png"
      }
    ]
  }
}

details example:

{
  "description": "",
  "aspectRatio": 1.7777777777777777,
  "sources": [
    {
      "type": "hls",
      "path": "sources/hls/720p.m3u8",
      "size": 2870760
    },
    {
      "type": "hls",
      "path": "sources/hls/480p.m3u8",
      "size": 2043372
    },
    {
      "type": "hls",
      "path": "sources/hls/360p.m3u8",
      "size": 1716252
    },
    {
      "type": "hls",
      "path": "sources/hls/audio.m3u8",
      "size": 921388
    },
    {
      "type": "hls",
      "path": "sources/hls/manifest.m3u8",
      "size": 0
    }
  ],
  "batchId": "8a3191917e72f038df179ad0587319bcb438da76e0e01bee3864535efe351291"
}

Schema v1.2

type SwarmVideo = {
  /**  UUID v4 of the video (Used for feed topic) */
  id: string
  /**  Title of the video */
  title: string
  /**  Description of the video */
  description: string
  /**  Quality of the original video */
  originalQuality: `${number}p`
  /**  Address of the owner of the video */
  ownerAddress: string
  /**  Duration of the video in seconds */
  duration: number
  /** Thumbnail raw image */
  thumbnail: SwarmImage | null
  /**  List of available qualities of the video */
  sources: Array<{
    /** Source quality */
    quality: string
    /** Source reference on Swarm */
    reference: string
    /** Source size in bytes */
    size?: number
    /** Source bitrate */
    bitrate?: number
  }>
  /** Video creation timestamp */
  createdAt: number,
  /** Video creation timestamp */
  updatedAt?: number | null,
  /** batch id used */
  batchId?: string | null,
  /** Optional extra data */
  personalData?: string,
  /** Schema version */
  v: "1.2"
}

Schema v1.1

type SwarmVideo = {
  /**  UUID v4 of the video (Used for feed topic) */
  id: string
  /**  Title of the video */
  title: string
  /**  Description of the video */
  description: string
  /**  Quality of the original video */
  originalQuality: `${number}p`
  /**  Address of the owner of the video */
  ownerAddress: string
  /**  Duration of the video in seconds */
  duration: number
  /** Thumbnail raw image */
  thumbnail: SwarmImage | null
  /**  List of available qualities of the video */
  sources: Array<{
    /** Source quality */
    quality: string
    /** Source reference on Swarm */
    reference: string
    /** Source size in bytes */
    size?: number
    /** Source bitrate */
    bitrate?: number
  }>
  /** Video creation timestamp */
  createdAt: number,
  /** Video creation timestamp */
  updatedAt?: number | null,
  /** batch id used */
  batchId?: string | null,
  /** Schema version */
  v: "1.1"
}

Schema v1.0

type SwarmVideo = {
  /**  UUID v4 of the video (Used for feed topic) */
  id: string
  /**  Title of the video */
  title: string
  /**  Description of the video */
  description: string
  /**  Quality of the original video */
  originalQuality: `${number}p`
  /**  Address of the owner of the video */
  ownerAddress: string
  /**  Duration of the video in seconds */
  duration: number
  /** Thumbnail raw image */
  thumbnail: SwarmImage | null
  /**  List of available qualities of the video */
  sources: Array<{
    /** Source quality */
    quality: string
    /** Source reference on Swarm */
    reference: string
    /** Source size in bytes */
    size?: number
    /** Source bitrate */
    bitrate?: number
  }>
  /** Schema version (defaults to 1.0) */
  v?: "1.0"
}

source example

{
  quality: "1080p"
  reference: "<reference hash>"
  size: 10000000
  bitrate: 100
}

Feed

The video does NOT implement a feed to avoid user’s direct manipulation of the manifest data without the index consent.

To have both a static hash (for SEO purpose) and decentralization, the video will have two links:

• A static one provided by the index (used in home, search, frame pages)

• A dynamic one with the direct reference to the swarm manifest hash (used in channel page, channel playlists)