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
- Take stock of what you have and what has to come with it.
- Set up the project the videos go to.
- Try a few videos, all the way to playing on your site.
- Move the library, with both platforms playing side by side.
- 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
- Make an API token with the
editorrole (adminif your script also makes webhooks or signing keys). - Make the folders and labels your videos go into, so the import can put each in its place.
- Make the player your embeds will use, with your logo and colours, and set it as the project's default.
- 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.
- For videos only some may watch, make a signing key.
- Add a webhook for
video.ready,video.encodedandvideo.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 are | How to get links |
|---|---|
| Your own S3, GCS or Azure bucket | Presigned URLs (an hour or more is plenty); the bucket can stay private |
| Your own servers | Their URLs, if the server's on the internet; else upload the files |
| Vimeo | No links needed: connect the account and import from its list (below) |
| A video platform | Most 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 |
| YouTube | Not 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:
| What | How |
|---|---|
| Description, chapters | Update Video: description, chapters ([{"start": 0, "title": "Intro"}, …]) |
| Captions | Upload Captions: a WebVTT or SRT file per language. None to bring? Generate them |
| Thumbnail | Upload 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.mpdfor 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
editorrole - Folders, labels and the default player made
- Encoding, protection and watermarks chosen before importing
- Webhook for
video.ready,video.encodedandvideo.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.