Skip to main content

Migrating to Crumbcast

Moving a video library to Crumbcast from another platform (Vimeo, Wistia, Mux, Cloudflare Stream, JW Player and the like) or from your own stack (files in S3, encoded with FFmpeg, served through a CDN). Nothing is taken from where your videos are now: Crumbcast fetches a copy of each file and encodes it again, so both keep playing until you switch over.

Who this is for​

  • Teams on another video platform moving their library, and their site's embeds, to Crumbcast.
  • Teams running their own video stack (storage, encoding, a CDN and a player, each set up and paid for apart) who'd rather have one service.
  • Course creators and publishers bringing their videos over with their titles, captions and chapters.

Starting from nothing? You don't need this page: upload a video.

The move, in five steps​

  1. Take stock of what you have and what has to come with it.
  2. Set up the project the videos go to.
  3. Try a few videos, all the way to playing on your site.
  4. Move the library, with both platforms playing side by side.
  5. Switch over your links and embeds, then retire the old platform.

1. Take stock​

  • How many videos, and how long in all. Your plan's limits on videos and storage apply to imports too: past one, the API answers 402.
  • Where each original file is. Crumbcast encodes from a file. Bring the best copy you have, the original upload if you can, not one of the old platform's renditions.
  • What comes with each video: title, description, folder or category, tags, captions, chapters, its thumbnail, who may watch it.
  • Where it's shown: embeds on your site, links in emails and apps, players of your own reading an HLS playlist.
  • What the old platform charges to download your files: some bill for the traffic.

2. Set up​

  1. Make an API token with the editor role (admin if your script also makes webhooks or signing keys).
  2. Make the folders and labels your videos go into, so the import can put each in its place.
  3. Make the player your embeds will use, with your logo and colours, and set it as the project's default.
  4. Choose how videos are encoded and protected: in each import's choices, or a workflow that every import names. For DRM or forensic watermarks, set them before importing; changing them later encodes each video again.
  5. For videos only some may watch, make a signing key.
  6. Add a webhook for video.ready, video.encoded and video.errored: they tell your script how each import went, rather than it asking.

3. Get the files out​

What Crumbcast needs is a link it can download each file from (http or https, on a public address), or the file itself to upload.

Where they areHow to get links
Your own S3, GCS or Azure bucketPresigned URLs (an hour or more is plenty); the bucket can stay private
Your own serversTheir URLs, if the server's on the internet; else upload the files
VimeoNo links needed: connect the account and import from its list (below)
A video platformMost give a download link for each video's original through their API, often only on paid plans; look in its API docs for download, source or original
YouTubeNot from a watch link: connect the channel and upload each video's file from your Google Takeout export (below)

Links that expire: make them as you go, a batch at a time, not all at the start.

4. Move the library​

A few videos​

Upload them in the dashboard, or import them there from their links.

From Vimeo​

On Pro or Business, a project admin connects the Vimeo account on the dashboard's Integrations page. Its row there then lists the account's videos, newest first: pick the ones to bring over, then their titles and settings, as for an upload. Each comes with its original file, title, description, captions and subtitles, and its custom thumbnail if it has one. The new video keeps its Vimeo ID in its metadata as vimeo_id, and the list marks the videos that have been imported.

Vimeo gives its files only on its paid plans (Standard and up), and only once a video is done processing there. The list shows which videos can't be imported.

With the API, page through List Vimeo Videos (the connection's ID is in List Connections) and Import Vimeo Video each one, with the same choices Import Video takes:

curl https://your-crumbcast/api/v1/connections/$CONNECTION_ID/vimeo/videos/76979871/import/ \
-H "Authorization: Bearer $CRUMBCAST_TOKEN" \
-H "Content-Type: application/json" \
-d '{"folder_id": "'$FOLDER_ID'", "playback_policy": "public"}'

From YouTube​

YouTube gives no link to a video's file, not even to the channel's owner, so the files come from you: export the channel's videos with Google Takeout (YouTube and YouTube Music, videos only), and unzip the export.

On Pro or Business, a project admin connects the channel on the dashboard's Integrations page. Its row there lists the channel's uploads, newest first, with their privacy on YouTube: pick the ones to bring over, then drop the export's files into the upload dialog. Takeout names each file after its video's title, and the dialog matches each file to its video; place any it can't match yourself. Each video comes with its title, description and thumbnail from YouTube, and keeps its YouTube ID in its metadata as youtube_id. The list marks the videos that have been imported.

A broadcast that's upcoming or still live has no file yet, and isn't offered. Captions don't come with them: a workflow with captions makes them from the speech.

With the API, page through List YouTube Videos (its next_page token) and make each one with Upload YouTube Video. It takes what Create Video takes, the file's name and size among them, and answers the same way: upload the file's parts and complete the upload as in Upload videos.

curl https://your-crumbcast/api/v1/connections/$CONNECTION_ID/youtube/videos/dQw4w9WgXcQ/upload/ \
-H "Authorization: Bearer $CRUMBCAST_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Launch day.mp4", "size": 734003200, "folder_id": "'$FOLDER_ID'"}'

Many videos, with the API​

For each video, Import Video with its link and what it can take at once: title, folder, labels, who may watch it, and its old ID in its metadata. It answers 202 with the new video straight away; the download and encoding follow.

curl https://your-crumbcast/api/v1/projects/$PROJECT_ID/videos/import/ \
-H "Authorization: Bearer $CRUMBCAST_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://old-videos.s3.amazonaws.com/talks/keynote.mp4?X-Amz-Signature=…",
"title": "Keynote",
"folder_id": "6c1d…",
"label_ids": ["9a0e…"],
"playback_policy": "public",
"metadata": {"old_id": "talks/keynote.mp4"}
}'

Keep the old ID with the new video: it's how you'll find what to replace when you switch over. In its metadata, List Videos finds it again (metadata=old_id:talks/keynote.mp4), and every webhook about the video carries it. Keep the new ID in your own database or CMS too, beside the old one.

Then, once the video plays (video.ready), bring over what an import doesn't take:

WhatHow
Description, chaptersUpdate Video: description, chapters ([{"start": 0, "title": "Intro"}, …])
CaptionsUpload Captions: a WebVTT or SRT file per language. None to bring? Generate them
ThumbnailUpload Video Thumbnail: a JPEG, PNG or WebP image

A script for a bucket​

In Python, from an S3 bucket, writing each old key and new ID to a CSV as it goes:

import csv
import os

import boto3
import requests

API = "https://your-crumbcast/api/v1"
PROJECT_ID = os.environ["CRUMBCAST_PROJECT_ID"]
BUCKET, PREFIX = "old-videos", "talks/"

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['CRUMBCAST_TOKEN']}"
s3 = boto3.client("s3")

with open("migrated.csv", "a", newline="") as out:
done = csv.writer(out)
pages = s3.get_paginator("list_objects_v2").paginate(Bucket=BUCKET, Prefix=PREFIX)
for page in pages:
for obj in page.get("Contents", []):
key = obj["Key"]
if not key.endswith((".mp4", ".mov", ".mkv")):
continue
url = s3.generate_presigned_url(
"get_object", Params={"Bucket": BUCKET, "Key": key}, ExpiresIn=6 * 3600
)
title = os.path.splitext(os.path.basename(key))[0]
answer = session.post(
f"{API}/projects/{PROJECT_ID}/videos/import/",
json={"url": url, "title": title, "metadata": {"old_id": key[:500]}},
)
if answer.status_code == 402:
raise SystemExit("The plan's limit is reached: " + answer.json()["detail"])
answer.raise_for_status()
done.writerow([key, answer.json()["id"]])

For thousands of videos, put one job per video on a queue of your own, a few at a time, so a failure is tried again alone and a rerun skips what's in migrated.csv.

Try a few first​

Run the whole thing on ten videos: import, captions, the embed on a page of your site, signed playback if you use it. Then the rest.

When an import fails​

The video is deleted, and a video.errored webhook says why (the link expired, the file isn't a video, …). Make a new link and import it again.

5. Switch over​

Replace each old embed and link with Crumbcast's, by the ID you kept:

https://your-crumbcast/watch/<video id>
https://your-crumbcast/embed/<video id>
https://your-crumbcast/api/v1/videos/<video id>/master.m3u8
  • Embeds: an <iframe> of the embed link, or the HTML that oEmbed gives for a watch link (CMSs that read oEmbed take the watch link alone).
  • Your own player: the HLS playlist (or manifest.mpd for DASH).
  • Signed videos: your backend makes Crumbcast's playback tokens in place of the old platform's.
  • Old links in emails and elsewhere: redirect them to the new ones, if your old platform or your site can.

Keep the old platform until the new links are everywhere and its analytics have stopped counting views; then delete the videos there.

Checklist​

Setup

  • API token made, with the editor role
  • Folders, labels and the default player made
  • Encoding, protection and watermarks chosen before importing
  • Webhook for video.ready, video.encoded and video.errored

The move

  • Ten videos moved and playing on your site
  • Every video imported, each with its old ID in its metadata
  • Descriptions, chapters, captions and thumbnails brought over
  • Count in Crumbcast (List Videos) matches the old platform's

Switching over

  • Embeds and links replaced
  • Signed playback made by your backend
  • Old links redirected
  • Old platform's videos deleted

What's next​

  • Webhooks: keep your records in step as videos are added and changed.
  • Signed playback: for videos only some may watch.
  • AI agents: caption, cut and sort the library by asking.