asciify-engine 1.0.43 → 1.0.44

package/dist/index.d.cts

@@ -233,10 +233,17 @@ interface AsciifySimpleOptions {
     options?: Partial<AsciiOptions>;
 }
 interface AsciifyLiveVideoOptions extends AsciifySimpleOptions {
+    /**
+     * When `true`, automatically sizes the canvas to the video's native pixel
+     * dimensions after metadata loads, before `onReady` fires.
+     * Eliminates manual canvas-sizing boilerplate for the common case.
+     * Default: `false`
+     */
+    autoSize?: boolean;
     /**
      * 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.
+     * Receives the backing video element — use this to size the canvas, trigger
+     * a loading state change, start a timer, etc.
      */
     onReady?: (video: HTMLVideoElement) => void;
     /** Called after every rendered frame. Useful for frame counters or timers. */
@@ -288,7 +295,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, onReady, onFrame }?: AsciifyLiveVideoOptions): Promise<() => void>;
+declare function asciifyLiveVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, artStyle, options, autoSize, onReady, onFrame }?: AsciifyLiveVideoOptions): Promise<() => void>;
 
 interface WaveBackgroundOptions {
     /** Font size in CSS pixels (default: 13) */

package/dist/index.d.ts

@@ -233,10 +233,17 @@ interface AsciifySimpleOptions {
     options?: Partial<AsciiOptions>;
 }
 interface AsciifyLiveVideoOptions extends AsciifySimpleOptions {
+    /**
+     * When `true`, automatically sizes the canvas to the video's native pixel
+     * dimensions after metadata loads, before `onReady` fires.
+     * Eliminates manual canvas-sizing boilerplate for the common case.
+     * Default: `false`
+     */
+    autoSize?: boolean;
     /**
      * 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.
+     * Receives the backing video element — use this to size the canvas, trigger
+     * a loading state change, start a timer, etc.
      */
     onReady?: (video: HTMLVideoElement) => void;
     /** Called after every rendered frame. Useful for frame counters or timers. */
@@ -288,7 +295,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, onReady, onFrame }?: AsciifyLiveVideoOptions): Promise<() => void>;
+declare function asciifyLiveVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, artStyle, options, autoSize, onReady, onFrame }?: AsciifyLiveVideoOptions): Promise<() => void>;
 
 interface WaveBackgroundOptions {
     /** Font size in CSS pixels (default: 13) */

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 = {}, onReady, onFrame } = {}) {
+async function asciifyLiveVideo(source, canvas, { fontSize = 10, artStyle = "classic", options = {}, autoSize = false, onReady, onFrame } = {}) {
   let video;
   let ownedVideo = false;
   if (typeof source === "string") {
@@ -1103,13 +1103,16 @@ async function asciifyLiveVideo(source, canvas, { fontSize = 10, artStyle = "cla
     });
     await video.play().catch(() => {
     });
-    onReady?.(video);
   } else {
     video = source;
     if (video.paused) await video.play().catch(() => {
     });
-    onReady?.(video);
   }
+  if (autoSize) {
+    canvas.width = video.videoWidth;
+    canvas.height = video.videoHeight;
+  }
+  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.");