diff --git a/README.md b/README.md index 0ca29e08..9cbfdbe7 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ https://github.com/user-attachments/assets/1186067a-72c0-41b9-836f-987438f2332a > [!NOTE] -> **Media Processing & Storage:** When uploading media, Shumai always preserves and stores your original raw file. Note that the file size shown in the system represents the original file size and does not include the size of any transcoded files. For all media types (both images and videos), Shumai creates a 480p WebP poster image to serve as the preview in the file list view. Additionally: +> **Media Processing & Storage:** When uploading media, Shumai always preserves and stores your original raw file. Note that the file size shown in the system represents the original file size and does not include the size of any transcoded files. For all media types (both images and videos), Shumai creates a 300p WebP poster image to serve as the preview in the file list view. Additionally: > * **For Images:** Shumai generates a high-quality WebP proxy at the exact same resolution as your original file for optimized viewing. > * **For Videos:** It generates at least one proxy video (depending on your transcoding settings), alongside a sprite image and a small preview video (capped at 1600 frames) to enable fast timeline scrubbing and lightning-quick previews. diff --git a/README_CN.md b/README_CN.md index 15b0b261..ac50da7c 100644 --- a/README_CN.md +++ b/README_CN.md @@ -40,7 +40,7 @@ Shumai 是一个开源的 Frame.io 替代方案,专为创意团队打造,让 https://github.com/user-attachments/assets/1186067a-72c0-41b9-836f-987438f2332a > [!NOTE] -> **媒体处理与存储机制:** 上传媒体文件后,Shumai 始终会保留并存储原始文件。请注意,系统中显示的文件大小为原始文件的大小,不包含转码后生成的代理文件大小。无论图片还是视频,都会额外生成一张 480p 的 WebP 封面图,作为文件列表中的预览图。此外: +> **媒体处理与存储机制:** 上传媒体文件后,Shumai 始终会保留并存储原始文件。请注意,系统中显示的文件大小为原始文件的大小,不包含转码后生成的代理文件大小。无论图片还是视频,都会额外生成一张 300p 的 WebP 封面图,作为文件列表中的预览图。此外: > > * **图片:** 会生成一份与原图分辨率完全一致的高质量 WebP 转码版本,在保证画质的同时提升浏览性能。 > * **视频:** 会根据转码配置生成至少一个代理视频,同时生成雪碧图(Sprite)和一段最长 1600 帧的低分辨率转码视频,用于实现快速拖动时间轴和即时视频预览。 diff --git a/packages/core/src/transcode/transcode.test.ts b/packages/core/src/transcode/transcode.test.ts index a851398b..293277c3 100644 --- a/packages/core/src/transcode/transcode.test.ts +++ b/packages/core/src/transcode/transcode.test.ts @@ -1,5 +1,5 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest' -import { transcodeService } from './transcode' +import { transcodeService, calculatePreviewDimensions } from './transcode' import { s3Service } from '@shumai/core/src/s3/s3' import * as path from 'path' import * as child_process from 'child_process' @@ -185,18 +185,100 @@ describe('TranscodeService', () => { ) }) - it('should use sharp for image transcoding with sRGB conversion', async () => { + it('should use sharp for image transcoding with sRGB conversion (production 300p spec)', async () => { const outputFile = path.join(tempDir, 'output.webp') - await transcodeService.transcodeImage('input.png', outputFile, 480, 80) + await transcodeService.transcodeImage('input.png', outputFile, 300, 80, { isPreview: true }) expect(sharp).toHaveBeenCalledWith('input.png', { limitInputPixels: false }) const mockSharp = vi.mocked(sharp).mock.results[0].value expect(mockSharp.toColorspace).toHaveBeenCalledWith('srgb') - expect(mockSharp.resize).toHaveBeenCalledWith(480, 7680, expect.any(Object)) + expect(mockSharp.resize).toHaveBeenCalledWith(400, 300, expect.any(Object)) expect(mockSharp.webp).toHaveBeenCalledWith({ quality: 80 }) expect(mockSharp.toFile).toHaveBeenCalledWith(outputFile) }) + it('should support legacy 480 width fallback shim', async () => { + const outputFile = path.join(tempDir, 'output_legacy.webp') + await transcodeService.transcodeImage('input.png', outputFile, 480, 80) + + const mockSharp = vi.mocked(sharp).mock.results[vi.mocked(sharp).mock.results.length - 1].value + expect(mockSharp.resize).toHaveBeenCalledWith(400, 300, expect.any(Object)) + }) + + it('should handle preview and full-res proxy dimension calculations correctly', async () => { + const outputFile = path.join(tempDir, 'out.webp') + + // 16:9 source (1920x1080) in preview mode -> 533x300 + const mockSharp169 = { + resize: vi.fn().mockReturnThis(), + toColorspace: vi.fn().mockReturnThis(), + webp: vi.fn().mockReturnThis(), + toFile: vi.fn().mockResolvedValue({}), + metadata: vi.fn().mockResolvedValue({ width: 1920, height: 1080 }), + } + // eslint-disable-next-line @typescript-eslint/no-explicit-any + vi.mocked(sharp).mockReturnValueOnce(mockSharp169 as any) + await transcodeService.transcodeImage('169.png', outputFile, 300, 80, { isPreview: true }) + expect(mockSharp169.resize).toHaveBeenCalledWith(533, 300, expect.any(Object)) + + // Small image (200x150) in preview mode -> 200x150 + const mockSharpSmall = { + resize: vi.fn().mockReturnThis(), + toColorspace: vi.fn().mockReturnThis(), + webp: vi.fn().mockReturnThis(), + toFile: vi.fn().mockResolvedValue({}), + metadata: vi.fn().mockResolvedValue({ width: 200, height: 150 }), + } + // eslint-disable-next-line @typescript-eslint/no-explicit-any + vi.mocked(sharp).mockReturnValueOnce(mockSharpSmall as any) + await transcodeService.transcodeImage('small.png', outputFile, 300, 80, { isPreview: true }) + expect(mockSharpSmall.resize).toHaveBeenCalledWith(200, 150, expect.any(Object)) + + // 1:10 Tall screenshot (1000x10000) in preview mode -> 53x533 + const mockSharpTall = { + resize: vi.fn().mockReturnThis(), + toColorspace: vi.fn().mockReturnThis(), + webp: vi.fn().mockReturnThis(), + toFile: vi.fn().mockResolvedValue({}), + metadata: vi.fn().mockResolvedValue({ width: 1000, height: 10000 }), + } + // eslint-disable-next-line @typescript-eslint/no-explicit-any + vi.mocked(sharp).mockReturnValueOnce(mockSharpTall as any) + await transcodeService.transcodeImage('tall.png', outputFile, 300, 80, { isPreview: true }) + expect(mockSharpTall.resize).toHaveBeenCalledWith(53, 533, expect.any(Object)) + + // Square full-resolution proxy (10000x10000, isPreview: false) -> capped at WEBP_MAX_DIMENSION (7680) + const mockSharpSquareProxy = { + resize: vi.fn().mockReturnThis(), + toColorspace: vi.fn().mockReturnThis(), + webp: vi.fn().mockReturnThis(), + toFile: vi.fn().mockResolvedValue({}), + metadata: vi.fn().mockResolvedValue({ width: 10000, height: 10000 }), + } + // eslint-disable-next-line @typescript-eslint/no-explicit-any + vi.mocked(sharp).mockReturnValueOnce(mockSharpSquareProxy as any) + await transcodeService.transcodeImage('square.png', outputFile, 10000, 90, { + height: 10000, + isPreview: false, + }) + expect(mockSharpSquareProxy.resize).toHaveBeenCalledWith(7680, 7680, expect.any(Object)) + }) + + it('should calculate preview dimensions correctly for 300p (short side 300, max long side 533)', () => { + // 16:9 Landscape + expect(calculatePreviewDimensions(1920, 1080)).toEqual({ width: 533, height: 300 }) + // 9:16 Portrait + expect(calculatePreviewDimensions(1080, 1920)).toEqual({ width: 300, height: 533 }) + // 1:1 Square + expect(calculatePreviewDimensions(1000, 1000)).toEqual({ width: 300, height: 300 }) + // 21:9 Ultrawide + expect(calculatePreviewDimensions(2560, 1080)).toEqual({ width: 533, height: 225 }) + // 1:10 Tall screenshot (capped at max long side = 533) + expect(calculatePreviewDimensions(1000, 10000)).toEqual({ width: 53, height: 533 }) + // Small image (no enlargement) + expect(calculatePreviewDimensions(200, 150)).toEqual({ width: 200, height: 150 }) + }) + it('should use ImageMagick for PSD image transcoding', async () => { const outputFile = path.join(tempDir, 'output_psd.webp') const psdBuffer = Buffer.from('8BPS-fake-psd-content') @@ -264,7 +346,7 @@ describe('TranscodeService', () => { expect(sharp).toHaveBeenCalledWith(inputBuffer, { limitInputPixels: false }) const mockSharp = vi.mocked(sharp).mock.results[vi.mocked(sharp).mock.results.length - 1].value expect(mockSharp.toColorspace).toHaveBeenCalledWith('srgb') - expect(mockSharp.resize).toHaveBeenCalledWith(480, 7680, expect.any(Object)) + expect(mockSharp.resize).toHaveBeenCalledWith(400, 300, expect.any(Object)) expect(mockSharp.webp).toHaveBeenCalledWith({ quality: 80 }) expect(mockSharp.toFile).toHaveBeenCalledWith(outputFile) }) @@ -451,7 +533,7 @@ describe('TranscodeService', () => { ) expect(child_process.execFile).toHaveBeenCalledWith( 'ffmpeg', - expect.arrayContaining(['-filter_complex', 'scale=w=480:h=-2,tile=10x10']), + expect.arrayContaining(['-filter_complex', 'scale=w=300:h=-2,tile=10x10']), expect.any(Function), ) expect(child_process.execFile).toHaveBeenCalledWith( diff --git a/packages/core/src/transcode/transcode.ts b/packages/core/src/transcode/transcode.ts index 48d75dbd..56906350 100644 --- a/packages/core/src/transcode/transcode.ts +++ b/packages/core/src/transcode/transcode.ts @@ -145,6 +145,40 @@ export function isPsdInput(input: string | Buffer): boolean { input[3] === 0x53 ) } +export function calculatePreviewDimensions( + origW: number, + origH: number, + targetShort = 300, + maxLong = 533, +): { width: number; height: number } { + if (origW <= 0 || origH <= 0) { + return { width: targetShort, height: targetShort } + } + + const origShort = Math.min(origW, origH) + const origLong = Math.max(origW, origH) + + if (origShort <= targetShort && origLong <= maxLong) { + return { width: origW, height: origH } + } + + let scale = targetShort / origShort + const scaledLong = Math.round(origLong * scale) + + if (scaledLong > maxLong) { + scale = maxLong / origLong + } + + const newW = Math.max(1, Math.round(origW * scale)) + const newH = Math.max(1, Math.round(origH * scale)) + + return { width: newW, height: newH } +} + +export interface TranscodeImageOptions { + height?: number | null + isPreview?: boolean +} export class TranscodeService { constructor(private readonly prismaClient: typeof prisma = prisma) {} @@ -402,8 +436,22 @@ export class TranscodeService { outputFile: string, width: number, quality: number, - height: number | null = null, + heightOrOptions: number | null | TranscodeImageOptions = null, ): Promise { + const height = + typeof heightOrOptions === 'object' && heightOrOptions !== null + ? (heightOrOptions.height ?? null) + : heightOrOptions + let isPreview = + typeof heightOrOptions === 'object' && heightOrOptions !== null + ? (heightOrOptions.isPreview ?? false) + : false + + // Backward compatibility shim for legacy queued tasks or old call signatures passing width 480 or height 0 + if (width === 480 || height === 0) { + isPreview = true + } + let input: string | Buffer = inputFile if (typeof inputFile === 'string' && inputFile.startsWith('http')) { const resp = await fetch(inputFile) @@ -414,8 +462,30 @@ export class TranscodeService { } const WEBP_MAX_DIMENSION = 7680 - const targetW = width > 0 ? Math.min(width, WEBP_MAX_DIMENSION) : WEBP_MAX_DIMENSION - const targetH = height && height > 0 ? Math.min(height, WEBP_MAX_DIMENSION) : WEBP_MAX_DIMENSION + let targetW = width > 0 ? Math.min(width, WEBP_MAX_DIMENSION) : WEBP_MAX_DIMENSION + let targetH = height && height > 0 ? Math.min(height, WEBP_MAX_DIMENSION) : WEBP_MAX_DIMENSION + + const sharpInstance = sharp(input, { limitInputPixels: false }) + + if (isPreview) { + try { + const meta = await sharpInstance.metadata() + if (meta.width && meta.height) { + // Fallback shim: If legacy 480 caller passed width=480, map targetShort to 300 + const targetShort = width === 480 ? 300 : width + const maxLong = Math.round((targetShort * 16) / 9) + const dims = calculatePreviewDimensions(meta.width, meta.height, targetShort, maxLong) + targetW = dims.width + targetH = dims.height + } + } catch { + // Fallback to targetW/targetH as calculated above + } + } + + // WEBP_MAX_DIMENSION (7680) safety cap is ALWAYS enforced + targetW = Math.min(targetW, WEBP_MAX_DIMENSION) + targetH = Math.min(targetH, WEBP_MAX_DIMENSION) if (isPsdInput(input)) { let psdPath: string @@ -452,8 +522,6 @@ export class TranscodeService { } } - const sharpInstance = sharp(input, { limitInputPixels: false }) - sharpInstance.toColorspace('srgb').resize(targetW, targetH, { withoutEnlargement: true, fit: 'inside', @@ -469,7 +537,7 @@ export class TranscodeService { duration: number, ): Promise { const spriteFps = 100 / duration - const filterComplex = `[0:v]fps=${spriteFps},scale=w=480:h=-2,tile=10x10[sprite_out];[0:v]scale=-2:480:force_original_aspect_ratio=decrease,select='eq(n\\,0)'[thumb_out]` + const filterComplex = `[0:v]fps=${spriteFps},scale=w=300:h=-2,tile=10x10[sprite_out];[0:v]scale=-2:300:force_original_aspect_ratio=decrease,select='eq(n\\,0)'[thumb_out]` const args = [ '-i', @@ -557,7 +625,7 @@ export class TranscodeService { '-i', path.join(tmpDir, 'frame_%d.png'), '-filter_complex', - 'scale=w=480:h=-2,tile=10x10', + 'scale=w=300:h=-2,tile=10x10', '-frames:v', '1', '-c:v', @@ -570,7 +638,7 @@ export class TranscodeService { await sharp(firstPagePath, { limitInputPixels: false }) .toColorspace('srgb') - .resize(480, null, { withoutEnlargement: true, fit: 'inside' }) + .resize(300, 533, { withoutEnlargement: true, fit: 'inside' }) .webp({ quality: 75 }) .toFile(outputPoster) diff --git a/packages/db/src/prisma-json-types.ts b/packages/db/src/prisma-json-types.ts index 1b6af340..fb876eb5 100644 --- a/packages/db/src/prisma-json-types.ts +++ b/packages/db/src/prisma-json-types.ts @@ -83,6 +83,7 @@ declare global { height: number quality: number format: string + isPreview?: boolean } export interface SpriteInfo { diff --git a/packages/transcode/src/activities/transcode.ts b/packages/transcode/src/activities/transcode.ts index 6f4343bf..df73ad23 100644 --- a/packages/transcode/src/activities/transcode.ts +++ b/packages/transcode/src/activities/transcode.ts @@ -377,6 +377,10 @@ export async function transcodeImageActivity( outputFile, params.imageSpec.width, params.imageSpec.quality, + { + height: params.imageSpec.height || null, + isPreview: params.imageSpec.isPreview ?? false, + }, ) const buffer = fs.readFileSync(outputFile) await s3Service.putObject(bucket, key, buffer, buffer.length, 'image/webp') diff --git a/packages/transcode/src/workflows/transcode-image.test.ts b/packages/transcode/src/workflows/transcode-image.test.ts index 8c3b199f..af3a2cc8 100644 --- a/packages/transcode/src/workflows/transcode-image.test.ts +++ b/packages/transcode/src/workflows/transcode-image.test.ts @@ -115,8 +115,8 @@ describe('transcodeImageWorkflow', () => { mockActivities.transcodeImageActivity.mockResolvedValue({ key: 't.webp', - width: 480, - height: 480, + width: 300, + height: 300, format: 'webp', }) @@ -132,8 +132,8 @@ describe('transcodeImageWorkflow', () => { mediaInfo: expect.objectContaining({ thumbnail: expect.objectContaining({ key: 't.webp', - width: 480, - height: 480, + width: 300, + height: 300, }), }), }) diff --git a/packages/transcode/src/workflows/transcode-image.ts b/packages/transcode/src/workflows/transcode-image.ts index 00b64287..4250e3c4 100644 --- a/packages/transcode/src/workflows/transcode-image.ts +++ b/packages/transcode/src/workflows/transcode-image.ts @@ -75,7 +75,7 @@ export async function transcodeImageWorkflow(task: WorkflowTask): Promise const thumbTranscode = await executeActivity(workerQueue, transcodeImageActivity, { assetKey: key, filePath, - imageSpec: { width: 480, height: 0, quality: 80, format: 'webp' }, + imageSpec: { width: 300, height: 300, quality: 80, format: 'webp', isPreview: true }, }) mediaInfo.thumbnail = thumbTranscode } diff --git a/packages/transcode/src/workflows/transcode-video.test.ts b/packages/transcode/src/workflows/transcode-video.test.ts index b5da86f3..3043e7a6 100644 --- a/packages/transcode/src/workflows/transcode-video.test.ts +++ b/packages/transcode/src/workflows/transcode-video.test.ts @@ -124,8 +124,8 @@ describe('transcodeVideoWorkflow', () => { }) mockActivities.transcodeImageActivity.mockResolvedValue({ key: 't.webp', - width: 480, - height: 270, + width: 300, + height: 300, }) await transcodeVideoWorkflow(task) diff --git a/packages/transcode/src/workflows/transcode-video.ts b/packages/transcode/src/workflows/transcode-video.ts index 01f58715..0c2e7d99 100644 --- a/packages/transcode/src/workflows/transcode-video.ts +++ b/packages/transcode/src/workflows/transcode-video.ts @@ -108,7 +108,7 @@ export async function transcodeVideoWorkflow(task: WorkflowTask): Promise const thumbTranscode = await executeActivity(workerQueue, transcodeImageActivity, { assetKey: key, filePath, - imageSpec: { width: 480, height: 0, quality: 80, format: 'webp' }, + imageSpec: { width: 300, height: 300, quality: 80, format: 'webp', isPreview: true }, }) mediaInfo.thumbnail = thumbTranscode }