Skip to content

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.meta
index 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 file
diff --git a/packages/vite-plugin/src/main.ts b/packages/vite-plugin/src/main.ts
index 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.ts
index 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>;
}
/**