🎥 Make videos programmatically with React
`@remotion/browser-studio`: Load GitHub projects (#10673)
Jonny Burger0efa19c0345a
diff --git a/packages/browser-studio/src/index.tsx b/packages/browser-studio/src/index.tsxindex b222aaba1f..9a0d1150e4 100644--- a/packages/browser-studio/src/index.tsx+++ b/packages/browser-studio/src/index.tsx@@ -1,4 +1,5 @@export {BrowserStudio} from './BrowserStudio';+export {loadGitHubRepository} from './load-github-repository';export {createBlankTemplateProject} from './templates/blank';export type {BrowserStudioDependencyResolution,@@ -10,3 +11,4 @@ export type {VirtualFileSystem,VirtualProject,} from './types';+export type {LoadGitHubRepositoryProgress} from './load-github-repository';diff --git a/packages/browser-studio/src/load-github-repository.ts b/packages/browser-studio/src/load-github-repository.tsnew file mode 100644index 0000000000..00052d6a1e--- /dev/null+++ b/packages/browser-studio/src/load-github-repository.ts@@ -0,0 +1,251 @@+import type {VirtualProject} from './types';++type GitHubTreeEntry = {+ path: string;+ size?: number;+ type: 'blob' | 'commit' | 'tree';+};++type GitHubTreeResponse = {+ message?: string;+ sha?: string;+ tree?: GitHubTreeEntry[];+ truncated?: boolean;+};++export type LoadGitHubRepositoryProgress =+ | {+ phase: 'reading-repository';+ }+ | {+ loadedBytes: number;+ loadedFiles: number;+ phase: 'downloading-files';+ totalBytes: number;+ totalFiles: number;+ }+ | {+ phase: 'preparing-project';+ };++const entryPointCandidates = [+ 'src/index.ts',+ 'src/index.tsx',+ 'src/index.js',+ 'src/index.mjs',+ 'remotion/index.tsx',+ 'remotion/index.ts',+ 'remotion/index.js',+ 'remotion/index.mjs',+ 'src/remotion/index.tsx',+ 'src/remotion/index.ts',+ 'src/remotion/index.js',+ 'src/remotion/index.mjs',+];++const maximumRepositoryBytes = 100 * 1024 * 1024;+const maximumRepositoryFiles = 2_000;+const downloadConcurrency = 8;++const parseGitHubRepositoryUrl = (repoUrl: string) => {+ let url: URL;+ try {+ url = new URL(repoUrl);+ } catch {+ throw new Error(`Invalid GitHub repository URL: ${repoUrl}`);+ }++ if (url.protocol !== 'https:' || url.hostname !== 'github.com') {+ throw new Error('The repo parameter must be an https://github.com URL.');+ }++ const pathSegments = url.pathname.split('/').filter(Boolean);+ if (pathSegments.length !== 2) {+ throw new Error(+ 'The GitHub URL must point to a repository, for example https://github.com/remotion-dev/template-audiogram.',+ );+ }++ const owner = pathSegments[0];+ const repo = pathSegments[1].replace(/\.git$/, '');+ if (+ !owner ||+ !repo ||+ ![owner, repo].every((part) => /^[a-zA-Z0-9_.-]+$/.test(part))+ ) {+ throw new Error(`Invalid GitHub repository URL: ${repoUrl}`);+ }++ return {owner, repo};+};++const getResponseError = async (response: Response) => {+ try {+ const body = (await response.json()) as {message?: unknown};+ if (typeof body.message === 'string') {+ return body.message;+ }+ } catch {+ // The GitHub raw file server generally has no JSON error body.+ }++ return response.statusText || `HTTP ${response.status}`;+};++const encodePath = (path: string) =>+ path+ .split('/')+ .map((segment) => encodeURIComponent(segment))+ .join('/');++const validateRepositoryPath = (path: string) => {+ if (+ path.includes('\\') ||+ path.includes('\0') ||+ path+ .split('/')+ .some((segment) => segment === '' || segment === '.' || segment === '..')+ ) {+ throw new Error(`The repository contains an unsupported path: ${path}`);+ }+};++const decodeTextFile = (contents: Uint8Array) => {+ if (contents.includes(0)) {+ return null;+ }++ try {+ return new TextDecoder('utf-8', {fatal: true}).decode(contents);+ } catch {+ return null;+ }+};++export const loadGitHubRepository = async ({+ onProgress,+ repoUrl,+ signal,+}: {+ onProgress?: (progress: LoadGitHubRepositoryProgress) => void;+ repoUrl: string;+ signal?: AbortSignal;+}): Promise<VirtualProject> => {+ const {owner, repo} = parseGitHubRepositoryUrl(repoUrl);+ onProgress?.({phase: 'reading-repository'});++ const treeResponse = await fetch(+ `https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/git/trees/HEAD?recursive=1`,+ {signal},+ );+ if (!treeResponse.ok) {+ throw new Error(+ `Could not read ${owner}/${repo}: ${await getResponseError(treeResponse)}`,+ );+ }++ const tree = (await treeResponse.json()) as GitHubTreeResponse;+ if (!tree.tree || !tree.sha) {+ throw new Error(+ `Could not read ${owner}/${repo}: ${tree.message ?? 'GitHub returned an invalid file tree.'}`,+ );+ }++ const treeSha = tree.sha;++ if (tree.truncated) {+ throw new Error(+ `${owner}/${repo} has too many files for Browser Studio to load.`,+ );+ }++ const fileEntries = tree.tree.filter(+ (entry): entry is GitHubTreeEntry & {type: 'blob'} => entry.type === 'blob',+ );+ for (const file of fileEntries) {+ validateRepositoryPath(file.path);+ }++ if (fileEntries.length > maximumRepositoryFiles) {+ throw new Error(+ `${owner}/${repo} has ${fileEntries.length.toLocaleString()} files. Browser Studio supports up to ${maximumRepositoryFiles.toLocaleString()}.`,+ );+ }++ const totalBytes = fileEntries.reduce(+ (total, entry) => total + (entry.size ?? 0),+ 0,+ );+ if (totalBytes > maximumRepositoryBytes) {+ throw new Error(+ `${owner}/${repo} is larger than the 100 MB Browser Studio limit.`,+ );+ }++ let loadedBytes = 0;+ let loadedFiles = 0;+ const files: Record<string, string> = {};+ const publicFiles: Record<string, Uint8Array> = {};+ const totalFiles = fileEntries.length;+ const reportDownloadProgress = () =>+ onProgress?.({+ loadedBytes,+ loadedFiles,+ phase: 'downloading-files',+ totalBytes,+ totalFiles,+ });+ reportDownloadProgress();++ let nextFileIndex = 0;+ await Promise.all(+ Array.from(+ {length: Math.min(downloadConcurrency, fileEntries.length)},+ async () => {+ while (nextFileIndex < fileEntries.length) {+ const file = fileEntries[nextFileIndex++];+ const response = await fetch(+ `https://raw.githubusercontent.com/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/${encodeURIComponent(treeSha)}/${encodePath(file.path)}`,+ {signal},+ );+ if (!response.ok) {+ throw new Error(+ `Could not download ${file.path}: ${await getResponseError(response)}`,+ );+ }++ const contents = new Uint8Array(await response.arrayBuffer());+ if (file.path.startsWith('public/')) {+ publicFiles[file.path.slice('public/'.length)] = contents;+ } else {+ const text = decodeTextFile(contents);+ if (text !== null) {+ files[`/project/${file.path}`] = text;+ }+ }++ loadedBytes += file.size ?? contents.byteLength;+ loadedFiles++;+ reportDownloadProgress();+ }+ },+ ),+ );++ onProgress?.({phase: 'preparing-project'});+ const entryPoint = entryPointCandidates.find(+ (candidate) => files[`/project/${candidate}`] !== undefined,+ );+ if (!entryPoint) {+ throw new Error(+ `${owner}/${repo} does not have a supported Remotion entry point. Expected src/index.ts or another standard Remotion entry point.`,+ );+ }++ return {+ entryPoint: `/project/${entryPoint}`,+ files,+ publicFiles,+ rootDir: '/project',+ };+};diff --git a/packages/browser-studio/src/test/load-github-repository.test.ts b/packages/browser-studio/src/test/load-github-repository.test.tsnew file mode 100644index 0000000000..8d89cc84c3--- /dev/null+++ b/packages/browser-studio/src/test/load-github-repository.test.ts@@ -0,0 +1,114 @@+import {afterEach, expect, test} from 'bun:test';+import {+ loadGitHubRepository,+ type LoadGitHubRepositoryProgress,+} from '../load-github-repository';++const originalFetch = globalThis.fetch;++afterEach(() => {+ globalThis.fetch = originalFetch;+});++test('loads a GitHub repository into a virtual project', async () => {+ const rawFiles: Record<string, Uint8Array | string> = {+ 'package.json': '{"name":"example"}',+ 'public/audio.wav': new Uint8Array([0, 1, 2, 255]),+ 'public/captions.json': '[{"text":"Hello"}]',+ 'Promo.png': new Uint8Array([137, 80, 78, 71, 0, 255]),+ 'src/Root.tsx': 'export const Root = () => null;',+ 'src/index.ts': 'import {registerRoot} from "remotion";',+ };+ const encoder = new TextEncoder();+ const tree = Object.entries(rawFiles).map(([path, contents]) => ({+ path,+ size:+ typeof contents === 'string'+ ? encoder.encode(contents).byteLength+ : contents.byteLength,+ type: 'blob',+ }));+ globalThis.fetch = ((input: RequestInfo | URL) => {+ const url = input.toString();+ if (url.includes('api.github.com')) {+ return Promise.resolve(+ Response.json({+ sha: 'ddc7ec42c2c9c06e84c9d5d2606e7ffc1394d900',+ tree,+ truncated: false,+ }),+ );+ }++ const marker = '/ddc7ec42c2c9c06e84c9d5d2606e7ffc1394d900/';+ const path = decodeURIComponent(+ url.slice(url.indexOf(marker) + marker.length),+ );+ const contents = rawFiles[path];+ if (contents === undefined) {+ return Promise.resolve(new Response(null, {status: 404}));+ }++ return Promise.resolve(+ new Response(+ typeof contents === 'string' ? contents : contents.slice().buffer,+ ),+ );+ }) as unknown as typeof fetch;++ const progress: LoadGitHubRepositoryProgress[] = [];+ const project = await loadGitHubRepository({+ onProgress: (update) => progress.push(update),+ repoUrl: 'https://github.com/remotion-dev/example.git',+ });++ expect(project.rootDir).toBe('/project');+ expect(project.entryPoint).toBe('/project/src/index.ts');+ expect(project.files['/project/src/Root.tsx']).toBe(+ 'export const Root = () => null;',+ );+ expect(project.files['/project/Promo.png']).toBeUndefined();+ expect(project.publicFiles?.['audio.wav']).toEqual(+ new Uint8Array([0, 1, 2, 255]),+ );+ const captions = project.publicFiles?.['captions.json'];+ if (!(captions instanceof Uint8Array)) {+ throw new Error('Expected captions.json to be a Uint8Array');+ }++ expect(new TextDecoder().decode(captions)).toBe('[{"text":"Hello"}]');+ expect(progress[0]).toEqual({phase: 'reading-repository'});+ expect(progress.at(-1)).toEqual({phase: 'preparing-project'});+ expect(+ progress.some(+ (update) =>+ update.phase === 'downloading-files' &&+ update.loadedFiles === tree.length &&+ update.loadedBytes === tree.reduce((sum, entry) => sum + entry.size, 0),+ ),+ ).toBe(true);+});++test('validates GitHub repository URLs before fetching', async () => {+ await expect(+ loadGitHubRepository({repoUrl: 'https://example.com/owner/repo'}),+ ).rejects.toThrow('must be an https://github.com URL');+ await expect(+ loadGitHubRepository({+ repoUrl: 'https://github.com/owner/repo/tree/main',+ }),+ ).rejects.toThrow('must point to a repository');+});++test('reports GitHub API errors', async () => {+ globalThis.fetch = (() =>+ Promise.resolve(+ Response.json({message: 'Not Found'}, {status: 404}),+ )) as unknown as typeof fetch;++ await expect(+ loadGitHubRepository({+ repoUrl: 'https://github.com/remotion-dev/missing',+ }),+ ).rejects.toThrow('Could not read remotion-dev/missing: Not Found');+});diff --git a/packages/docs/src/pages/experimental_new/index.tsx b/packages/docs/src/pages/experimental_new/index.tsxindex fc5de1c672..142c701c19 100644--- a/packages/docs/src/pages/experimental_new/index.tsx+++ b/packages/docs/src/pages/experimental_new/index.tsx@@ -4,6 +4,9 @@ import useDocusaurusContext from '@docusaurus/useDocusaurusContext';import {BrowserStudio,createBlankTemplateProject,+ loadGitHubRepository,+ type LoadGitHubRepositoryProgress,+ type VirtualProject,} from '@remotion/browser-studio';import {StudioProtocolInternals} from '@remotion/studio-protocol';import React, {useEffect, useState} from 'react';@@ -26,6 +29,33 @@ const fallback: React.CSSProperties = {width: '100%',};+const loadingBackdrop: React.CSSProperties = {+ ...fallback,+ backgroundColor: '#111111',+ color: '#ffffff',+ padding: 24,+};++const loadingDialog: React.CSSProperties = {+ backgroundColor: '#1f1f1f',+ border: '1px solid #3a3a3a',+ borderRadius: 8,+ boxShadow: '0 16px 60px rgba(0, 0, 0, 0.5)',+ boxSizing: 'border-box',+ color: '#ffffff',+ maxWidth: 480,+ padding: 24,+ width: '100%',+};++const progressBar: React.CSSProperties = {+ accentColor: '#0b84f3',+ display: 'block',+ height: 8,+ marginTop: 20,+ width: '100%',+};+const standaloneCss = `html,body,@@ -54,6 +84,28 @@ type InitialElementState =>;};+type ProjectState =+ | {type: 'ready'; project: VirtualProject}+ | {+ type: 'loading';+ repoUrl: string;+ progress: LoadGitHubRepositoryProgress;+ }+ | {type: 'error'; repoUrl: string; message: string};++const getInitialProjectState = (): ProjectState => {+ const repoUrl = new URLSearchParams(window.location.search).get('repo');+ if (!repoUrl) {+ return {type: 'ready', project: createBlankTemplateProject()};+ }++ return {+ type: 'loading',+ repoUrl,+ progress: {phase: 'reading-repository'},+ };+};+const getInitialElementState = (): InitialElementState => {const hasPayload = new URLSearchParams(window.location.hash.slice(1)).has('remotion-browser-studio',@@ -83,7 +135,9 @@ const BrowserStudioContent: React.FC<{readonly browserStudioWorkspaceCommit: string;}> = ({browserStudioWorkspaceCommit}) => {const [initialElementState] = useState(getInitialElementState);- const [project] = useState(createBlankTemplateProject);+ const [projectState, setProjectState] = useState(getInitialProjectState);+ const loadingRepoUrl =+ projectState.type === 'loading' ? projectState.repoUrl : null;useEffect(() => {if (initialElementState.type === 'none') {@@ -97,10 +151,132 @@ const BrowserStudioContent: React.FC<{);}, [initialElementState.type]);+ useEffect(() => {+ if (loadingRepoUrl === null) {+ return;+ }++ const controller = new AbortController();+ loadGitHubRepository({+ onProgress: (progress) => {+ setProjectState((currentState) =>+ currentState.type === 'loading'+ ? {...currentState, progress}+ : currentState,+ );+ },+ repoUrl: loadingRepoUrl,+ signal: controller.signal,+ })+ .then((project) => setProjectState({type: 'ready', project}))+ .catch((error: unknown) => {+ if (controller.signal.aborted) {+ return;+ }++ setProjectState({+ message: error instanceof Error ? error.message : String(error),+ repoUrl: loadingRepoUrl,+ type: 'error',+ });+ });++ return () => controller.abort();+ }, [loadingRepoUrl]);+if (initialElementState.type === 'invalid') {return <div style={fallback}>Invalid Browser Studio payload.</div>;}+ if (projectState.type !== 'ready') {+ let progress: number | null = null;+ if (+ projectState.type === 'loading' &&+ projectState.progress.phase === 'downloading-files'+ ) {+ progress =+ projectState.progress.totalBytes === 0+ ? projectState.progress.totalFiles === 0+ ? 0+ : Math.min(+ 1,+ projectState.progress.loadedFiles /+ projectState.progress.totalFiles,+ )+ : Math.min(+ 1,+ projectState.progress.loadedBytes /+ projectState.progress.totalBytes,+ );+ }++ return (+ <div style={loadingBackdrop}>+ <div aria-modal="true" role="dialog" style={loadingDialog}>+ <div style={{fontSize: 18, fontWeight: 600}}>+ {projectState.type === 'loading'+ ? 'Loading GitHub project'+ : 'Could not load GitHub project'}+ </div>+ <div+ style={{+ color: '#aaaaaa',+ fontSize: 13,+ marginTop: 8,+ overflowWrap: 'anywhere',+ }}+ >+ {projectState.repoUrl}+ </div>+ {projectState.type === 'loading' ? (+ <>+ <progress+ aria-label="Loading repository"+ max={1}+ style={progressBar}+ value={progress ?? undefined}+ />+ <div style={{color: '#cccccc', fontSize: 13, marginTop: 10}}>+ {projectState.progress.phase === 'reading-repository'+ ? 'Reading repository…'+ : projectState.progress.phase === 'preparing-project'+ ? 'Preparing project…'+ : `Downloading files… ${Math.round((progress ?? 0) * 100)}%`}+ </div>+ </>+ ) : (+ <>+ <div style={{color: '#ff8080', fontSize: 14, marginTop: 20}}>+ {projectState.message}+ </div>+ <button+ onClick={() =>+ setProjectState({+ project: createBlankTemplateProject(),+ type: 'ready',+ })+ }+ style={{+ backgroundColor: '#0b84f3',+ border: 0,+ borderRadius: 4,+ color: '#ffffff',+ cursor: 'pointer',+ fontSize: 14,+ marginTop: 20,+ padding: '8px 12px',+ }}+ type="button"+ >+ Start with a blank project+ </button>+ </>+ )}+ </div>+ </div>+ );+ }+return (<BrowserStudioiframeSrc="/experimental_new/frame.html"@@ -109,7 +285,7 @@ const BrowserStudioContent: React.FC<{? initialElementState.payload: null}- project={project}+ project={projectState.project}readOnly={false}remotionPackageSource={{baseUrl: new URL(