An embeddable video player that refreshes its own signed links

Two ways to embed

The web component. <video-piper> is a drop-in player for developers. It plays the HLS stream (with hls.js loaded only where the browser needs it) or the MP4, shows captions, and refreshes its signed links before they expire, keeping the viewer's position. It is one script of about 3 KB gzipped, with no framework.

The iframe. For a page where you'd rather not write code, open a video's menu, choose Embed and copy the code, with options for autoplay (muted), loop, captions on and a start time.

Example

Your server returns the links for a video (it holds the API key, and can cache them per video). The page needs only the script and the element:

// Your server (Node.js): GET /api/videos/:id/links, cached per video
const cache = new Map();
app.get("/api/videos/:id/links", async (req, res) => {
  const hit = cache.get(req.params.id), now = Date.now() / 1000;
  if (hit && hit.playbackExpiresAt - now > 0.2 * hit.ttl) return res.json(hit);
  const r = await fetch(`${API}/videos/${req.params.id}?linkTtl=86400`, { headers: { Authorization: `Bearer ${API_KEY}` } });
  if (!r.ok) return res.status(r.status).end();
  const s = await r.json();
  const links = { playbackUrl: s.playbackUrl, streamUrl: s.streamUrl, posterUrl: s.posterPlaybackUrl,
                  captionsUrl: s.captions?.vttUrl, playbackExpiresAt: s.playbackExpiresAt, ttl: s.playbackExpiresAt - now };
  cache.set(req.params.id, links);
  res.json(links);
});

<script src="https://videopiper.com/player/player.js"></script>

<video-piper links-url="/api/videos/VIDEO_ID/links"></video-piper>

Both snippets come from the documentation, which also has a C# (ASP.NET Core) version of the server code.

Attributes and events

No endpoint? Leave out links-url, listen for the vp-expiring event and call element.setLinks({...}) with fresh links. The element is 16:9 by default and styled like any element (video-piper { width: 100%; }); the inner video is element.video for events like timeupdate and ended.

Control where it plays

• No key in the page. The signed links are all the page holds, and your endpoint decides who gets them.
• Allowed domains. List up to 20 sites, such as example.com and *.example.com. Links only play there, and the iframe's page can only be framed by them.
• Opt-in iframes. Embedding is off for each video until you turn it on. The embed URL carries a random token; turning embedding off revokes it, and turning it on again makes a new one. Changes take up to 5 minutes to reach every viewer, because embed pages are cached.

Plays count as delivery, like any other playback. See the HLS streaming API for signed links and allowed domains in more detail, or the captions API for subtitle files.

Which plans include the player

The web component and the iframe embed work on every plan, playing the signed MP4 playback link. On Pro and Scale they prefer the adaptive HLS stream when there is one. Embeds from Free-plan accounts show a small brand badge.

Usage beyond a paid plan is billed at $0.09 per processing minute, $0.15 per GB-month of storage and $0.55 per GB of delivery. Full details are on the pricing page.

In the documentation

• The video-piper web component
• Build your own player
• Embedding with an iframe (no code)
• Allowed domains
• Captions

Frequently asked questions