@xiping/node-utils 1.0.38 → 1.0.39

package/lib/index.d.ts

@@ -2,3 +2,5 @@ export * from "./src/directory-tree.js";
 export * from "./src/path-utils.js";
 export * from "./src/srt-to-vtt/index.js";
 export * from "./src/ffmpeg/index.js";
+export * from "./src/file/getFileConfig.js";
+export * from "./src/image/index.js";

package/lib/index.js

@@ -6,3 +6,7 @@ export * from "./src/path-utils.js";
 export * from "./src/srt-to-vtt/index.js";
 // FFmpeg相关功能
 export * from "./src/ffmpeg/index.js";
+// 文件操作相关功能
+export * from "./src/file/getFileConfig.js";
+// 图片处理相关功能
+export * from "./src/image/index.js";

package/lib/src/ffmpeg/cutVideo.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 视频截取器
+ * 使用 ffmpeg 截取视频的一部分，保持原视频编码和质量
+ */
+interface CutVideoOptions {
+    startTime?: string;
+    duration?: string;
+    endTime?: string;
+    outputFileName?: string;
+    outputFormat?: string;
+    tempDir?: string;
+    overwrite?: boolean;
+}
+interface CutVideoResult {
+    outputPath: string;
+    metadata: {
+        originalDuration: number;
+        cutDuration: number;
+        startTime: string;
+        endTime: string;
+        fileSize: number;
+        processingTime: number;
+    };
+}
+export declare const cutVideo: (videoPath: string, options?: CutVideoOptions) => Promise<CutVideoResult>;
+export declare const cutVideoByTimeRange: (videoPath: string, startTime: string, endTime: string, options?: Omit<CutVideoOptions, "startTime" | "endTime">) => Promise<CutVideoResult>;
+export declare const cutVideoByDuration: (videoPath: string, startTime: string, duration: string, options?: Omit<CutVideoOptions, "startTime" | "duration">) => Promise<CutVideoResult>;
+export declare const cutVideoFromStart: (videoPath: string, durationSeconds: number, options?: Omit<CutVideoOptions, "startTime" | "duration">) => Promise<CutVideoResult>;
+export {};

package/lib/src/ffmpeg/cutVideo.js

@@ -0,0 +1,241 @@
+import shell from "shelljs";
+import * as fs from "fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { checkFFmpegAvailability } from "./check.js";
+// 日志函数
+const log = (message, data) => {
+    console.log(`[VideoCutter] ${message}`, data ? JSON.stringify(data, null, 2) : '');
+};
+// 验证和清理路径
+function validateAndSanitizePath(inputPath) {
+    if (!inputPath || typeof inputPath !== 'string') {
+        throw new Error('Invalid path provided');
+    }
+    // 确保是绝对路径
+    if (!path.isAbsolute(inputPath)) {
+        throw new Error('Path must be absolute');
+    }
+    return inputPath;
+}
+// 时间格式转换
+function normalizeTimeFormat(time) {
+    if (typeof time === 'number') {
+        const hours = Math.floor(time / 3600);
+        const minutes = Math.floor((time % 3600) / 60);
+        const seconds = Math.floor(time % 60);
+        return `${hours.toString().padStart(2, '0')}:${minutes.toString().padStart(2, '0')}:${seconds.toString().padStart(2, '0')}`;
+    }
+    // 如果已经是 HH:MM:SS 格式，直接返回
+    if (/^\d{2}:\d{2}:\d{2}$/.test(time)) {
+        return time;
+    }
+    // 如果是秒数，转换为 HH:MM:SS
+    const seconds = parseFloat(time);
+    if (!isNaN(seconds)) {
+        return normalizeTimeFormat(seconds);
+    }
+    throw new Error(`Invalid time format: ${time}`);
+}
+// 获取视频时长
+function getDurationInSeconds(videoPath) {
+    log('Getting video duration', { videoPath });
+    const result = shell.exec(`ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "${videoPath}"`, { silent: true });
+    if (result.code !== 0) {
+        throw new Error(`FFprobe failed to get duration: ${result.stderr}`);
+    }
+    const duration = parseFloat(result.stdout);
+    if (isNaN(duration) || duration <= 0) {
+        throw new Error('Invalid video duration');
+    }
+    return duration;
+}
+// 验证时间参数
+function validateTimeParameters(startTime, duration, endTime, videoDuration) {
+    const startSeconds = timeToSeconds(startTime);
+    if (startSeconds >= videoDuration) {
+        throw new Error(`Start time (${startTime}) is greater than or equal to video duration (${videoDuration}s)`);
+    }
+    let endSeconds;
+    let durationStr;
+    if (endTime) {
+        endSeconds = timeToSeconds(endTime);
+        if (endSeconds <= startSeconds) {
+            throw new Error(`End time (${endTime}) must be greater than start time (${startTime})`);
+        }
+        if (endSeconds > videoDuration) {
+            endSeconds = videoDuration;
+        }
+        durationStr = normalizeTimeFormat(endSeconds - startSeconds);
+    }
+    else if (duration) {
+        durationStr = duration;
+        endSeconds = startSeconds + timeToSeconds(duration);
+        if (endSeconds > videoDuration) {
+            endSeconds = videoDuration;
+            durationStr = normalizeTimeFormat(videoDuration - startSeconds);
+        }
+    }
+    else {
+        // 默认截取到视频结束
+        endSeconds = videoDuration;
+        durationStr = normalizeTimeFormat(videoDuration - startSeconds);
+    }
+    return {
+        startTime,
+        endTime: normalizeTimeFormat(endSeconds),
+        duration: durationStr
+    };
+}
+// 时间字符串转换为秒数
+function timeToSeconds(timeStr) {
+    const parts = timeStr.split(':').map(Number);
+    if (parts.length === 3) {
+        // HH:MM:SS 格式
+        return parts[0] * 3600 + parts[1] * 60 + parts[2];
+    }
+    else if (parts.length === 2) {
+        // MM:SS 格式
+        return parts[0] * 60 + parts[1];
+    }
+    else if (parts.length === 1) {
+        // 秒数格式
+        return parts[0];
+    }
+    throw new Error(`Invalid time format: ${timeStr}`);
+}
+// 构建 FFmpeg 命令
+function buildFFmpegCommand(inputPath, outputPath, startTime, duration, options) {
+    const { overwrite = false } = options;
+    // 使用 copy 模式，保持原视频编码和质量
+    let command = `ffmpeg -ss ${startTime} -i "${inputPath}" -t ${duration}`;
+    // 复制视频和音频流，不重新编码
+    command += ' -c copy';
+    // 其他设置
+    command += ' -avoid_negative_ts make_zero';
+    command += ' -y'; // 自动覆盖输出文件
+    // 输出文件
+    command += ` "${outputPath}"`;
+    return command;
+}
+// 临时目录管理
+async function withTempDir(fn, customTempDir) {
+    const tempDir = customTempDir || fs.mkdtempSync(path.join(os.tmpdir(), "video-cut-"));
+    try {
+        return await fn(tempDir);
+    }
+    finally {
+        if (fs.existsSync(tempDir) && !customTempDir) {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+            log('Cleaned up temporary directory', { tempDir });
+        }
+    }
+}
+// 主函数
+export const cutVideo = async (videoPath, options = {}) => {
+    const startTime = Date.now();
+    try {
+        // 输入验证
+        const validatedPath = validateAndSanitizePath(videoPath);
+        if (!fs.existsSync(validatedPath)) {
+            throw new Error(`Video file not found: ${validatedPath}`);
+        }
+        // 检查 ffmpeg 可用性
+        if (!checkFFmpegAvailability()) {
+            throw new Error('FFmpeg is not available. Please install FFmpeg first.');
+        }
+        // 参数设置和验证
+        const { startTime: startTimeParam = "00:00:00", duration, endTime, outputFileName, outputFormat = "mp4", tempDir: customTempDir, overwrite = false } = options;
+        log('Starting video cutting', {
+            videoPath: validatedPath,
+            options: { startTime: startTimeParam, duration, endTime, outputFormat }
+        });
+        // 获取视频信息
+        const videoDuration = getDurationInSeconds(validatedPath);
+        log('Video analysis complete', { duration: videoDuration });
+        // 验证和标准化时间参数
+        const timeParams = validateTimeParameters(startTimeParam, duration, endTime, videoDuration);
+        log('Time parameters validated', timeParams);
+        // 准备输出路径
+        const videoDir = path.dirname(validatedPath);
+        const fileNameWithoutExt = path.basename(validatedPath, path.extname(validatedPath));
+        const defaultOutputName = `${fileNameWithoutExt}_cut_${timeParams.startTime.replace(/:/g, '-')}_to_${timeParams.endTime.replace(/:/g, '-')}.${outputFormat}`;
+        const outputFileNameFinal = outputFileName || defaultOutputName;
+        const outputPath = path.join(videoDir, outputFileNameFinal);
+        // 检查输出文件是否已存在
+        if (fs.existsSync(outputPath) && !overwrite) {
+            throw new Error(`Output file already exists: ${outputPath}. Use overwrite option to force overwrite.`);
+        }
+        // 使用临时目录处理
+        await withTempDir(async (tempDir) => {
+            const tempOutputPath = path.join(tempDir, `temp_output.${outputFormat}`);
+            // 构建 FFmpeg 命令
+            const command = buildFFmpegCommand(validatedPath, tempOutputPath, timeParams.startTime, timeParams.duration, options);
+            log('Executing FFmpeg command', { command });
+            // 执行 FFmpeg 命令
+            const result = shell.exec(command, { silent: true });
+            if (result.code !== 0) {
+                throw new Error(`FFmpeg failed: ${result.stderr}`);
+            }
+            // 移动文件到最终位置
+            fs.copyFileSync(tempOutputPath, outputPath);
+            log('Video cutting complete', { outputPath });
+        }, customTempDir);
+        // 获取输出文件信息
+        const outputStats = fs.statSync(outputPath);
+        const processingTime = Date.now() - startTime;
+        log('Video cutting successful', {
+            outputPath,
+            processingTime: `${processingTime}ms`,
+            fileSize: `${(outputStats.size / 1024 / 1024).toFixed(2)}MB`
+        });
+        return {
+            outputPath,
+            metadata: {
+                originalDuration: videoDuration,
+                cutDuration: timeToSeconds(timeParams.duration),
+                startTime: timeParams.startTime,
+                endTime: timeParams.endTime,
+                fileSize: outputStats.size,
+                processingTime
+            }
+        };
+    }
+    catch (error) {
+        log('Video cutting failed', {
+            error: error instanceof Error ? error.message : String(error),
+            videoPath
+        });
+        throw error;
+    }
+};
+// 便捷函数：按时间范围截取
+export const cutVideoByTimeRange = async (videoPath, startTime, endTime, options = {}) => {
+    return cutVideo(videoPath, {
+        ...options,
+        startTime,
+        endTime
+    });
+};
+// 便捷函数：按持续时间截取
+export const cutVideoByDuration = async (videoPath, startTime, duration, options = {}) => {
+    return cutVideo(videoPath, {
+        ...options,
+        startTime,
+        duration
+    });
+};
+// 便捷函数：从头开始截取指定秒数的视频
+export const cutVideoFromStart = async (videoPath, durationSeconds, options = {}) => {
+    // 验证持续时间参数
+    if (durationSeconds <= 0) {
+        throw new Error('Duration must be greater than 0 seconds');
+    }
+    // 将秒数转换为时间格式
+    const duration = normalizeTimeFormat(durationSeconds);
+    return cutVideo(videoPath, {
+        ...options,
+        startTime: "00:00:00", // 从头开始
+        duration
+    });
+};

package/lib/src/ffmpeg/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./getThumbnail.js";
 export * from "./check.js";
+export * from "./cutVideo.js";
 /**
  * 获取视频信息的接口定义
  */

package/lib/src/ffmpeg/index.js

@@ -1,6 +1,7 @@
 import shell from "shelljs";
 export * from "./getThumbnail.js";
 export * from "./check.js";
+export * from "./cutVideo.js";
 /**
  * 获取视频信息（使用 ffprobe）
  * @param videoPath 视频文件路径

package/lib/src/file/getFileConfig.d.ts

@@ -0,0 +1,30 @@
+import { VideoInfo } from '../ffmpeg/index.js';
+/**
+ * 文件配置信息接口
+ */
+export interface FileConfig {
+    /** 文件大小（带单位） */
+    size: string;
+    /** 文件大小（字节） */
+    sizeInBytes: number;
+    /** 文件编码格式 */
+    encoding: string;
+    /** 文件扩展名 */
+    extension: string;
+    /** 文件是否存在 */
+    exists: boolean;
+    /** 视频信息（仅当文件是视频时存在） */
+    videoInfo?: VideoInfo;
+}
+/**
+ * 获取文件配置信息
+ * @param filePath 文件绝对路径
+ * @returns 文件配置信息
+ */
+export declare function getFileConfig(filePath: string): FileConfig;
+/**
+ * 获取文件配置信息（异步版本）
+ * @param filePath 文件绝对路径
+ * @returns Promise<FileConfig>
+ */
+export declare function getFileConfigAsync(filePath: string): Promise<FileConfig>;

package/lib/src/file/getFileConfig.js

@@ -0,0 +1,208 @@
+import { statSync, readFileSync } from 'fs';
+import { extname } from 'path';
+import { getVideoInfo } from '../ffmpeg/index.js';
+/**
+ * 检测文件是否为视频文件
+ * @param filePath 文件路径
+ * @returns 是否为视频文件
+ */
+function isVideoFile(filePath) {
+    const videoExtensions = [
+        '.mp4', '.avi', '.mov', '.wmv', '.flv', '.webm', '.mkv',
+        '.m4v', '.3gp', '.ogv', '.ts', '.mts', '.m2ts', '.vob',
+        '.asf', '.rm', '.rmvb', '.divx', '.xvid', '.mpg', '.mpeg',
+        '.m2v', '.mpe', '.mpv', '.m1v', '.m2p', '.m2t', '.mxf'
+    ];
+    const extension = extname(filePath).toLowerCase();
+    return videoExtensions.includes(extension);
+}
+/**
+ * 格式化文件大小
+ * @param bytes 字节数
+ * @returns 格式化后的大小字符串
+ */
+function formatFileSize(bytes) {
+    if (bytes === 0)
+        return '0 B';
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}
+/**
+ * 检测文件编码格式
+ * @param filePath 文件路径
+ * @returns 编码格式
+ */
+function detectEncoding(filePath) {
+    try {
+        // 读取文件的前几个字节来检测编码
+        const buffer = readFileSync(filePath);
+        // 检查BOM（字节顺序标记）
+        if (buffer.length >= 3 && buffer[0] === 0xEF && buffer[1] === 0xBB && buffer[2] === 0xBF) {
+            return 'UTF-8';
+        }
+        if (buffer.length >= 2 && buffer[0] === 0xFF && buffer[1] === 0xFE) {
+            return 'UTF-16LE';
+        }
+        if (buffer.length >= 2 && buffer[0] === 0xFE && buffer[1] === 0xFF) {
+            return 'UTF-16BE';
+        }
+        // 简单的UTF-8检测
+        try {
+            const text = buffer.toString('utf8');
+            // 如果能够正确解码为UTF-8，则认为是UTF-8
+            if (Buffer.from(text, 'utf8').equals(buffer)) {
+                return 'UTF-8';
+            }
+        }
+        catch {
+            // 如果UTF-8解码失败，继续其他检测
+        }
+        // 检查是否为二进制文件
+        const textContent = buffer.toString('utf8', 0, Math.min(1024, buffer.length));
+        const hasNullBytes = buffer.includes(0);
+        const hasControlChars = /[\x00-\x08\x0E-\x1F\x7F]/.test(textContent);
+        if (hasNullBytes || hasControlChars) {
+            return 'Binary';
+        }
+        // 默认返回UTF-8
+        return 'UTF-8';
+    }
+    catch (error) {
+        return 'Unknown';
+    }
+}
+/**
+ * 获取文件配置信息
+ * @param filePath 文件绝对路径
+ * @returns 文件配置信息
+ */
+export function getFileConfig(filePath) {
+    try {
+        // 检查文件是否存在
+        const stats = statSync(filePath);
+        if (!stats.isFile()) {
+            throw new Error('路径不是文件');
+        }
+        const sizeInBytes = stats.size;
+        const size = formatFileSize(sizeInBytes);
+        const encoding = detectEncoding(filePath);
+        const extension = extname(filePath);
+        const config = {
+            size,
+            sizeInBytes,
+            encoding,
+            extension,
+            exists: true
+        };
+        // 如果是视频文件，获取视频信息
+        if (isVideoFile(filePath)) {
+            try {
+                config.videoInfo = getVideoInfo(filePath);
+            }
+            catch (error) {
+                // 如果获取视频信息失败，不抛出错误，只是不包含视频信息
+                console.warn(`获取视频信息失败: ${error}`);
+            }
+        }
+        return config;
+    }
+    catch (error) {
+        // 文件不存在或无法访问
+        return {
+            size: '0 B',
+            sizeInBytes: 0,
+            encoding: 'Unknown',
+            extension: extname(filePath),
+            exists: false
+        };
+    }
+}
+/**
+ * 获取文件配置信息（异步版本）
+ * @param filePath 文件绝对路径
+ * @returns Promise<FileConfig>
+ */
+export async function getFileConfigAsync(filePath) {
+    const { stat, readFile } = await import('fs/promises');
+    try {
+        const stats = await stat(filePath);
+        if (!stats.isFile()) {
+            throw new Error('路径不是文件');
+        }
+        const sizeInBytes = stats.size;
+        const size = formatFileSize(sizeInBytes);
+        const encoding = await detectEncodingAsync(filePath);
+        const extension = extname(filePath);
+        const config = {
+            size,
+            sizeInBytes,
+            encoding,
+            extension,
+            exists: true
+        };
+        // 如果是视频文件，获取视频信息
+        if (isVideoFile(filePath)) {
+            try {
+                config.videoInfo = getVideoInfo(filePath);
+            }
+            catch (error) {
+                // 如果获取视频信息失败，不抛出错误，只是不包含视频信息
+                console.warn(`获取视频信息失败: ${error}`);
+            }
+        }
+        return config;
+    }
+    catch (error) {
+        return {
+            size: '0 B',
+            sizeInBytes: 0,
+            encoding: 'Unknown',
+            extension: extname(filePath),
+            exists: false
+        };
+    }
+}
+/**
+ * 异步检测文件编码格式
+ * @param filePath 文件路径
+ * @returns Promise<string>
+ */
+async function detectEncodingAsync(filePath) {
+    try {
+        const { readFile } = await import('fs/promises');
+        const buffer = await readFile(filePath);
+        // 检查BOM
+        if (buffer.length >= 3 && buffer[0] === 0xEF && buffer[1] === 0xBB && buffer[2] === 0xBF) {
+            return 'UTF-8';
+        }
+        if (buffer.length >= 2 && buffer[0] === 0xFF && buffer[1] === 0xFE) {
+            return 'UTF-16LE';
+        }
+        if (buffer.length >= 2 && buffer[0] === 0xFE && buffer[1] === 0xFF) {
+            return 'UTF-16BE';
+        }
+        // 简单的UTF-8检测
+        try {
+            const text = buffer.toString('utf8');
+            if (Buffer.from(text, 'utf8').equals(buffer)) {
+                return 'UTF-8';
+            }
+        }
+        catch {
+            // 继续其他检测
+        }
+        // 检查是否为二进制文件
+        const textContent = buffer.toString('utf8', 0, Math.min(1024, buffer.length));
+        const hasNullBytes = buffer.includes(0);
+        const hasControlChars = /[\x00-\x08\x0E-\x1F\x7F]/.test(textContent);
+        if (hasNullBytes || hasControlChars) {
+            return 'Binary';
+        }
+        return 'UTF-8';
+    }
+    catch (error) {
+        return 'Unknown';
+    }
+}

package/lib/src/image/convert.d.ts

@@ -0,0 +1,89 @@
+import sharp from 'sharp';
+/**
+ * 支持的图片格式
+ */
+export type SupportedFormat = 'jpeg' | 'jpg' | 'png' | 'webp' | 'avif' | 'tiff' | 'gif';
+/**
+ * 图片转换选项
+ */
+export interface ConvertOptions {
+    /** 输出质量 (1-100)，仅对 JPEG、WebP、AVIF 有效 */
+    quality?: number;
+    /** 是否保持透明度，仅对 PNG、WebP 有效 */
+    keepTransparency?: boolean;
+    /** 输出宽度，保持宽高比 */
+    width?: number;
+    /** 输出高度，保持宽高比 */
+    height?: number;
+    /** 是否强制调整尺寸（不保持宽高比） */
+    forceResize?: boolean;
+    /** 压缩级别 (0-9)，仅对 PNG 有效 */
+    compressionLevel?: number;
+    /** 是否渐进式编码，仅对 JPEG 有效 */
+    progressive?: boolean;
+}
+/**
+ * 图片转换结果
+ */
+export interface ConvertResult {
+    /** 输入文件路径 */
+    inputPath: string;
+    /** 输出文件路径 */
+    outputPath: string;
+    /** 原始文件大小（字节） */
+    originalSize: number;
+    /** 转换后文件大小（字节） */
+    convertedSize: number;
+    /** 压缩率 */
+    compressionRatio: number;
+    /** 转换耗时（毫秒） */
+    processingTime: number;
+}
+/**
+ * 将图片转换为指定格式
+ * @param inputPath 输入图片路径
+ * @param outputPath 输出图片路径
+ * @param format 目标格式
+ * @param options 转换选项
+ * @returns 转换结果
+ */
+export declare function convertImage(inputPath: string, outputPath: string, format: SupportedFormat, options?: ConvertOptions): Promise<ConvertResult>;
+/**
+ * 批量转换图片格式
+ * @param files 文件列表，每个文件包含 inputPath, outputPath, format
+ * @param options 转换选项
+ * @returns 转换结果列表
+ */
+export declare function batchConvert(files: Array<{
+    inputPath: string;
+    outputPath: string;
+    format: SupportedFormat;
+}>, options?: ConvertOptions): Promise<ConvertResult[]>;
+/**
+ * 获取图片信息
+ * @param imagePath 图片路径
+ * @returns 图片信息
+ */
+export declare function getImageInfo(imagePath: string): Promise<{
+    path: string;
+    format: keyof sharp.FormatEnum;
+    width: number;
+    height: number;
+    size: number;
+    hasAlpha: boolean;
+    density: number;
+    space: keyof sharp.ColourspaceEnum;
+    channels: sharp.Channels;
+    depth: keyof sharp.DepthEnum;
+}>;
+/**
+ * 创建缩略图
+ * @param inputPath 输入图片路径
+ * @param outputPath 输出缩略图路径
+ * @param width 缩略图宽度
+ * @param height 缩略图高度
+ * @param format 输出格式
+ * @param options 转换选项
+ * @returns 转换结果
+ */
+export declare function createThumbnail(inputPath: string, outputPath: string, width: number, height: number, format?: SupportedFormat, options?: ConvertOptions): Promise<ConvertResult>;

package/lib/src/image/convert.js

@@ -0,0 +1,164 @@
+import sharp from 'sharp';
+import { promises as fs } from 'fs';
+import path from 'path';
+/**
+ * 将图片转换为指定格式
+ * @param inputPath 输入图片路径
+ * @param outputPath 输出图片路径
+ * @param format 目标格式
+ * @param options 转换选项
+ * @returns 转换结果
+ */
+export async function convertImage(inputPath, outputPath, format, options = {}) {
+    const startTime = Date.now();
+    // 验证输入文件是否存在
+    try {
+        await fs.access(inputPath);
+    }
+    catch {
+        throw new Error(`输入文件不存在: ${inputPath}`);
+    }
+    // 获取原始文件大小
+    const originalStats = await fs.stat(inputPath);
+    const originalSize = originalStats.size;
+    // 确保输出目录存在
+    const outputDir = path.dirname(outputPath);
+    await fs.mkdir(outputDir, { recursive: true });
+    // 创建 Sharp 实例
+    let sharpInstance = sharp(inputPath);
+    // 处理尺寸调整
+    if (options.width || options.height) {
+        if (options.forceResize) {
+            sharpInstance = sharpInstance.resize(options.width, options.height, {
+                fit: 'fill'
+            });
+        }
+        else {
+            sharpInstance = sharpInstance.resize(options.width, options.height, {
+                fit: 'inside',
+                withoutEnlargement: true
+            });
+        }
+    }
+    // 根据格式设置转换选项
+    switch (format.toLowerCase()) {
+        case 'jpeg':
+        case 'jpg':
+            sharpInstance = sharpInstance.jpeg({
+                quality: options.quality || 80,
+                progressive: options.progressive || false
+            });
+            break;
+        case 'png':
+            sharpInstance = sharpInstance.png({
+                quality: options.quality || 80,
+                compressionLevel: options.compressionLevel || 6,
+                progressive: options.progressive || false
+            });
+            break;
+        case 'webp':
+            sharpInstance = sharpInstance.webp({
+                quality: options.quality || 80,
+                lossless: false,
+                nearLossless: false,
+                smartSubsample: true
+            });
+            break;
+        case 'avif':
+            sharpInstance = sharpInstance.avif({
+                quality: options.quality || 80,
+                lossless: false
+            });
+            break;
+        case 'tiff':
+            sharpInstance = sharpInstance.tiff({
+                quality: options.quality || 80,
+                compression: 'lzw'
+            });
+            break;
+        case 'gif':
+            // GIF 转换需要特殊处理，因为 Sharp 不直接支持 GIF 输出
+            throw new Error('GIF 格式暂不支持输出，请使用其他格式');
+        default:
+            throw new Error(`不支持的格式: ${format}`);
+    }
+    // 执行转换
+    await sharpInstance.toFile(outputPath);
+    // 获取转换后文件大小
+    const convertedStats = await fs.stat(outputPath);
+    const convertedSize = convertedStats.size;
+    const processingTime = Date.now() - startTime;
+    return {
+        inputPath,
+        outputPath,
+        originalSize,
+        convertedSize,
+        compressionRatio: Math.round((1 - convertedSize / originalSize) * 100),
+        processingTime
+    };
+}
+/**
+ * 批量转换图片格式
+ * @param files 文件列表，每个文件包含 inputPath, outputPath, format
+ * @param options 转换选项
+ * @returns 转换结果列表
+ */
+export async function batchConvert(files, options = {}) {
+    const results = [];
+    for (const file of files) {
+        try {
+            const result = await convertImage(file.inputPath, file.outputPath, file.format, options);
+            results.push(result);
+        }
+        catch (error) {
+            console.error(`转换失败 ${file.inputPath}:`, error);
+            // 继续处理其他文件
+        }
+    }
+    return results;
+}
+/**
+ * 获取图片信息
+ * @param imagePath 图片路径
+ * @returns 图片信息
+ */
+export async function getImageInfo(imagePath) {
+    try {
+        await fs.access(imagePath);
+    }
+    catch {
+        throw new Error(`图片文件不存在: ${imagePath}`);
+    }
+    const metadata = await sharp(imagePath).metadata();
+    const stats = await fs.stat(imagePath);
+    return {
+        path: imagePath,
+        format: metadata.format,
+        width: metadata.width,
+        height: metadata.height,
+        size: stats.size,
+        hasAlpha: metadata.hasAlpha,
+        density: metadata.density,
+        space: metadata.space,
+        channels: metadata.channels,
+        depth: metadata.depth
+    };
+}
+/**
+ * 创建缩略图
+ * @param inputPath 输入图片路径
+ * @param outputPath 输出缩略图路径
+ * @param width 缩略图宽度
+ * @param height 缩略图高度
+ * @param format 输出格式
+ * @param options 转换选项
+ * @returns 转换结果
+ */
+export async function createThumbnail(inputPath, outputPath, width, height, format = 'jpeg', options = {}) {
+    return convertImage(inputPath, outputPath, format, {
+        ...options,
+        width,
+        height,
+        quality: options.quality || 85
+    });
+}

package/lib/src/image/example.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 常用转换场景示例
+ */
+export declare class ImageConverter {
+    /**
+     * 将图片转换为 WebP 格式（推荐用于 Web）
+     */
+    static toWebP(inputPath: string, outputPath: string, quality?: number): Promise<import("./convert.js").ConvertResult>;
+    /**
+     * 将图片转换为 AVIF 格式（最新格式，压缩率更高）
+     */
+    static toAVIF(inputPath: string, outputPath: string, quality?: number): Promise<import("./convert.js").ConvertResult>;
+    /**
+     * 将图片转换为 PNG 格式（保持透明度）
+     */
+    static toPNG(inputPath: string, outputPath: string, keepTransparency?: boolean): Promise<import("./convert.js").ConvertResult>;
+    /**
+     * 将图片转换为 JPEG 格式（通用格式）
+     */
+    static toJPEG(inputPath: string, outputPath: string, quality?: number): Promise<import("./convert.js").ConvertResult>;
+    /**
+     * 创建多种格式的图片（用于响应式 Web 设计）
+     */
+    static createResponsiveImages(inputPath: string, outputDir: string, baseName: string, sizes: Array<{
+        width: number;
+        height: number;
+        suffix: string;
+    }>): Promise<any[]>;
+}

package/lib/src/image/example.js

@@ -0,0 +1,116 @@
+import { convertImage, batchConvert, getImageInfo, createThumbnail, } from "./convert.js";
+import path from "node:path";
+/**
+ * 图片转换使用示例
+ */
+async function examples() {
+    try {
+        // 示例 1: 将 JPG 转换为 WebP
+        console.log("=== 示例 1: JPG 转 WebP ===");
+        const result1 = await convertImage("./input/sample.jpg", "./output/sample.webp", "webp", {
+            quality: 85,
+            width: 800,
+            height: 600,
+        });
+        console.log("转换结果:", result1);
+        // 示例 2: 将 PNG 转换为 AVIF
+        console.log("\n=== 示例 2: PNG 转 AVIF ===");
+        const result2 = await convertImage("./input/sample.png", "./output/sample.avif", "avif", {
+            quality: 90,
+            keepTransparency: true,
+        });
+        console.log("转换结果:", result2);
+        // 示例 3: 批量转换
+        console.log("\n=== 示例 3: 批量转换 ===");
+        const batchFiles = [
+            {
+                inputPath: "./input/image1.jpg",
+                outputPath: "./output/image1.webp",
+                format: "webp",
+            },
+            {
+                inputPath: "./input/image2.png",
+                outputPath: "./output/image2.avif",
+                format: "avif",
+            },
+        ];
+        const batchResults = await batchConvert(batchFiles, {
+            quality: 80,
+            width: 1200,
+        });
+        console.log("批量转换结果:", batchResults);
+        // 示例 4: 获取图片信息
+        console.log("\n=== 示例 4: 获取图片信息 ===");
+        const imageInfo = await getImageInfo("./input/sample.jpg");
+        console.log("图片信息:", imageInfo);
+        // 示例 5: 创建缩略图
+        console.log("\n=== 示例 5: 创建缩略图 ===");
+        const thumbnailResult = await createThumbnail("./input/sample.jpg", "./output/thumbnail.jpg", 200, 200, "jpeg", { quality: 90 });
+        console.log("缩略图创建结果:", thumbnailResult);
+    }
+    catch (error) {
+        console.error("转换过程中出现错误:", error);
+    }
+}
+/**
+ * 常用转换场景示例
+ */
+export class ImageConverter {
+    /**
+     * 将图片转换为 WebP 格式（推荐用于 Web）
+     */
+    static async toWebP(inputPath, outputPath, quality = 85) {
+        return convertImage(inputPath, outputPath, "webp", { quality });
+    }
+    /**
+     * 将图片转换为 AVIF 格式（最新格式，压缩率更高）
+     */
+    static async toAVIF(inputPath, outputPath, quality = 80) {
+        return convertImage(inputPath, outputPath, "avif", { quality });
+    }
+    /**
+     * 将图片转换为 PNG 格式（保持透明度）
+     */
+    static async toPNG(inputPath, outputPath, keepTransparency = true) {
+        return convertImage(inputPath, outputPath, "png", {
+            keepTransparency,
+            quality: 95,
+        });
+    }
+    /**
+     * 将图片转换为 JPEG 格式（通用格式）
+     */
+    static async toJPEG(inputPath, outputPath, quality = 90) {
+        return convertImage(inputPath, outputPath, "jpeg", {
+            quality,
+            progressive: true,
+        });
+    }
+    /**
+     * 创建多种格式的图片（用于响应式 Web 设计）
+     */
+    static async createResponsiveImages(inputPath, outputDir, baseName, sizes) {
+        const formats = [
+            { format: "webp", quality: 85 },
+            { format: "avif", quality: 80 },
+            { format: "jpeg", quality: 90 },
+        ];
+        const results = [];
+        for (const size of sizes) {
+            for (const { format, quality } of formats) {
+                const outputPath = path.join(outputDir, `${baseName}-${size.suffix}.${format}`);
+                const result = await convertImage(inputPath, outputPath, format, {
+                    width: size.width,
+                    height: size.height,
+                    quality,
+                });
+                results.push(result);
+            }
+        }
+        return results;
+    }
+}
+// // 如果直接运行此文件，执行示例
+// if (import.meta.url === `file://${process.argv[1]}`) {
+//   examples();
+// }

package/lib/src/image/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 图片处理工具模块
+ * 提供图片格式转换、缩略图生成、批量处理等功能
+ */
+export { convertImage, batchConvert, getImageInfo, createThumbnail, type SupportedFormat, type ConvertOptions, type ConvertResult } from './convert.js';
+export { ImageConverter } from './example.js';

package/lib/src/image/index.js

@@ -0,0 +1,6 @@
+/**
+ * 图片处理工具模块
+ * 提供图片格式转换、缩略图生成、批量处理等功能
+ */
+export { convertImage, batchConvert, getImageInfo, createThumbnail } from './convert.js';
+export { ImageConverter } from './example.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiping/node-utils",
-  "version": "1.0.38",
+  "version": "1.0.39",
   "description": "node-utils",
   "type": "module",
   "author": "The-End-Hero <527409987@qq.com>",
@@ -25,20 +25,22 @@
   "bugs": {
     "url": "https://github.com/The-End-Hero/wang-ping/issues"
   },
-  "gitHead": "dfd6b927e90517bf6703b066c9a2857e34ce68ce",
+  "gitHead": "189a73a39a274b78c9385c52cba91a3841198cfa",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
     "@xiping/srt-to-vtt": "1.0.37",
-    "chalk": "^5.5.0",
-    "sharp": "^0.34.3",
-    "shelljs": "0.10.0"
+    "chalk": "^5.6.2",
+    "fs-extra": "^11.3.2",
+    "sharp": "^0.34.4",
+    "shelljs": "0.10.0",
+    "srt-parser-2": "^1.2.3"
   },
   "devDependencies": {
-    "@types/node": "^22.15.34",
+    "@types/node": "^22.18.6",
     "tslib": "^2.8.1",
-    "typescript": "^5.7.3"
+    "typescript": "^5.9.2"
   }
 }