Upload videos

Uploading a video is two steps: ffmpeg turns the source into an HLS package on your disk, and the upload stores every file of it under one video id. The command line does both; the SDK lets you run them separately.

You need ffmpeg and ffprobe (any build from the last few years; ffprobe comes with ffmpeg), a folder that takes the package's types (see the overview), and the secret key: uploads of whole packages run on your machine or your server, never in a browser.

From the command lineCopy Anchor Link

npx shipmantis video intro.mp4 --folder videos

Transcoding intro.mp4 with ffmpeg…
  25%
  50%
  75%
  1080p, 720p, 480p, 360p, 6-second segments and a poster
Uploading 70 files to videos…
Uploaded. 70 files, 118.4 MB.
  id        videos/7e0f3c1a-…
  playlist  videos/7e0f3c1a-…/master.m3u8
  poster    videos/7e0f3c1a-…/poster.jpg
  link      https://cdn.shipmantis.com/<project>/videos/7e0f3c1a-…/master.m3u8

The command reads MANTIS_URL and MANTIS_SECRET_KEY from the environment or .env.local. link is printed only for a folder anyone may read.

Pass a directory instead of a file to upload a package you made already:

npx shipmantis video ./out/intro --folder videos --id intro

From the SDKCopy Anchor Link

import { createClient } from "@shipmantis/sdk";
import { transcode, uploadVideo } from "@shipmantis/sdk/video";

const mantis = createClient({ url: process.env.MANTIS_URL!, key: process.env.MANTIS_SECRET_KEY! });

const made = await transcode("intro.mp4", "./out/intro", {
  onProgress: (fraction) => console.log(`${Math.round(fraction * 100)}%`),
});
// { dir: "./out/intro", source: { width: 1920, height: 1080, duration: 94.2, audio: true },
//   rungs: ["1080p", "720p", "480p", "360p"] }

const video = await uploadVideo(mantis, made.dir, {
  folder: "videos",
  id: "intro",
  onFile: (done, total) => console.log(`${done}/${total}`),
});
// { id: "videos/intro", playlist: "videos/intro/master.m3u8", poster: "videos/intro/poster.jpg",
//   publicUrl, posterUrl, files: 70, bytes: 124151808 }

use Illuminate\Support\Facades\Process;

class PublishVideo implements ShouldQueue
{
    use Queueable;

    public int $timeout = 3600;

    public function __construct(public Lesson $lesson, public string $source, public ?string $id = null)
    {
    }

    public function handle(): void
    {
        $id = $this->id ?? (string) $this->lesson->id;

        Process::path(base_path())
            ->timeout($this->timeout)
            ->run(['npx', 'shipmantis', 'video', $this->source, '--folder', 'videos', '--id', $id])
            ->throw();

        $this->lesson->update(['video' => "videos/{$id}"]);
    }
}

PublishVideo::dispatch($lesson, storage_path("app/uploads/{$lesson->id}.mp4"));

The order of an uploadCopy Anchor Link

1. Checked first, on your disk: every file name, every type, and every line of every playlist. Nothing is sent until the whole package passes.
2. Playlists and the poster, then the segments, four files at a time, each straight to storage.
3. The master playlist last. Until it lands the video can't be played, and the dashboard shows it as no master playlist yet.

If any file is refused, the files already stored are removed again, so a failed upload never leaves half a video behind. The error is the one the refused file got.

Your own packagesCopy Anchor Link

Any HLS package uploads as it is, from your own encoder settings, a pipeline you already run or a vendor's export, if it holds to these rules:

• master.m3u8 at its top. It is the video's entry point; the rest may sit in any directories under it.
• File names of letters, digits, ., _ and -, in every directory.
• Playlists point only at files in the package, by relative path. An absolute URL (https://…, /…) or a file that isn't there is refused before anything is sent.
• These types only:

The Videos folder from the dashboard takes .m3u8, video segments and JPEG posters. A package with subtitles, separate audio or PNG thumbnails needs those types added to the folder in the schema (mantis/schema.ts, or database/mantis.php from PHP):

videos: {
  maxBytes: 1024 * 1024 * 1024,
  types: ["video/*", "audio/*", "application/vnd.apple.mpegurl", "text/vtt", "image/*"],
  rules: { read: fileRule.public() },
},

'videos' => [
    'maxBytes' => 1024 * 1024 * 1024,
    'types' => ['video/*', 'audio/*', 'application/vnd.apple.mpegurl', 'text/vtt', 'image/*'],
    'rules' => ['read' => ['public' => true]],
],

The first image at the package's top is the video's poster.

Edge casesCopy Anchor Link

Uploading many videosCopy Anchor Link

for (const source of sources) {
  const id = basename(source, extname(source));
  const made = await transcode(source, join("out", id));
  const video = await uploadVideo(mantis, made.dir, { folder: "videos", id });
  await mantis.from("lessons").update({ set: { video: video.id }, where: { slug: id } });
}

foreach (Lesson::whereNull('video')->get() as $lesson) {
    PublishVideo::dispatch($lesson, storage_path("app/sources/{$lesson->slug}.mp4"))->onQueue('video');
}

php artisan queue:work --queue=video --timeout=3600