textmode.export.js 1.8.0 → 1.8.1

package/dist/types/exporters/base/FramePreparation.d.ts

@@ -2,6 +2,13 @@
 export interface ExportFrameContext {
     frameIndex: number;
     frameCount: number;
+    /** Left edge of the output-frame interval. Alias of `timeSeconds`. */
+    startSeconds: number;
+    /** Center of the output-frame interval; use this to sample external media. */
+    centerSeconds: number;
+    /** Exclusive right edge of the output-frame interval. */
+    endSeconds: number;
+    /** @deprecated Use `startSeconds`. */
     timeSeconds: number;
     frameRate: number;
     signal?: AbortSignal;

package/dist/types/exporters/gif/types.d.ts

@@ -1,21 +1,21 @@
 import type { PrepareExportFrame } from '../base';
 export type GIFRecordingState = 'idle' | 'recording' | 'encoding' | 'completed' | 'error';
 /**
- * Progress information emitted during the GIF export process.
+ * Progress information emitted while deterministic frames are captured and encoded as an animated GIF.
  *
- * @category Animation export
+ * @category GIF export
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/GIFExportProgress | GIFExportProgress API reference}
  */
 export type GIFExportProgress = {
     /**
-     * Current state of the recording process.
+     * Current GIF capture or encoding state.
      *
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/GIFExportProgress#state | GIFExportProgress.state API reference}
      */
     state: 'idle' | 'recording' | 'encoding' | 'completed' | 'error';
     /**
-     * Number of frames that have been recorded so far.
+     * Number of frames captured so far.
      *
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/GIFExportProgress#frameindex | GIFExportProgress.frameIndex API reference}
      */
@@ -34,9 +34,9 @@ export type GIFExportProgress = {
     message?: string;
 };
 /**
- * Options for exporting the textmode content to GIF format.
+ * Options for capturing deterministic textmode frames as an animated GIF.
  *
- * @category Animation export
+ * @category GIF export
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/GIFExportOptions | GIFExportOptions API reference}
  */

package/dist/types/exporters/video/VideoEncodingPolicy.d.ts

@@ -1,20 +1,3 @@
-import type { VideoBitrateMode, VideoCodec, VideoContentHint, VideoEncodingPlan, VideoGenerationOptions } from './types';
-export declare const MAX_SAFE_IN_MEMORY_VIDEO_BYTES = 100000000;
-export declare const ULTRA_FALLBACK_BITS_PER_PIXEL_PER_FRAME = 0.5;
-export type VideoQualityDescriptor = {
-    kind: 'named';
-    level: 'medium' | 'high' | 'very-high';
-} | {
-    kind: 'bitrate';
-    bitrate: number;
-    bitrateMode: VideoBitrateMode;
-} | {
-    kind: 'ultra';
-    bitrate: number;
-};
-export declare function resolveUltraFallbackBitrate(width: number, height: number, frameRate: number): number;
-export declare function estimateVideoOutputBytes(bitrate: number, frameCount: number, frameRate: number): number;
-export declare function getVideoQualityDescriptor(plan: VideoEncodingPlan): VideoQualityDescriptor;
-export declare function normalizeVideoContentHint(value: VideoContentHint | undefined): VideoContentHint;
+import type { VideoCodec, VideoEncodingPlan, VideoGenerationOptions } from './types';
+/** Resolves product-level format constraints independently of encoder probing. */
 export declare function createVideoEncodingPlan(options: VideoGenerationOptions, codec?: VideoCodec): VideoEncodingPlan;
-export declare function assertVideoOutputFitsMemory(plan: VideoEncodingPlan, allowLargeInMemory: boolean): void;

package/dist/types/exporters/video/VideoExporter.d.ts

@@ -15,12 +15,11 @@ export declare class VideoExporter {
     private _applyDefaultOptions;
     private _positiveInteger;
     private _positiveNumber;
-    private _bitrate;
-    private _bitrateMode;
-    private _contentHint;
-    private _latencyMode;
+    private _quality;
+    private _isBitrateMode;
     private _hardwareAcceleration;
     private _keyFrameInterval;
     private _currentPixelDensity;
     private _withExtension;
+    private _createFileSystemDestination;
 }

package/dist/types/exporters/video/VideoFrameSchedule.d.ts

@@ -0,0 +1,8 @@
+export interface VideoFrameTiming {
+    startSeconds: number;
+    centerSeconds: number;
+    endSeconds: number;
+    durationSeconds: number;
+}
+/** Produces one stable microsecond-rounded interval for an output frame. */
+export declare function videoFrameTiming(frameIndex: number, frameRate: number): VideoFrameTiming;

package/dist/types/exporters/video/VideoRecorder.d.ts

@@ -2,10 +2,11 @@ import { type StreamTargetChunk } from 'mediabunny';
 import type { VideoExportProgress, VideoFrameDriverLike, VideoGenerationOptions } from './types';
 export type VideoOutputDestination = {
     kind: 'blob';
-    allowLargeInMemory: boolean;
 } | {
     kind: 'stream';
     writable: WritableStream<StreamTargetChunk>;
+    /** Releases a destination selected before encoder probing starts. */
+    abort?: (reason?: unknown) => Promise<void>;
 };
 /** Records deterministic textmode frames through WebCodecs and muxes them with Mediabunny. */
 export declare class VideoRecorder {

package/dist/types/exporters/video/index.d.ts

@@ -1,2 +1,2 @@
 export { VideoExportError } from './errors';
-export type { VideoBitrateMode, VideoBitratePreset, VideoContentHint, VideoEncodingPlan, VideoExportErrorCode, VideoExportFormat, VideoExportOptions, VideoExportPhase, VideoFrameDriverLike, VideoHardwareAcceleration, VideoLatencyMode, VideoExportProgress, VideoGenerationOptions, VideoRecordingState, VideoRenderFrameOptions, } from './types';
+export type { VideoBitrateMode, VideoEncodingPlan, VideoExportErrorCode, VideoExportFormat, VideoExportOptions, VideoExportPhase, VideoFrameDriverLike, VideoHardwareAcceleration, VideoQuality, VideoQualityLevel, VideoSaveDestination, VideoExportProgress, VideoGenerationOptions, VideoRecordingState, VideoRenderFrameOptions, } from './types';

package/dist/types/exporters/video/types.d.ts

@@ -1,45 +1,83 @@
 import type { PrepareExportFrame } from '../base';
 /**
- * Lifecycle state reported while a video export is being prepared, recorded, encoded, or completed.
+ * High-level lifecycle state reported while a video export is captured, encoded, or completed.
  *
- * @category Animation export
+ * @category Video export
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoRecordingState | VideoRecordingState API reference}
  */
 export type VideoRecordingState = 'idle' | 'recording' | 'encoding' | 'completed' | 'error';
 /**
- * More granular phase information for progress UIs that need to distinguish setup, rendering, and finalization.
+ * Detailed phase information for progress UIs that distinguish capability probing, frame capture, and output.
  *
- * `rendering` is retained for 1.5.x compatibility. Current deterministic video capture emits `capturing`.
+ * Current exports emit `probing`, `capturing`, and either `writing` for streamed file-system output or `finalizing`
+ * for buffered output. `rendering`, `encoding`, and `draining` remain available for compatibility with older progress
+ * producers.
  *
- * @category Animation export
+ * @category Video export
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportPhase | VideoExportPhase API reference}
  */
 export type VideoExportPhase = 'probing' | 'rendering' | 'capturing' | 'encoding' | 'draining' | 'writing' | 'finalizing';
 export type VideoCodec = 'vp8' | 'vp9' | 'avc' | (string & {});
 /**
- * Subjective bitrate preset used when an exact bits-per-second value is not supplied.
+ * Qualitative video quality level matching Mediabunny's five native levels.
  *
- * Higher presets request higher constant perceptual quality from Mediabunny. The `ultra` preset requests quantizer
- * zero with a frame-rate-aware bitrate fallback and should be described as near-lossless, never mathematically
- * lossless. For exact bitrate control, pass a numeric `bitrate` value in bits per second instead.
+ * Higher levels generally preserve more detail and produce larger, content-dependent files. Mediabunny may use
+ * quantizer-based encoding or a codec-adjusted bitrate, depending on codec and browser support.
  *
- * @category Animation export
+ * @category Video export
  *
- * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoBitratePreset | VideoBitratePreset API reference}
+ * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoQualityLevel | VideoQualityLevel API reference}
  */
-export type VideoBitratePreset = 'low' | 'medium' | 'high' | 'ultra';
+export type VideoQualityLevel = 'very-low' | 'low' | 'medium' | 'high' | 'very-high';
 /**
- * Hint for the encoder's content-aware rate control.
+ * Video compression policy passed to Mediabunny.
  *
- * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoContentHint | VideoContentHint API reference}
+ * Use a named {@link VideoQualityLevel} for content-dependent qualitative encoding. Use the object form to request a
+ * positive target bitrate in bits per second and, optionally, constant or variable allocation. When `bitrateMode` is
+ * omitted, Mediabunny defaults bitrate-based encoding to `'variable'`. A target bitrate guides the encoder but does
+ * not guarantee an exact final file size.
+ *
+ * @example Named qualitative quality
+ * ```ts
+ * await t.saveVideo({ quality: 'very-high' });
+ * ```
+ *
+ * @example Target bitrate with constant allocation
+ * ```ts
+ * await t.saveVideo({ quality: { bitrate: 8_000_000, bitrateMode: 'constant' } });
+ * ```
+ *
+ * @category Video export
+ *
+ * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoQuality | VideoQuality API reference}
+ */
+export type VideoQuality = VideoQualityLevel | {
+    bitrate: number;
+    bitrateMode?: VideoBitrateMode;
+};
+/**
+ * Destination policy used by `saveVideo()`.
+ *
+ * - `'download'` is the default. The complete video is buffered in memory before a browser download begins.
+ * - `'file-system'` opens the browser's save picker and streams encoded chunks directly to the selected file. It
+ *   requires the File System Access API and rejects with `VIDEO_EXPORT_UNSUPPORTED` when that API is unavailable.
+ *
+ * This setting does not affect `toVideoBlob()`, which always returns an in-memory `Blob`.
+ *
+ * @category Video export
+ *
+ * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoSaveDestination | VideoSaveDestination API reference}
  */
-export type VideoContentHint = '' | 'motion' | 'detail' | 'text';
+export type VideoSaveDestination = 'download' | 'file-system';
 /**
- * Video container format written by `saveVideo`.
+ * Video container format produced by `saveVideo()` and `toVideoBlob()`.
  *
- * @category Animation export
+ * MP4 uses AVC/H.264 and requires even coded dimensions. WebM selects VP9 when available and falls back to VP8; it
+ * is the only format that can be requested with transparency.
+ *
+ * @category Video export
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportFormat | VideoExportFormat API reference}
  */
@@ -52,23 +90,13 @@ export type VideoExportFormat = 'webm' | 'mp4';
  * - `'constant'`: asks the encoder to keep the bitrate steadier throughout the export. This can make file size
  *   more predictable, but may waste bits on simple frames or reduce detail on complex frames.
  *
- * @category Animation export
+ * If omitted for an explicit target bitrate, Mediabunny uses `'variable'`.
+ *
+ * @category Video export
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoBitrateMode | VideoBitrateMode API reference}
  */
 export type VideoBitrateMode = 'variable' | 'constant';
-/**
- * Encoder scheduling mode.
- *
- * - `'quality'`: prioritizes complete, stable export output. Mediabunny notes that this mode prevents dropped frames.
- * - `'realtime'`: prioritizes low-latency encoding. It is intended for live streams and may drop frames when overloaded,
- *   so it is usually not recommended for frame-perfect exports.
- *
- * @category Animation export
- *
- * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoLatencyMode | VideoLatencyMode API reference}
- */
-export type VideoLatencyMode = 'quality' | 'realtime';
 /**
  * WebCodecs hardware acceleration preference.
  *
@@ -78,34 +106,34 @@ export type VideoLatencyMode = 'quality' | 'realtime';
  *   availability and output characteristics vary by device.
  * - `'prefer-software'`: prefer CPU encoding, often more consistent across machines, but usually slower.
  *
- * @category Animation export
+ * @category Video export
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoHardwareAcceleration | VideoHardwareAcceleration API reference}
  */
 export type VideoHardwareAcceleration = 'no-preference' | 'prefer-hardware' | 'prefer-software';
-export type VideoExportErrorCode = 'VIDEO_EXPORT_UNSUPPORTED' | 'VIDEO_CODEC_UNSUPPORTED' | 'VIDEO_EXPORT_ABORTED' | 'VIDEO_EXPORT_TIMEOUT' | 'VIDEO_EXPORT_FAILED' | 'VIDEO_TRANSPARENCY_UNSUPPORTED' | 'VIDEO_DIMENSIONS_UNSUPPORTED' | 'VIDEO_OUTPUT_TOO_LARGE';
+export type VideoExportErrorCode = 'VIDEO_EXPORT_UNSUPPORTED' | 'VIDEO_CODEC_UNSUPPORTED' | 'VIDEO_EXPORT_ABORTED' | 'VIDEO_EXPORT_TIMEOUT' | 'VIDEO_EXPORT_FAILED' | 'VIDEO_TRANSPARENCY_UNSUPPORTED' | 'VIDEO_DIMENSIONS_UNSUPPORTED';
 /**
- * Progress information emitted during the video export process.
+ * Progress information emitted while a deterministic video is probed, captured, and written.
  *
- * @category Animation export
+ * @category Video export
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress | VideoExportProgress API reference}
  */
 export type VideoExportProgress = {
     /**
-     * Current state of the recording process.
+     * Current high-level export state.
      *
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#state | VideoExportProgress.state API reference}
      */
     state: VideoRecordingState;
     /**
-     * Current export phase for newer progress UIs.
+     * Current detailed phase. See {@link VideoExportPhase} for current and compatibility-only values.
      *
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#phase | VideoExportProgress.phase API reference}
      */
     phase?: VideoExportPhase;
     /**
-     * Number of frames that have been recorded so far.
+     * Number of frames captured so far.
      *
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#frameindex | VideoExportProgress.frameIndex API reference}
      */
@@ -123,7 +151,9 @@ export type VideoExportProgress = {
      */
     totalFrames?: number;
     /**
-     * Export completion ratio between `0` and `1`.
+     * Normalized frame-capture completion ratio between `0` and `1`.
+     *
+     * Final writing or muxing may still be in progress when this value reaches `1`.
      *
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#progress | VideoExportProgress.progress API reference}
      */
@@ -135,22 +165,34 @@ export type VideoExportProgress = {
      */
     message?: string;
     /**
-     * The rate-control path selected by the browser, when known.
+     * Effective codec family selected after capability probing (`avc`, `vp9`, or `vp8`).
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#codec | VideoExportProgress.codec API reference}
+     */
+    codec?: VideoCodec;
+    /**
+     * Effective coded width in pixels.
+     *
+     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#codedwidth | VideoExportProgress.codedWidth API reference}
+     */
+    codedWidth?: number;
+    /**
+     * Effective coded height in pixels.
      *
-     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#ratecontrol | VideoExportProgress.rateControl API reference}
+     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#codedheight | VideoExportProgress.codedHeight API reference}
      */
-    rateControl?: 'quantizer' | 'bitrate-fallback' | 'bitrate';
+    codedHeight?: number;
     /**
-     * Conservative output-size estimate in bytes, when available.
+     * Exact output frame rate passed to the muxer.
      *
-     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#estimatedbytes | VideoExportProgress.estimatedBytes API reference}
+     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress#framerate | VideoExportProgress.frameRate API reference}
      */
-    estimatedBytes?: number;
+    frameRate?: number;
 };
 /**
- * Options for exporting the textmode content to video format.
+ * Options for capturing deterministic textmode frames as MP4 or WebM video.
  *
- * @category Animation export
+ * @category Video export
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions | VideoExportOptions API reference}
  */
@@ -180,39 +222,23 @@ export type VideoExportOptions = {
      */
     frameRate?: number;
     /**
-     * Target bitrate in bits per second or a quality preset. Defaults to `'medium'`.
-     *
-     * String values request constant-quality encoding through Mediabunny. `low`, `medium`, and `high` map to the
-     * upstream `medium`, `high`, and `very-high` quality levels; `ultra` requests quantizer zero and may create very
-     * large files. Numeric values remain exact bits-per-second targets and are wrapped in Mediabunny `Quality`.
-     *
-     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#bitrate | VideoExportOptions.bitrate API reference}
-     */
-    bitrate?: number | VideoBitratePreset;
-    /**
-     * Bitrate allocation mode for numeric bitrates and quality fallback paths. Defaults to `'variable'`.
-     *
-     * Use `'variable'` for most exports so simple frames can compress efficiently and complex frames can receive more
-     * bits. Use `'constant'` only when a steadier data rate is more important than compression efficiency.
+     * Video quality policy. Defaults to `'medium'`.
      *
-     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#bitratemode | VideoExportOptions.bitrateMode API reference}
-     */
-    bitrateMode?: VideoBitrateMode;
-    /**
-     * Content hint passed to the native video encoder. Defaults to `'text'`.
+     * Named levels map one-to-one to Mediabunny's qualitative levels and produce content-dependent file sizes. Use the
+     * object form to request a positive target bitrate in bits per second and an optional bitrate mode.
      *
-     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#contenthint | VideoExportOptions.contentHint API reference}
+     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#quality | VideoExportOptions.quality API reference}
      */
-    contentHint?: VideoContentHint;
+    quality?: VideoQuality;
     /**
-     * Encoder latency mode. Defaults to `'quality'`.
+     * Save destination used by `saveVideo()`. Defaults to `'download'`.
      *
-     * Use `'quality'` for deterministic exports; it prioritizes completed output and avoids dropped frames. Use
-     * `'realtime'` only for low-latency use cases where dropped frames are acceptable.
+     * `'file-system'` opens a save picker and streams directly to the selected file when the File System Access API is
+     * available. `toVideoBlob()` always returns an in-memory blob and does not use this setting.
      *
-     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#latencymode | VideoExportOptions.latencyMode API reference}
+     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#destination | VideoExportOptions.destination API reference}
      */
-    latencyMode?: VideoLatencyMode;
+    destination?: VideoSaveDestination;
     /**
      * WebCodecs hardware acceleration hint. Defaults to `'no-preference'`.
      *
@@ -251,7 +277,7 @@ export type VideoExportOptions = {
      */
     prepareFrame?: PrepareExportFrame;
     /**
-     * When true, attempts to preserve alpha data in WebM recordings. MP4 exports reject this option.
+     * When `true`, attempts to preserve alpha data in WebM recordings. MP4 exports reject this option.
      *
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#transparent | VideoExportOptions.transparent API reference}
      */
@@ -268,22 +294,13 @@ export type VideoExportOptions = {
      * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#debuglogging | VideoExportOptions.debugLogging API reference}
      */
     debugLogging?: boolean;
-    /**
-     * Allows `toVideoBlob()` to retain its in-memory contract above the safe 100 MB default.
-     *
-     * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions#allowlargeinmemory | VideoExportOptions.allowLargeInMemory API reference}
-     */
-    allowLargeInMemory?: boolean;
 };
 export interface VideoGenerationOptions {
     filename?: string;
     format: VideoExportFormat;
     frameRate: number;
     frameCount: number;
-    bitrate: number | VideoBitratePreset;
-    bitrateMode: VideoBitrateMode;
-    contentHint?: VideoContentHint;
-    latencyMode: VideoLatencyMode;
+    quality: VideoQuality;
     hardwareAcceleration: VideoHardwareAcceleration;
     keyFrameInterval: number;
     pixelDensity: number;
@@ -291,7 +308,6 @@ export interface VideoGenerationOptions {
     height: number;
     transparent: boolean;
     debugLogging: boolean;
-    allowLargeInMemory?: boolean;
     signal?: AbortSignal;
     prepareFrame?: PrepareExportFrame;
 }
@@ -300,14 +316,7 @@ export interface VideoEncodingPlan {
     extension: '.webm' | '.mp4';
     mimeType: string;
     codec: VideoCodec;
-    bitrate: number;
-    bitrateMode: VideoBitrateMode;
-    qualityPreset: VideoBitratePreset | null;
-    rateControlIntent: 'bitrate' | 'constant-quality' | 'ultra';
-    qualityLevel?: 'medium' | 'high' | 'very-high';
-    contentHint: VideoContentHint;
-    estimatedBytes: number;
-    latencyMode: VideoLatencyMode;
+    quality: VideoQuality;
     hardwareAcceleration: VideoHardwareAcceleration;
     keyFrameInterval: number;
     frameRate: number;

package/dist/types/index.d.ts

@@ -5,15 +5,38 @@
  *
  * ## Choose an output
  *
- * Use **canvas capture** for the exact image on screen: PNG, JPEG, WebP, GIF,
- * or video preserve compositing, filters, shaders, and post-processing. Use
- * **layer data export** when the artwork should stay editable or machine
- * readable: TXT, SVG, and JSON read from the selected layer, while JSON can
- * also describe the full layer stack.
+ * Use **canvas capture** for the rendered image on screen: PNG, JPEG, WebP,
+ * GIF, and video preserve compositing, filters, shaders, and post-processing.
+ * Use **layer data export** when the artwork should stay editable or machine
+ * readable: TXT and SVG read from the selected layer, while JSON can describe
+ * either the selected layer or the full layer stack.
  *
  * Start with {@link ExportPlugin}, then call the helpers added to your sketch
  * or use the built-in export overlay. For recipes and format trade-offs, read
  * the [Exporting guide](/docs/exporting).
+ *
+ * @categoryDescription Workflow
+ * Install the plugin and use the export helpers added to a textmode.js sketch.
+ *
+ * @categoryDescription Canvas capture
+ * Export a still image from the rendered canvas.
+ *
+ * @categoryDescription GIF export
+ * Capture deterministic frames and encode an animated GIF.
+ *
+ * @categoryDescription Video export
+ * Capture deterministic frames and encode MP4 or WebM video with Mediabunny.
+ *
+ * @categoryDescription Layer data export
+ * Export selected-layer text or vector data as TXT or SVG.
+ *
+ * @categoryDescription JSON document data
+ * Export selected-layer or full-stack document data as JSON.
+ *
+ * @categoryDescription Overlay
+ * Configure and control the built-in export overlay.
+ *
+ * @showCategories
  */
 import type { TextmodePlugin } from 'textmode.js';
 import './augmentations';
@@ -24,7 +47,7 @@ export type { SVGExportOptions } from './exporters/svg';
 export type { TXTExportOptions } from './exporters/txt';
 export type { JSONExportColorMode, JSONExportOptions, JSONExportTarget, TextmodeDocumentJSON } from './exporters/json';
 export type { GIFExportOptions, GIFExportProgress } from './exporters/gif';
-export type { VideoBitrateMode, VideoBitratePreset, VideoContentHint, VideoExportFormat, VideoExportOptions, VideoExportPhase, VideoExportProgress, VideoHardwareAcceleration, VideoLatencyMode, VideoRecordingState, } from './exporters/video';
+export type { VideoBitrateMode, VideoExportFormat, VideoExportOptions, VideoExportPhase, VideoExportProgress, VideoHardwareAcceleration, VideoQuality, VideoQualityLevel, VideoSaveDestination, VideoRecordingState, } from './exporters/video';
 export type { LayerExportOptions } from './exporters/base';
 /**
  * Default export plugin instance for the standard textmode.js workflow.

package/dist/types/overlay/blades/VideoBlade.d.ts

@@ -3,11 +3,9 @@ import type { BladeConfig } from './Blade';
 import { Blade } from './Blade';
 export declare class VideoBlade extends Blade<VideoExportOptions> {
     private formatSelect;
-    private bitrateSelect;
+    private qualitySelect;
     private frameRateInput;
     private frameCountInput;
-    private bitrateModeSelect;
-    private latencyModeSelect;
     private hardwareAccelerationSelect;
     private keyFrameIntervalInput;
     private transparencyInput;
@@ -27,13 +25,12 @@ export declare class VideoBlade extends Blade<VideoExportOptions> {
     private syncStatus;
     private resolvePlannedFrameCount;
     private applyDefaults;
-    private resolveBitratePreset;
-    private readonly handleBitrateChange;
+    private resolveQuality;
+    private readonly handleQualityChange;
     private readonly handleEstimateChange;
     private syncReadyStatus;
     private readonly handleFormatChange;
     private syncOutputEstimate;
-    private formatBytes;
     protected _onUnmount(): void;
     private syncTransparencyAvailability;
 }

package/dist/types/overlay/types.d.ts

@@ -2,7 +2,7 @@ import type { ImageExportOptions } from '../exporters/image';
 import type { TXTExportOptions } from '../exporters/txt';
 import type { SVGExportOptions } from '../exporters/svg';
 import type { GIFExportOptions } from '../exporters/gif';
-import type { VideoBitratePreset, VideoExportOptions } from '../exporters/video';
+import type { VideoExportOptions } from '../exporters/video';
 import type { JSONExportOptions } from '../exporters/json';
 export type ExportFormat = 'txt' | 'json' | 'image' | 'gif' | 'video' | 'svg';
 export type ExportOptionsMap = {
@@ -18,9 +18,7 @@ export type JSONOverlayDefaults = Pick<JSONExportOptions, 'target' | 'pretty' |
 export type ImageOverlayDefaults = Pick<ImageExportOptions, 'format' | 'scale'>;
 export type SVGOverlayDefaults = Pick<SVGExportOptions, 'includeBackgroundRectangles' | 'drawMode' | 'strokeWidth'>;
 export type GIFOverlayDefaults = Pick<GIFExportOptions, 'frameCount' | 'frameRate' | 'scale' | 'repeat'>;
-export type VideoOverlayDefaults = Pick<VideoExportOptions, 'format' | 'frameCount' | 'frameRate' | 'bitrateMode' | 'latencyMode' | 'hardwareAcceleration' | 'keyFrameInterval' | 'transparent'> & {
-    bitrate?: VideoBitratePreset;
-};
+export type VideoOverlayDefaults = Pick<VideoExportOptions, 'format' | 'frameCount' | 'frameRate' | 'quality' | 'hardwareAcceleration' | 'keyFrameInterval' | 'transparent'>;
 /**
  * Curated default options for every export format.
  *

package/dist/types/types.d.ts

@@ -2,7 +2,7 @@ import type { ImageExportOptions } from './exporters/image';
 import type { TXTExportOptions } from './exporters/txt';
 import type { SVGExportOptions } from './exporters/svg';
 import type { GIFExportOptions } from './exporters/gif';
-import type { VideoBitratePreset, VideoExportOptions } from './exporters/video';
+import type { VideoExportOptions } from './exporters/video';
 import type { JSONExportOptions, TextmodeDocumentJSON } from './exporters/json';
 /**
  * Default TXT export fields controlled by the export overlay.
@@ -51,9 +51,7 @@ export type GIFOverlayDefaults = Pick<GIFExportOptions, 'frameCount' | 'frameRat
  *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoOverlayDefaults | VideoOverlayDefaults API reference}
  */
-export type VideoOverlayDefaults = Pick<VideoExportOptions, 'format' | 'frameCount' | 'frameRate' | 'bitrateMode' | 'latencyMode' | 'hardwareAcceleration' | 'keyFrameInterval' | 'transparent'> & {
-    bitrate?: VideoBitratePreset;
-};
+export type VideoOverlayDefaults = Pick<VideoExportOptions, 'format' | 'frameCount' | 'frameRate' | 'quality' | 'hardwareAcceleration' | 'keyFrameInterval' | 'transparent'>;
 /**
  * Per-format default options used to seed the overlay UI inputs at mount time
  * and after a {@link ExportOverlayController.resetDefaults} call.
@@ -463,15 +461,29 @@ export interface TextmodeExportAPI {
      *
      * @example
      * ```ts
-     * await t.saveVideo({ frameCount: 240, frameRate: 60, filename: 'capture' });
+     * // Mediabunny's qualitative quality levels produce content-dependent file sizes.
      * await t.saveVideo({
      *     format: 'webm',
-     *     bitrate: 'high',
-     *     bitrateMode: 'variable',
-     *     latencyMode: 'quality',
-     *     keyFrameInterval: 2,
+     *     quality: 'very-high',
+     *     frameCount: 240,
+     *     frameRate: 60,
+     *     filename: 'high-quality-capture',
+     * });
+     *
+     * // Request a target bitrate and rate-control mode.
+     * await t.saveVideo({
+     *     quality: { bitrate: 8_000_000, bitrateMode: 'variable' },
      *     frameCount: 240,
-     *     filename: 'capture',
+     *     frameRate: 60,
+     *     filename: 'target-bitrate-capture',
+     * });
+     *
+     * // Stream directly to a user-selected file when the browser supports it.
+     * await t.saveVideo({
+     *     destination: 'file-system',
+     *     quality: 'high',
+     *     frameCount: 240,
+     *     frameRate: 60,
      * });
      * ```
      *
@@ -479,7 +491,9 @@ export interface TextmodeExportAPI {
      */
     saveVideo(options?: VideoExportOptions): Promise<void>;
     /**
-     * Generates a video blob without downloading it.
+     * Generates an in-memory video blob without downloading it.
+     *
+     * `destination` is only used by {@link saveVideo}; this method always buffers and returns a `Blob`.
      *
      * @example
      * ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "textmode.export.js",
-	"version": "1.8.0",
+	"version": "1.8.1",
 	"description": "Export plugin for textmode.js - Save your creations as images, GIFs, videos, SVG, JSON, and plain text.",
 	"type": "module",
 	"devEngines": {
@@ -64,7 +64,7 @@
 	},
 	"dependencies": {
 		"gifenc": "^1.0.1",
-		"mediabunny": "^1.52.3"
+		"mediabunny": "1.55.2"
 	},
 	"devDependencies": {
 		"@textmode/build": "^0.1.0",