asciify-engine 1.0.42 → 1.0.43

package/dist/index.d.cts

@@ -232,6 +232,16 @@ interface AsciifySimpleOptions {
     /** Extra options to merge on top of the preset */
     options?: Partial<AsciiOptions>;
 }
+interface AsciifyLiveVideoOptions extends AsciifySimpleOptions {
+    /**
+     * Called once when the video metadata is ready and playback has started.
+     * Receive the backing video element — useful for sizing the canvas or
+     * triggering a ready state in your UI.
+     */
+    onReady?: (video: HTMLVideoElement) => void;
+    /** Called after every rendered frame. Useful for frame counters or timers. */
+    onFrame?: () => void;
+}
 /**
  * Convert an image/video/canvas element to ASCII art and render it onto a canvas.
  *
@@ -278,7 +288,7 @@ declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCan
  * const stop = await asciifyLiveVideo('/clip.mp4', canvas);
  * // later: stop();
  */
-declare function asciifyLiveVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, artStyle, options }?: AsciifySimpleOptions): Promise<() => void>;
+declare function asciifyLiveVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, artStyle, options, onReady, onFrame }?: AsciifyLiveVideoOptions): Promise<() => void>;
 
 interface WaveBackgroundOptions {
     /** Font size in CSS pixels (default: 13) */
@@ -939,4 +949,4 @@ interface WebcamOptions {
  */
 declare function asciifyWebcam(canvas: HTMLCanvasElement, { fontSize, style, options, liveOptions, mirror, constraints, dpr: dprOverride, }?: WebcamOptions): Promise<() => void>;
 
-export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiBackgroundOptions, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciifySimpleOptions, type AuroraBackgroundOptions, BACKGROUND_TYPES, type BackgroundType, CHARSETS, type CharsetKey, type CircuitBackgroundOptions, type ColorMode, DEFAULT_OPTIONS, type DnaBackgroundOptions, type FireBackgroundOptions, type GridBackgroundOptions, HOVER_PRESETS, type HoverEffect, type HoverPreset, type MorphBackgroundOptions, type MountWaveOptions, type NoiseBackgroundOptions, PALETTE_THEMES, type PaletteTheme, type PulseBackgroundOptions, type RainBackgroundOptions, type RenderMode, type SilkBackgroundOptions, type SnapshotOptions, type SourceType, type StarsBackgroundOptions, type TerrainBackgroundOptions, type TextBackgroundOptions, type VoidBackgroundOptions, type WaveBackgroundOptions, type WebcamOptions, asciiBackground, asciiText, asciiTextAnsi, asciify, asciifyGif, asciifyLiveVideo, asciifyVideo, asciifyWebcam, buildTextFrame, captureSnapshot, gifToAsciiFrames, imageToAsciiFrame, mountWaveBackground, renderAuroraBackground, renderCircuitBackground, renderDnaBackground, renderFireBackground, renderFrameToCanvas, renderGridBackground, renderMorphBackground, renderNoiseBackground, renderPulseBackground, renderRainBackground, renderSilkBackground, renderStarsBackground, renderTerrainBackground, renderTextBackground, renderVoidBackground, renderWaveBackground, snapshotAndDownload, videoToAsciiFrames };
+export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiBackgroundOptions, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciifyLiveVideoOptions, type AsciifySimpleOptions, type AuroraBackgroundOptions, BACKGROUND_TYPES, type BackgroundType, CHARSETS, type CharsetKey, type CircuitBackgroundOptions, type ColorMode, DEFAULT_OPTIONS, type DnaBackgroundOptions, type FireBackgroundOptions, type GridBackgroundOptions, HOVER_PRESETS, type HoverEffect, type HoverPreset, type MorphBackgroundOptions, type MountWaveOptions, type NoiseBackgroundOptions, PALETTE_THEMES, type PaletteTheme, type PulseBackgroundOptions, type RainBackgroundOptions, type RenderMode, type SilkBackgroundOptions, type SnapshotOptions, type SourceType, type StarsBackgroundOptions, type TerrainBackgroundOptions, type TextBackgroundOptions, type VoidBackgroundOptions, type WaveBackgroundOptions, type WebcamOptions, asciiBackground, asciiText, asciiTextAnsi, asciify, asciifyGif, asciifyLiveVideo, asciifyVideo, asciifyWebcam, buildTextFrame, captureSnapshot, gifToAsciiFrames, imageToAsciiFrame, mountWaveBackground, renderAuroraBackground, renderCircuitBackground, renderDnaBackground, renderFireBackground, renderFrameToCanvas, renderGridBackground, renderMorphBackground, renderNoiseBackground, renderPulseBackground, renderRainBackground, renderSilkBackground, renderStarsBackground, renderTerrainBackground, renderTextBackground, renderVoidBackground, renderWaveBackground, snapshotAndDownload, videoToAsciiFrames };

package/dist/index.d.ts

@@ -232,6 +232,16 @@ interface AsciifySimpleOptions {
     /** Extra options to merge on top of the preset */
     options?: Partial<AsciiOptions>;
 }
+interface AsciifyLiveVideoOptions extends AsciifySimpleOptions {
+    /**
+     * Called once when the video metadata is ready and playback has started.
+     * Receive the backing video element — useful for sizing the canvas or
+     * triggering a ready state in your UI.
+     */
+    onReady?: (video: HTMLVideoElement) => void;
+    /** Called after every rendered frame. Useful for frame counters or timers. */
+    onFrame?: () => void;
+}
 /**
  * Convert an image/video/canvas element to ASCII art and render it onto a canvas.
  *
@@ -278,7 +288,7 @@ declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCan
  * const stop = await asciifyLiveVideo('/clip.mp4', canvas);
  * // later: stop();
  */
-declare function asciifyLiveVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, artStyle, options }?: AsciifySimpleOptions): Promise<() => void>;
+declare function asciifyLiveVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, artStyle, options, onReady, onFrame }?: AsciifyLiveVideoOptions): Promise<() => void>;
 
 interface WaveBackgroundOptions {
     /** Font size in CSS pixels (default: 13) */
@@ -939,4 +949,4 @@ interface WebcamOptions {
  */
 declare function asciifyWebcam(canvas: HTMLCanvasElement, { fontSize, style, options, liveOptions, mirror, constraints, dpr: dprOverride, }?: WebcamOptions): Promise<() => void>;
 
-export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiBackgroundOptions, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciifySimpleOptions, type AuroraBackgroundOptions, BACKGROUND_TYPES, type BackgroundType, CHARSETS, type CharsetKey, type CircuitBackgroundOptions, type ColorMode, DEFAULT_OPTIONS, type DnaBackgroundOptions, type FireBackgroundOptions, type GridBackgroundOptions, HOVER_PRESETS, type HoverEffect, type HoverPreset, type MorphBackgroundOptions, type MountWaveOptions, type NoiseBackgroundOptions, PALETTE_THEMES, type PaletteTheme, type PulseBackgroundOptions, type RainBackgroundOptions, type RenderMode, type SilkBackgroundOptions, type SnapshotOptions, type SourceType, type StarsBackgroundOptions, type TerrainBackgroundOptions, type TextBackgroundOptions, type VoidBackgroundOptions, type WaveBackgroundOptions, type WebcamOptions, asciiBackground, asciiText, asciiTextAnsi, asciify, asciifyGif, asciifyLiveVideo, asciifyVideo, asciifyWebcam, buildTextFrame, captureSnapshot, gifToAsciiFrames, imageToAsciiFrame, mountWaveBackground, renderAuroraBackground, renderCircuitBackground, renderDnaBackground, renderFireBackground, renderFrameToCanvas, renderGridBackground, renderMorphBackground, renderNoiseBackground, renderPulseBackground, renderRainBackground, renderSilkBackground, renderStarsBackground, renderTerrainBackground, renderTextBackground, renderVoidBackground, renderWaveBackground, snapshotAndDownload, videoToAsciiFrames };
+export { ART_STYLE_PRESETS, type AnimationStyle, type ArtStyle, type AsciiBackgroundOptions, type AsciiCell, type AsciiFrame, type AsciiOptions, type AsciiResult, type AsciifyLiveVideoOptions, type AsciifySimpleOptions, type AuroraBackgroundOptions, BACKGROUND_TYPES, type BackgroundType, CHARSETS, type CharsetKey, type CircuitBackgroundOptions, type ColorMode, DEFAULT_OPTIONS, type DnaBackgroundOptions, type FireBackgroundOptions, type GridBackgroundOptions, HOVER_PRESETS, type HoverEffect, type HoverPreset, type MorphBackgroundOptions, type MountWaveOptions, type NoiseBackgroundOptions, PALETTE_THEMES, type PaletteTheme, type PulseBackgroundOptions, type RainBackgroundOptions, type RenderMode, type SilkBackgroundOptions, type SnapshotOptions, type SourceType, type StarsBackgroundOptions, type TerrainBackgroundOptions, type TextBackgroundOptions, type VoidBackgroundOptions, type WaveBackgroundOptions, type WebcamOptions, asciiBackground, asciiText, asciiTextAnsi, asciify, asciifyGif, asciifyLiveVideo, asciifyVideo, asciifyWebcam, buildTextFrame, captureSnapshot, gifToAsciiFrames, imageToAsciiFrame, mountWaveBackground, renderAuroraBackground, renderCircuitBackground, renderDnaBackground, renderFireBackground, renderFrameToCanvas, renderGridBackground, renderMorphBackground, renderNoiseBackground, renderPulseBackground, renderRainBackground, renderSilkBackground, renderStarsBackground, renderTerrainBackground, renderTextBackground, renderVoidBackground, renderWaveBackground, snapshotAndDownload, videoToAsciiFrames };

package/dist/index.js

@@ -1075,7 +1075,7 @@ async function asciifyVideo(source, canvas, { fontSize = 10, artStyle = "classic
     cancelAnimationFrame(animId);
   };
 }
-async function asciifyLiveVideo(source, canvas, { fontSize = 10, artStyle = "classic", options = {} } = {}) {
+async function asciifyLiveVideo(source, canvas, { fontSize = 10, artStyle = "classic", options = {}, onReady, onFrame } = {}) {
   let video;
   let ownedVideo = false;
   if (typeof source === "string") {
@@ -1101,12 +1101,14 @@ async function asciifyLiveVideo(source, canvas, { fontSize = 10, artStyle = "cla
       video.onloadedmetadata = () => resolve();
       video.onerror = () => reject(new Error(`asciifyLiveVideo: failed to load "${source}"`));
     });
-    video.play().catch(() => {
+    await video.play().catch(() => {
     });
+    onReady?.(video);
   } else {
     video = source;
-    if (video.paused) video.play().catch(() => {
+    if (video.paused) await video.play().catch(() => {
     });
+    onReady?.(video);
   }
   const merged = { ...DEFAULT_OPTIONS, ...ART_STYLE_PRESETS[artStyle], ...options, fontSize };
   const ctx = canvas.getContext("2d");
@@ -1118,7 +1120,10 @@ async function asciifyLiveVideo(source, canvas, { fontSize = 10, artStyle = "cla
     animId = requestAnimationFrame(tick);
     if (video.readyState < 2 || canvas.width === 0 || canvas.height === 0) return;
     const { frame } = imageToAsciiFrame(video, merged, canvas.width, canvas.height);
-    if (frame.length > 0) renderFrameToCanvas(ctx, frame, merged, canvas.width, canvas.height, 0, null);
+    if (frame.length > 0) {
+      renderFrameToCanvas(ctx, frame, merged, canvas.width, canvas.height, 0, null);
+      onFrame?.();
+    }
   };
   animId = requestAnimationFrame(tick);
   return () => {