@bowenqt/qiniu-ai-sdk 0.19.1 → 0.20.0

package/dist/lib/vframe.mjs

@@ -0,0 +1,181 @@
+/**
+ * Video Frame Extraction using Qiniu vframe API.
+ *
+ * @see https://developer.qiniu.com/dora/1313/video-frame-thumbnails-vframe
+ */
+import { resolveAsset } from './asset-resolver.mjs';
+// ============================================================================
+// Constants
+// ============================================================================
+const DEFAULT_COUNT = 5;
+const DEFAULT_WIDTH = 640;
+const DEFAULT_FORMAT = 'jpg';
+const MIN_DIMENSION = 20;
+const MAX_LONG_EDGE = 3840;
+const MAX_SHORT_EDGE = 2160;
+// ============================================================================
+// Errors
+// ============================================================================
+export class VframeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'VframeError';
+    }
+}
+// ============================================================================
+// URL Building
+// ============================================================================
+/**
+ * Build a vframe fop command.
+ *
+ * @example
+ * ```typescript
+ * buildVframeFop(5, { width: 320, format: 'jpg' });
+ * // 'vframe/jpg/offset/5/w/320'
+ * ```
+ */
+export function buildVframeFop(offset, options = {}) {
+    if (offset < 0) {
+        throw new VframeError('Offset must be non-negative');
+    }
+    const format = options.format ?? DEFAULT_FORMAT;
+    const parts = [`vframe/${format}/offset/${offset}`];
+    // Width
+    if (options.width !== undefined) {
+        if (options.width < MIN_DIMENSION || options.width > MAX_LONG_EDGE) {
+            throw new VframeError(`Width must be between ${MIN_DIMENSION} and ${MAX_LONG_EDGE}`);
+        }
+        parts.push(`w/${options.width}`);
+    }
+    // Height
+    if (options.height !== undefined) {
+        if (options.height < MIN_DIMENSION || options.height > MAX_SHORT_EDGE) {
+            throw new VframeError(`Height must be between ${MIN_DIMENSION} and ${MAX_SHORT_EDGE}`);
+        }
+        parts.push(`h/${options.height}`);
+    }
+    // Rotate
+    if (options.rotate !== undefined) {
+        parts.push(`rotate/${options.rotate}`);
+    }
+    return parts.join('/');
+}
+/**
+ * Build a complete vframe URL from a base URL.
+ *
+ * @example
+ * ```typescript
+ * buildVframeUrl('https://cdn.example.com/video.mp4', 5, { width: 320 });
+ * // 'https://cdn.example.com/video.mp4?vframe/jpg/offset/5/w/320'
+ * ```
+ */
+export function buildVframeUrl(baseUrl, offset, options = {}) {
+    const fop = buildVframeFop(offset, options);
+    const separator = baseUrl.includes('?') ? '|' : '?';
+    return `${baseUrl}${separator}${fop}`;
+}
+// ============================================================================
+// Frame Extraction
+// ============================================================================
+/**
+ * Calculate uniform offsets for frame extraction.
+ */
+function calculateUniformOffsets(count, duration) {
+    if (count <= 0) {
+        throw new VframeError('Count must be positive');
+    }
+    if (duration <= 0) {
+        throw new VframeError('Duration must be positive');
+    }
+    if (count === 1) {
+        return [duration / 2];
+    }
+    const offsets = [];
+    const step = duration / (count + 1);
+    for (let i = 1; i <= count; i++) {
+        offsets.push(Math.round(step * i * 100) / 100);
+    }
+    return offsets;
+}
+/**
+ * Extract frames from a video.
+ *
+ * @example Uniform extraction
+ * ```typescript
+ * const result = await extractFrames(asset, signer, {
+ *     count: 5,
+ *     duration: 120,  // 2 minute video
+ *     width: 640,
+ * });
+ * // Frames at: 20s, 40s, 60s, 80s, 100s
+ * ```
+ *
+ * @example Explicit offsets
+ * ```typescript
+ * const result = await extractFrames(asset, signer, {
+ *     offsets: [0, 30, 60, 90],
+ *     width: 640,
+ * });
+ * ```
+ */
+export async function extractFrames(asset, signer, options, resolveOptions) {
+    // Validate options
+    if (options.offsets && options.count) {
+        throw new VframeError('Cannot specify both offsets and count');
+    }
+    let offsets;
+    if (options.offsets) {
+        // Explicit offsets mode
+        offsets = options.offsets;
+        for (const offset of offsets) {
+            if (offset < 0) {
+                throw new VframeError('All offsets must be non-negative');
+            }
+        }
+    }
+    else {
+        // Uniform extraction mode
+        const count = options.count ?? DEFAULT_COUNT;
+        if (!options.duration) {
+            throw new VframeError('Duration is required for uniform extraction');
+        }
+        offsets = calculateUniformOffsets(count, options.duration);
+    }
+    // Build frame extraction options
+    const frameOpts = {
+        width: options.width ?? DEFAULT_WIDTH,
+        height: options.height,
+        format: options.format ?? DEFAULT_FORMAT,
+        rotate: options.rotate,
+    };
+    // Extract frames in parallel
+    const frames = await Promise.all(offsets.map(async (offset, index) => {
+        const fop = buildVframeFop(offset, frameOpts);
+        const resolved = await resolveAsset(asset, signer, {
+            ...resolveOptions,
+            fop,
+        });
+        return {
+            url: resolved.url,
+            expiresAt: resolved.expiresAt,
+            offset,
+            index,
+        };
+    }));
+    return {
+        frames,
+        count: frames.length,
+        duration: options.duration,
+    };
+}
+/**
+ * Extract a single frame at a specific offset.
+ */
+export async function extractFrame(asset, signer, offset, options = {}, resolveOptions) {
+    const result = await extractFrames(asset, signer, {
+        offsets: [offset],
+        ...options,
+    }, resolveOptions);
+    return result.frames[0];
+}
+//# sourceMappingURL=vframe.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bowenqt/qiniu-ai-sdk",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "TypeScript SDK for Qiniu Cloud AI Token API - Chat, Image, Video generation and more",
   "main": "dist/index.js",
   "module": "dist/index.mjs",