asciify-engine 1.0.41 → 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.
  *
@@ -258,6 +268,27 @@ declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElem
  * // later: stop();
  */
 declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, artStyle, options }?: AsciifySimpleOptions): Promise<() => void>;
+/**
+ * Stream a video element (or URL) as live ASCII art onto a canvas — frame by
+ * frame in real time, with no pre-extraction delay.
+ *
+ * Unlike `asciifyVideo` (which pre-processes the full clip), this renders each
+ * video frame live as the video plays, making it suitable for long videos,
+ * looping clips, and any case where you want instant playback.
+ *
+ * ⚠️ Important: never set the backing `<video>` element to `display: none` —
+ * browsers skip GPU frame decoding for hidden elements, resulting in a blank
+ * canvas. `asciifyLiveVideo` handles this automatically when given a URL.
+ * If you supply your own video element, make sure it is visible or uses
+ * `opacity: 0; position: fixed` instead.
+ *
+ * @returns A `stop()` function that cancels the animation loop and cleans up.
+ *
+ * @example
+ * const stop = await asciifyLiveVideo('/clip.mp4', canvas);
+ * // later: stop();
+ */
+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) */
@@ -918,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, 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.
  *
@@ -258,6 +268,27 @@ declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElem
  * // later: stop();
  */
 declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, artStyle, options }?: AsciifySimpleOptions): Promise<() => void>;
+/**
+ * Stream a video element (or URL) as live ASCII art onto a canvas — frame by
+ * frame in real time, with no pre-extraction delay.
+ *
+ * Unlike `asciifyVideo` (which pre-processes the full clip), this renders each
+ * video frame live as the video plays, making it suitable for long videos,
+ * looping clips, and any case where you want instant playback.
+ *
+ * ⚠️ Important: never set the backing `<video>` element to `display: none` —
+ * browsers skip GPU frame decoding for hidden elements, resulting in a blank
+ * canvas. `asciifyLiveVideo` handles this automatically when given a URL.
+ * If you supply your own video element, make sure it is visible or uses
+ * `opacity: 0; position: fixed` instead.
+ *
+ * @returns A `stop()` function that cancels the animation loop and cleans up.
+ *
+ * @example
+ * const stop = await asciifyLiveVideo('/clip.mp4', canvas);
+ * // later: stop();
+ */
+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) */
@@ -918,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, 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,6 +1075,67 @@ async function asciifyVideo(source, canvas, { fontSize = 10, artStyle = "classic
     cancelAnimationFrame(animId);
   };
 }
+async function asciifyLiveVideo(source, canvas, { fontSize = 10, artStyle = "classic", options = {}, onReady, onFrame } = {}) {
+  let video;
+  let ownedVideo = false;
+  if (typeof source === "string") {
+    video = document.createElement("video");
+    video.src = source;
+    video.muted = true;
+    video.loop = true;
+    video.playsInline = true;
+    video.setAttribute("playsinline", "");
+    Object.assign(video.style, {
+      position: "fixed",
+      top: "0",
+      left: "0",
+      width: "1px",
+      height: "1px",
+      opacity: "0",
+      pointerEvents: "none",
+      zIndex: "-1"
+    });
+    document.body.appendChild(video);
+    ownedVideo = true;
+    await new Promise((resolve, reject) => {
+      video.onloadedmetadata = () => resolve();
+      video.onerror = () => reject(new Error(`asciifyLiveVideo: failed to load "${source}"`));
+    });
+    await video.play().catch(() => {
+    });
+    onReady?.(video);
+  } else {
+    video = source;
+    if (video.paused) await video.play().catch(() => {
+    });
+    onReady?.(video);
+  }
+  const merged = { ...DEFAULT_OPTIONS, ...ART_STYLE_PRESETS[artStyle], ...options, fontSize };
+  const ctx = canvas.getContext("2d");
+  if (!ctx) throw new Error("asciifyLiveVideo: could not get 2d context from canvas.");
+  let cancelled = false;
+  let animId;
+  const tick = () => {
+    if (cancelled) return;
+    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);
+      onFrame?.();
+    }
+  };
+  animId = requestAnimationFrame(tick);
+  return () => {
+    cancelled = true;
+    cancelAnimationFrame(animId);
+    if (ownedVideo) {
+      video.pause();
+      video.src = "";
+      document.body.removeChild(video);
+    }
+  };
+}
 
 // src/backgrounds/rain.ts
 function renderRainBackground(ctx, width, height, time, options = {}) {
@@ -2455,6 +2516,6 @@ async function asciifyWebcam(canvas, {
   };
 }
 
-export { ART_STYLE_PRESETS, BACKGROUND_TYPES, CHARSETS, DEFAULT_OPTIONS, HOVER_PRESETS, PALETTE_THEMES, asciiBackground, asciiText, asciiTextAnsi, asciify, asciifyGif, 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, BACKGROUND_TYPES, CHARSETS, DEFAULT_OPTIONS, HOVER_PRESETS, PALETTE_THEMES, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map