divoom-timesgate-sdk 0.1.0

package/dist/image/index.d.cts

@@ -0,0 +1,279 @@
+import { Sharp } from 'sharp';
+import { F as FetchLike, P as PanelIndex } from '../common-D8oHDNi6.cjs';
+
+/**
+ * Types for the image pipeline (`divoom-timesgate-sdk/image`).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Anything the image helpers can turn into a panel frame:
+ * - a file path (`"./cover.png"`),
+ * - an `http(s)` URL (downloaded automatically),
+ * - raw encoded bytes (`Buffer` / `Uint8Array`), or
+ * - an existing `sharp` pipeline.
+ */
+type ImageSource = string | Buffer | Uint8Array | Sharp;
+/** Output encoding for a panel frame. */
+type EncodedFormat = 'jpeg' | 'png';
+/** Resize strategies, mirroring sharp's `fit` options. */
+type ResizeFit = 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+/** A fully-encoded frame, ready to hand to the device's draw commands. */
+interface EncodedFrame {
+    /**
+     * Base64-encoded image data — drop this straight into the `picData`
+     * argument of {@link DrawCommands.sendImage} (the device's `PicData` field).
+     */
+    data: string;
+    /** The raw encoded bytes. */
+    buffer: Buffer;
+    /** The container format the bytes are encoded in. */
+    format: EncodedFormat;
+    /** Frame width in pixels (square frames: equal to {@link EncodedFrame.height}). */
+    width: number;
+    /** Frame height in pixels. */
+    height: number;
+}
+/** Common encoding options shared by most image helpers. */
+interface EncodeOptions {
+    /** Output edge length in pixels. Defaults to `128` (one panel). */
+    size?: number;
+    /** Output format. Defaults to `"jpeg"` (smaller, what the device expects). */
+    format?: EncodedFormat;
+    /** JPEG quality, `1`–`100`. Defaults to `95`. */
+    quality?: number;
+    /** JPEG chroma subsampling. Defaults to `"4:4:4"` for crisp edges. */
+    chromaSubsampling?: string;
+    /** Background used when flattening transparency for JPEG. Defaults to black. */
+    background?: string;
+}
+/** Options for {@link encodePanel}. */
+interface EncodePanelOptions extends EncodeOptions {
+    /** How the source is fitted into the square frame. Defaults to `"cover"`. */
+    fit?: ResizeFit;
+    /** Resampling kernel. Defaults to `"lanczos3"` for the sharpest downscale. */
+    kernel?: 'nearest' | 'cubic' | 'mitchell' | 'lanczos2' | 'lanczos3';
+}
+
+/**
+ * Turns any {@link ImageSource} into a `sharp` pipeline.
+ *
+ * @remarks
+ * **Trust model.** A `string` source is treated as an `http(s)` URL when it
+ * starts with that scheme, and otherwise as a **local file path**. Do not pass
+ * untrusted/attacker-influenced strings here: a URL can trigger a server-side
+ * request (SSRF) and a path can read arbitrary local files. URL downloads are
+ * bounded by a timeout and a maximum size, but callers handling untrusted input
+ * should validate/allowlist the source themselves (and prefer passing a
+ * `Buffer` you fetched under your own controls).
+ *
+ * @packageDocumentation
+ */
+
+/** Options controlling how URL image sources are downloaded. */
+interface LoadImageOptions {
+    /** Per-download timeout in milliseconds (URL sources only). Defaults to `15000`. */
+    timeoutMs?: number;
+    /** Maximum bytes to download before aborting (URL sources only). Defaults to 64 MiB. */
+    maxBytes?: number;
+    /** A custom `fetch` for URL sources. Defaults to the global `fetch`. */
+    fetch?: FetchLike;
+}
+/**
+ * Resolves an {@link ImageSource} to a `sharp` pipeline. Existing pipelines are
+ * cloned so callers can reuse the original safely.
+ *
+ * @param source - A file path, an `http(s)` URL, raw bytes, or a `sharp` instance.
+ *   See the module-level note on the URL/path trust model before passing
+ *   untrusted input.
+ * @param options - Download controls for URL sources (timeout, size cap, fetch).
+ * @throws {@link DivoomValidationError} for unsupported sources or oversized downloads.
+ * @throws {@link DivoomConnectionError} when a URL cannot be downloaded.
+ * @throws {@link DivoomTimeoutError} when a download exceeds `timeoutMs`.
+ */
+declare function loadImage(source: ImageSource, options?: LoadImageOptions): Promise<Sharp>;
+
+/**
+ * Frame encoding: resize-and-encode any source to a panel-ready
+ * {@link EncodedFrame}, plus a helper for solid-color frames.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Encodes an already-sized `sharp` pipeline into an {@link EncodedFrame},
+ * applying the SDK's default high-quality JPEG settings (q95, 4:4:4 chroma).
+ *
+ * @internal Shared by the higher-level helpers; exported for advanced use.
+ */
+declare function finalizeFrame(pipeline: Sharp, options: EncodeOptions & {
+    size: number;
+}): Promise<EncodedFrame>;
+/**
+ * Resizes and encodes any {@link ImageSource} into a single square panel frame.
+ *
+ * @example
+ * ```ts
+ * const frame = await encodePanel('./album.jpg'); // 128×128 JPEG, q95
+ * await client.draw.sendImage(0, frame.data);
+ * ```
+ */
+declare function encodePanel(source: ImageSource, options?: EncodePanelOptions): Promise<EncodedFrame>;
+/**
+ * Produces a solid-color panel frame — handy for clearing a panel or showing a
+ * status color.
+ *
+ * @example
+ * ```ts
+ * await client.draw.sendImage(1, (await solidFrame('#000000')).data); // blank
+ * ```
+ */
+declare function solidFrame(color: string, options?: EncodeOptions): Promise<EncodedFrame>;
+
+/**
+ * Color helpers: hex⇄RGB conversion, mixing, and accent extraction from
+ * artwork (used to tint the now-playing panels).
+ *
+ * @packageDocumentation
+ */
+
+/** An `[r, g, b]` triple with each channel in `0`–`255`. */
+type Rgb = [number, number, number];
+/** Parses a `#RGB` or `#RRGGBB` hex string into an {@link Rgb} triple. */
+declare function hexToRgb(hex: string): Rgb;
+/** Formats an {@link Rgb} triple as an uppercase `#RRGGBB` string. */
+declare function rgbToHex([r, g, b]: Rgb): string;
+/** Linearly interpolates between two colors (`t` in `0`–`1`). */
+declare function mixRgb(a: Rgb, b: Rgb, t: number): Rgb;
+/** Scales every channel of a color by `factor`. */
+declare function scaleRgb([r, g, b]: Rgb, factor: number): Rgb;
+/**
+ * Extracts a vivid accent color from artwork — the most saturated reasonably
+ * bright pixel — for tinting backgrounds and progress bars. Mirrors the proven
+ * heuristic from the reference now-playing app.
+ *
+ * @param source - The artwork to sample.
+ * @param fallback - Returned when no saturated pixel is found. Defaults to
+ *   Spotify green (`#1DB954`).
+ */
+declare function getAccentColor(source: ImageSource, fallback?: string): Promise<string>;
+
+/**
+ * Album-art styling — the two looks from the reference now-playing app:
+ * a crisp "smooth" treatment and a chunky "pixel" treatment.
+ *
+ * @packageDocumentation
+ */
+
+/** Visual treatment applied by {@link prepareAlbumArt}. */
+type AlbumArtStyle = 'smooth' | 'pixel';
+/** Options for {@link prepareAlbumArt}. */
+interface PrepareAlbumArtOptions extends EncodeOptions {
+    /**
+     * `"smooth"` (default) gently boosts saturation/contrast and unsharp-masks for
+     * a clean look; `"pixel"` downsamples to 32×32 nearest-neighbour for a retro,
+     * blocky aesthetic.
+     */
+    style?: AlbumArtStyle;
+}
+/**
+ * Prepares album/cover artwork for a panel, matching the look of the reference
+ * Spotify app.
+ *
+ * @example
+ * ```ts
+ * const art = await prepareAlbumArt(coverUrl, { style: 'smooth' });
+ * await client.draw.sendImage(0, art.data);
+ * ```
+ */
+declare function prepareAlbumArt(source: ImageSource, options?: PrepareAlbumArtOptions): Promise<EncodedFrame>;
+
+/**
+ * Split one image across several panels to create a single wide (or tall)
+ * canvas spanning the Times Gate.
+ *
+ * @packageDocumentation
+ */
+
+/** A frame paired with the panel it belongs on. */
+interface PanelFrame {
+    /** The target panel index. */
+    panel: PanelIndex;
+    /** The encoded frame for that panel. */
+    frame: EncodedFrame;
+}
+/** Options for {@link splitImageAcrossPanels}. */
+interface SplitOptions extends EncodeOptions {
+    /** Panels to span, in visual order. Defaults to all five (`[0,1,2,3,4]`). */
+    panels?: PanelIndex[];
+    /**
+     * `"horizontal"` (default) lays the image out left-to-right across panels;
+     * `"vertical"` stacks top-to-bottom.
+     */
+    layout?: 'horizontal' | 'vertical';
+}
+/**
+ * Slices a single image into one square frame per panel, so a panorama spans
+ * the whole device.
+ *
+ * @example
+ * ```ts
+ * const tiles = await splitImageAcrossPanels('./wide-banner.png');
+ * for (const { panel, frame } of tiles) {
+ *   await client.draw.sendImage(panel, frame.data);
+ * }
+ * ```
+ */
+declare function splitImageAcrossPanels(source: ImageSource, options?: SplitOptions): Promise<PanelFrame[]>;
+
+/**
+ * Renders a designed "now-playing"-style text panel: a tinted gradient
+ * background, an optional eyebrow with a play glyph, an auto-fitted title, a
+ * subtitle, and an optional progress bar. Text is rendered with Pango (via
+ * sharp) for crisp, properly-wrapped output that doesn't depend on the host's
+ * system fonts the way the original Python reference did.
+ *
+ * @packageDocumentation
+ */
+
+/** Options for {@link renderTextPanel}. */
+interface RenderTextPanelOptions extends EncodeOptions {
+    /** The headline text (e.g. a track title). Auto-sized to fit. */
+    title: string;
+    /** Secondary text below the title (e.g. an artist). Optional. */
+    subtitle?: string;
+    /** Small uppercase label above the title (e.g. `"NOW PLAYING"`). Optional. */
+    eyebrow?: string;
+    /** Accent color (hex) used for the tint, eyebrow, subtitle and bar. Defaults to `#1DB954`. */
+    accent?: string;
+    /** Progress fraction `0`–`1`. When set, a progress bar is drawn. */
+    progress?: number;
+    /**
+     * Background style: `"gradient"` (default, an accent-tinted vertical fade),
+     * `"solid"` (a flat accent), or any hex string for a custom flat color.
+     */
+    background?: 'gradient' | 'solid' | string;
+    /** Pango font family. Defaults to `"DejaVu Sans"`. */
+    font?: string;
+}
+/**
+ * Renders a designed now-playing-style panel and returns an
+ * {@link EncodedFrame} ready for a panel. Overly long titles/subtitles are
+ * shrunk to fit rather than overflowing the panel.
+ *
+ * @example
+ * ```ts
+ * const panel = await renderTextPanel({
+ *   eyebrow: 'Now Playing',
+ *   title: 'Bohemian Rhapsody',
+ *   subtitle: 'Queen',
+ *   accent: '#E94F37',
+ *   progress: 0.42,
+ * });
+ * await client.draw.sendImage(1, panel.data);
+ * ```
+ */
+declare function renderTextPanel(options: RenderTextPanelOptions): Promise<EncodedFrame>;
+
+export { type AlbumArtStyle, type EncodeOptions, type EncodePanelOptions, type EncodedFormat, type EncodedFrame, type ImageSource, type LoadImageOptions, type PanelFrame, type PrepareAlbumArtOptions, type RenderTextPanelOptions, type ResizeFit, type Rgb, type SplitOptions, encodePanel, finalizeFrame, getAccentColor, hexToRgb, loadImage, mixRgb, prepareAlbumArt, renderTextPanel, rgbToHex, scaleRgb, solidFrame, splitImageAcrossPanels };

package/dist/image/index.d.ts

@@ -0,0 +1,279 @@
+import { Sharp } from 'sharp';
+import { F as FetchLike, P as PanelIndex } from '../common-D8oHDNi6.js';
+
+/**
+ * Types for the image pipeline (`divoom-timesgate-sdk/image`).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Anything the image helpers can turn into a panel frame:
+ * - a file path (`"./cover.png"`),
+ * - an `http(s)` URL (downloaded automatically),
+ * - raw encoded bytes (`Buffer` / `Uint8Array`), or
+ * - an existing `sharp` pipeline.
+ */
+type ImageSource = string | Buffer | Uint8Array | Sharp;
+/** Output encoding for a panel frame. */
+type EncodedFormat = 'jpeg' | 'png';
+/** Resize strategies, mirroring sharp's `fit` options. */
+type ResizeFit = 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+/** A fully-encoded frame, ready to hand to the device's draw commands. */
+interface EncodedFrame {
+    /**
+     * Base64-encoded image data — drop this straight into the `picData`
+     * argument of {@link DrawCommands.sendImage} (the device's `PicData` field).
+     */
+    data: string;
+    /** The raw encoded bytes. */
+    buffer: Buffer;
+    /** The container format the bytes are encoded in. */
+    format: EncodedFormat;
+    /** Frame width in pixels (square frames: equal to {@link EncodedFrame.height}). */
+    width: number;
+    /** Frame height in pixels. */
+    height: number;
+}
+/** Common encoding options shared by most image helpers. */
+interface EncodeOptions {
+    /** Output edge length in pixels. Defaults to `128` (one panel). */
+    size?: number;
+    /** Output format. Defaults to `"jpeg"` (smaller, what the device expects). */
+    format?: EncodedFormat;
+    /** JPEG quality, `1`–`100`. Defaults to `95`. */
+    quality?: number;
+    /** JPEG chroma subsampling. Defaults to `"4:4:4"` for crisp edges. */
+    chromaSubsampling?: string;
+    /** Background used when flattening transparency for JPEG. Defaults to black. */
+    background?: string;
+}
+/** Options for {@link encodePanel}. */
+interface EncodePanelOptions extends EncodeOptions {
+    /** How the source is fitted into the square frame. Defaults to `"cover"`. */
+    fit?: ResizeFit;
+    /** Resampling kernel. Defaults to `"lanczos3"` for the sharpest downscale. */
+    kernel?: 'nearest' | 'cubic' | 'mitchell' | 'lanczos2' | 'lanczos3';
+}
+
+/**
+ * Turns any {@link ImageSource} into a `sharp` pipeline.
+ *
+ * @remarks
+ * **Trust model.** A `string` source is treated as an `http(s)` URL when it
+ * starts with that scheme, and otherwise as a **local file path**. Do not pass
+ * untrusted/attacker-influenced strings here: a URL can trigger a server-side
+ * request (SSRF) and a path can read arbitrary local files. URL downloads are
+ * bounded by a timeout and a maximum size, but callers handling untrusted input
+ * should validate/allowlist the source themselves (and prefer passing a
+ * `Buffer` you fetched under your own controls).
+ *
+ * @packageDocumentation
+ */
+
+/** Options controlling how URL image sources are downloaded. */
+interface LoadImageOptions {
+    /** Per-download timeout in milliseconds (URL sources only). Defaults to `15000`. */
+    timeoutMs?: number;
+    /** Maximum bytes to download before aborting (URL sources only). Defaults to 64 MiB. */
+    maxBytes?: number;
+    /** A custom `fetch` for URL sources. Defaults to the global `fetch`. */
+    fetch?: FetchLike;
+}
+/**
+ * Resolves an {@link ImageSource} to a `sharp` pipeline. Existing pipelines are
+ * cloned so callers can reuse the original safely.
+ *
+ * @param source - A file path, an `http(s)` URL, raw bytes, or a `sharp` instance.
+ *   See the module-level note on the URL/path trust model before passing
+ *   untrusted input.
+ * @param options - Download controls for URL sources (timeout, size cap, fetch).
+ * @throws {@link DivoomValidationError} for unsupported sources or oversized downloads.
+ * @throws {@link DivoomConnectionError} when a URL cannot be downloaded.
+ * @throws {@link DivoomTimeoutError} when a download exceeds `timeoutMs`.
+ */
+declare function loadImage(source: ImageSource, options?: LoadImageOptions): Promise<Sharp>;
+
+/**
+ * Frame encoding: resize-and-encode any source to a panel-ready
+ * {@link EncodedFrame}, plus a helper for solid-color frames.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Encodes an already-sized `sharp` pipeline into an {@link EncodedFrame},
+ * applying the SDK's default high-quality JPEG settings (q95, 4:4:4 chroma).
+ *
+ * @internal Shared by the higher-level helpers; exported for advanced use.
+ */
+declare function finalizeFrame(pipeline: Sharp, options: EncodeOptions & {
+    size: number;
+}): Promise<EncodedFrame>;
+/**
+ * Resizes and encodes any {@link ImageSource} into a single square panel frame.
+ *
+ * @example
+ * ```ts
+ * const frame = await encodePanel('./album.jpg'); // 128×128 JPEG, q95
+ * await client.draw.sendImage(0, frame.data);
+ * ```
+ */
+declare function encodePanel(source: ImageSource, options?: EncodePanelOptions): Promise<EncodedFrame>;
+/**
+ * Produces a solid-color panel frame — handy for clearing a panel or showing a
+ * status color.
+ *
+ * @example
+ * ```ts
+ * await client.draw.sendImage(1, (await solidFrame('#000000')).data); // blank
+ * ```
+ */
+declare function solidFrame(color: string, options?: EncodeOptions): Promise<EncodedFrame>;
+
+/**
+ * Color helpers: hex⇄RGB conversion, mixing, and accent extraction from
+ * artwork (used to tint the now-playing panels).
+ *
+ * @packageDocumentation
+ */
+
+/** An `[r, g, b]` triple with each channel in `0`–`255`. */
+type Rgb = [number, number, number];
+/** Parses a `#RGB` or `#RRGGBB` hex string into an {@link Rgb} triple. */
+declare function hexToRgb(hex: string): Rgb;
+/** Formats an {@link Rgb} triple as an uppercase `#RRGGBB` string. */
+declare function rgbToHex([r, g, b]: Rgb): string;
+/** Linearly interpolates between two colors (`t` in `0`–`1`). */
+declare function mixRgb(a: Rgb, b: Rgb, t: number): Rgb;
+/** Scales every channel of a color by `factor`. */
+declare function scaleRgb([r, g, b]: Rgb, factor: number): Rgb;
+/**
+ * Extracts a vivid accent color from artwork — the most saturated reasonably
+ * bright pixel — for tinting backgrounds and progress bars. Mirrors the proven
+ * heuristic from the reference now-playing app.
+ *
+ * @param source - The artwork to sample.
+ * @param fallback - Returned when no saturated pixel is found. Defaults to
+ *   Spotify green (`#1DB954`).
+ */
+declare function getAccentColor(source: ImageSource, fallback?: string): Promise<string>;
+
+/**
+ * Album-art styling — the two looks from the reference now-playing app:
+ * a crisp "smooth" treatment and a chunky "pixel" treatment.
+ *
+ * @packageDocumentation
+ */
+
+/** Visual treatment applied by {@link prepareAlbumArt}. */
+type AlbumArtStyle = 'smooth' | 'pixel';
+/** Options for {@link prepareAlbumArt}. */
+interface PrepareAlbumArtOptions extends EncodeOptions {
+    /**
+     * `"smooth"` (default) gently boosts saturation/contrast and unsharp-masks for
+     * a clean look; `"pixel"` downsamples to 32×32 nearest-neighbour for a retro,
+     * blocky aesthetic.
+     */
+    style?: AlbumArtStyle;
+}
+/**
+ * Prepares album/cover artwork for a panel, matching the look of the reference
+ * Spotify app.
+ *
+ * @example
+ * ```ts
+ * const art = await prepareAlbumArt(coverUrl, { style: 'smooth' });
+ * await client.draw.sendImage(0, art.data);
+ * ```
+ */
+declare function prepareAlbumArt(source: ImageSource, options?: PrepareAlbumArtOptions): Promise<EncodedFrame>;
+
+/**
+ * Split one image across several panels to create a single wide (or tall)
+ * canvas spanning the Times Gate.
+ *
+ * @packageDocumentation
+ */
+
+/** A frame paired with the panel it belongs on. */
+interface PanelFrame {
+    /** The target panel index. */
+    panel: PanelIndex;
+    /** The encoded frame for that panel. */
+    frame: EncodedFrame;
+}
+/** Options for {@link splitImageAcrossPanels}. */
+interface SplitOptions extends EncodeOptions {
+    /** Panels to span, in visual order. Defaults to all five (`[0,1,2,3,4]`). */
+    panels?: PanelIndex[];
+    /**
+     * `"horizontal"` (default) lays the image out left-to-right across panels;
+     * `"vertical"` stacks top-to-bottom.
+     */
+    layout?: 'horizontal' | 'vertical';
+}
+/**
+ * Slices a single image into one square frame per panel, so a panorama spans
+ * the whole device.
+ *
+ * @example
+ * ```ts
+ * const tiles = await splitImageAcrossPanels('./wide-banner.png');
+ * for (const { panel, frame } of tiles) {
+ *   await client.draw.sendImage(panel, frame.data);
+ * }
+ * ```
+ */
+declare function splitImageAcrossPanels(source: ImageSource, options?: SplitOptions): Promise<PanelFrame[]>;
+
+/**
+ * Renders a designed "now-playing"-style text panel: a tinted gradient
+ * background, an optional eyebrow with a play glyph, an auto-fitted title, a
+ * subtitle, and an optional progress bar. Text is rendered with Pango (via
+ * sharp) for crisp, properly-wrapped output that doesn't depend on the host's
+ * system fonts the way the original Python reference did.
+ *
+ * @packageDocumentation
+ */
+
+/** Options for {@link renderTextPanel}. */
+interface RenderTextPanelOptions extends EncodeOptions {
+    /** The headline text (e.g. a track title). Auto-sized to fit. */
+    title: string;
+    /** Secondary text below the title (e.g. an artist). Optional. */
+    subtitle?: string;
+    /** Small uppercase label above the title (e.g. `"NOW PLAYING"`). Optional. */
+    eyebrow?: string;
+    /** Accent color (hex) used for the tint, eyebrow, subtitle and bar. Defaults to `#1DB954`. */
+    accent?: string;
+    /** Progress fraction `0`–`1`. When set, a progress bar is drawn. */
+    progress?: number;
+    /**
+     * Background style: `"gradient"` (default, an accent-tinted vertical fade),
+     * `"solid"` (a flat accent), or any hex string for a custom flat color.
+     */
+    background?: 'gradient' | 'solid' | string;
+    /** Pango font family. Defaults to `"DejaVu Sans"`. */
+    font?: string;
+}
+/**
+ * Renders a designed now-playing-style panel and returns an
+ * {@link EncodedFrame} ready for a panel. Overly long titles/subtitles are
+ * shrunk to fit rather than overflowing the panel.
+ *
+ * @example
+ * ```ts
+ * const panel = await renderTextPanel({
+ *   eyebrow: 'Now Playing',
+ *   title: 'Bohemian Rhapsody',
+ *   subtitle: 'Queen',
+ *   accent: '#E94F37',
+ *   progress: 0.42,
+ * });
+ * await client.draw.sendImage(1, panel.data);
+ * ```
+ */
+declare function renderTextPanel(options: RenderTextPanelOptions): Promise<EncodedFrame>;
+
+export { type AlbumArtStyle, type EncodeOptions, type EncodePanelOptions, type EncodedFormat, type EncodedFrame, type ImageSource, type LoadImageOptions, type PanelFrame, type PrepareAlbumArtOptions, type RenderTextPanelOptions, type ResizeFit, type Rgb, type SplitOptions, encodePanel, finalizeFrame, getAccentColor, hexToRgb, loadImage, mixRgb, prepareAlbumArt, renderTextPanel, rgbToHex, scaleRgb, solidFrame, splitImageAcrossPanels };