Developers: embed player, oEmbed and tus uploads
Technical reference for VideoBB: the iframe embed and its parameters, the oEmbed endpoint, tus resumable uploads, HLS playback and structured data.
You can build on VideoBB in four ways: embed the player with one iframe, turn watch links into players with oEmbed, upload files with any tus client, and read the VideoObject data on every watch page.
This page is the technical reference. For a step-by-step walk-through for site owners, read the embed guide instead.
Embed the player
Every video with embedding turned on can play on any website. You only need one iframe.
The embed code
<iframe src="https://videobb.com/embed/VIDEO_ID" width="640" height="360" frameborder="0"
allow="autoplay; fullscreen; picture-in-picture" allowfullscreen loading="lazy" title="Video title"></iframe>The video ID is the short code at the start of a watch URL, such as v7fs1pq. The Share button on each video gives you this code ready to copy.
Embed parameters
| Parameter | Effect |
|---|---|
autoplay=1 | Starts playing on load. It also mutes the player, because browsers only allow muted autoplay. |
muted=1 | Starts with the sound off. |
loop=1 | Plays the video again when it ends. |
t=90 | Starts at a time, given in seconds. |
Join parameters with &, for example /embed/VIDEO_ID?autoplay=1&loop=1. Our guide to browser autoplay rules explains why sound must start muted.
When a video will not embed
- The creator turned off Allow embedding for that video.
- The video is private. Public and unlisted videos can be embedded.
- The video is still processing, or it was removed.
In each case the iframe shows "This video is unavailable" instead of the player.
oEmbed
oEmbed is an open standard. It lets a CMS turn a pasted link into a player on its own.
The request
GET https://videobb.com/api/oembed?url=WATCH_URLEvery page also points to this endpoint with a <link rel="alternate" type="application/json+oembed"> tag, so tools can find it without setup.
The response
The answer is JSON (oEmbed version 1.0, type video). It includes these fields:
title,author_nameandauthor_urlfor the video and its channel.html: the iframe, sized 640 by 360.thumbnail_url, with a width of 1280 and a height of 720.provider_nameandprovider_url.
Only public videos with embedding on are returned. Any other link gets a 404.
Upload with tus
Uploads use the open tus resumable upload protocol, version 1.0.0. A tus client sends a file in pieces, so it can resume after a break.
Endpoint and extensions
The endpoint is /files. It supports the creation, termination and expiration extensions. Uploads run on your signed-in session, and VideoBB does not issue API keys. An unfinished upload can be resumed for 48 hours.
Metadata and limits
filenameis required and must end in a supported type, such as .mp4, .mkv or .mov.filetypeandtitleare optional.- Files can be up to 4 GB. Free accounts get 10 uploads per 24 hours and Premium gets 100.
| Status | Meaning |
|---|---|
| 412 | The Tus-Resumable header is not 1.0.0 |
| 413 | The file is larger than 4 GB |
| 415 | The file name has an unsupported extension |
| 429 | The daily upload allowance is used up |
The full list of file types is in supported formats and size limits.
Playback with HLS
Every video streams as HLS (RFC 8216). Segments are fragmented MP4, six seconds long, with H.264 video and AAC audio.
The master playlist
The playlist lives at /hls/VIDEO_ID/master.m3u8. It lists the quality levels the viewer may play: 144p to 1080p for everyone, and up to 2160p for Premium members.
Signed rendition links
Each quality level has a signed link that expires after six hours. Do not store these links. Fetch the master playlist again when you need fresh ones. See what HLS streaming is for how playlists and segments fit together.
Structured data and sitemaps
Watch pages carry VideoObject JSON-LD with the embed URL, the thumbnail and the duration. A video sitemap is published at /sitemap-videos.xml. Both help search engines find and understand each public video.