textmode.js 0.6.0-beta.4 → 0.6.0

package/dist/types/textmode/loadables/{TextmodeVideo.d.ts → video/TextmodeVideo.d.ts}

@@ -1,45 +1,9 @@
-import type { GLRenderer } from '../../rendering/webgl/core/Renderer';
-import type { Material } from '../../rendering/webgl/materials/Material';
-import type { TextmodeFont } from './font/TextmodeFont';
-import { TextmodeSource } from './TextmodeSource';
-type TextmodeVideoPreloadStrategy = 'captureStream' | 'seeking';
-export interface TextmodeVideoPreloadProgress {
-    percent: number;
-    loadedFrames: number;
-    totalFrames: number;
-    strategy: TextmodeVideoPreloadStrategy;
-}
-export interface TextmodeVideoPreloadComplete {
-    totalFrames: number;
-    strategy: TextmodeVideoPreloadStrategy;
-}
-/**
- * Options for preloading video frames in {@link TextmodeVideo}.
- *
- * When providing this options object as a second argument to {@link Textmodifier.loadVideo},
- * you can choose to preload all video frames at a specified frame rate before using the video.
- *
- * When preloading, the video will not play live asynchronously. Instead, all frames will be captured
- * upfront, allowing for frame-accurate seeking and rendering.
- *
- * This is especially useful for scenarios where precise frame control is needed,
- * like capturing GIFs/videos from textmode.js canvas using the `textmode.export.js` add-on library without
- * missing frames due to asynchronous video playback.
- *
- * Preloading takes time proportional to the video length and frame rate, which introduces significant delays
- * before the sketch can start rendering. Therefore, it is recommended to use this feature only when intending
- * to capture or export frames, rather than for real-time playback.
- */
-export interface TextmodeVideoOptions {
-    /** Frame rate to use when preloading video frames. If not specified, video will not be preloaded. */
-    frameRate?: number;
-    /** Callback invoked periodically during preloading to report progress. */
-    onProgress?: (progress: TextmodeVideoPreloadProgress) => void;
-    /** Callback invoked once preloading is complete. */
-    onComplete?: (summary: TextmodeVideoPreloadComplete) => void;
-    /** Callback invoked if an error occurs during preloading. */
-    onError?: (error: Error) => void;
-}
+import type { GLRenderer } from '../../../rendering/webgl/core/Renderer';
+import type { Material } from '../../../rendering/webgl/materials/Material';
+import type { TextmodeFont } from '../font/TextmodeFont';
+import { TextmodeSource } from '../TextmodeSource';
+import type { TextmodeVideoOptions } from './types';
+export type { TextmodeVideoOptions, TextmodeVideoPreloadStrategy, TextmodeVideoPreloadProgress, TextmodeVideoPreloadComplete, } from './types';
 /**
  * Represents a video element for textmode rendering via {@link Textmodifier.loadVideo}.
  *
@@ -79,12 +43,8 @@ export interface TextmodeVideoOptions {
  */
 export declare class TextmodeVideo extends TextmodeSource {
     private _videoElement;
-    private _isPreloaded;
-    private _preloadedFrames;
-    private _frameRate;
-    private _totalFrames;
     private _currentFrameIndex;
-    private _lastProgressBucket;
+    private _preloader;
     /**
      * Create a new TextmodeVideo instance.
      * @param gl WebGL2 rendering context
@@ -125,20 +85,6 @@ export declare class TextmodeVideo extends TextmodeSource {
      */
     $getMaterial(): Material;
     protected $beforeMaterialUpdate(): void;
-    /**
-     * Preload all frames of the video at the specified frame rate.
-     * Chooses the most optimal strategy based on browser capabilities.
-     * @param frameRate Frame rate to use for capturing frames
-     * @ignore
-     */
-    private _preloadFrames;
-    private _initializePreloadState;
-    private _finalizePreloadSuccess;
-    private _captureSourceToTexture;
-    private _reportPreloadProgress;
-    private _tryPreloadWithTrackProcessor;
-    private _preloadWithLegacySeeking;
-    private _waitForSeek;
     /**
      * For preloaded videos, set or get the current frame index.
      * When called without arguments, returns this video instance for use with t.image().
@@ -171,12 +117,11 @@ export declare class TextmodeVideo extends TextmodeSource {
      * @param source Video URL string or HTMLVideoElement
      * @param gridCols Number of columns in the grid
      * @param gridRows Number of rows in the grid
-     * @param glyphResolver Function to resolve character strings to glyph colors
      * @param options Optional preload configuration (frameRate, onProgress, onComplete, onError).
      * @returns Promise resolving to TextmodeVideo instance
      * @ignore
      */
-    static $fromSource(renderer: GLRenderer, font: TextmodeFont, source: string | HTMLVideoElement, gridCols: number, gridRows: number, glyphResolver: (s: string) => ([number, number, number])[], options?: TextmodeVideoOptions): Promise<TextmodeVideo>;
+    static $fromSource(renderer: GLRenderer, font: TextmodeFont, source: string, gridCols: number, gridRows: number, options?: TextmodeVideoOptions): Promise<TextmodeVideo>;
     /**
      * Play the video.
      * @returns Promise that resolves when playback starts
@@ -246,21 +191,8 @@ export declare class TextmodeVideo extends TextmodeSource {
      * Whether the video is currently playing.
      */
     get isPlaying(): boolean;
-    /**
-     * Whether this video has been preloaded with frames.
-     */
-    get isPreloaded(): boolean;
     /**
      * Total number of preloaded frames. Returns 0 for non-preloaded videos.
      */
     get totalFrames(): number;
-    /**
-     * The frame rate used for preloading. Returns null for non-preloaded videos.
-     */
-    get preloadFrameRate(): number | null;
-    /**
-     * Current frame index for preloaded videos. Returns 0 for non-preloaded videos.
-     */
-    get currentFrameIndex(): number;
 }
-export {};

package/dist/types/textmode/loadables/video/TextmodeVideoPreloader.d.ts

@@ -0,0 +1,29 @@
+import type { TextmodeVideoPreloadCallbacks, TextmodeVideoPreloadStrategy } from './types';
+/**
+ * Handles extracting still frames from an {@link HTMLVideoElement} into WebGL textures
+ * so that {@link TextmodeVideo} can render deterministic, frame-accurate playback.
+ */
+export declare class TextmodeVideoPreloader {
+    private readonly _gl;
+    private readonly _videoElement;
+    private _frameRate;
+    private _totalFrames;
+    private _isPreloaded;
+    private _preloadedFrames;
+    private _lastProgressBucket;
+    constructor(gl: WebGL2RenderingContext, videoElement: HTMLVideoElement);
+    get isPreloaded(): boolean;
+    get totalFrames(): number;
+    get frameRate(): number | null;
+    get textures(): readonly WebGLTexture[];
+    dispose(): void;
+    preload(frameRate: number, callbacks?: TextmodeVideoPreloadCallbacks): Promise<TextmodeVideoPreloadStrategy>;
+    private _initializePreloadState;
+    private _finalizePreloadSuccess;
+    private _captureSourceToTexture;
+    private _reportPreloadProgress;
+    private _tryPreloadWithTrackProcessor;
+    private _preloadWithLegacySeeking;
+    private _waitForSeek;
+    private _deletePreloadedTextures;
+}

package/dist/types/textmode/loadables/video/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Options for preloading video frames in {@link TextmodeVideo}.
+ *
+ * When providing this options object as a second argument to {@link Textmodifier.loadVideo},
+ * you can choose to preload all video frames at a specified frame rate before using the video.
+ *
+ * When preloading, the video will not play live asynchronously. Instead, all frames will be captured
+ * upfront, allowing for frame-accurate seeking and rendering.
+ *
+ * This is especially useful for scenarios where precise frame control is needed,
+ * like capturing GIFs/videos from textmode.js canvas using the `textmode.export.js` add-on library without
+ * missing frames due to asynchronous video playback.
+ *
+ * Preloading takes time proportional to the video length and frame rate, which introduces significant delays
+ * before the sketch can start rendering. Therefore, it is recommended to use this feature only when intending
+ * to capture or export frames, rather than for real-time playback.
+ */
+export interface TextmodeVideoOptions {
+    /** Frame rate to use when preloading video frames. If not specified, video will not be preloaded. */
+    frameRate?: number;
+    /** Callback invoked periodically during preloading to report progress. */
+    onProgress?: (progress: TextmodeVideoPreloadProgress) => void;
+    /** Callback invoked once preloading is complete. */
+    onComplete?: (summary: TextmodeVideoPreloadComplete) => void;
+    /** Callback invoked if an error occurs during preloading. */
+    onError?: (error: Error) => void;
+}
+export type TextmodeVideoPreloadStrategy = 'captureStream' | 'seeking';
+export interface TextmodeVideoPreloadProgress {
+    percent: number;
+    loadedFrames: number;
+    totalFrames: number;
+    strategy: TextmodeVideoPreloadStrategy;
+}
+export interface TextmodeVideoPreloadComplete {
+    totalFrames: number;
+    strategy: TextmodeVideoPreloadStrategy;
+}
+export type TextmodeVideoPreloadCallbacks = {
+    onProgress?: (progress: TextmodeVideoPreloadProgress) => void;
+    onComplete?: (summary: TextmodeVideoPreloadComplete) => void;
+    onError?: (error: Error) => void;
+};

package/dist/types/textmode/mixins/interfaces/IRenderingMixin.d.ts

@@ -1,7 +1,7 @@
 import type { GLFramebuffer, GLShader, TextmodeFramebufferOptions, UniformValue } from "../../../rendering/webgl";
 import type { TextmodeSource } from '../../loadables/TextmodeSource';
 import type { TextmodeImage } from '../../loadables/TextmodeImage';
-import type { TextmodeVideo, TextmodeVideoOptions } from "../../loadables/TextmodeVideo";
+import type { TextmodeVideo, TextmodeVideoOptions } from "../../loadables/video/TextmodeVideo";
 import type { TextmodeColor } from "../../TextmodeColor";
 /**
  * Interface for rendering capabilities that will be mixed into Textmodifier
@@ -81,9 +81,9 @@ export interface IRenderingMixin {
      */
     createFramebuffer(options: TextmodeFramebufferOptions): GLFramebuffer;
     /**
-     * Draw a TextmodeFramebuffer or TextmodeImage to the current render target.
+     * Draw a TextmodeFramebuffer or TextmodeSource (TextmodeImage/TextmodeVideo) to the current render target.
      *
-     * @param source The TextmodeFramebuffer or TextmodeImage to render
+     * @param source The TextmodeFramebuffer or TextmodeSource to render
      * @param x X position on the grid where to place the content *(top-left corner)*
      * @param y Y position on the grid where to place the content *(top-left corner)*
      * @param width Width to potentially scale the content
@@ -546,8 +546,7 @@ export interface IRenderingMixin {
     /**
      * Create a reusable color object compatible with textmode drawing APIs.
      *
-     * Accepts grayscale, RGB, RGBA, hex string values as arguments, and
-     * single characters that resolve to their encoded glyph color. Returned
+     * Accepts grayscale, RGB, RGBA, and hex string values as arguments. Returned
      * {@link TextmodeColor} instances can be passed to {@link background},
      * {@link char}, {@link charColor}, {@link cellColor}, and more.
      *
@@ -574,13 +573,6 @@ export interface IRenderingMixin {
     * // Hex string
     * const dusk = t.color('#203040');
     *
-    * // Single character: resolves to a TextmodeColor that may encode a glyph
-    * let glyphColor;
-    *
-    * t.setup(() => {
-    *     glyphColor = t.color('B'); // Color based on 'B' character glyph
-    * });
-    *
     * t.draw(() => {
     *     // Using colors with other drawing APIs
     *     t.background(gray);
@@ -595,7 +587,7 @@ export interface IRenderingMixin {
     *
     *     t.translate(5, 0);
     *     t.charColor("#FF00FF");
-    *     t.char(glyphColor);
+    *     t.char("B");
     *     t.rect(5, 5);
     * });
     * ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "textmode.js",
-  "version": "0.6.0-beta.4",
+  "version": "0.6.0",
   "description": "textmode.js is a lightweight creative coding library for creating real-time ASCII art on the web.",
   "type": "module",
   "types": "./dist/types/index.d.ts",
@@ -41,6 +41,7 @@
     "tslib": "^2.8.1",
     "typedoc": "^0.28.13",
     "typedoc-plugin-markdown": "^4.7.0",
+    "typedoc-vitepress-theme": "^1.1.2",
     "typescript": "^5.9.2",
     "vite": "^6.3.4",
     "vite-plugin-glsl": "^1.5.1",