Visualize Your Ideas With Code
feat: finalize custom exporters (#660)
Jacob6a50430cdf99
diff --git a/packages/core/src/app/Exporter.ts b/packages/core/src/app/Exporter.tsindex 936a5970..48ca8260 100644--- a/packages/core/src/app/Exporter.ts+++ b/packages/core/src/app/Exporter.ts@@ -1,24 +1,50 @@import type {RendererResult, RendererSettings} from './Renderer';-import {MetaField} from '../meta';+import type {Project} from './Project';+import type {MetaField} from '../meta';/**- * The main interface for implementing custom exporters.+ * The static interface for exporters.*/-export interface Exporter {+export interface ExporterClass {+ /**+ * The unique identifier of this exporter.+ *+ * @remarks+ * This identifier will be used to store the settings of this exporter.+ * It's recommended to prepend it with the name of the package to avoid+ * collisions.+ */+ readonly id: string;+/*** The name of this exporter.** @remarks- * This name will be displayed in the editor and used to store the related- * settings.+ * This name will be displayed in the editor.*/- readonly name: string;+ readonly displayName: string;++ /**+ * Create an instance of this exporter.+ *+ * @remarks+ * A new exporter is created whenever the user starts a new rendering process.+ *+ * @param project - The current project.+ * @param settings - The rendering settings.+ */+ create(project: Project, settings: RendererSettings): Promise<Exporter>;/*** Create a meta field representing the options of this exporter.*/- meta(): MetaField<any>;+ meta(project: Project): MetaField<any>;+}+/**+ * The main interface for implementing custom exporters.+ */+export interface Exporter {/*** Prepare the rendering configuration.*@@ -26,10 +52,8 @@ export interface Exporter {* Called at the beginning of the rendering process, before anything else has* been set up. The returned value can be used to override the rendering* settings provided by the user.- *- * @param settings - Rendering settings provided by the user.*/- configure(settings: RendererSettings): Promise<RendererSettings | void>;+ configuration?(): Promise<RendererSettings | void>;/*** Begin the rendering process.@@ -38,9 +62,9 @@ export interface Exporter {* Called after the rendering has been set up, right before the first frame* is rendered. Once `start()` is called, it is guaranteed that the `stop()`* method will be called as well. Can be used to initialize any resources that- * require clean-up.+ * require a clean-up.*/- start(): Promise<void>;+ start?(): Promise<void>;/*** Export a frame.@@ -68,9 +92,9 @@ export interface Exporter {* @remarks* Guaranteed to be called after the rendering has finished - no matter the* result. Can be used to finalize the exporting and perform any necessary- * clean up.+ * clean-up.** @param result - The result of the rendering.*/- stop(result: RendererResult): Promise<void>;+ stop?(result: RendererResult): Promise<void>;}diff --git a/packages/core/src/app/ImageExporter.ts b/packages/core/src/app/ImageExporter.tsindex 86346c45..810d7c98 100644--- a/packages/core/src/app/ImageExporter.ts+++ b/packages/core/src/app/ImageExporter.ts@@ -1,7 +1,8 @@import {CanvasOutputMimeType} from '../types';-import {Exporter} from './Exporter';-import {Logger} from './Logger';-import {RendererSettings} from './Renderer';+import type {Project} from './Project';+import type {Exporter} from './Exporter';+import type {Logger} from './Logger';+import type {RendererSettings} from './Renderer';import {BoolMetaField,EnumMetaField,@@ -11,34 +12,25 @@ import {} from '../meta';import {clamp} from '../tweening';import {FileTypes} from './presets';+import {EventDispatcher} from '../events';const EXPORT_FRAME_LIMIT = 256;const EXPORT_RETRY_DELAY = 1000;-type ImageExporterOptions = ValueOf<ReturnType<ImageExporter['meta']>>;+type ImageExporterOptions = ValueOf<ReturnType<typeof ImageExporter.meta>>;++interface ServerResponse {+ frame: number;+}/*** Image sequence exporter.*/export class ImageExporter implements Exporter {- public readonly name = 'image sequence';-- private readonly frameLookup = new Map<number, Callback>();- private frameCounter = 0;- private projectName = 'unknown';- private quality = 1;- private fileType: CanvasOutputMimeType = 'image/png';- private groupByScene = false;+ public static readonly id = '@motion-canvas/core/image-sequence';+ public static readonly displayName = 'Image sequence';- public constructor(private readonly logger: Logger) {- if (import.meta.hot) {- import.meta.hot.on('motion-canvas:export-ack', ({frame}) => {- this.frameLookup.get(frame)?.();- });- }- }-- public meta() {+ public static meta() {const meta = new ObjectMetaField(this.name, {fileType: new EnumMetaField('file type', FileTypes),quality: new NumberMetaField('quality', 100).setRange(0, 100),@@ -52,7 +44,33 @@ export class ImageExporter implements Exporter {return meta;}- public async configure(settings: RendererSettings) {+ public static async create(+ project: Project,+ settings: RendererSettings,+ ): Promise<ImageExporter> {+ return new ImageExporter(project.logger, settings);+ }++ private static readonly response = new EventDispatcher<ServerResponse>();++ static {+ if (import.meta.hot) {+ import.meta.hot.on('motion-canvas:export-ack', response => {+ this.response.dispatch(response);+ });+ }+ }++ private readonly frameLookup = new Set<number>();+ private readonly projectName: string;+ private readonly quality: number;+ private readonly fileType: CanvasOutputMimeType;+ private readonly groupByScene: boolean;++ public constructor(+ private readonly logger: Logger,+ private readonly settings: RendererSettings,+ ) {const options = settings.exporter.options as ImageExporterOptions;this.projectName = settings.name;this.quality = clamp(0, 1, options.quality / 100);@@ -61,7 +79,7 @@ export class ImageExporter implements Exporter {}public async start() {- this.frameLookup.clear();+ ImageExporter.response.subscribe(this.handleResponse);}public async handleFrame(@@ -76,19 +94,14 @@ export class ImageExporter implements Exporter {return;}if (import.meta.hot) {- while (this.frameCounter > EXPORT_FRAME_LIMIT) {+ while (this.frameLookup.size > EXPORT_FRAME_LIMIT) {await new Promise(resolve => setTimeout(resolve, EXPORT_RETRY_DELAY));if (signal.aborted) {return;}}- this.frameCounter++;- this.frameLookup.set(frame, () => {- this.frameCounter--;- this.frameLookup.delete(frame);- });-+ this.frameLookup.add(frame);import.meta.hot!.send('motion-canvas:export', {frame,sceneFrame,@@ -103,8 +116,13 @@ export class ImageExporter implements Exporter {}public async stop() {- while (this.frameCounter > 0) {+ while (this.frameLookup.size > 0) {await new Promise(resolve => setTimeout(resolve, EXPORT_RETRY_DELAY));}+ ImageExporter.response.unsubscribe(this.handleResponse);}++ private handleResponse = ({frame}: ServerResponse) => {+ this.frameLookup.delete(frame);+ };}diff --git a/packages/core/src/app/ProjectMetadata.ts b/packages/core/src/app/ProjectMetadata.tsindex d0715c37..d1888f4b 100644--- a/packages/core/src/app/ProjectMetadata.ts+++ b/packages/core/src/app/ProjectMetadata.ts@@ -29,10 +29,7 @@ function createProjectMetadata(project: Project) {fps: new NumberMetaField('frame rate', 60).setPresets(FrameRates),resolutionScale: new EnumMetaField('scale', Scales, 1),colorSpace: new EnumMetaField('color space', ColorSpaces),- exporter: new ExporterMetaField(- 'exporter',- project.plugins.flatMap(plugin => plugin.exporters?.(project) ?? []),- ),+ exporter: new ExporterMetaField('exporter', project),}),};diff --git a/packages/core/src/app/Renderer.ts b/packages/core/src/app/Renderer.tsindex 26995a75..24800c1c 100644--- a/packages/core/src/app/Renderer.ts+++ b/packages/core/src/app/Renderer.ts@@ -4,7 +4,6 @@ import type {Scene} from '../scenes';import {PlaybackManager, PlaybackState} from './PlaybackManager';import {Stage, StageSettings} from './Stage';import {EventDispatcher, ValueDispatcher} from '../events';-import {ImageExporter} from './ImageExporter';import {Vector2} from '../types';import {PlaybackStatus} from './PlaybackStatus';import {Semaphore} from '../utils';@@ -64,7 +63,7 @@ export class Renderer {private readonly lock = new Semaphore();private readonly playback: PlaybackManager;private readonly status: PlaybackStatus;- private readonly exporter: Exporter = new ImageExporter(this.project.logger);+ private exporter: Exporter | null = null;private abortController: AbortController | null = null;public constructor(private project: Project) {@@ -102,6 +101,14 @@ export class Renderer {} catch (e: any) {this.project.logger.error(e);result = RendererResult.Error;+ if (this.exporter) {+ try {+ await this.exporter.stop?.(result);+ } catch (_) {+ // do nothing+ }+ this.exporter = null;+ }}this.state.current = RendererState.Initial;@@ -163,7 +170,23 @@ export class Renderer {settings: RendererSettings,signal: AbortSignal,): Promise<RendererResult> {- settings = (await this.exporter.configure(settings)) ?? settings;+ const exporterClass = this.project.meta.rendering.exporter.exporters.find(+ exporter => exporter.id === settings.exporter.name,+ );+ if (!exporterClass) {+ this.project.logger.error(+ `Could not find the "${settings.exporter.name}" exporter.`,+ );+ return RendererResult.Error;+ }++ this.exporter = await exporterClass.create(this.project, settings);+ if (this.exporter.configuration) {+ settings = {+ ...settings,+ ...((await this.exporter.configuration()) ?? {}),+ };+ }this.stage.configure(settings);this.playback.fps = settings.fps;this.playback.state = PlaybackState.Rendering;@@ -178,7 +201,7 @@ export class Renderer {await this.playback.seek(from);if (signal.aborted) return RendererResult.Aborted;- await this.exporter.start();+ await this.exporter.start?.();let lastRefresh = performance.now();let result = RendererResult.Success;@@ -209,7 +232,8 @@ export class Renderer {result = RendererResult.Error;}- await this.exporter.stop(result);+ await this.exporter.stop?.(result);+ this.exporter = null;return result;}@@ -235,7 +259,7 @@ export class Renderer {const sceneFrame =this.playback.frame - this.playback.currentScene.firstFrame;- await this.exporter.handleFrame(+ await this.exporter!.handleFrame(this.stage.finalBuffer,this.playback.frame,sceneFrame,diff --git a/packages/core/src/meta/ExporterMetaFile.ts b/packages/core/src/meta/ExporterMetaFile.tsindex 9f3e54eb..0afcf00e 100644--- a/packages/core/src/meta/ExporterMetaFile.ts+++ b/packages/core/src/meta/ExporterMetaFile.ts@@ -1,5 +1,5 @@import {MetaField} from './MetaField';-import type {Exporter} from '../app';+import type {ExporterClass, Project} from '../app';import {EnumMetaField} from './EnumMetaField';import {ValueDispatcher} from '../events';@@ -26,32 +26,30 @@ export class ExporterMetaField extends MetaField<{return this.optionFields[this.current];}- public get exporter() {- return this.exporters[this.current];- }-private readonly exporterField: EnumMetaField<string>;private readonly optionFields: MetaField<unknown>[];+ public readonly exporters: ExporterClass[];- public constructor(- name: string,- public readonly exporters: Exporter[],- private current = 0,- ) {- const optionFields = exporters.map(exporter => exporter.meta());+ public constructor(name: string, project: Project, private current = 0) {+ const exporters = project.plugins.flatMap(+ plugin => plugin.exporters?.(project) ?? [],+ );+ const optionFields = exporters.map(exporter => exporter.meta(project));const exporterField = new EnumMetaField('exporter',exporters.map(exporter => ({- value: exporter.name,- text: exporter.name,+ value: exporter.id,+ text: exporter.displayName,})),- exporters[current].name,+ exporters[current].id,);+super(name, {name: exporterField.get(),options: optionFields[current].get(),});+ this.exporters = exporters;this.exporterField = exporterField;this.exporterField.onChanged.subscribe(this.handleChange, false);this.exporterField.disable(optionFields.length < 2).space();@@ -79,7 +77,7 @@ export class ExporterMetaField extends MetaField<{private handleChange = () => {const value = this.exporterField.get();const index = Math.max(- this.exporters.findIndex(exporter => exporter.name === value),+ this.exporters.findIndex(exporter => exporter.id === value),0,);diff --git a/packages/core/src/plugin/DefaultPlugin.ts b/packages/core/src/plugin/DefaultPlugin.tsindex cb098a37..02e5eeef 100644--- a/packages/core/src/plugin/DefaultPlugin.ts+++ b/packages/core/src/plugin/DefaultPlugin.ts@@ -1,12 +1,12 @@import {makePlugin} from './makePlugin';-import {type Exporter, ImageExporter, type Project} from '../app';+import {type ExporterClass, ImageExporter} from '../app';/*** The default plugin included in every Motion Canvas project.*/export default makePlugin({name: 'mc-default-plugin',- exporters(project: Project): Exporter[] {- return [new ImageExporter(project.logger)];+ exporters(): ExporterClass[] {+ return [ImageExporter];},});diff --git a/packages/core/src/plugin/Plugin.ts b/packages/core/src/plugin/Plugin.tsindex a3f47779..22307524 100644--- a/packages/core/src/plugin/Plugin.ts+++ b/packages/core/src/plugin/Plugin.ts@@ -1,9 +1,9 @@-import type {Exporter, Project} from '../app';+import type {ExporterClass, Project} from '../app';/*** Represents a runtime Motion Canvas plugin.*/export interface Plugin {name: string;- exporters?(project: Project): Exporter[];+ exporters?(project: Project): ExporterClass[];}diff --git a/packages/template/src/project.meta b/packages/template/src/project.metaindex 992720b2..34b674e5 100644--- a/packages/template/src/project.meta+++ b/packages/template/src/project.meta@@ -20,7 +20,13 @@"fps": 30,"resolutionScale": 1,"colorSpace": "srgb",- "fileType": "image/png",- "quality": 1+ "exporter": {+ "name": "@motion-canvas/core/image-sequence",+ "options": {+ "fileType": "image/png",+ "quality": 100,+ "groupByScene": false+ }+ }}}\ No newline at end of filediff --git a/packages/vite-plugin/src/main.ts b/packages/vite-plugin/src/main.tsindex be2dbe19..97e8053b 100644--- a/packages/vite-plugin/src/main.ts+++ b/packages/vite-plugin/src/main.ts@@ -9,7 +9,7 @@ import {setupEnvVarsForProxy,} from './proxy-middleware';import {getVersions} from './versions';-import {PluginOptions, isPlugin, PLUGIN_OPTIONS} from './plugins';+import {PluginOptions, isPlugin, PLUGIN_OPTIONS, ProjectData} from './plugins';export interface MotionCanvasPluginConfig {/**@@ -85,11 +85,6 @@ export interface MotionCanvasPluginConfig {proxy?: boolean | MotionCanvasCorsProxyOptions;}-interface ProjectData {- name: string;- url: string;-}-export default ({project = './src/project.ts',output = './output',@@ -157,6 +152,14 @@ export default ({.filter(isPlugin).map(plugin => plugin[PLUGIN_OPTIONS]),);+ await Promise.all(+ plugins.map(plugin =>+ plugin.config?.({+ output: outputPath,+ projects,+ }),+ ),+ );viteConfig = resolvedConfig;},async load(id) {diff --git a/packages/vite-plugin/src/plugins.ts b/packages/vite-plugin/src/plugins.tsindex eb78fcb2..e3066775 100644--- a/packages/vite-plugin/src/plugins.ts+++ b/packages/vite-plugin/src/plugins.ts@@ -1,5 +1,37 @@import {Plugin as VitePlugin} from 'vite';+/**+ * Represents a Motion Canvas project configured in the Vite plugin.+ */+export interface ProjectData {+ /**+ * The name of the project.+ */+ name: string;+ /**+ * The file name containing the project.+ */+ fileName: string;+ /**+ * The path to the project relative to the Vite configuration file.+ */+ url: string;+}++/**+ * The Motion Canvas configuration passed to each plugin.+ */+export interface PluginConfig {+ /**+ * The projects configured in the Vite plugin.+ */+ projects: ProjectData[];+ /**+ * The output path relative to the Vite configuration file.+ */+ output: string;+}+export const PLUGIN_OPTIONS = Symbol.for('@motion-canvas/vite-plugin/PLUGIN_OPTIONS',);@@ -17,6 +49,17 @@ export interface PluginOptions {* imported. The module should contain a default export of a runtime plugin.*/entryPoint: string;++ /**+ * The configuration hook of the plugin.+ *+ * @remarks+ * Invoked during `configResolved` hook of Vite, contains the Motion Canvas+ * specific configuration.+ *+ * @param config - The configuration passed to the plugin.+ */+ config?(config: PluginConfig): Promise<void>;}/**