Play videos

A video plays from its master playlist. Which link you hand the player depends on the folder's read rule:

• A folder anyone may read gives every file a lasting publicUrl on cdn.shipmantis.com, cached at the edge. Use it as it is.
• Any other folder has no public link. Ask for a signed playback link, which opens that one video for as long as you say, or only for one signed-in user.

Public foldersCopy Anchor Link

const url = `https://cdn.shipmantis.com/${projectId}/${video.id}/master.m3u8`;
// the same link uploadVideo returned as publicUrl; posterUrl is …/poster.jpg

$url = "https://cdn.shipmantis.com/{$projectId}/{$lesson->video}/master.m3u8";
$poster = "https://cdn.shipmantis.com/{$projectId}/{$lesson->video}/poster.jpg";

The link never expires and the files are cached at the edge for an hour, so a video watched by thousands is served from Cloudflare, not from storage. Anyone who has the link can watch: public means public.

Signed playbackCopy Anchor Link

const url = await mantis.storage.playbackUrl(lesson.video); // works for an hour
const short = await mantis.storage.playbackUrl(lesson.video, { expiresIn: 10 * 60 });
const mine = await mantis.storage.playbackUrl(lesson.video, { userId: user.id }); // only this user

use Shipmantis\Mantis\Laravel\Facades\Mantis;

$url = Mantis::storage()->playbackUrl($lesson->video); // works for an hour
$short = Mantis::storage()->playbackUrl($lesson->video, expiresIn: 10 * 60);
$mine = Mantis::storage()->playbackUrl($lesson->video, userId: (string) $user->id); // only this user

The link looks like https://cdn.shipmantis.com/play/{token}/{id}/master.m3u8.

Who may ask for one follows the folder's read rule, like storage.url(): the secret key always, the publishable key when the rule lets the signed-in user read the video's master playlist.

How it is checked: the token sits in the link's path, and the master playlist points at its variant playlists by relative path, so every playlist the player asks for carries the same token, and every one of those requests checks it. The variant playlists point their segments at signed segment URLs (/play/c/{expires}/{signature}/...) that every viewer shares. That means:

• One link opens one video. Any playlist under the video's id opens with it; another id, or a path that leaves the video, opens nothing. A segment URL opens that one segment.
• Playlists are never cached. They are served private, no-store, so no cache hands the list of segments to someone without the token.
• Segments are cached at the edge. A segment URL ends on the next six-hour boundary after the link's expiry, so every link that ends in the same window gets the same URL, and Cloudflare serves one copy to every viewer until the window ends. A video watched by a thousand buyers streams from storage about once per window.
• Expiry is enforced when a playlist is read. A player reads the playlists when it starts, so an expired link refuses a new start or a reload, while a video already playing carries on to the end of its segment window. Give a link that outlives the viewing: the video's length plus a margin, or a few hours for a course page someone leaves open.

PlayersCopy Anchor Link

"use client";

import Hls from "hls.js";
import { useEffect, useRef } from "react";

export function VideoPlayer({ src, poster, token }: { src: string; poster?: string; token?: () => string }) {
  const ref = useRef<HTMLVideoElement>(null);
  const currentToken = useRef(token);
  const locked = token !== undefined;

  useEffect(() => {
    currentToken.current = token;
  });

  useEffect(() => {
    const video = ref.current;
    if (!video) return;

    if (!locked && video.canPlayType("application/vnd.apple.mpegurl")) {
      video.src = src;
      return;
    }
    if (!Hls.isSupported()) return;

    const hls = new Hls({
      xhrSetup: locked
        ? (xhr, url) => {
            if (new URL(url).pathname.endsWith(".m3u8")) {
              xhr.setRequestHeader("mantis-user-token", currentToken.current?.() ?? "");
            }
          }
        : undefined,
    });
    hls.loadSource(src);
    hls.attachMedia(video);
    return () => hls.destroy();
  }, [src, locked]);

  return <video ref={ref} poster={poster} controls playsInline className="aspect-video w-full" />;
}

npm install hls.js

@props(['src', 'poster' => null, 'locked' => false])

<video data-hls="{{ $src }}" @if ($locked) data-token-url="{{ route('mantis.token') }}" @endif
    @if ($poster) poster="{{ $poster }}" @endif controls playsinline
    {{ $attributes->merge(['class' => 'aspect-video w-full']) }}></video>

@once
    <script type="module">
        import Hls from "https://cdn.jsdelivr.net/npm/hls.js@1/dist/hls.mjs";

        const tokens = {};
        async function freshToken(url) {
            const now = Date.now();
            if (!tokens[url] || tokens[url].until < now) {
                const answer = await fetch(url, { credentials: "same-origin" }).then((r) => r.json());
                tokens[url] = { token: answer.token, until: Date.parse(answer.expiresAt) - 60_000 };
            }
            return tokens[url].token;
        }

        for (const video of document.querySelectorAll("video[data-hls]")) {
            const src = video.dataset.hls;
            const tokenUrl = video.dataset.tokenUrl;
            if (!tokenUrl && video.canPlayType("application/vnd.apple.mpegurl")) {
                video.src = src;
                continue;
            }
            if (!Hls.isSupported()) continue;

            let token = tokenUrl ? await freshToken(tokenUrl) : null;
            const hls = new Hls({
                xhrSetup: token
                    ? (xhr, url) => {
                          if (new URL(url).pathname.endsWith(".m3u8")) xhr.setRequestHeader("mantis-user-token", token);
                      }
                    : undefined,
            });
            if (tokenUrl) setInterval(async () => (token = await freshToken(tokenUrl)), 60_000);
            hls.loadSource(src);
            hls.attachMedia(video);
        }
    </script>
@endonce

<x-video-player :src="$url" :poster="$posterUrl" />
<x-video-player :src="$lockedUrl" locked />

One viewer onlyCopy Anchor Link

A link made with userId plays only for that user. Every playlist request must carry the user's current sign-in token in a mantis-user-token header:

So a link copied into a group chat plays for nobody else. Segments are not checked per viewer: they are cached for everyone and a segment URL, without its playlist, is six seconds of video. The secret key may lock a link to any user; the publishable key may lock one only to the signed-in user itself.

A plain <video src> can't send a header, so locked links always need hls.js, Safari included. Pass token to the component above. It is read on every request, so a token that refreshes mid-video keeps working, and a new function on each render doesn't restart the video.

Locking needs auth in the schema, so Mantis can check the user's token.

AnswersCopy Anchor Link

Browsers can reach every playback file from any origin (Access-Control-Allow-Origin: *), with the mantis-user-token and Range headers allowed, so a player on your own domain needs no setup.

Asking for a link answers 422 for an id that isn't a folder and a name (videos/intro) or an expiresIn outside 1 to 86400, 403 when the folder's read rule refuses the caller, and 404 when the video has no master playlist yet.

Edge casesCopy Anchor Link

• The link is made per page view, not stored. Make it where you render the page; a stored link expires and a public one would never need storing.
• A long watch on a short link stops at the expiry. For a viewer who might pause for hours, either give 24 hours or ask the server for a new link and call hls.loadSource(newUrl), then seek back to video.currentTime.
• A segment URL works for anyone holding it until its window ends, at most six hours after the link's expiry; the playlist that lists them stays locked.
• Download managers and ffmpeg -i <link> can save a video from any link they can play. A locked link narrows that to the user's own session; nothing stops a user recording their own screen.
• Moving a video from a public folder to a private one doesn't recall copies Cloudflare holds: public files stay cached for up to an hour.
• A video still uploading has no master playlist, so a signed link is refused with 404 and a public link answers 404 too until the upload finishes.